MCP 适配器

ctxctl mcp 是一个可选适配器，把同样五个命令作为 MCP 工具经 stdio 提供。CLI 始终是规范接口；适配器运行时，CLI 的行为没有任何改变。

工具

工具	包装的命令
`ctxctl_outline`	`outline <file>`
`ctxctl_symbol`	`symbol <file> --name <s>`
`ctxctl_read`	`read <file> [--lines N-M]`
`ctxctl_deps`	`deps <file>`
`ctxctl_exec`	`exec <cmd> [--keep <pat>]`

结果以纯文本返回，附带与 CLI 相同的 saved% 统计，包装为 { content: [{ type: "text", text }] }。失败（文件不存在、符号未找到、参数错误）以 isError: true 结果返回，绝不是协议错误。被包裹的命令以非零码退出时，ctxctl_exec 调用同样以携带该退出码的错误结果返回。

工具参数

file 接受工作区相对路径，或固定工作区根目录之下的绝对路径（已存在的目标会做符号链接解析）；根目录之外的绝对路径会被拒绝。
ctxctl_read 的 lines 为可选（inputSchema.required 为 ["file"]）：省略或传空字符串即返回整个文件。格式："N"、"N-M"、"N-"（开放区间到文件末尾），以及逗号列表如 "100-150,200-210"。非法的区间串会被拒绝，并指明接受的格式： invalid range `1x2`: expected N, N-M, or N-。
字符串型参数收到 JSON 数字时会良性转换为十进制字符串形式（lines: 100 → "100"）；其他类型不匹配会失败并指明参数名、期望类型与实际类型。
错误信息自带修正指引：未知工具会枚举可用工具，缺失参数会附加由该工具 schema 生成的用法示例，未知参数键会列出有效键。ctxctl_symbol 未命中时更进一步——见自愈式查找。

自愈式查找

自 v0.3.3 起，ctxctl_symbol 未命中时不再只报错。首行保持原样（symbol not found: <名称>），其下的错误信息带齐了正确重试所需的全部内容：

一行 suggestions:，最多 5 个来自文件真实符号的相似名称——大小写不敏感的前缀匹配优先，其次子串匹配，再次编辑距离 ≤ 2，并列按字母序。
文件顶层符号的迷你大纲，每行一条 类型名称，最多 20 行，超出以 ... and N more 结尾。

symbol not found: NodeDataa
suggestions: NodeData

struct NodeData
enum NodeKind
fn parse_node
... and 6 more

建议与大纲仅由文件内容和查询决定，消息保持字节稳定；当查询毫无相似项时，裸错误原样返回，不做任何修饰。

安全姿态

自 v0.3.1 起，适配器按设计钉定工作区：

工具调用基于服务器的固定工作区根目录解析路径，而不是进程的环境 CWD。
工具参数在分发前完成校验——畸形调用直接快速失败，不会进入处理器。
exec 派生的子进程受墙钟超时约束，挂起的命令无法卡死 stdio 循环。

配置

把 ctxctl 添加到任何支持启动 stdio 服务器的 MCP 客户端：

{
  "mcpServers": {
    "ctxctl": {
      "command": "ctxctl",
      "args": ["mcp"]
    }
  }
}

这种写法适用于 opencode、Cursor、Claude Desktop 以及其他 MCP 原生客户端。

协议说明

基于 stdio 的换行分隔 JSON-RPC 2.0。
initialize 以 protocolVersion: "2025-03-26"、工具能力与服务器信息（name: "ctxctl"）响应。
通知（没有 id 的消息）不会产生响应。
畸形 JSON 返回 JSON-RPC 错误 -32700；带 id 但缺少 method 的消息返回 -32600（无效请求）；未知方法返回 -32601。
配置解析与 CLI 完全一致，包括 --config。
stdin 干净 EOF 时服务器以 0 退出。