# kimi-search-mcp

把 Kimi Code 的 web search / fetch 能力包装成标准 MCP Server（stdio），
供 Hermes 等任意 agent 在需要搜索时自动调用。无命令行、无交互，
只有 `kimi_web_search` 和 `kimi_web_fetch` 两个工具。

核心调用逻辑参考 [Tsukumi233/astrbot_plugin_kimi_web_search](https://github.com/Tsukumi233/astrbot_plugin_kimi_web_search)，
去掉了 AstrBot 依赖和 `/kimi`、`/kimifetch` 命令层。

## 安装

需要 Python 3.10+，推荐用 [uv](https://docs.astral.sh/uv/)：

```bash
git clone <this-repo> && cd kimi-search-mcp
uv venv .venv && uv pip install -p .venv/bin/python -r requirements.txt
# Windows: uv pip install -p .venv/Scripts/python.exe -r requirements.txt
```

不用 uv 的话，普通 venv + pip 也可以。

## Agent 配置（MCP stdio）

```json
{
  "mcpServers": {
    "kimi-search": {
      "command": "/path/to/kimi-search-mcp/.venv/bin/python",
      "args": ["/path/to/kimi-search-mcp/kimi_search_mcp.py"],
      "env": {
        "KIMI_API_KEY": "sk-..."
      }
    }
  }
}
```

`KIMI_API_KEY` 必须是 Kimi Code Console 里创建的 API Key（Kimi 会员权益），
不是 platform.moonshot.cn 的开放平台 key。

## 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `KIMI_API_KEY` | （必填） | Kimi Code API Key |
| `KIMI_DEFAULT_LIMIT` | `8` | 默认返回结果数（1-20） |
| `KIMI_INCLUDE_CONTENT` | `false` | 搜索时是否默认抓取页面正文 |
| `KIMI_MAX_CONTENT_CHARS` | `4000` | 单条正文截断长度 |
| `KIMI_TIMEOUT` | `60` | 请求超时（秒） |
| `KIMI_SEARCH_URL` / `KIMI_FETCH_URL` | 官方地址 | 端点覆盖，一般不用动 |
| `KIMI_CLI_IDENTITY` | `false` | 见下文「合规风险」 |
| `KIMI_USER_AGENT` | 自动 | 自定义 User-Agent |

## 费用

`api.kimi.com/coding/v1/search` 不是独立计费 API：它走 Kimi 会员的
Kimi Code 额度（订阅制，CLI / VS Code / 第三方工具共享同一额度池，
7 天滚动刷新），**没有单独的按次搜索费用**。已有会员（Andante ¥49/月起）
搜索就是额度内的既有权益；超额后可开 Extra Usage（按量付费兜底）。

对比：开放平台（platform.moonshot.cn）的内置 web_search 工具按次收费，
本方案不走那条路。

## 合规风险（重要）

Kimi Code 官方文档明确写道：篡改客户端标识（User-Agent）属于违规，
可能导致会员权益被暂停。本 server 默认以真实身份 `kimi-search-mcp/0.1.0`
请求。如果服务端校验官方 CLI 身份导致 401/403，可以设
`KIMI_CLI_IDENTITY=1` 复刻官方 CLI 的 `KimiCLI/1.30.0` UA 和 `X-Msh-*`
请求头（即原插件的做法）——能用，但属于账号持有者自行承担的风险。

## 测试

已验证（mcp 2.x / Python 3.14）：stdio 握手、`tools/list`、参数校验、
无 key / 错误 key 的报错透传均正常。本仓库附带 `smoke_test.py`：

```bash
# 在仓库根目录、venv 已装依赖后：
.venv/bin/python smoke_test.py .venv/bin/python kimi_search_mcp.py
# 预期输出：TOOLS: ['kimi_web_search', 'kimi_web_fetch'] 及两条中文报错
```

也可以用 MCP Inspector 交互调试：

```bash
npx @modelcontextprotocol/inspector .venv/bin/python kimi_search_mcp.py
```

最后给 agent 配好后让它「搜索一下今天的 AI 新闻」，
观察是否自动触发 `kimi_web_search`。

## 实现说明

- 基于 MCP Python SDK v2（`mcp.server.mcpserver.MCPServer`），要求 `mcp>=2.0`；
  v1 的 `Server` + `@list_tools` 装饰器 API 已移除，请勿降级安装。
- 工具内抛 `ToolError`，错误消息会原文透传给调用方 LLM，便于自我纠错。