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

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:

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

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