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

  • Node.js server

  • Python server

• API

  • POST /mcp (Node.js)

  • POST /mcp (Python)

• Examples

• Development notes

• Troubleshooting

• License

Related MCP server: Astro Blog MCP Server

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_content directory.

• 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 repo scope to read private repository READMEs.

• Node.js 18+ (for server.js) and npm.

• Python 3.9+ with pip (for server.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 (default 5000).

Python server

python server.py

Environment:

• PORT (optional): HTTP port (default 5000).

• 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>/readme with the provided token.

• Decodes the base64 README content.

• Writes <owner>_<repo>.md inside blog_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:

1. action: "import_github_readme" — mirrors the Node.js behavior.

2. 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 with blog_path in the payload.

• Filenames replace / in the repo name with _ (e.g., owner_repo.md).

• Node.js implementation sets the GitHub User-Agent header to MCP-Server-Node; Python uses MCP-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 repo scope for private repos.

• File permission issues: ensure the process can create and write to blog_path.

• Port conflicts: set PORT to a free port or stop other services using the default port.

License

See LICENSE.