# mcp-repo-health

MCP server that scores a **local git repository** the way a recruiter or ghfind-style scanner would: README substance, license, package description, TypeScript config, tests, and GitHub Actions.

It is meant to run inside Cursor / Claude / any MCP host over **stdio**. Scoring is deterministic and has no GitHub API dependency.

## Why this exists

Public GitHub scores overweight empty demos and underweight complete local projects. This server lets an agent inspect a checkout and return a numbered hygiene report before you push.

## Tools

| Tool | Input | Output |
| --- | --- | --- |
| `score_repo` | `{ "root": "/abs/path" }` | Human report + JSON (`score`, `maxScore`, `checks`, `gaps`) |
| `list_hygiene_gaps` | `{ "root": "/abs/path" }` | Failing checks only |

Weights (100 points):

- README ≥ 400 characters — 20
- LICENSE file or `package.json` license — 10
- `package.json` description — 10
- `.gitignore` — 8
- `tsconfig.json` — 10
- Tests (`*.test.ts`, `*.spec.tsx`, `tests/`) — 16
- `.github/workflows/*.yml` — 16
- `src/`, `app/`, or `lib/` — 10

## Install

```bash
git clone https://github.com/ashwinmridul/mcp-repo-health.git
cd mcp-repo-health
npm install
npm test
npm run build
```

## Cursor MCP config

Add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "repo-health": {
      "command": "node",
      "args": ["/ABS/PATH/mcp-repo-health/dist/index.js"]
    }
  }
}
```

Then ask the agent: “Score `/Users/you/personal/mcp-workbench` for repo hygiene.”

## Development

```bash
npm run typecheck
npm test
npm run dev
```

`npm run dev` speaks MCP on stdin/stdout, so run it from an MCP host, not a TTY.

## License

MIT