# dev-doc-mcp

**Repository Path**: itfitness/dev-doc-mcp

## Basic Information

- **Project Name**: dev-doc-mcp
- **Description**: RAG文档查询mcp
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 开发文档 RAG 智能体（LangChain + MCP）

把 `docs/` 目录下的开发文档（Markdown/Txt）建成本地向量库，封装为 MCP Server，
供 Claude Code、ZCode、Cursor 等支持 MCP 的 AI 工具直接查询。

## 架构

- **LLM**：任意 OpenAI 兼容接口（DeepSeek、Kimi、硅基流动等），环境变量可换
- **Embedding**：本地 Ollama（默认 `qwen3-embedding:0.6b`），文档数据不出本机
- **向量库**：Chroma 本地持久化（`chroma_db/`）
- **索引策略**：全量重建--每次索引先清空旧库再重建，永不产生重复数据，
  文档修改/删除自动同步
- **框架**：LangChain 1.x（`create_agent`）+ fastmcp（stdio 传输）

## 环境要求

- Python 3.9+（当前使用 conda 环境 `langchaintest`，Python 3.12.11）
- Ollama 桌面端运行中，并已拉取 embedding 模型：

  ```bash
  ollama pull qwen3-embedding:0.6b
  ```

- 依赖安装（含约束文件，见下方说明）：

  ```bash
  pip install -r requirements.txt -c constraints.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
  ```

> **constraints.txt 说明**：Intel Mac 上 cryptography 46+ 无预编译 wheel
> （源码编译需 Rust 且会失败），约束文件将其钉在 45.0.7。Apple Silicon 可忽略。

## 配置

LLM 与 Embedding 支持两种配置方式，优先级：**命令行参数 > .env > 默认值**。

**方式一：命令行参数（推荐，配置随 MCP 注册命令，无需配置文件）**

注册 MCP 时直接传参（详见下方"注册到 AI 工具"），完整参数如下，
随时可执行 `python server.py --help` 查看：

| 参数 | 说明 | 默认值 |
|---|---|---|
| `--llm-base-url` | OpenAI 兼容接口地址，如 `https://api.deepseek.com/v1` | 无（不配置则 `ask_docs` 不可用） |
| `--llm-api-key` | LLM API Key | 无 |
| `--llm-model` | LLM 模型名，如 `deepseek-chat` | 无 |
| `--ollama-base-url` | Ollama 服务地址 | `http://localhost:11434` |
| `--embedding-model` | Ollama embedding 模型名 | `qwen3-embedding:0.6b` |
| `--docs-dir` | 开发文档目录（可指向项目外的任意文件夹） | 项目内 `docs/` |
| `--chroma-dir` | 向量库持久化目录 | 项目内 `chroma_db/` |

> 路径参数支持绝对或相对路径：绝对路径原样生效，相对路径基于项目根目录解析。

> 安全提示：Key 只会保存在 AI 工具的本地 MCP 配置中，与 `.env` 方式同等安全；
> 不要把 Key 做成对话中传递的参数，避免留在聊天记录里。

**方式二：.env 文件**

复制 `.env.example` 为 `.env`，填写 LLM 三项（不填则 `ask_docs` 不可用，
`search_docs` 检索不受影响）：

```
LLM_BASE_URL=https://api.deepseek.com/v1   # 任意 OpenAI 兼容厂商
LLM_API_KEY=sk-xxx
LLM_MODEL=deepseek-chat
```

## 使用

1. 把开发文档（.md / .txt）放入 `docs/`
2. 建立索引（二选一）：

   ```bash
   python -m rag.ingest
   ```

   或注册 MCP 后在对话中说"重新索引文档"
3. 注册到 AI 工具（一次性，配置直接写在命令里）：

   ```bash
   # Claude Code（LLM 三项按需填写，不填 ask_docs 时才需要补）
   claude mcp add dev-docs -- ~/miniconda3/envs/langchaintest/bin/python server.py \
       --llm-base-url https://api.deepseek.com/v1 \
       --llm-api-key sk-xxx \
       --llm-model deepseek-chat

   # 也可以走 .env：claude mcp add dev-docs --env-file .env -- python server.py
   # ZCode：完整配置见下方"ZCode 工作区配置"章节（已配置在本项目 .zcode/config.json）
   # Cursor：在各自 MCP 配置中添加等价的 stdio 命令与参数
   ```

## ZCode 工作区配置

本项目已在 `.zcode/config.json` 中注册 `dev-docs` 服务器，ZCode 打开本项目时会话自动连接。
完整配置如下（API Key 已打码，实际值在本地配置文件中）：

```json
{
  "mcp": {
    "servers": {
      "dev-docs": {
        "type": "stdio",
        "command": "/Users/a1/miniconda3/envs/langchaintest/bin/python",
        "args": [
          "/Users/a1/Desktop/PythonProject/Study01/server.py",
          "--docs-dir", "/Users/a1/Desktop/mcptemp/docs-dir",
          "--chroma-dir", "/Users/a1/Desktop/mcptemp/chroma-dir",
          "--llm-base-url", "https://ark.cn-beijing.volces.com/api/coding/v3",
          "--llm-api-key", "ark-****（实际值见本地 .zcode/config.json）",
          "--llm-model", "glm-5.3"
        ],
        "timeoutMs": 300000
      }
    }
  }
}
```

字段说明：

- **所有运行配置都通过 `args` 传递**（文档目录、向量库目录、LLM 三项），
  不使用 `env` 字段--ZCode 桌面端曾因空名称的 env 条目同步校验失败，
  导致服务器加载不出来（表现为调用时报 Connection closed）
- **`timeoutMs: 300000`**：默认 30 秒对 RAG 问答偏短（实测 `ask_docs` 约 16 秒），
  5 分钟可覆盖慢速索引与长回答
- 修改配置后需**重启 ZCode 应用**（仅新开会话可能沿用旧状态），并在
  **设置 -> MCP** 确认 `dev-docs` 显示已连接
- ⚠️ 该文件含 API Key 时不要提交到代码仓库（或仅提交打码版本）

4. 之后直接对话提问即可，例如："帮我查一下登录接口的限流规则"

## MCP 工具一览

| 工具 | 作用 | 前置条件 |
|---|---|---|
| `search_docs(query)` | 检索最相关文档片段+来源路径，不耗 LLM | 已建索引 |
| `ask_docs(question)` | RAG 问答，LLM 生成带来源引用的回答 | 已建索引 + 配置 LLM |
| `reindex_docs()` | 全量重建向量库（对话中说"重新索引"即可） | Ollama 运行中 |
| `clear_vector_store()` | 清空向量库释放空间 | 无 |

文档有增删改后，只需再次触发索引（对话或命令均可），旧内容会被彻底替换。

## 常见问题

- **提示向量库为空**：还没建过索引或刚清空，触发一次 `reindex_docs` 即可
- **索引失败 / model not found**：Ollama 未启动，或未拉取 embedding 模型
- **ask_docs 提示未配置 LLM**：注册命令里没传 `--llm-*` 参数，且 `.env` 中 LLM 三项没填全
- **重复索引会有重复数据吗**：不会，全量重建策略先清后建

## 项目结构

```
docs/             开发文档（.md/.txt）
rag/config.py     配置读取（命令行参数 > .env > 默认值）
rag/ingest.py     索引管线（python -m rag.ingest）
rag/agent.py      检索与 RAG 智能体
server.py         MCP Server（stdio，支持 --llm-* 等启动参数）
.env.example      配置模板（可省略，改用命令行参数）
requirements.txt  依赖清单（锁定版本）
constraints.txt   cryptography <46 约束（仅 Intel Mac 需要）
```