MCP 服务器

Readme-builder-mcp

An MCP server that automatically scans project directories, extracts routes and environment variables, and generates GitHub-style README files in Chinese with explicit confirmation before writing.

README

README.md（中文，更新版）

Readme-builder-mcp

一个基于 Model Context Protocol (MCP) 的“README 生成器”服务器：

提供可在 Trae 等 MCP 客户端中调用的工具；
支持自动扫描项目目录、提取路由与环境变量、汇总脚本与依赖；
一键生成GitHub 风格的 README（中文），并在显式确认后写入磁盘。

⚠️ 默认只读安全：所有写入磁盘的操作都要求 confirm: true 才会执行。

功能特性

🧠 Pro 版 README 生成： generateReadmePro 会：
- 递归扫描目录（忽略 node_modules / dist 等），生成简洁的项目结构树；
- 基于源码静态匹配提取API 端点（如 app.get('/api') / router.post(...)）；
- 搜集 .env.example 与源码中的 process.env.*，罗列环境变量清单；
- 汇总 npm scripts 与依赖清单，自动推断特性（Express/Mongoose/JWT 等）；
- 可选徽章与目录，输出完整中文 README。
🔒 默认只读：所有写文件操作必须传入 confirm: true，避免误写入。
🧩 MCP 标准：通过 STDIO 运行，适配支持 MCP 的 IDE / 客户端（如 Trae）。
🧪 Zod 输入参数校验：工具输入参数全部通过 Zod 校验，类型安全、错误可控。

环境要求

Node.js ≥ 18
推荐包管理器：npm / pnpm / bun（示例以 npm 为主）

快速开始

# 1) 安装依赖
npm i

# 2) 构建 TypeScript
npm run build

# 3) 本地启动（STDIO 模式，不会主动打印界面）
node dist/server.js

这是一个 STDIO 服务器：它会在标准输入/输出上等待 MCP 客户端连接。直接运行看到“没有反应”是正常的——请通过 Trae 等 MCP 客户端来调用它的工具。

在 Trae（或其它 MCP 客户端）中使用

在 Trae 的 MCP 配置中注册该服务器（指向 编译后的 JS）：

{
  "mcpServers": {
    "readme-builder": {
      "command": "node",
      "args": [
        "C\\\\path\\\\to\\\\readme-mcp\\\\dist\\\\server.js"
      ]
    }
  }
}

Windows 路径建议用双反斜杠；或改用正斜杠。
修改配置后重启 Trae，以加载新 MCP 服务器。

在 Trae 的“工具（Tools）”里选择 readme-builder，即可看到工具列表： detectRepo、generateReadme、generateReadmePro、writeFile。

工具 API

1) `detectRepo`

读取指定目录的 package.json 并返回关键信息（名称、描述、scripts、dependencies 等）。

输入参数

{ "dir": "C\\\\path\\\\to\\\\your-project" }

dir：目标仓库绝对路径（省略则取当前工作目录）。

content[0].text：包含项目信息的 JSON 字符串。

2) `generateReadme`

基础版 README 生成（标题 + 简介 + 特性），只读返回 Markdown。

输入参数

{
  "name": "your-project",
  "description": "一句话简介。",
  "features": ["要点1", "要点2"]
}

content[0].text：Markdown 文本。

3) `generateReadmePro`

推荐。扫描目录，自动生成GitHub 风格完整 README（中文）。

输入参数（建议最少传 dir 与 description）

{
  "dir": "C\\\\path\\\\to\\\\your-project",
  "description": "示例 Node.js/Express 项目结构与实践。",
  "addBadges": true,
  "includeTOC": true,
  "maxTreeDepth": 2,
  "language": "zh",
  "extraFeatures": ["额外功能点（可选）"]
}

做的事

读取 package.json（名称、scripts、dependencies、engines、license 等）；
扫描目录，生成结构树（深度由 maxTreeDepth 控制）；
匹配 app.get/post/... / router.get/post/... 识别端点（最多列出 20 条）；
汇总 .env.example 与源码中的 process.env.* 作为“环境变量”章节；
从依赖推断功能点（Express/Mongoose/JWT/bcrypt/morgan 等）；
选择性添加徽章/目录，输出完整中文 README。

content[0].text：Markdown 文本。

4) `writeFile`

写入文件（需要显式确认 confirm: true）。

输入参数

{
  "filePath": "C\\\\path\\\\to\\\\your-project\\\\README.md",
  "content": "# your-project\n...完整 Markdown...",
  "confirm": true
}

成功：已写入：<绝对路径>（<字节数> bytes）
若未设置 confirm: true：仅返回预览，不落盘

典型工作流

探测仓库

{ "tool": "detectRepo", "server": "readme-builder",
  "args": { "dir": "C\\\\path\\\\to\\\\your-project" } }

生成 README（Pro 版）

{ "tool": "generateReadmePro", "server": "readme-builder",
  "args": {
    "dir": "C\\\\path\\\\to\\\\your-project",
    "description": "你的项目一句话或一段简介。",
    "addBadges": true,
    "includeTOC": true,
    "maxTreeDepth": 2,
    "language": "zh"
  } }

写入 README.md（显式确认）

{ "tool": "writeFile", "server": "readme-builder",
  "args": {
    "filePath": "C\\\\path\\\\to\\\\your-project\\\\README.md",
    "content": "<把上一步返回的 Markdown 原文粘这里>",
    "confirm": true
  } }

🔐 安全提醒：只有当你明确传 confirm: true 时才会真正写入磁盘。

命令行自测（可选）

未接入 Trae 前，你也可以用 MCP 的命令行客户端（选其一）快速验证：

# 列出工具
npx @modelcontextprotocol/client-cli tools list \
  --command node \
  --args "C:\\path\\to\\readme-mcp\\dist\\server.js"

# 调用 generateReadmePro
npx @modelcontextprotocol/client-cli tools call generateReadmePro \
  --input "{\"dir\":\"C\\\\\\\\path\\\\\\\\to\\\\\\\\your-project\",\"description\":\"示例项目。\",\"addBadges\":true,\"includeTOC\":true,\"language\":\"zh\"}" \
  --command node \
  --args "C:\\path\\to\\readme-mcp\\dist\\server.js"

项目结构

src/
  server.ts          # MCP 服务器入口（含 detectRepo / generateReadme / generateReadmePro / writeFile）
dist/
  server.js          # 构建后的运行文件（Trae 指向的就是它）
package.json
package-lock.json
tsconfig.json
.gitignore
README.md

常见问题

运行 node dist/server.js 没反应？ 正常。它是 STDIO 服务端，不会主动输出。请用 Trae 或命令行客户端与之通信。
Trae 里看不到工具？
- 确认 MCP 配置指向 dist/server.js（不是 src/server.ts）。
- 重启 Trae。
- node -v 能在系统 PATH 中执行。
写入失败？
- 检查是否传了 confirm: true；
- 检查 filePath 目录是否存在（本项目会自动 mkdir -p）；
- Windows 路径建议用双反斜杠。
API 端点识别不全？ 正则仅覆盖常见 app. / router. 调用，且默认最多展示 20 条。复杂路由（动态加载、框架封装）可能无法静态识别。