docs-mcp-server(pure-admin-docs)

MCP 文档服务器，从 GitHub 仓库同步 Markdown 文档并为 AI Agent 提供搜索、阅读等服务。

功能

• sync_documents - 从 GitHub 克隆/更新文档仓库
• list_documents - 列出所有文档（支持目录过滤）
• read_document - 读取指定文档完整内容
• search_documents - 全文搜索（支持中文分词）
• semantic_search - 语义搜索（需配置 DASHSCOPE_API_KEY 或 EMBEDDING_PROVIDER=local）
• get_document_outline - 获取文档标题大纲
• get_table_of_contents - 获取完整目录树

快速开始

cd docs-mcp-server
bun install
bun run start

环境变量配置

支持两种方式：

1. .env 文件（推荐）：在 docs-mcp-server/ 目录下创建 .env，复制 .env.example 并修改：

cp .env.example .env
# 编辑 .env，填入 DASHSCOPE_API_KEY 等

2. Cursor MCP 配置：在 .cursor/mcp.json 的 env 中直接设置：

{
  "mcpServers": {
    "docs-server": {
      "command": "bun",
      "args": ["./docs-mcp-server/src/index.ts"],
      "env": {
        "DOCS_REPO_URL": "https://github.com/pure-admin/pure-admin-doc",
        "DOCS_BRANCH": "master",
        "EMBEDDING_PROVIDER": "dashscope",
        "DASHSCOPE_API_KEY": "sk-xxx"
      }
    }
  }
}

Cursor 集成

在 .cursor/mcp.json 中配置：

{
  "mcpServers": {
    "docs-server": {
      "command": "bun",
      "args": ["./docs-mcp-server/src/index.ts"],
      "env": {
        "DOCS_REPO_URL": "https://github.com/pure-admin/pure-admin-doc",
        "DOCS_BRANCH": "master"
      }
    }
  }
}

环境变量

变量	说明	默认值
DOCS_REPO_URL	GitHub 文档仓库地址	https://github.com/pure-admin/pure-admin-doc
DOCS_BRANCH	分支名	master
EMBEDDING_PROVIDER	语义搜索后端：dashscope 或 local	dashscope
DASHSCOPE_API_KEY	阿里云 DashScope API 密钥（dashscope 时必填）	-
EMBEDDING_BASE_URL	自定义 API 端点	DashScope 默认
EMBEDDING_MODEL	Embedding 模型名	text-embedding-v3

本地语义搜索（EMBEDDING_PROVIDER=local）

使用 @xenova/transformers 加载 bge-small-zh-v1.5，无需 API Key：

# 安装到项目（optionalDependencies）
bun add @xenova/transformers

# 设置环境变量
EMBEDDING_PROVIDER=local bun run start

或在 .env 中设置 EMBEDDING_PROVIDER=local。首次运行会下载约 95MB 模型到缓存。

技术栈

• Bun - 运行时（直接运行 TS，零编译）
• @modelcontextprotocol/sdk - MCP TypeScript SDK
• simple-git - Git 操作
• minisearch - 全文搜索引擎
• gray-matter - Frontmatter 解析
• fast-glob - 文件扫描
• openai - DashScope API 兼容