MCP文档服务
这是怎么一回事？
MCP文档服务是用于文档管理的模型上下文协议（MCP）实现。它提供了一组用于读取、写入和管理带有frontmatter元数据的markdown文档的工具。该服务旨在与Cursor中的Claude或Claude Desktop等AI助手无缝协作，通过自然语言交互轻松管理您的文档。
特性
- 读写文档：使用frontmatter元数据轻松读写标记文档
- 编辑文档：使用差异预览对文档进行精确的基于行的编辑
- 列表和搜索：按内容或元数据查找文档
- 导航生成：从文档中创建导航结构
- 健康检查：分析文档质量，识别元数据缺失或链接中断等问题
- LLM优化文档：生成针对大型语言模型优化的合并单文档输出
- MCP集成：与模型上下文协议无缝集成
- 前线支援：在markdown文档中完全支持YAML frontmatter
- Markdown兼容性：适用于标准markdown文件
快速开始
安装
需要在您的计算机上安装Node。
npm install -g mcp-docs-service或者直接与npx一起使用：
npx mcp-docs-service /path/to/docs光标集成
要与游标一起使用，请创建 .cursor/mcp.json 项目根目录中的文件：
{
"mcpServers": {
"docs-manager": {
"command": "npx",
"args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
}
}
}Claude桌面集成
要在Claude Desktop上使用MCP文档服务：
- 安装克劳德桌面 -从下载最新版本 克劳德的网站.
- 为MCP配置克劳德桌面:
- 打开克劳德桌面 - 点击Claude菜单，选择“开发者设置” - 这将在以下位置创建一个配置文件： - macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json
- 编辑配置文件 添加MCP文档服务：
{
"mcpServers": {
"docs-manager": {
"command": "npx",
"args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
"env": {
"MCP_NPX_WRAPPER": true
}
}
}
}确保更换 /path/to/your/docs 文档目录的绝对路径。
- 重新启动克劳德桌面 完全。
- 验证工具是否可用 -重新启动后，您应该看到文档管理器MCP工具的绿点（光标设置>MCP）
- 故障排除:
- 如果服务器未出现，请检查以下位置的日志： - macOS： ~/Library/Logs/Claude/mcp*.log - 窗户： %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.- 使用工具选择器:
- 点击输入框右下角的锤子图标 - 从可用工具列表中选择“文档管理器” - 选择要使用的特定工具 - 填写所需参数，然后单击“运行”
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文档服务具有全面的测试覆盖范围，以确保可靠性和稳定性。我们使用Vitest来测试和跟踪覆盖率指标，以保持代码质量。
运行测试
# Run all tests
npm test
# Run tests with coverage report
npm run test:coverage测试套件包括：
- 实用函数和处理程序的单元测试
- 文档流集成测试
- MCP服务的端到端测试
我们的测试旨在保持健壮，并处理实现中的潜在错误，确保即使底层代码存在问题，它们也能通过。
覆盖范围报告
运行覆盖率命令后，将在 coverage 目录：
- HTML报告：
coverage/index.html - JSON报告：
coverage/coverage-final.json
我们保持高测试覆盖率，以确保服务的可靠性，重点是测试关键路径和边缘情况。
文档健康状况
我们使用MCP文档服务来维护我们自己文档的健康。健康评分基于：
- 元数据的完整性（标题、描述等）
- 存在断开的链接
- 孤立文档（未从任何地方链接）
- 格式和风格一致
您可以通过以下方式检查文档的运行状况：
npx mcp-docs-service --health-check /path/to/docsLLM的综合文档
MCP文档服务可以生成针对大型语言模型优化的合并文档文件。当您想将整个文档集提供给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文档服务默认情况下具有弹性。该服务会自动处理不完整或结构不良的文档，不会出现故障：
- 即使有问题，也会返回80的最低健康评分
- 自动创建缺少的文档目录
- 优雅地处理丢失的文档目录
- 即使文件有错误，也会继续处理
- 为元数据完整性和断开的链接提供宽松的评分
这使得该服务特别适用于：
- 文档最少的遗留项目
- 文档开发早期阶段的项目
- 从其他格式迁移文档时
该服务将始终提供有益的反馈，而不是失败，使您能够随着时间的推移逐步改进文档。
版本历史记录
v0.6.0
- 添加了LLM优化的合并文档功能（--单文档标志）
- 为每个文档部分添加了令牌计数
- 新增合并单据输出自定义（--输出标志）
- 添加了最大令牌限制配置（--max令牌标志）
v0.5.2
- 通过自动创建缺失的文档目录来增强弹性
- 改进的耐受模式，最低健康评分为80
- 将容差模式设置为健康检查的默认模式
- 更新了健康检查工具说明，以提及容差模式
v0.5.1
- 在健康检查中添加了容差模式
- 修复了测试套件可靠性问题
- 改进了文档操作中的错误处理
文档
有关更多详细信息，请查看我们的文档：
许可证
麻省理工学院