Skip to main content
Glama
QinyangTan

github-readme-mcp

by QinyangTan
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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).

Related MCP server: MCP GitHub README Generator

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.

Available Tools

2 tools
compare_before_afterB

Compare two README markdown strings and summarize improvements vs remaining gaps.

ParametersJSON Schema
NameRequiredDescriptionDefault
improvedYes
originalYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must convey behavioral traits. It only says 'compare and summarize', with no mention of side effects, authorization needs, rate limits, or any limitations. This is minimal behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no fluff, but it omits important details. It is concise but not adequately informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and a comparison tool, the description should explain the output format or criteria for improvement/gaps. It only vaguely mentions 'summarize improvements vs remaining gaps', leaving agents to guess the output structure. The sibling tool further calls for differentiation which is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (no parameter descriptions). The description adds the phrase 'two README markdown strings', which maps to the parameters 'original' and 'improved', but does not provide expected format, constraints, or examples. This is insufficient compensation for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the verb 'compare', the resource 'two README markdown strings', and the outcome 'summarize improvements vs remaining gaps'. It clearly distinguishes from sibling tool 'suggest_readme_improvements' which likely focuses on suggesting improvements rather than comparing two versions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when an original and improved version are available, but provides no explicit guidance on when to use this tool versus the sibling 'suggest_readme_improvements', nor any exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

suggest_readme_improvementsC

Same inputs as analyze_readme. Returns grouped recommendations (mustFix / shouldImprove / niceToHave) with rationale and optional example text.

ParametersJSON Schema
NameRequiredDescriptionDefault
rawUrlNo
contentNo
repoUrlNo
filePathNo

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does not disclose whether the tool is read-only, requires authentication, or has any side effects. The description only covers the output format, leaving behavioral traits opaque.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and to the point, but the phrase 'Same inputs as analyze_readme' adds a dependency on another tool's description, reducing self-containment. Still, every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of 4 parameters with no schema descriptions and no output schema, the description is inadequate. It does not explain the return format in detail, and the reliance on analyze_readme for inputs is a gap. The tool needs more information to be used effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only says 'Same inputs as analyze_readme' without describing any of the four parameters. This is insufficient for an agent to understand what values to provide, especially since analyze_readme is not described here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns grouped recommendations with rationale and example text, and it mentions the inputs are the same as analyze_readme. However, it does not explicitly state what the tool does in terms of its core function (i.e., improving READMEs) beyond the output structure.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the sibling tool compare_before_after. It references analyze_readme for inputs but does not explain how or when this tool should be preferred, and analyze_readme is not listed as a sibling, which could cause confusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.8/5.0
Disambiguation3/5

The two tools have distinct inputs and outputs (compare vs. suggest), but the reference to a non-existent 'analyze_readme' tool in the suggest tool's description creates ambiguity about the intended workflow.

Naming Consistency4/5

Both tools follow a consistent verb_noun pattern with snake_case, but the missing 'analyze_readme' tool referenced in the description is a minor inconsistency.

Tool Count2/5

With only 2 tools, the server feels incomplete for its stated purpose of README analysis. A typical set would include at least 3-5 tools for a well-scoped domain.

Completeness2/5

The server lacks a basic 'analyze_readme' tool that is referenced in the suggest tool's description, and the surface only covers comparison and suggestion, missing standalone analysis and likely other operations.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/QinyangTan/GitHub-README-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server