内容
# 文档-MCP
一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io) 服务器，公开 Actian 产品文档、GA4 内容分析以及 Jenkins CI 构建状态给 Claude — 在单个对话中实现跨这三个来源的自然语言查询。
```
Claude Desktop / Claude 代码
│
│ JSON-RPC 超过 stdio
▼
文档-MCP
│
├── 搜索文档 → Actian Markdown 文档库（TF-IDF，交换为 pgvector）
├── 获取主题 → 按 ID 获取完整主题内容
├── 列出主题 → 带有产品/类型过滤的文档库索引
├── 获取内容空白 → GA4 零结果搜索查询（模拟 → BigQuery）
└── 获取构建状态 → Jenkins 发布管道状态（模拟 → 实时 API）
```
## 功能
连接后，您可以询问 Claude：
> *"本月 Actian 文档站点上返回无结果的十大搜索查询是什么？"*
> *"在 Analytics Engine 8.0 文档库中找出所有提及 Tableau 连接器的主题，并检查发布管道当前是否为绿色。"*
> *"文档构建是否通过？如果失败，请在文档库中搜索 RPM 升级过程并向我显示相关步骤。"*
---
## 快速开始
### 1. 克隆和安装
```bash
git clone https://github.com/Bipin-24/docs-mcp.git
cd docs-mcp
npm install
npm run build
```
### 2. 连接到 Claude Desktop
打开您的 Claude Desktop 配置文件：
| 操作系统 | 路径 |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
添加此块（用实际克隆位置替换路径）：
```json
{
"mcpServers": {
"actian-docs": {
"command": "node",
"args": ["/绝对路径/到/docs-mcp/dist/index.js"]
}
}
}
```
重启 Claude Desktop。您应该在工具列表中看到 `actian-docs`。
### 3. 连接到 Claude 代码
在项目根目录中放置一个 `.mcp.json` 文件：
```json
{
"mcpServers": {
"actian-docs": {
"command": "node",
"args": ["../docs-mcp/dist/index.js"]
}
}
}
```
---
## 工具
### `搜索文档`
跨文档库的语义搜索。
```
输入：
查询 字符串 必需 自然语言搜索查询
产品 字符串 可选 analytics-engine | ingres | actian-client | all
版本 字符串 可选 例如 "8.0", "11.x"
限制 数字 可选 1–10，默认 5
输出：带有摘录和相关性评分的匹配主题的排名列表
```
**示例提示：** *"如何使用 RPM 包升级 Analytics Engine？"*
---
### `获取主题`
按 ID 检索主题的完整 Markdown 内容。
```
输入：
主题 ID 字符串 必需 来自 search_docs 结果的主题 ID
输出：带有元数据的完整主题内容
```
---
### `列出主题`
浏览文档库索引。
```
输入：
产品 字符串 可选 analytics-engine | ingres | actian-client | all
主题类型 字符串 可选 概念 | 任务 | 参考 | 故障排除 | all
输出：按产品分组的主题
```
---
### `获取内容空白`
显示返回零或极少结果的搜索查询 — 即用户需要但尚不存在的文档。
```
输入：
天数 数字 可选 回顾窗口，默认 30
限制 数字 可选 最大空白返回，默认 20
最小搜索量 数字 可选 最小搜索量，默认 2
输出：带有空白类型、搜索量和最近现有主题的排名空白列表
```
**示例提示：** *"根据过去 30 天的搜索数据，什么是主要的缺失文档主题？"*
---
### `获取构建状态`
返回文档发布作业的当前 Jenkins CI 管道状态。
```
输入：
作业 字符串 可选 Jenkins 作业名称，默认 "actian-docs-publish"
输出：最新的构建结果、阶段分解和近期历史
```
---
## 架构
### 搜索
服务器配备了一个轻量级的 TF-IDF 关键词搜索引擎（`src/lib/search.ts`），无需外部依赖或 API 密钥。它使用标题和标签匹配奖励的词频来评分文档。
要升级到基于嵌入的语义搜索：
1. 在 `package.json` 中添加 `chromadb`
2. 运行 `npm run index` 使用 Python 索引器（`scripts/index_corpus.py`）嵌入文档库
3. 在 `src/lib/search.ts` 中将 `scoreTopics()` 替换为 Chroma 相似性查询
### 实时数据
服务器配备了 GA4 分析和 Jenkins 的模拟数据。要切换到实时源，请在 `.env` 中添加凭据：
```bash
cp .env.example .env
# 使用您的 BigQuery 项目 ID 和 Jenkins 令牌编辑 .env
```
有关所有可用的配置选项，请参见 `.env.example`。
GA4 站点搜索导出的 BigQuery 查询在 `scripts/ga4_export.sql` 中。
---
## 项目结构
```
docs-mcp/
├── src/
│ ├── index.ts # MCP 服务器 — 工具注册和路由
│ ├── tools/
│ │ ├── searchDocs.ts # search_docs 处理程序
│ │ ├── getTopic.ts # get_topic 处理程序
│ │ ├── listTopics.ts # list_topics 处理程序
│ │ ├── getContentGaps.ts # get_content_gaps 处理程序
│ │ └── getBuildStatus.ts # get_build_status 处理程序
│ ├── data/
│ │ ├── corpus.ts # 示例 Actian 文档主题
│ │ ├── analyticsData.ts # 模拟 GA4 站点搜索数据
│ │ └── jenkinsData.ts # 模拟 Jenkins 构建历史
│ └── lib/
│ └── search.ts # TF-IDF 搜索引擎
├── scripts/
│ └── ga4_export.sql # BigQuery 查询用于真实 GA4 导出
├── config/
│ ├── claude_desktop_config.json # Claude Desktop 设置
│ └── mcp.json # Claude 代码项目设置
├── .env.example
└── tsconfig.json
```
---
## 技术栈
- **运行时：** Node.js 18+ / TypeScript
- **MCP SDK：** `@modelcontextprotocol/sdk`
- **搜索：** TF-IDF（内置）→ 可升级到 pgvector / Chroma
- **分析：** 模拟 GA4 数据 → 可升级到 BigQuery
- **CI 状态：** 模拟 Jenkins 数据 → 可升级到实时 Jenkins REST API
---
## 相关项目
- [`doc-rag-chatbot`](https://github.com/Bipin-24/doc-rag-chatbot) — RAG 管道和文档库上的聊天 UI
- [`doc-content-gap-finder`](https://github.com/Bipin-24/doc-content-gap-finder) — 从搜索查询数据中查找未记录主题的 CLI 工具
- [IA Playbook](https://information-architecture-playbook.vercel.app) — AI 可读文档的参考架构
---
## 作者
**Bipin Pandey** — 首席信息架构师
[LinkedIn](https://www.linkedin.com/in/bipinpandey24/) · [作品集](https://bipin-24.github.io)
