Skip to main content
Glama
@mcpx-digital/readme-score

@mcpx-digital/readme-score

@mcpx-digital/readme-score

MCP server that scores README quality and suggests improvements.

Honest, heuristic scoring for install/usage/license/badges/structure plus relative link checks. Local markdown files only.

Scoring rubric (100 points)

Category

Max

What we look for

Title

5

Top-level # heading

Description

10

Short prose intro

Install

20

Install heading + package-manager / clone commands

Usage

20

Usage/examples heading + fenced code

License

10

License section or clear license mention

Badges

10

Status/shield badges

Contributing

5

Contributing section or link

Relative links

15

Relative paths resolve on disk

Structure

5

Enough markdown headings

Grades: A≥90, B≥80, C≥70, D≥60, else F.

Heuristic for documentation completeness — not code quality, security, or SEO.

Related MCP server: codebase-doc-generator

Install

npx -y @mcpx-digital/readme-score

Cursor mcp.json example

{
  "mcpServers": {
    "readme-score": {
      "command": "npx",
      "args": ["-y", "@mcpx-digital/readme-score"]
    }
  }
}

Local clone:

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

Tools

Tool

What it does

score_readme

Full 0–100 score with category breakdown

suggest_improvements

Concrete fix list

check_readme_links

Relative link existence only

Example prompts

  • “Score ./README.md”

  • “Suggest README improvements for this repo”

  • “Which relative links in the README are broken?”

Development

git clone https://github.com/TheoryofShadows/readme-score-mcp.git
cd readme-score-mcp
npm install
npm test

License

MIT

Available Tools

3 tools
score_readmeA

Score a README for install/usage/license/badges/structure and relative link validity (0–100). Scores a local README markdown file only.

Inputs: filePath (required), skipLinkCheck.

suggest_improvementsB

Suggest concrete README improvements based on the scoring rubric. Scores a local README markdown file only.

Inputs: filePath (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 3 tools

    Disambiguation4/5

    The three tools are mostly easy to distinguish: score_readme produces an overall score, suggest_improvements produces recommendations, and check_readme_links verifies link resolution. However, score_readme already includes relative link validity in its scoring, so an agent could be uncertain whether to call score_readme or check_readme_links for link checking.

    Naming Consistency5/5

    All tool names follow a consistent lowercase snake_case verb-object pattern: score_readme, suggest_improvements, check_readme_links. The naming makes the action and target predictable across the entire set.

    Tool Count5/5

    Three tools is well-scoped for a focused README-scoring server. Each tool covers a distinct stage of the workflow—evaluating, suggesting improvements, and validating links—without unnecessary bloat.

    Completeness5/5

    The toolkit covers the complete local README workflow: scoring, receiving concrete improvement suggestions, and checking relative link integrity. Since the server explicitly targets local README files, there are no major missing operations within its stated scope.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides direct access to local documentation files through simple search and overview tools, enabling LLMs to query project-specific markdown documentation without requiring vector databases or RAG pipelines.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Scores local git repositories for README substance, license, package description, TypeScript config, tests, and GitHub Actions, providing a numbered hygiene report.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Lints local Markdown files or whole directory trees for broken relative links and images, empty link targets or text, heading hierarchy problems, and common README issues. Only relative targets on disk are checked, so external http(s) links are never fetched.
      2
      MIT