# 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** - 获取完整目录树

## 快速开始

```bash
cd docs-mcp-server
bun install
bun run start
```

## 环境变量配置

支持两种方式：

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

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

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

```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",
        "EMBEDDING_PROVIDER": "dashscope",
        "DASHSCOPE_API_KEY": "sk-xxx"
      }
    }
  }
}
```

## Cursor 集成

在 `.cursor/mcp.json` 中配置：

```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：

```bash
# 安装到项目（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 兼容