内容
# Kimi K3 MCP
一个小型、只读的 [模型上下文协议](https://modelcontextprotocol.io/) 服务器，通过 OpenRouter 为 Codex 和其他 MCP 客户端提供 Kimi K3 的第二意见。
它暴露了三个工具：
- `review_algorithm`：挑战正确性、不变性、边缘情况、反例和复杂性。
- `review_code`：查找具体的正确性、安全、可靠性和性能缺陷。
- `plan_project`：生成一个具有依赖关系、验证、风险和回滚的实施就绪计划。
服务器无法读取或修改本地文件。MCP 客户端选择要发送的代码和上下文。
提交的内容被视为不受信任的数据，Kimi 的私有推理被排除在工具结果之外。
响应包括令牌使用、成本、延迟、提供商和重试元数据。
这些工具是严格选择加入的。服务器指令告诉 MCP 客户端不要为常规审查或规划调用它们；
显式提及 Kimi、K3、Kimi MCP 或工具名称时才需要调用。
## 要求
- Python 3.11 或更新版本
- [uv](https://docs.astral.sh/uv/)
- 具有 `moonshotai/kimi-k3` 访问权限的 `OPENROUTER_API_KEY`
## 安装
```bash
git clone git@github.com:catid/k3mcp.git
cd k3mcp
uv sync --frozen
```
不要将 OpenRouter 密钥放入此仓库或 `config.toml` 中。在启动 Codex 的环境中导出它：
```bash
export OPENROUTER_API_KEY=sk-or-v1-...
```
## 配置 Codex
将服务器添加到 `~/.codex/config.toml` 中。调整克隆的绝对路径：
```toml
[mcp_servers.kimi_k3]
command = "/absolute/path/to/k3mcp/.venv/bin/k3mcp"
env_vars = ["OPENROUTER_API_KEY"]
enabled = true
required = false
startup_timeout_sec = 20
tool_timeout_sec = 15600
default_tools_approval_mode = "approve"
```
在更改 MCP 配置后重新启动 Codex。在 TUI 中，`/mcp` 显示服务器及其工具是否成功加载。
## 其他 MCP 客户端
服务器使用 stdio 传输：
```bash
OPENROUTER_API_KEY=... uv run k3mcp
```
进程将 MCP 协议消息写入 stdout。应用程序日志必须进入 stderr。
## 配置
| 变量 | 默认值 | 目的 |
|---|---|---|
| `OPENROUTER_API_KEY` | 需要 | OpenRouter 凭证 |
| `OPENROUTER_MODEL` | `moonshotai/kimi-k3` | 模型_slug |
| `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | API 根 |
| `K3MCP_MAX_TOKENS` | `256000` | 每次调用的最大完成令牌 |
| `K3MCP_MAX_INPUT_CHARS` | `400000` | 系统和用户提示的综合限制 |
| `K3MCP_TIMEOUT_SECONDS` | `7200` | 每次尝试的响应读取超时 |
| `K3MCP_TOTAL_TIMEOUT_SECONDS` | `15000` | 包括重试的总调用截止日期 |
| `K3MCP_MAX_ATTEMPTS` | `8` | 可重试故障的总尝试次数 |
| `K3MCP_REASONING_EFFORT` | `max` | OpenRouter 推理努力 |
| `OPENROUTER_APP_NAME` | `k3mcp` | OpenRouter 属性标题 |
| `OPENROUTER_SITE_URL` | 仓库 URL | OpenRouter 属性引用 |
Kimi K3 推理是 OpenRouter 上必需的。服务器请求最大努力并排除推理跟踪，同时在其使用元数据中保留令牌计数。
## 开发
```bash
uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pytest
```
测试使用模拟的 OpenRouter 传输和真正的 MCP stdio 握手；它们不会花费 API 积分。
重试测试涵盖网络故障、速率限制、每个 `5xx` 状态、格式错误或空的成功响应，以及 OpenRouter 偶尔的瞬时 `invalid model ID` 响应。
OpenRouter 可以在 HTTP `200` 响应内报告提供商故障；这些故障由其嵌入的状态分类，因此计费、身份验证、防护栏和令牌上限错误不会重试。
显式瞬时提供商响应和连接建立故障使用完整的重试预算。可能已经产生使用量的模糊故障最多重试一次，读取超时不会重试。
回退是有界的；`Retry-After` 支持高达五分钟的增量秒和 HTTP 日期，而较长的冷却时间会在不提前重试的情况下失败。
连接和池等待时间上限为 30 秒，请求写入上限为 60 秒，独立于高努力 K3 补全所需的更长的响应读取超时。
服务器的总调用截止日期故意比示例 MCP 客户端超时少 10 分钟，以便有时间返回结构化错误，而不是被客户端取消。
GitHub Actions 在 Python 3.11、3.12 和 3.13 上运行 linting、格式化、测试、stdio 协议握手和软件包构建。
工作流操作被固定到不可变的提交 SHA。
## 安全性和成本
- 工具调用将提供的代码和项目上下文发送到 OpenRouter 及其选定的提供商。
- 服务器是只读的，但调用了一个计量的外部 API (`openWorldHint=true`)。
- 256,000 个令牌的完成设置是一个上限，而不是预留，但长时间的推理调用仍可以消耗大量的计量的输出令牌。
- 输入和输出受到环境可配置限制的约束。
- 错误永远不包括请求头或 API 密钥。
- 模型输出是建议性的。在应用更改之前请验证发现和计划。
