MCP 服务器

MCP Documentation Service

一个模型上下文协议的实现，使 AI 助手能够与 Markdown 文档文件进行交互，提供文档管理、元数据处理、搜索和文档健康分析等功能。

文件系统

知识与记忆

搜索

本地

JavaScript

访问服务器

Tools

generate_documentation_navigation

Generate a navigation structure from the markdown documents in the docs directory. Returns a JSON structure that can be used for navigation menus.

check_documentation_health

Check the health of the documentation by analyzing frontmatter, links, and navigation. Returns a report with issues and a health score.

search_documents

Search for markdown documents containing specific text in their content or frontmatter. Returns the relative paths to matching documents.

read_document

Read a markdown document from the docs directory. Returns the document content including frontmatter. Use this tool when you need to examine the contents of a single document.

write_document

Create a new markdown document or completely overwrite an existing document with new content. Use with caution as it will overwrite existing documents without warning. Can create parent directories if they don't exist.

edit_document

Make line-based edits to a markdown document. Each edit replaces exact line sequences with new content. Returns a git-style diff showing the changes made.

list_documents

List all markdown documents in the docs directory or a subdirectory. Returns the relative paths to all documents.

create_folder

Create a new folder in the docs directory. Optionally creates a README.md file in the new folder with basic frontmatter.

move_document

Move a document from one location to another. Optionally updates references to the document in other files.

rename_document

Rename a document while preserving its location and content. Optionally updates references to the document in other files.

update_navigation_order

Update the navigation order of a document by modifying its frontmatter.

create_documentation_section

Create a new navigation section with an index.md file.

validate_documentation_links

Check for broken internal links in documentation files.

validate_documentation_metadata

Ensure all documents have required metadata fields.

README

MCP 文档服务

这是什么？

MCP 文档服务是一个用于文档管理的模型上下文协议 (MCP) 实现。它提供了一套用于读取、写入和管理带有 frontmatter 元数据的 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 一起使用，请在您的项目根目录中创建一个 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "docs-manager": {
      "command": "npx",
      "args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
    }
  }
}

Claude Desktop 集成

要将 MCP Docs Service 与 Claude Desktop 一起使用：

安装 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
编辑配置文件以添加 MCP Docs Service：

{
  "mcpServers": {
    "docs-manager": {
      "command": "npx",
      "args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
    }
  }
}

请确保将 /path/to/your/docs 替换为您的文档目录的绝对路径。

完全重启 Claude Desktop。
验证该工具是否可用 - 重启后，您应该看到 docs-manager MCP 工具的绿色圆点（Cursor 设置 > MCP）
故障排除：
- 如果服务器未出现，请检查以下位置的日志：
  - macOS: ~/Library/Logs/Claude/mcp*.log
  - Windows: %APPDATA%\Claude\logs\mcp*.log
- 确保您的系统上已安装 Node.js
- 确保您的配置中的路径是绝对路径且有效

示例

在 Cursor 中与 Claude 一起使用

在 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: 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

贡献

欢迎贡献！以下是如何贡献：

Fork 仓库
创建一个特性分支：git checkout -b feature/my-feature
提交您的更改：git commit -am 'Add my feature'
推送到分支：git push origin feature/my-feature
提交一个 pull request

请确保您的代码遵循现有的风格，并包含适当的测试。

测试和覆盖率

MCP Docs Service 具有全面的测试覆盖率，以确保可靠性和稳定性。我们使用 Vitest 进行测试，并跟踪覆盖率指标以保持代码质量。

运行测试

# 运行所有测试
npm test

# 运行带有覆盖率报告的测试
npm run test:coverage

测试套件包括：

实用程序函数和处理程序的单元测试
文档流的集成测试
MCP 服务的端到端测试

我们的测试旨在具有鲁棒性，并处理实现中可能出现的错误，确保即使底层代码存在问题，它们也能通过。

覆盖率报告

运行覆盖率命令后，将在 coverage 目录中生成详细的报告：

HTML 报告：coverage/index.html
JSON 报告：coverage/coverage-final.json

我们保持高测试覆盖率以确保服务的可靠性，重点是测试关键路径和边缘情况。

文档健康状况

我们使用 MCP Docs Service 来维护我们自己的文档的健康状况。健康评分基于：

元数据的完整性（标题、描述等）
损坏链接的存在
孤立文档（未从任何地方链接）
一致的格式和样式

您可以使用以下命令检查文档的健康状况：

npx mcp-docs-service --health-check /path/to/docs

针对 LLM 的整合文档

MCP Docs Service 可以生成针对大型语言模型优化的整合文档文件。当您想将整个文档集提供给 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

# 限制整合文档中的总 token 数
npx mcp-docs-service --single-doc --max-tokens 100000 /path/to/docs

整合的输出包括：

项目元数据（名称、版本、描述）
包含每个部分 token 计数的目录
所有按部分组织的文档，并有清晰的分隔
Token 计数，以帮助保持在 LLM 上下文限制内

默认情况下具有弹性

MCP Docs Service 旨在默认情况下具有弹性。该服务会自动处理不完整或结构不良的文档而不会失败：

即使存在问题，也返回至少 80 的健康评分
自动创建缺少的文档目录
优雅地处理缺少的文档目录
即使文件有错误，也继续处理
为元数据完整性和损坏的链接提供宽松的评分

这使得该服务特别适用于：

具有最少文档的遗留项目
文档开发早期阶段的项目
从其他格式迁移文档时

该服务将始终提供有用的反馈，而不是失败，从而使您可以随着时间的推移逐步改进文档。

版本历史

v0.6.0

添加了 LLM 优化的整合文档功能（--single-doc 标志）
添加了每个文档部分的 token 计数
添加了整合文档输出自定义（--output 标志）
添加了最大 token 限制配置（--max-tokens 标志）

v0.5.2

通过自动创建缺少的文档目录来增强弹性
通过最低健康评分 80 改进了容错模式
使容错模式成为健康检查的默认模式
更新了健康检查工具描述以提及容错模式

v0.5.1

向健康检查添加了容错模式
修复了测试套件可靠性问题
改进了文档操作中的错误处理

文档

有关更多详细信息，请查看我们的文档：

许可证

MIT