@mcpx-digital/readme-score
Provides tools for scoring local Markdown README files, suggesting improvements, and checking relative link existence.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@mcpx-digital/readme-score score ./README.md and suggest improvements"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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 |
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-scoreCursor 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 |
| Full 0–100 score with category breakdown |
| Concrete fix list |
| 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 testLicense
MIT
Available Tools
3 toolscheck_readme_linksC
Check that relative links in a README resolve on disk. Scores a local README markdown file only.
Inputs: filePath (required).
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
Scored across 3 tools
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.
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.
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.
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
Related MCP Connectors
Scores your code across 12 areas, with findings, fix prompts, and re-assessment in your AI agent
Grade any website out of 100 for speed, SEO, trust and lead capture, with plain-English fixes.
Checks any domain's DMARC, SPF, MX and DKIM setup, scores it 0-100, and ranks the fixes.
Check a deployed web app for security headers, SEO, accessibility and performance, with a grade.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides 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
- AlicenseNot gradedqualityDmaintenanceGenerates comprehensive documentation (architecture overview, dependency graph, API surface, and README) for any codebase locally without external APIs.6 npm1MIT
- AlicenseBqualityCmaintenanceScores local git repositories for README substance, license, package description, TypeScript config, tests, and GitHub Actions, providing a numbered hygiene report.2MIT
- AlicenseAqualityCmaintenanceLints 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.2MIT