# 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](https://modelcontextprotocol.io) (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):

   ```bash
   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:

   ```bash
   npm run demo:compare
   ```

4. Same analysis as JSON:

   ```bash
   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

```bash
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):

```bash
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):

```bash
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`:

```bash
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`](./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):

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

Optional OpenAI polish:

```json
{
  "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

```mermaid
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

```bash
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](./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.