AI导哈

README分析工具

一个用于分析和改进README文件的工具，提供评分、缺失部分检测和改进建议。

  • by QinyangTan
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 QinyangTan/GitHub-README-MCP

使用说明

github自述文件mcp

给每个README一个明确的分数、一个有力的介绍和一个复制粘贴改进计划——不需要LLM。

github readme mcp是一个小型 模型上下文协议 （MCP）服务器，使用透明、确定的规则审查README文件。粘贴标记、指向本地文件、传递GitHub repo URL或给它一个原始URL——它返回分数、缺失的部分、具体问题和改进的草稿。可选的OpenAI抛光仅在您设置时生效 OPENAI_API_KEY；如果密钥丢失或呼叫失败，一切仍然正常。

尝试演示（约30秒）

  1. git clone <repo-url> && cd github-readme-mcp && npm install

  2. 对故意弱化的示例README进行评分审查（不需要构建步骤）：

    npm run demo

    您应该看到一个较低的总分，缺少部分（安装、使用、许可证等），以及具体的建议。

  3. 并排比较弱例子和强例子：

    npm run demo:compare

  4. 与JSON相同的分析：

    npm run demo:json | head

  5. 可选： npm run build 然后使用 node dist/cli.js … （见下文）。

为什么它存在

优秀的README可以减少支持负载并加快采用速度，但大多数团队缺乏一致的清单。这个项目将一个实用的量规（标题、价值道具、安装、使用、功能、演示、徽章、贡献、许可证、支持）编码到MCP工具和一个小型CLI中，这样你就可以在本地运行评论，将它们连接到代理中，或在几分钟内演示这个想法。

特性

  • 确定性分析 --按维度细分（标题、清晰度、安装、使用、功能、演示、徽章、贡献/联系、许可证）加权0-100分。
  • 多重输入 --内联标记、本地路径， https://github.com/owner/repo，或任何生的 https:// markdown URL（带有基本安全检查）。
  • 五个MCP工具 --分析、分组建议、重写介绍、完整改进的README、比较前后。
  • 可选LLM抛光剂 — OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL；优雅地回退到基于规则的文本。
  • 命令行界面 — analyze, improve，以及 compare 和 --json 或降价输出。
  • 测试+脱毛 --Vitest，ESLint，Prettier。

快速入门

git clone <your-fork-or-url>
cd github-readme-mcp
npm install
npm run build   # optional until you run dist/ or publish

MCP服务器（stdio）

使用 dist/server.js 对于像Cursor这样的主机（单用途条目，易于推理）：

npm start
# same as:
node dist/server.js

这个 github-readme-mcp npm bin 指向 dist/cli.js：与 没有争论 它还会启动stdio MCP服务器，因此 npx github-readme-mcp 构建后的工作方式相同。

CLI命令

在开发过程中（TypeScript通过 tsx，无构建）：

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

之后 npm run build:

node dist/cli.js analyze ./README.md
node dist/cli.js serve          # MCP stdio (explicit)

旗帜： --json 用于机器可读输出； --markdown / --md 用于人类可读（默认用于分析/改进/比较）。

npm脚本

脚本 它运行什么
npm run build tsc → dist/
npm start node dist/server.js （MCP）
npm run dev tsx src/cli.ts +你的args后面 --
npm run dev:server tsx src/server.ts （MCP，开发）
npm run demo 分析 examples/weak-readme.md
npm run demo:json 同样，JSON
npm run demo:compare 弱夹具与强夹具
npm test Vitest
npm run lint 埃斯林特
npm run format 预写

MCP工具概述

工具 目的
analyze_readme 完整报告： overallScore, sectionScores、章节、问题、速赢、徽章/标语， rewrittenIntro, summary.
suggest_readme_improvements 相同的输入； mustFix / shouldImprove / niceToHave 和 whyItMatters 和 suggestedFix （基本问题与 analyze_readme).
rewrite_intro introVariants, taglineVariants, rationale；可选的OpenAI细化。
generate_improved_readme 脚手架缺失部分，可选徽章/贡献；可选OpenAI抛光剂。
compare_before_after summary, improvements, stillMissing 对于两个markdown字符串。

输入形状（解析一个源）：

  • content?: string --原始降价
  • filePath?: string --本地路径
  • repoUrl?: string --GitHub存储库URL
  • rawUrl?: string --直接原始标记URL

rewrite_intro 需要 content. compare_before_after 需要 original 和 improved.

示例输出

看 examples/sample-analyze-output.json 对于返回的JSON形状 analyze_readme （说明性分数）。

Markdown CLI输出列出了部分分数、检测到的部分与缺失的部分、速赢、标语创意、确定性介绍重写以及严重性问题。

光标/MCP配置

点 command/args 在 dist/server.js 之后 npm run build （调整绝对路径）：

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

可选OpenAI抛光剂：

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

建筑

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/ --从四种输入类型中解析markdown；GitHub使用REST API default_branch 加上原始的倒退；原始URL是通过大小和内容类型保护来获取的。
  • src/analysis/ --分段检测、启发式和 buildAnalyzeResult （分数+问题的单一管道）。
  • src/scoring/ --加权量规；总分是每个维度0-100分的加权平均值。
  • src/rewrite/ --确定性介绍和完整的README框架； compare 重复使用分析。
  • src/providers/ --可选的OpenAI聊天只需要波兰语。
  • src/tools/ --MCP工具处理程序与CLI共享（如适用）。
  • src/server.ts --stdio MCP服务器。
  • src/cli.ts --子命令；不使用子命令，启动相同的MCP服务器（npm bin 入口）。

发展

npm install
npm run typecheck
npm run lint
npm run format
npm test
npm run build
  • 节点20+ 推荐。
  • 环境 --复制 .env.example 到 .env 如果您使用密钥，则在本地；服务器未加载 .env 单独使用（在MCP主机或shell中设置变量）。

路线图

  • 通过一个小JSON文件配置量规权重。
  • 其他主机（GitLab原始URL、自托管GitHub）。
  • 非英语README的本地化提示。
  • 可选的 read_lints 只列出问题而不评分的样式工具。

贡献

欢迎发布问题和PR。请快跑 npm test 和 npm run lint 在提交之前。保持变化的重点；匹配现有的TypeScript风格，避免新的依赖关系，除非有明显的胜利。

许可证

麻省理工学院——见 许可证.

GitHub关于复制（选择一个）

  1. MCP服务器+CLI，对README进行评分，查找缺失的部分，并起草改进方案——默认情况下是确定性的，OpenAI是可选的。
  2. 面向开发人员的README审阅者：GitHub URL、原始URL或本地路径→ 分数、问题、比MCP更低的降价。
  3. 发布更清晰的OSS文档：加权README准则、速赢和通过模型上下文协议复制粘贴脚手架。

建议的GitHub主题

readme documentation mcp model-context-protocol github developer-tools markdown lint oss typescript nodejs

发布帖子（简短）

发送通过“5秒浏览”的自述文件 我开源了 github自述文件mcp--MCP服务器+CLI，为您的README评分，列出缺失的部分，建议徽章和标语，并起草改进版本。它完全离线运行，遵循确定性规则；仅当您需要额外的润色时，才添加OpenAI密钥。尝试 npm run demo 在包含的弱README上，或将其指向任何GitHub repo URL。麻省理工学院授权——欢迎明星和反馈。

相关 MCP