# ima-mcp-server

> **给你的自建智能体接上 IMA 的「大脑」**

将 [IMA 知识库](https://ima.qq.com) 的核心能力——**RAG 语义检索 + 知识图谱推理 + LLM 生成**——通过标准 MCP 协议暴露出来，让任何个人开发的 AI Agent 都能直接调用。

---

## 核心亮点：`ask_knowledge_base`

这是整个项目的灵魂工具。一句话：**把你的知识库变成一个可对话的专家。**

```
用户输入问题
    ↓
ask_knowledge_base 自动完成：
  ① 语义检索 → 在知识库中找到最相关的文档片段
  ② 知识图谱 → 关联实体、概念，补全上下文
  ③ LLM 生成 → 基于检索结果生成带引用的回答
  ④ 引用增强 → 自动下载前 3 条引用文件的完整内容
    ↓
返回：结构化答案 + 引用来源 + 文件内容
```

这本质上就是 IMA 产品内部的完整 RAG 管线，通过 MCP 协议直接接入到你自己的 Agent 中。你的自建智能体不再只是一个"聊天机器人"，而是真正拥有了一个能检索、能推理、能引用的知识后台。

### 适用场景

- 🤖 **个人知识助手**：把自己积累的文档/笔记/网页变成可问答的知识库
- 🏭 **企业内部知识库**：将 SOP、产品文档、技术规范接入 Agent，实现智能问答
- 📚 **学习与研究**：论文、教材、课程笔记导入后，随时提问和交叉检索
- 🔧 **开发者工具链**：API 文档、设计规范、代码仓库接入，让 Coding Agent 直接查阅

---

## 项目亮点一览

| 亮点 | 说明 |
|---|---|
| 🧠 **完整 RAG 管线** | 不是简单关键词搜索，而是语义检索 + 知识图谱 + LLM 生成的完整链路 |
| 🔌 **标准 MCP 协议** | 基于 stdio 传输，兼容 Claude Desktop、Cursor、Cline、WorkBuddy 等主流 Agent 平台 |
| 🔐 **双认证体系** | OpenAPI 凭证（基础读写）+ IMA Cookie（解锁完整 RAG），按需配置 |
| 📎 **引用自动增强** | ask_knowledge_base 返回引用后，自动下载前 3 条文件并解析内容（Excel→表格、文本→截取） |
| 🔄 **Token 自动刷新** | Cookie 过期时自动解析 refresh token 换取新 token，无需重启 |
| 📦 **零外部依赖** | 纯 Node.js 内置模块（crypto、https、fs），不依赖第三方 COS SDK |
| 📝 **10 个工具全覆盖** | 从问答、读取、笔记管理到网页导入、文件上传，覆盖知识库全流程 |

---

## 入口文件

项目提供两个等效的入口文件：

| 文件 | 说明 |
|---|---|
| `server.js` | JavaScript 入口，`.js` 扩展名。**如果你的 MCP 客户端不支持 `.mjs`，用这个** |
| `server.mjs` | ES Module 入口，`.mjs` 扩展名。如果客户端支持 ESM，用这个 |

两个文件内容完全一致，任选其一即可。

---

## 运行方式：本地 stdio

本项目是一个**命令行 MCP 服务器**，通过 stdin/stdout 与 MCP 客户端通信。它不是网络服务——不需要启动端口、不需要远程访问，在你的 MCP 客户端配置中指定 `node server.js`（或 `node server.mjs`）即可。

```
你的 Agent 平台（如 Claude Desktop、Cursor）
    │
    │  启动子进程：node server.js
    │  通过 stdin 发送 JSON-RPC 请求
    │  通过 stdout 接收 JSON-RPC 响应
    ▼
┌─────────────────────────────────┐
│  ima-mcp-server (Node.js)       │
│  ├─ OpenAPI 认证 → ima.qq.com   │
│  └─ Cookie 认证 → ima.qq.com    │
└─────────────────────────────────┘
```

**优点**：无需公网 IP、无需部署服务器、凭证不出本地机器。

---

## 快速开始

### 1. 前置要求

- **Node.js ≥ 18**（内置 fetch，无需额外安装）
- IMA 账号（用 QQ/微信登录 https://ima.qq.com）

### 2. 安装

```bash
git clone https://github.com/qqpp13465/ima-mcp-server.git
cd ima-mcp-server
npm install
```

### 3. 获取凭证

项目需要两类凭证，按你使用的工具选择配置：

| 凭证 | 环境变量 | 适用工具 | 获取难度 |
|---|---|---|---|
| **OpenAPI** | `IMA_CLIENT_ID` + `IMA_API_KEY` | get_media_info、import_urls、upload_file 等 8 个读写工具 | 简单（网页一键获取） |
| **Cookie** | `IMA_COOKIE` | ask_knowledge_base、list_knowledge_bases_full（完整 RAG） | 中等（浏览器开发者工具） |

#### 获取 OpenAPI 凭证（必须）

1. 浏览器打开 https://ima.qq.com → 登录你的 QQ/微信账号
2. 访问 https://ima.qq.com/agent-interface
3. 点击「创建凭证」，复制 `Client ID` 和 `API Key`

#### 获取 IMA_COOKIE（如需 RAG 问答）

> 只有 `ask_knowledge_base` 和 `list_knowledge_bases_full` 需要 Cookie 认证。如果只需要文件读写，只配 OpenAPI 凭证就够了。

1. 浏览器打开 https://ima.qq.com ，登录你的 QQ/微信账号
2. 按 `F12` 打开开发者工具，切换到 **Network（网络）** 标签
3. 在 IMA 页面中点击任意知识库，进行一次提问
4. 在 Network 中找到发往 `/cgi-bin/assistant/qa` 的请求，点击查看详情
5. 在 **Request Headers** 中找到 `x-ima-cookie` 字段，复制完整值
6. 将复制的内容作为 `IMA_COOKIE` 环境变量

> ⚠️ **Cookie 会过期**。如果某次调用返回 600001 错误（登录过期），项目会自动尝试用 refresh token 续期。如果自动续期也失败，需重新按上述步骤获取 Cookie。

### 4. 配置 MCP 客户端

以 Claude Desktop 为例，编辑 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "ima": {
      "command": "node",
      "args": ["C:\\Users\\你的用户名\\ima-mcp-server\\server.js"],
      "env": {
        "IMA_CLIENT_ID": "你的_client_id",
        "IMA_API_KEY": "你的_api_key",
        "IMA_COOKIE": "你的_x-ima-cookie值"
      }
    }
  }
}
```

> **注意**：Windows 路径用 `\\`（JSON 转义），macOS/Linux 用 `/`。

> **`.js` vs `.mjs`**：如果你的 MCP 客户端不支持 `.mjs` 扩展名（部分国产 Agent 平台有此限制），只需将 `server.js` 换成 `server.mjs` 即可，内容完全一致。

### 5. 验证

重启 MCP 客户端后，对 Agent 说：
> "列出我的所有知识库"

返回知识库列表即配置成功。

---

## 可用工具

| 工具 | 认证 | 功能 |
|---|---|---|
| ⭐ `ask_knowledge_base` | Cookie | **核心工具**：知识库 RAG 问答（语义检索 + LLM 生成），返回答案 + 引用文件，自动下载前 3 条引用内容 |
| `list_knowledge_bases_full` | Cookie | 列出所有知识库，返回 Cookie ID + OpenAPI ID，供后续工具调用 |
| `get_media_info` | OpenAPI | 获取条目原文/下载链接；笔记类自动返回正文 |
| `get_note_content` | OpenAPI | 读取笔记正文（纯文本） |
| `get_addable_knowledge_base_list` | OpenAPI | 获取可添加内容的知识库列表 |
| `import_urls` | OpenAPI | 将网页/微信文章添加到知识库 |
| `create_note` | OpenAPI | 创建 IMA 笔记（支持 Markdown） |
| `add_note_to_knowledge_base` | OpenAPI | 将笔记添加到知识库 |
| `check_repeated_names` | OpenAPI | 检查知识库中是否已存在同名文件 |
| `upload_file` | OpenAPI | 上传本地文件到知识库 |

> 📌 **关于已删除的工具**：本项目移除了 IMA 官方 OpenAPI 中的 `search_knowledge_base`、`get_knowledge_base`、`get_knowledge_list` 三个读取工具，因为它们的功能已被 `ask_knowledge_base`（RAG 语义检索 + 知识图谱 + LLM 生成）完全覆盖且体验更好。如果你仍需要原生的关键字搜索或列表分页功能，可参考 [IMA 官方 API 文档](https://ima.qq.com/agent-interface) 自行在 `server.js` 中添加。

---

## 所有 MCP 客户端配置参考

以下配置请将路径和凭证替换为实际值。

### Claude Desktop

配置文件：`%APPDATA%\Claude\claude_desktop_config.json` (Windows) / `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)

### Cursor

配置文件：`~/.cursor/mcp.json`（全局）或项目内 `.cursor/mcp.json`

### Cline (VS Code)

在 Cline 设置 → MCP Servers → 添加

### WorkBuddy

编辑 `~/.workbuddy/mcp.json`，在 `mcpServers` 中添加 `ima` 条目 → 连接器管理页面点击「Trust」

### 通用配置模板

```json
{
  "mcpServers": {
    "ima": {
      "command": "node",
      "args": ["/path/to/ima-mcp-server/server.js"],
      "env": {
        "IMA_CLIENT_ID": "你的_client_id",
        "IMA_API_KEY": "你的_api_key",
        "IMA_COOKIE": "你的_x-ima-cookie值（可选，用于 RAG 问答）"
      }
    }
  }
}
```

---

## 局限性

坦率列出当前版本的限制，帮助你判断是否适用：

| 限制 | 说明 |
|---|---|
| 🖥️ **仅本地 stdio 运行** | 不支持 HTTP/SSE 远程连接，必须和 MCP 客户端在同一台机器上。无法部署为云服务 |
| ⏱️ **Cookie 有时效** | IMA Cookie 会过期（通常几小时到一天），需定期重新获取。虽然有自动刷新机制但不保证 100% 成功 |
| 📋 **单知识库问答** | `ask_knowledge_base` 每次仅查询一个知识库，不支持跨知识库联合检索 |
| 🔢 **结果数量有限** | 单次 RAG 问答最多返回 IMA 服务端限制数量的结果，不适合超大规模全文检索 |
| 🚫 **无流式输出** | 当前返回完整回答，不支持 SSE 流式逐字输出（MCP 协议限制） |
| 📦 **仅支持 JavaScript** | 目前只有 Node.js 实现，无 Python/Go 版本 |

---

## 故障排查

| 问题 | 解决方案 |
|---|---|
| `未找到 IMA 凭证` | 检查环境变量是否正确设置；确认 MCP 客户端配置中 `env` 字段格式正确 |
| `IMA API 错误 [51]` | 通常是参数范围超出限制，检查传入的值是否在允许范围内 |
| `600001 登录过期` | Cookie 已失效。项目会自动尝试刷新，如失败需重新获取 IMA_COOKIE |
| `COS 上传 Access Denied` | 已修复（v4.2.1），确保使用最新版本 |
| MCP 客户端未显示工具 | 重启客户端；检查 JSON 格式、路径是否存在；确保 Node.js ≥ 18 |
| Windows 路径问题 | JSON 中 `\\` 表示一个 `\`，如 `C:\\Users\\name\\...` |

---

## 安全说明

- **凭证不出本地**：所有凭证仅通过 HTTP 头发送至 `ima.qq.com`，不发送到任何第三方
- **容器化你的凭证**：建议在 MCP 客户端配置中通过 `env` 传入凭证，不要在代码中硬编码
- **git 安全**：`.gitignore` 已配置忽略 `node_modules/`、日志文件和 IDE 配置，不会意外提交敏感信息

---

## License

MIT