项目介绍
MCP 文档服务
这是什么？
MCP 文档服务是一个用于文档管理的模型上下文协议（MCP）实现。它提供了一套工具，用于读取、写入和管理带有前言元数据的 Markdown 文档。该服务旨在与像 Claude 在 Cursor 或 Claude Desktop 中这样的AI助手无缝协作，使您能够通过自然语言交互轻松管理您的文档。
功能
- 读取和写入文档：轻松读取和写入带有前言元数据的 Markdown 文档
- 编辑文档：基于行进行精确编辑，并预览差异
- 列表和搜索：根据内容或元数据查找文档
- 导航生成：从您的文档创建导航结构
- 健康检查：分析文档质量并识别问题，如缺少元数据或断开的链接
- 针对大型语言模型优化的文档：生成适合大型语言模型的整合单文档输出
- MCP 集成：与模型上下文协议无缝集成
- 前言支持：完全支持 Markdown 文档中的 YAML 前言
- Markdown 兼容性：适用于标准 Markdown 文件
快速开始
安装
需要在您的机器上安装 Node。
npm install -g mcp-docs-service
或者直接使用 npx：
npx mcp-docs-service /path/to/docs
Cursor 集成
要与 Cursor 集成，在项目根目录中创建一个 .cursor/mcp.json 文件：
{
"mcpServers": {
"docs-manager": {
"command": "npx",
"args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
}
}
}
Claude Desktop 集成
要在 Claude Desktop 中使用 MCP 文档服务：
-
安装 Claude Desktop - 从 Claude 的网站 下载最新版本。
-
配置 Claude Desktop 以支持 MCP：
- 打开 Claude Desktop
- 点击 Claude 菜单并选择“开发者设置”
- 这将在以下位置创建配置文件：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
编辑配置文件 以添加 MCP 文档服务：
{
"mcpServers": {
"docs-manager": {
"command": "npx",
"args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
}
}
}
确保将 /path/to/your/docs 替换为您文档目录的绝对路径。
-
完全重启 Claude Desktop。
-
验证工具是否可用 - 重启后，您应该能在文档管理器 MCP 工具（Cursor 设置 > MCP）中看到绿色点。
-
故障排除：
- 如果服务器没有出现，请检查日志：
- macOS:
~/Library/Logs/Claude/mcp*.log - Windows:
%APPDATA%\Claude\logs\mcp*.log
- macOS:
- 确保系统已安装 Node.js
- 确保配置中的路径是绝对且有效的
- 如果服务器没有出现，请检查日志：
示例
使用 Claude 在 Cursor 中
当在 Cursor 中使用 Claude 时，您可以两种方式调用工具：
- 使用自然语言（推荐）：
- 直接用英语请求 Claude 执行任务：
你能帮我查找文档中与“入门”相关的内容吗？
请列出我文档目录下的所有 Markdown 文件。
你能检查一下我的文档是否有任何问题吗？
- 使用直接工具语法：
- 对于更精确的控制，可以使用直接工具语法：
@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 时，您可以两种方式调用工具：
- 使用自然语言（推荐）：
你能帮我读取 README.md 文件吗？
请找到所有提到“API”的文档。
我想让你检查我们的文档健康状况，并告诉我是否有任何问题。
- 使用工具选择器：
- 点击输入框右下角的锤子图标
- 从可用工具列表中选择“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: 新文档
description: 使用 MCP 文档服务创建的新文档
---
# 新文档
这是使用 MCP 文档服务创建的新文档。"
编辑文档
@docs-manager mcp_docs_manager_edit_document path=README.md edits=[{"oldText":"# 文档", "newText":"# 项目文档"}]
搜索文档
@docs-manager mcp_docs_manager_search_documents query="入门"
生成导航
@docs-manager mcp_docs_manager_generate_navigation
贡献
欢迎贡献！以下是您如何贡献的方法：
- 分叉仓库
- 创建功能分支：
git checkout -b feature/my-feature - 提交更改：
git commit -am '添加我的功能' - 推送到分支：
git push origin feature/my-feature - 提交拉取请求
请确保您的代码遵循现有风格，并包含适当的测试。
测试和覆盖率
MCP 文档服务具有全面的测试覆盖率，以确保可靠性和稳定性。我们使用 Vitest 进行测试，并跟踪覆盖率指标以维护代码质量。
运行测试
# 运行所有测试
npm test
# 运行带有覆盖率报告的测试
npm run test:coverage
测试套件包括：
- 实用函数和处理程序的单元测试
- 文档流程的集成测试
- MCP 服务的端到端测试
我们的测试设计得非常健壮，能够处理实现中的潜在错误，即使底层代码存在问题也能通过。
覆盖率报告
运行覆盖率命令后，详细的报告会在 coverage 目录中生成：
- HTML 报告：
coverage/index.html - JSON 报告：
coverage/coverage-final.json
我们保持高测试覆盖率，以确保服务的可靠性，重点关注关键路径和边缘情况的测试。
文档健康
我们使用 MCP 文档服务来维护我们自己的文档健康。健康分数基于：
- 元数据的完整性（标题、描述等）
- 断开链接的存在
- 孤立文档（未从任何地方链接）
- 格式和样式的统一
您可以使用以下命令检查文档的健康状况：
npx mcp-docs-service --health-check /path/to/docs
针对大型语言模型的整合文档
MCP 文档服务可以生成针对大型语言模型优化的整合文档文件。此功能在您希望将整个文档集提供给 LLM 作为上下文时非常有用：
# 生成默认文件名（consolidated-docs.md）的整合文档
npx mcp-docs-service --single-doc /path/to/docs
# 使用自定义输出文件名生成
npx mcp-docs-service --single-doc --output my-project-context.md /path/to/docs
# 限制整合文档中的总标记数
npx mcp-docs-service --single-doc --max-tokens 100000 /path/to/docs
整合输出包括：
- 项目元数据（名称、版本、描述）
- 各部分的标记计数的目录
- 按部分组织的所有文档，清晰分隔
- 标记计数帮助您保持在 LLM 上下文限制内
默认情况下具备韧性
MCP 文档服务默认设计为具备韧性。服务会自动处理不完整或结构不良的文档而不失败：
- 即使有问题也会返回最低健康分数 80
- 自动创建缺失的文档目录
- 优雅地处理缺失的文档目录
- 即使文件有错误也会继续处理
- 对元数据完整性和断开链接提供宽松评分
这使得服务特别适用于：
- 文档最少的遗留项目
- 文档开发初期阶段的项目
- 当从其他格式迁移文档时
服务始终提供有用的反馈而不是失败，允许您随着时间的推移逐步改进文档。
版本历史
v0.6.0
- 添加了针对大型语言模型优化的整合文档功能（--single-doc 标志）
- 添加了每个文档部分的标记计数
- 添加了整合文档输出的自定义（--output 标志）
- 添加了最大标记限制配置（--max-tokens 标志）
v0.5.2
- 通过自动创建缺失的文档目录增强了韧性
- 改进了容错模式，最低健康分数为 80
- 将容错模式设为健康检查的默认值
- 更新了健康检查工具描述，提及容错模式
v0.5.1
- 在健康检查中添加了容错模式
- 解决了测试套件可靠性的问题
- 改进了文档操作中的错误处理
文档
更多详细信息，请参阅我们的文档：
许可证
MIT