github-readme-mcp

Give every README a clear score, a punchy intro, and a copy-paste improvement plan—no LLM required.

github-readme-mcp is a small Model Context Protocol (MCP) server that reviews README files using transparent, deterministic rules. Paste markdown, point at a local file, pass a GitHub repo URL, or hand it a raw URL—it returns scores, missing sections, concrete issues, and an improved draft. Optional OpenAI polish kicks in only when you set OPENAI_API_KEY; if the key is missing or the call fails, everything still works.

---

Try the demo (about 30 seconds)

1. git clone <repo-url> && cd github-readme-mcp && npm install

2. Run a scored review on the intentionally weak sample README (no build step required):

   npm run demo
   

   You should see a low overall score, missing sections (install, usage, license, etc.), and concrete suggestions.

3. Compare weak vs strong examples side by side:

   npm run demo:compare
   

4. Same analysis as JSON:

   npm run demo:json | head
   

5. Optional: npm run build then use node dist/cli.js … (see below).

---

Why it exists

Great READMEs reduce support load and speed up adoption, but most teams lack a consistent checklist. This project encodes a practical rubric (title, value prop, install, usage, features, demo, badges, contributing, license, support) into MCP tools and a tiny CLI so you can run reviews locally, wire them into an agent, or demo the idea in minutes.

---

Features

• Deterministic analysis — weighted 0–100 score with per-dimension breakdown (title, clarity, install, usage, features, demo, badges, contributing/contact, license).
• Multiple inputs — inline markdown, local path, https://github.com/owner/repo, or any raw https:// markdown URL (with basic safety checks).
• Five MCP tools — analyze, grouped suggestions, intro rewrites, full improved README, before/after comparison.
• Optional LLM polish — OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL; graceful fallback to rule-based text.
• CLI — analyze, improve, and compare with --json or markdown output.
• Tests + linting — Vitest, ESLint, Prettier.

---

Quickstart

git clone <your-fork-or-url>
cd github-readme-mcp
npm install
npm run build   # optional until you run dist/ or publish

MCP server (stdio)

Use dist/server.js for hosts like Cursor (single-purpose entry, easy to reason about):

npm start
# same as:
node dist/server.js

The github-readme-mcp npm bin points at dist/cli.js: with no arguments it also starts the stdio MCP server, so npx github-readme-mcp works the same way after a build.

CLI commands

During development (TypeScript via tsx, no build):

npm run dev -- analyze ./README.md
npm run dev -- analyze https://github.com/modelcontextprotocol/servers --json
npm run dev -- improve ./examples/weak-readme.md
npm run dev -- compare ./examples/weak-readme.md ./examples/strong-readme.md

After npm run build:

node dist/cli.js analyze ./README.md
node dist/cli.js serve          # MCP stdio (explicit)

Flags: --json for machine-readable output; --markdown / --md for human-readable (default for analyze/improve/compare).

npm scripts

Script	What it runs
npm run build	tsc → dist/
npm start	node dist/server.js (MCP)
npm run dev	tsx src/cli.ts + your args after --
npm run dev:server	tsx src/server.ts (MCP, dev)
npm run demo	Analyze examples/weak-readme.md
npm run demo:json	Same, JSON
npm run demo:compare	Weak vs strong fixtures
npm test	Vitest
npm run lint	ESLint
npm run format	Prettier write

---

MCP tools overview

Tool	Purpose
analyze_readme	Full report: overallScore, sectionScores, sections, issues, quick wins, badges/taglines, rewrittenIntro, summary.
suggest_readme_improvements	Same inputs; mustFix / shouldImprove / niceToHave with whyItMatters and suggestedFix (same underlying issues as analyze_readme).
rewrite_intro	introVariants, taglineVariants, rationale; optional OpenAI refinement.
generate_improved_readme	Scaffold missing sections, optional badges/contributing; optional OpenAI polish.
compare_before_after	summary, improvements, stillMissing for two markdown strings.

Input shape (resolve one source):

• content?: string — raw markdown
• filePath?: string — local path
• repoUrl?: string — GitHub repository URL
• rawUrl?: string — direct raw markdown URL

rewrite_intro requires content. compare_before_after requires original and improved.

---

Example outputs

See examples/sample-analyze-output.json for the JSON shape returned by analyze_readme (illustrative scores).

Markdown CLI output lists section scores, detected vs missing sections, quick wins, tagline ideas, a deterministic intro rewrite, and issues with severities.

---

Cursor / MCP configuration

Point command/args at dist/server.js after npm run build (adjust the absolute path):

{
  "mcpServers": {
    "github-readme-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/github-readme-mcp/dist/server.js"]
    }
  }
}

Optional OpenAI polish:

{
  "mcpServers": {
    "github-readme-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/github-readme-mcp/dist/server.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_MODEL": "gpt-4o-mini"
      }
    }
  }
}

---

Architecture

flowchart LR
  subgraph inputs [Inputs]
    C[content]
    F[filePath]
    G[repoUrl]
    R[rawUrl]
  end
  L[loaders] --> A[analysis + scoring]
  A --> T[MCP tools / CLI]
  P[providers/openai optional] --> T
  inputs --> L

• src/loaders/ — Resolve markdown from the four input types; GitHub uses the REST API for default_branch plus raw fallbacks; raw URLs are fetched with size and content-type guards.
• src/analysis/ — Section detection, heuristics, and buildAnalyzeResult (single pipeline for scores + issues).
• src/scoring/ — Weighted rubric; overall score is the weighted mean of per-dimension 0–100 scores.
• src/rewrite/ — Deterministic intro and full README scaffolding; compare reuses analysis.
• src/providers/ — Optional OpenAI chat calls for polish only.
• src/tools/ — MCP tool handlers shared with the CLI where applicable.
• src/server.ts — stdio MCP server.
• src/cli.ts — Subcommands; with no subcommand, starts the same MCP server (npm bin entry).

---

Development

npm install
npm run typecheck
npm run lint
npm run format
npm test
npm run build

• Node 20+ recommended.
• Environment — copy .env.example to .env locally if you use a key; the server does not load .env by itself (set vars in your MCP host or shell).

---

Roadmap

• Configurable rubric weights via a small JSON file.
• Additional hosts (GitLab raw URLs, self-hosted GitHub).
• Localization hints for non-English READMEs.
• Optional read_lints style tool that only lists issues without scores.

---

Contributing

Issues and PRs are welcome. Please run npm test and npm run lint before submitting. Keep changes focused; match existing TypeScript style and avoid new dependencies unless there is a clear win.

---

License

MIT — see LICENSE.

---

GitHub About copy (pick one)

1. MCP server + CLI that scores READMEs, finds missing sections, and drafts improvements—deterministic by default, OpenAI optional.
2. README reviewer for developers: GitHub URL, raw URL, or local path → scores, issues, improved markdown over MCP.
3. Ship clearer OSS docs: weighted README rubric, quick wins, and copy-paste scaffolds via Model Context Protocol.

---

Suggested GitHub topics

readme documentation mcp model-context-protocol github developer-tools markdown lint oss typescript nodejs

---

Launch post (short)

Ship READMEs that pass the “5-second skim.” I open-sourced github-readme-mcp—an MCP server + CLI that scores your README, lists missing sections, suggests badges and taglines, and drafts an improved version. It runs fully offline with deterministic rules; add an OpenAI key only if you want extra polish. Try npm run demo on the included weak README, or point it at any GitHub repo URL. MIT licensed—stars and feedback welcome.