MCP4All
Comprehensive example implementations of a Model Context Protocol (MCP) server that transform GitHub repository READMEs into local blog content. The repository ships two lightweight HTTP servers:
- Node.js (Express) implementation in
server.js - Python (Flask) implementation in
server.py
Both variants expose a /mcp endpoint that can be driven by an MCP client (or any HTTP client) to pull a GitHub README, decode it, and write it to a local blog_content folder as Markdown.
Table of contents
- Features
- Repository layout
- Prerequisites
- Setup
- Running the servers
- API
- Examples
- Development notes
- Troubleshooting
- License
Features
- Fetches the README of any public or private GitHub repository via the GitHub REST API.
- Saves the decoded README as a Markdown file into a configurable
blog_contentdirectory. - Small, dependency-light servers that can be run with Node.js or Python.
- Simple HTTP contract that can be wired into MCP-aware clients or scripts.
Repository layout
server.js— Express server that fetches GitHub READMEs and writes them locally.server.py— Flask server with similar functionality plus a simple echo response for generic MCP testing.blog_content/— Output directory for generated Markdown files (created automatically).package.json/package-lock.json— Node.js dependencies and scripts.ChatGPT.md— Background conversation that inspired the project (not required for runtime).LICENSE— Project license.
Prerequisites
- GitHub Personal Access Token (PAT) with at least
reposcope to read private repository READMEs. - Node.js 18+ (for
server.js) and npm. - Python 3.9+ with
pip(forserver.py). - Outbound HTTPS access to
api.github.com.
Setup
Node.js dependencies
npm install
Python dependencies
python -m venv .venv
source .venv/bin/activate
pip install flask requests
You can run either server independently; installing both stacks is optional.
Running the servers
Node.js server
npm start
# or manually
node server.js
Environment:
PORT(optional): HTTP port (default5000).
Python server
python server.py
Environment:
PORT(optional): HTTP port (default5000).- Bind address defaults to
0.0.0.0.
API
POST /mcp (Node.js)
Fetches a README and stores it as Markdown.
Request body
{
"repo": "owner/repo",
"token": "<github_pat>",
"blog_path": "./blog_content" // optional
}
Behavior
- Calls
https://api.github.com/repos/<repo>/readmewith the provided token. - Decodes the base64 README content.
- Writes
<owner>_<repo>.mdinsideblog_path(folder created if missing). - Responds with
{ "success": true, "file": "<path>" }on success or an error payload on failure.
POST /mcp (Python)
Supports two modes:
action: "import_github_readme"— mirrors the Node.js behavior.- Without
action— simple echo helper to test connectivity.
Request body (import)
{
"action": "import_github_readme",
"repo": "owner/repo",
"token": "<github_pat>",
"blog_path": "./blog_content" // optional
}
Request body (echo)
{
"input": "Was ist MCP?"
}
Responses
- Import:
{ "success": true, "file": "<path>" }or{ "error": "<message>" }. - Echo:
{ "response": "Du hast gefragt: <input>. MCP antwortet: Hallo Welt!" }.
Examples
Create a blog-ready README (Node.js server)
curl -X POST http://localhost:5000/mcp \
-H "Content-Type: application/json" \
-d '{"repo":"username/repo","token":"<github_pat>"}'
Response:
{"success": true, "file": "blog_content/username_repo.md"}
Import via Python server
curl -X POST http://localhost:5000/mcp \
-H "Content-Type: application/json" \
-d '{"action":"import_github_readme","repo":"username/repo","token":"<github_pat>"}'
Echo test (Python server)
curl -X POST http://localhost:5000/mcp \
-H "Content-Type: application/json" \
-d '{"input":"Was ist MCP?"}'
Response:
{"response": "Du hast gefragt: Was ist MCP?. MCP antwortet: Hallo Welt!"}
Development notes
- The output path defaults to
./blog_content; override withblog_pathin the payload. - Filenames replace
/in the repo name with_(e.g.,owner_repo.md). - Node.js implementation sets the GitHub
User-Agentheader toMCP-Server-Node; Python usesMCP-Server. - Extend either server to render richer blog posts by transforming the README content before saving.
Troubleshooting
- 401/403 errors from GitHub: confirm the PAT is valid and includes
reposcope for private repos. - File permission issues: ensure the process can create and write to
blog_path. - Port conflicts: set
PORTto a free port or stop other services using the default port.
License
See LICENSE.