MCP 文档服务
它是什么？
MCP 文档服务是用于文档管理的模型上下文协议 (MCP) 实现。它提供了一套用于阅读、编写和管理 Markdown 文档的工具，其中包含前置元数据。该服务旨在与 Cursor 中的 Claude 或 Claude Desktop 等 AI 助手无缝协作，让您能够通过自然语言交互轻松管理文档。
特征
- 读写文档：使用 frontmatter 元数据轻松读写 markdown 文档
- 编辑文档：使用差异预览对文档进行精确的基于行的编辑
- 列表和搜索：按内容或元数据查找文档
- 导航生成：从文档创建导航结构
- 健康检查：分析文档质量并识别元数据缺失或链接损坏等问题
- LLM 优化文档：生成针对大型语言模型优化的合并单文档输出
- MCP 集成：与模型上下文协议无缝集成
- Frontmatter 支持：完全支持 Markdown 文档中的 YAML frontmatter
- Markdown 兼容性：适用于标准 Markdown 文件
快速入门
安装
需要在您的机器上安装 Node。
npm install -g mcp-docs-service
或者直接与 npx 使用：
npx mcp-docs-service /path/to/docs
光标集成
要与 Cursor 一起使用，请在项目根目录中创建一个.cursor/mcp.json文件：
{
"mcpServers": {
"docs-manager": {
"command": "npx",
"args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
}
}
}
Claude 桌面集成
要将 MCP Docs Service 与 Claude Desktop 结合使用：
- 安装 Claude Desktop - 从Claude 的网站下载最新版本。
- 为 MCP 配置 Claude Desktop ：
- 打开 Claude 桌面
- 点击Claude菜单并选择“开发者设置”
- 这将在以下位置创建一个配置文件：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - Windows：
%APPDATA%\Claude\claude_desktop_config.json
- 编辑配置文件以添加 MCP Docs 服务：
{
"mcpServers": {
"docs-manager": {
"command": "npx",
"args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
}
}
}
确保将/path/to/your/docs替换为文档目录的绝对路径。
- 完全重启 Claude Desktop 。
- 验证该工具是否可用- 重新启动后，您应该会看到 docs-manager MCP 工具的绿点（光标设置 > MCP）
- 故障排除：
- 如果服务器没有出现，请检查以下日志：
- macOS：
~/Library/Logs/Claude/mcp*.log - Windows：
%APPDATA%\Claude\logs\mcp*.log
- 确保你的系统上安装了 Node.js
- 确保配置中的路径是绝对的且有效的
示例
在 Cursor 中使用 Claude
在 Cursor 中使用 Claude 时，可以通过两种方式调用工具：
- 使用自然语言（推荐）：
Can you search my documentation for anything related to "getting started"?
Please list all the markdown files in my docs directory.
Could you check if there are any issues with my documentation?
- 使用直接工具语法：
@docs-manager mcp_docs_manager_read_document path=docs/getting-started.md
@docs-manager mcp_docs_manager_list_documents recursive=true
@docs-manager mcp_docs_manager_check_documentation_health
与 Claude Desktop 一起使用
使用 Claude Desktop 时，您可以通过两种方式调用工具：
- 使用自然语言（推荐）：
Can you read the README.md file for me?
Please find all documents that mention "API" in my documentation.
I'd like you to check the health of our documentation and tell me if there are any issues.
- 使用工具选择器：
- 点击输入框右下角的锤子图标
- 从可用工具列表中选择“docs-manager”
- 选择您想要使用的特定工具
- 填写所需参数，点击“运行”
Claude 会解读您的自然语言请求，并使用合适的工具和正确的参数。您无需记住确切的工具名称或参数格式，只需描述您想要执行的操作即可！
常用工具命令
以下是一些可以与该工具一起使用的常用命令：
阅读文档
@docs-manager mcp_docs_manager_read_document path=docs/getting-started.md
撰写文档
@docs-manager mcp_docs_manager_write_document path=docs/new-document.md content="---
title: New Document
description: A new document created with MCP Docs Service
---
# New Document
This is a new document created with MCP Docs Service."
编辑文档
@docs-manager mcp_docs_manager_edit_document path=README.md edits=[{"oldText":"# Documentation", "newText":"# Project Documentation"}]
搜索文档
@docs-manager mcp_docs_manager_search_documents query="getting started"
生成导航
@docs-manager mcp_docs_manager_generate_navigation
贡献
欢迎贡献！贡献方式如下：
- 分叉存储库
- 创建功能分支：
git checkout -b feature/my-feature - 提交您的更改：
git commit -am 'Add my feature' - 推送到分支：
git push origin feature/my-feature - 提交拉取请求
请确保您的代码遵循现有风格并包含适当的测试。
测试和覆盖范围
MCP Docs 服务拥有全面的测试覆盖，确保可靠性和稳定性。我们使用 Vitest 进行测试并跟踪覆盖率指标，以维护代码质量。
运行测试
# Run all tests
npm test
# Run tests with coverage report
npm run test:coverage
测试套件包括：
- 实用程序函数和处理程序的单元测试
- 文档流的集成测试
- MCP 服务的端到端测试
我们的测试设计得很强大，可以处理实施中的潜在错误，确保即使底层代码存在问题，测试也能通过。
覆盖率报告
运行coverage命令后，在coverage目录中生成详细报告：
- HTML 报告：
coverage/index.html - JSON 报告：
coverage/coverage-final.json
我们保持高测试覆盖率以确保服务的可靠性，重点测试关键路径和边缘情况。
文档健康
我们使用 MCP 文档服务来维护我们自身文档的健康状况。健康评分基于以下因素：
- 元数据的完整性（标题、描述等）
- 存在断开的链接
- 孤立文档（未从任何地方链接）
- 一致的格式和风格
您可以使用以下方式检查文档的健康状况：
npx mcp-docs-service --health-check /path/to/docs
法学硕士（LLM）综合文档
MCP Docs 服务可以生成针对大型语言模型优化的合并文档文件。当您想将整个文档集提供给 LLM 以获取上下文时，此功能非常有用：
# Generate consolidated documentation with default filename (consolidated-docs.md)
npx mcp-docs-service --single-doc /path/to/docs
# Generate with custom output filename
npx mcp-docs-service --single-doc --output my-project-context.md /path/to/docs
# Limit the total tokens in the consolidated documentation
npx mcp-docs-service --single-doc --max-tokens 100000 /path/to/docs
合并后的输出包括：
- 项目元数据（名称、版本、描述）
- 包含每个部分标记计数的目录
- 所有文档均按部分组织，并有明确的区分
- 标记计数有助于保持在 LLM 上下文限制内
默认弹性
MCP Docs 服务默认设计为具有高弹性。该服务可自动处理不完整或结构不良的文档，并且不会出现以下情况：
- 即使存在问题，也返回最低 80 的健康评分
- 自动创建缺失的文档目录
- 优雅地处理丢失的文档目录
- 即使文件有错误，仍继续处理
- 对元数据完整性和断开的链接提供宽松的评分
这使得该服务特别适用于：
- 文档极少的遗留项目
- 处于文档开发早期阶段的项目
- 从其他格式迁移文档时
该服务将始终提供有用的反馈而不是失败，让您随着时间的推移逐步改进您的文档。
版本历史记录
v0.6.0
- 添加了 LLM 优化的合并文档功能（--single-doc 标志）
- 为每个文档部分添加了令牌计数
- 添加了合并文档输出定制（--output 标志）
- 添加了最大令牌限制配置（--max-tokens 标志）
v0.5.2
- 通过自动创建缺失的文档目录来增强弹性
- 改进的耐受模式，最低健康评分为 80
- 将容忍模式设为健康检查的默认模式
- 更新了健康检查工具描述，提及容忍模式
v0.5.1
- 为健康检查添加了容忍模式
- 修复了测试套件可靠性问题
- 改进了文档操作中的错误处理
文档
欲了解更多详细信息，请查看我们的文档：
执照
麻省理工学院