# feature-mcp-server: Agent Retrieval Streamable HTTP MCP Server

## 文档信息

| 项目 | 内容 |
|------|------|
| **需求编号** | feature-mcp-server |
| **基线版本** | feature-806350 (KnSearch 模块) |
| **文档版本** | v1.0 |
| **创建日期** | 2026-02-01 |

---

## 1. 背景与目标

### 1.1 业务背景

Agent Retrieval 服务提供 KnSearch、KnRetrieval、Action Recall 等能力，当前通过 REST API 对外暴露。随着 MCP（Model Context Protocol）生态发展，需要让 MCP 客户端（如 Cursor、Claude Desktop）能够直接连接 Agent Retrieval，以 MCP 工具形式调用知识网络检索能力。

### 1.2 需求来源

- **产品需求**：支持 MCP 客户端（Cursor、Claude Desktop 等）直接接入 Agent Retrieval 的知识网络能力
- **技术需求**：复用现有 Gin 框架与认证中间件，在 ToolHandler 中获取 token 信息和 kn_id

---

## 2. 工具清单

### 2.1 规划工具（全部封装为 MCP Tool）

将以下 REST 接口全部封装为 MCP 工具，供 MCP 客户端（Cursor、Claude Desktop 等）调用：

| 工具名称 | 描述 | 对应 REST 接口 | 状态 |
|---------|------|----------------|------|
| kn_schema_search | 语义检索概念（Schema），返回与 query 相关的对象类/关系类/行动类 | POST /kn/semantic-search | 规划 |
| kn_search | 知识网络智能检索（v2），支持概念召回与语义实例召回 | POST /kn/kn_search | 规划 |
| query_object_instance | 单对象类实例过滤查询，按条件查询实例列表 | POST /kn/query_object_instance | 规划 |
| query_instance_subgraph | 沿关系路径拉取实例子图，支持多跳查询 | POST /kn/query_instance_subgraph | 规划 |
| resolve_logic_properties | 逻辑属性解析，针对实例批量计算指标/算子 | POST /kn/logic-property-resolver | 规划 |
| get_action_info | 行动信息召回，针对对象实例返回可执行行动（Function Call 定义） | POST /kn/get_action_info | 规划 |

### 2.2 工具依赖与调用链

- **探索发现**：`kn_schema_search` / `kn_search` → 获取概念（ot_id、rt_id、at_id 等）
- **精确查询**：`query_object_instance` / `query_instance_subgraph` → 获取实例与事实
- **逻辑属性**：`resolve_logic_properties` → 依赖 Schema + 实例结果
- **行动召回**：`get_action_info` → 依赖 Schema（at_id）+ 实例（unique_identity）

详细工具使用规则见 [工具使用指南](../../releases/v5.0.4/tool-usage-guide.md)。

### 2.3 kn_search 工具说明（示例）

- **功能**：根据用户 query 和知识网络 ID（kn_id），召回相关概念（object_types、relation_types、action_types）及语义实例（nodes）
- **必填参数**：
  - `query`：用户查询问题或关键词（通过 MCP 工具 arguments 传递）
  - `kn_id`：知识网络 ID（**通过 HTTP Header `X-Kn-ID` 传递**，见下文设计）
- **可选参数**：only_schema、enable_rerank（本期仅支持，后续可扩展）

---

## 3. kn_id 通过 Header 传递的设计

### 3.1 设计决策

**kn_id 必须通过 MCP 客户端的 HTTP Header `X-Kn-ID` 配置传入**，不作为 MCP 工具 arguments 的必填参数。

### 3.2 设计理由

| 考量 | 说明 |
|------|------|
| **用户使用习惯** | kn_id 是知识网络标识，用户通常在**连接 MCP Server 时**选定一个知识网络，属于连接级配置 |
| **减少 LLM 负担** | 若放在 arguments 中，LLM 每次调用都需生成 kn_id，增加 token 消耗且易出错 |
| **一次性配置** | 放在 Header 中，用户可在 Cursor/Claude Desktop 配置文件中一次性设置，无需每次对话指定 |
| **多知识网络场景** | 若用户需切换知识网络，可配置多个 MCP Server 连接（每个连接对应不同 X-Kn-ID），或通过 arguments 覆盖（见下文） |

### 3.3 获取优先级

ToolHandler 中 kn_id 的获取逻辑：

1. **优先**：`req.Header.Get("X-Kn-ID")`（MCP 客户端在连接时配置的 Header）
2. **兜底**：`req.GetString("kn_id", "")`（工具 arguments 中的 kn_id，用于单次调用覆盖）
3. **校验**：若两者均为空，返回错误 `kn_id is required (configure X-Kn-ID header or pass kn_id in arguments)`

### 3.4 Header 规范

| Header 名称 | 必填 | 说明 |
|-------------|------|------|
| X-Kn-ID | kn_search 调用时必填 | 知识网络 ID，由用户在 MCP 客户端配置中设置 |
| Authorization | 是 | Bearer token，用于认证（middlewareIntrospectVerify） |

### 3.5 MCP 客户端如何传递 Header

MCP 客户端（如 Cursor、Claude Desktop）通过 **mcp-remote** 等适配器连接 Streamable HTTP MCP Server 时，可使用 `--header` 参数传递自定义 Header：

```bash
npx mcp-remote https://agent-retrieval.example.com/api/agent-retrieval/v1/mcp \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "X-Kn-ID: your_kn_id_here"
```

用户需在配置文件中将 `YOUR_TOKEN` 和 `your_kn_id_here` 替换为实际值。

---

## 4. 功能性需求

### 4.1 需求清单

| 需求ID | 需求名称 | 优先级 | 描述 |
|--------|---------|--------|------|
| FR-001 | MCP Server | P0 | 提供 MCP Server，供 Cursor、Claude Desktop 等 MCP 客户端连接 |
| FR-002 | 工具封装 | P0 | 将 6 个 REST 接口封装为 MCP 工具：kn_schema_search、kn_search、query_object_instance、query_instance_subgraph、resolve_logic_properties、get_action_info |
| FR-003 | 认证与 kn_id 配置 | P0 | 支持 Bearer token 认证；kn_id 可在连接时通过 Header X-Kn-ID 配置，无需每次调用传递 |

### 4.2 需求详细说明

#### FR-003: 认证与 kn_id 配置（补充）

**描述**：MCP 客户端在连接时通过 HTTP Header 传递 `Authorization`（Bearer token）和 `X-Kn-ID`（知识网络 ID）。ToolHandler 可获取认证信息与 kn_id。

**验收标准**：
- ✅ ToolHandler 能正确读取 X-Kn-ID
- ✅ 若 Header 和 arguments 均无 kn_id，返回明确错误
- ✅ arguments 中的 kn_id 可覆盖 Header 中的值（用于单次调用切换知识网络）

---

## 5. 用户配置与使用示例

### 5.1 MCP Server 暴露方式

Agent Retrieval 部署后，MCP Server 端点格式为：

```
https://{host}:{port}/api/agent-retrieval/v1/mcp
```

- `{host}`：agent-retrieval 服务地址（如 `agent-retrieval.example.com` 或内网地址）
- `{port}`：服务端口（如 `443` 或 `30779`）
- 路径：`/api/agent-retrieval/v1/mcp` 为 MCP Streamable HTTP 端点基础路径
- **认证**：使用 Bearer token（middlewareIntrospectVerify），与 Cursor/Claude Desktop 等外部 MCP 客户端兼容

### 5.2 前置条件

1. **认证 Token**：用户需具备有效的 Bearer token（通过 Hydra 内省验证）
2. **知识网络 ID**：用户需知道要检索的知识网络 ID（kn_id）
3. **mcp-remote**：Cursor、Claude Desktop 等客户端需通过 mcp-remote 适配器连接远程 Streamable HTTP MCP Server

### 5.3 Cursor 配置示例

**配置文件路径**：`~/.cursor/mcp.json`

**简化配置（直接配置 url + headers）**：

```json
{
  "mcpServers": {
    "context-loader": {
      "url": "http://{host}:{port}/api/agent-retrieval/v1/mcp",
      "headers": {
        "Authorization": "Bearer 替换为实际token",
        "X-Kn-ID": "替换为实际kn_id"
      }
    }
  }
}
```

**说明**：
- `context-loader`：MCP Server 在 Cursor 中的显示名称，可自定义
- 将 `替换为实际token` / `替换为实际kn_id` 替换为真实值

```json
{
  "mcpServers": {
    "agent-retrieval-kn-search": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://agent-retrieval.example.com/api/agent-retrieval/v1/mcp",
        "--header",
        "Authorization: Bearer 替换为实际token",
        "--header",
        "X-Kn-ID: 替换为实际kn_id"
      ]
    }
  }
}
```

**说明**：
- `agent-retrieval-kn-search`：MCP Server 在 Cursor 中的显示名称，可自定义
- 将 `替换为实际token` 替换为有效的 Bearer token
- 将 `替换为实际kn_id` 替换为要检索的知识网络 ID
- 若需使用环境变量（避免敏感信息写入配置文件），可参考 mcp-remote 文档配置 `env`

### 5.4 Claude Desktop 配置示例

**配置文件路径**：
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "agent-retrieval-kn-search": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://agent-retrieval.example.com/api/agent-retrieval/v1/mcp",
        "--header",
        "Authorization: Bearer YOUR_ACCESS_TOKEN",
        "--header",
        "X-Kn-ID: your_knowledge_network_id"
      ]
    }
  }
}
```

**说明**：与 Cursor 类似，将 `YOUR_ACCESS_TOKEN` 和 `your_knowledge_network_id` 替换为实际值。

### 5.5 使用示例

配置完成并重启 Cursor/Claude Desktop 后：

1. **连接成功**：客户端会显示 MCP Server 已连接（如锤子图标或 MCP 指示器）
2. **查看工具**：点击 MCP 指示器可看到 `kn_search` 工具
3. **调用示例**：用户可输入自然语言，由 AI 调用 kn_search 工具，例如：
   - *"帮我检索一下知识网络中与'糖尿病治疗方案'相关的内容"*
   - *"搜索知识网络中关于'患者'和'诊断'的概念"*
4. **工具参数**：AI 会传递 `query` 参数（用户问题或关键词），`kn_id` 已通过 Header 配置，无需在每次调用时指定

### 5.6 多知识网络配置

若用户需同时使用多个知识网络，可配置多个 MCP Server 连接：

```json
{
  "mcpServers": {
    "agent-retrieval-kn-001": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://agent-retrieval.example.com/api/agent-retrieval/v1/mcp",
        "--header",
        "Authorization: Bearer YOUR_TOKEN",
        "--header",
        "X-Kn-ID: kn_id_001"
      ]
    },
    "agent-retrieval-kn-002": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://agent-retrieval.example.com/api/agent-retrieval/v1/mcp",
        "--header",
        "Authorization: Bearer YOUR_TOKEN",
        "--header",
        "X-Kn-ID: kn_id_002"
      ]
    }
  }
}
```

用户在不同对话中可选择不同的 MCP Server，从而使用不同的知识网络。

### 5.7 注意事项

| 事项 | 说明 |
|------|------|
| Token 有效期 | Bearer token 过期后需更新配置并重启客户端 |
| kn_id 有效性 | 需确保 kn_id 对应用户有权限访问的知识网络 |
| 网络可达性 | 客户端需能访问 agent-retrieval 服务地址 |
| mcp-remote 版本 | 建议使用支持 `--header` 的 mcp-remote 版本 |

---

## 6. 非功能性需求

### 6.1 性能需求

| 指标 | 要求 | 说明 |
|------|------|------|
| 响应时间 | 与 REST 接口一致 | KnSearch 逻辑复用，无额外开销 |
| 并发 | 支持多 MCP 客户端并发连接 | 无状态设计 |

### 6.2 安全需求

| 需求 | 描述 |
|------|------|
| 认证 | 必须通过 middlewareIntrospectVerify 认证 |
| 参数校验 | kn_id（Header 或 arguments）、query 等必填参数需校验 |
| Header 透传 | 仅透传业务需要的 Header（X-Kn-ID、Authorization） |

### 6.3 可观测性需求

| 需求 | 描述 |
|------|------|
| 日志 | 关键步骤记录 Debug 日志，错误记录 Error 日志 |
| 追踪 | 错误日志包含 tool_name、kn_id、错误详情 |

### 6.4 兼容性需求

| 需求 | 描述 |
|------|------|
| 向后兼容 | 不影响现有 REST 接口和 MCP Proxy |
| mcp-go 版本 | v0.43.2（当前最新稳定版，含 Header、WithHTTPContextFunc） |

---

## 7. 接口规范

### 7.1 MCP 端点

| 端点 | 方法 | 说明 |
|------|------|------|
| /api/agent-retrieval/v1/mcp/initialize | POST | MCP 会话初始化 |
| /api/agent-retrieval/v1/mcp/tools/list | POST | 列出工具 |
| /api/agent-retrieval/v1/mcp/tools/call | POST | 调用工具 |
| /api/agent-retrieval/v1/mcp/* | POST | 其他 MCP 标准端点 |

### 7.2 请求头

| Header | 必填 | 说明 |
|--------|------|------|
| Authorization | 是 | Bearer token，用于 middlewareIntrospectVerify |
| X-Kn-ID | 调用 kn_search 时必填 | 知识网络 ID，由 MCP 客户端在连接时配置 |

### 7.3 kn_search 工具参数（arguments）

为先打通流程，本期仅支持以下参数，后续可扩展：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| query | string | 是 | 用户查询问题或关键词 |
| kn_id | string | 否 | 若 Header 已配置 X-Kn-ID，可省略；否则必填；若同时存在则 arguments 优先 |
| only_schema | boolean | 否 | 是否只召回概念，默认 false |
| enable_rerank | boolean | 否 | 是否启用 Rerank，默认 true |

---

## 8. 错误处理

| 错误场景 | HTTP 状态码 | 处理方式 |
|---------|-------------|----------|
| 未认证 | 401 | 中间件层拒绝 |
| kn_id 缺失 | 400 | 返回 `kn_id is required (configure X-Kn-ID header or pass kn_id in arguments)` |
| query 缺失 | 400 | 返回 `query is required` |
| 工具不存在 | 404 | MCP 标准错误 |
| KnSearch 执行失败 | 500 | 记录日志并返回错误 |

---

## 9. 术语表

| 术语 | 英文 | 说明 |
|------|------|------|
| MCP | Model Context Protocol | 模型上下文协议 |
| Streamable HTTP | - | mcp-go 的请求/响应式 HTTP 传输 |
| 内省 | Introspect | 通过 Hydra 验证 token 并获取用户信息 |
| kn_id | - | 知识网络 ID |
| mcp-remote | - | 连接远程 MCP Server 的适配器，支持 stdio 客户端连接 HTTP MCP Server |

---

## 10. 修订历史

| 版本 | 日期 | 修改人 | 修改内容 |
|------|------|--------|----------|
| v1.0 | 2026-02-01 | - | 初始版本，工具清单（kn_search）、kn_id Header 设计、用户配置与使用示例 |
eader 设计、用户配置与使用示例 |