智能文档 MCP 服务器

一个生产就绪的模型上下文协议（MCP）服务器，能够智能地分析代码库并生成全面的文档。使用 TypeScript 和 tree-sitter 构建，以实现准确的代码解析。

特性

• 多语言支持：分析 TypeScript、JavaScript 和 Python 代码库
• 智能分析：提取函数、类、方法、接口、类型和变量
• 文档覆盖率：计算文档覆盖率指标
• 缺失文档检测：识别未记录的代码，并按严重程度分类（关键、中等、低）
• AI 功能建议：生成文档模板和改进建议
• Markdown 输出：专业文档，采用 Markdown 格式

安装

npm install
npm run build

使用

作为 MCP 服务器

在您的 MCP 客户端配置中添加（Claude Desktop）：

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "smart-docs": {
      "command": "node",
      "args": ["C:\\ProjectFolder\\dist\\index.js"]
    }
  }
}

然后重启 Claude Desktop。

可用工具

1. analyze_codebase

分析代码库或文件，提取代码元素并计算文档覆盖率。

输入：

{
  "path": "/path/to/your/codebase"
}

输出：

• 已分析的总文件数
• 找到的总代码元素数
• 文档覆盖率百分比
• 按文件和元素类型的详细分解

2. generate_documentation

为代码库生成全面的 Markdown 文档。

输入：

{
  "path": "/path/to/your/codebase",
  "format": "markdown"
}

输出：

• 完整的 Markdown 文档
• 汇总统计信息
• 按文件和元素类型组织

3. detect_missing_docs

检测缺少文档的代码元素，并按严重程度分类。

输入：

{
  "path": "/path/to/your/codebase",
  "minSeverity": "critical"
}

严重程度级别：

• 关键：公共类、接口和导出函数
• 中等：类型别名和导出类型
• 低：私有方法和内部变量

输出：

• 按严重程度分类的缺少文档列表
• 按严重程度和类型的汇总统计信息
• 详细的元素信息

4. suggest_improvements

分析现有文档并提出改进建议。

输入：

{
  "path": "/path/to/your/codebase",
  "limit": 20
}

输出：

• 缺少文档的文档模板
• 不完整文档的改进建议
• 参数和返回值文档提示

项目结构

smart-docs-mcp/
├── src/
│   ├── index.ts                    # MCP 服务器入口点
│   ├── types/
│   │   └── index.ts               # TypeScript 类型和接口
│   ├── parsers/
│   │   ├── base-parser.ts         # 抽象解析器基类
│   │   ├── typescript-parser.ts   # TypeScript/JavaScript 解析器
│   │   └── python-parser.ts       # Python 解析器
│   ├── analyzers/
│   │   ├── codebase-analyzer.ts   # 主要分析引擎
│   │   └── doc-detector.ts        # 缺少文档检测器
│   ├── generators/
│   │   ├── markdown-generator.ts  # Markdown 文档生成器
│   │   └── improvement-suggester.ts # 改进建议
│   ├── tools/
│   │   ├── analyze-codebase.ts
│   │   ├── generate-documentation.ts
│   │   ├── detect-missing-docs.ts
│   │   └── suggest-improvements.ts
│   └── utils/
│       └── file-utils.ts          # 文件系统工具
├── package.json
├── tsconfig.json
└── README.md

工作原理

1. 解析：使用 tree-sitter 将源代码解析成抽象语法树（AST）
2. 提取：从 AST 中识别代码元素（函数、类等）
3. 文档检测：检查 JSDoc、文档字符串和内联注释
4. 分析：计算覆盖率并检测缺少的文档
5. 生成：创建 Markdown 文档和改进建议

严重程度分类

服务器使用智能严重程度分类：

• 公共 API（类、接口、导出函数）→ 关键
• 类型定义和复杂类型 → 中等
• 私有方法和内部变量 → 低

错误处理

所有工具都包括全面的错误处理：

• 无效路径返回描述性错误消息
• 不支持的文件类型优雅跳过
• 解析错误包括文件位置和上下文

开发

# 安装依赖
npm install

# 构建项目
npm run build

# 开发监视模式
npm run watch

# 运行服务器
npm start

要求

• Node.js >= 18.0.0
• TypeScript 5.3+

依赖项

• @modelcontextprotocol/sdk: MCP 协议实现
• tree-sitter: 代码解析引擎
• tree-sitter-typescript: TypeScript/JavaScript 语法
• tree-sitter-python: Python 语法
• zod: 模式验证

测试

测试项目包含在 test-project/ 目录中，带有演示各种文档场景的示例文件。

许可证

MIT

贡献

欢迎贡献！请确保：

• 代码遵循 TypeScript 最佳实践
• 所有新功能包含错误处理
• 更新文档