qodercli-mcp

qodercli-mcp

English | 简体中文

Qoder CLI 缺少的 MCP 服务模式 — 从任意 MCP 客户端（Qoder IDE、Claude Code、Cursor……）向本地 Qoder Agent 委派编码任务。

一个精简的 MCP 服务，将本地 qodercli（Qoder CLI）封装为 MCP 工具，让任意 MCP 客户端（Qoder IDE、Claude Code、Cursor，……）都能像调用子 Agent 一样调用 Qoder。

30 秒演示：MCP 客户端 ⇄ qodercli-mcp ⇄ qodercli — 初始化 → tools/list → list-models（真实输出，未加速）

快速开始

通过 npx 零配置接入 — 将以下内容添加到 MCP 客户端配置中（~/.qoder/mcp.json、claude_desktop_config.json，……）：

{ "mcpServers": { "qodercli-mcp": { "command": "npx", "args": ["-y", "qodercli-mcp"] } } }

该服务提供三个工具：

工具	用途
ask-qoder	将任务委派给 qodercli
list-sessions	查找可恢复的会话
list-models	运行时发现模型

亮点：已验证的权限语义（见下文 — 例如，dont_ask 为只读）， codex 风格的 sandbox/approval_policy，结构化输出（session_id/duration_ms/total_credits）。

完整配置选项请见安装。

为什么要用

有些 CLI Agent 提供官方 MCP 服务模式（例如 codex mcp-server），但 qodercli 目前只能作为 MCP 客户端使用。本项目通过一个轻量封装填补了这一空缺：它在底层运行 qodercli -p <prompt>，并通过 MCP stdio 流式返回结果。

功能特性

• ask-qoder 工具 — 将提示词委派给 qodercli
• 通过解析 -o json 提供结构化输出（session_id、is_error、duration_ms、total_credits、num_turns）
• 使用 list-sessions 工具查找可恢复的会话
• 使用 list-models 工具在运行时发现模型（不使用过时的模型列表）
• reasoning_effort 参数（--reasoning-effort）
• MCP 初始化结果中的服务 instructions 可指导客户端使用
• Codex 风格的 sandbox 级别（read-only / workspace-write / danger-full-access）
• 注入系统提示词（system_prompt / append_system_prompt）
• 控制工作目录、模型、权限模式和输出格式
• 恢复会话（resume_session_id），支持多轮委派
• 超时保护，SIGKILL 作为后备方案
• 代理配额支持（注入 HTTP_PROXY / HTTPS_PROXY）
• 无需构建 — 纯 ESM JavaScript，Node.js >= 18

前提条件

1. Node.js >= 18
2. 已安装并登录 qodercli（qodercli login）

安装

选项 A — npx（推荐）：无需克隆，MCP 客户端首次使用时会下载该软件包。

"command": "npx", "args": ["-y", "qodercli-mcp"]

选项 B — 从源码安装（用于开发）：

git clone https://github.com/cantbeblank96/qodercli-mcp.git
cd qodercli-mcp
npm install

MCP 客户端配置

Qoder IDE

添加到 ~/.qoder/mcp.json。建议使用 node 的绝对路径并显式设置 QODERCLI_PATH（由 nvm 管理的二进制文件通常不在 MCP 子进程可见的 PATH 中）：

代理支持：若要使用 Qoder CLI 代理配额，请在服务环境中添加 HTTP_PROXY 和/或 HTTPS_PROXY。在 MCP 服务级别设置这些变量后，它们将传递给所有 qodercli 子进程。

{
  "mcpServers": {
    "qodercli-mcp": {
      "command": "npx",
      "args": ["-y", "qodercli-mcp"],
      "env": {
        "QODERCLI_PATH": "/absolute/path/to/qodercli",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    },
    "qodercli-mcp-with-proxy": {
      "command": "npx",
      "args": ["-y", "qodercli-mcp"],
      "env": {
        "QODERCLI_PATH": "/absolute/path/to/qodercli",
        "HTTP_PROXY": "http://127.0.0.1:39900",
        "HTTPS_PROXY": "http://127.0.0.1:39900",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

使用本地检出版本而非已发布软件包（选项 B）的开发者，应将 command/args 替换为 node 的绝对路径以及 /path/to/qodercli-mcp/src/index.js（由 nvm 管理的 node 通常不在 MCP 子进程可见的 PATH 中）。

Claude Code / Claude Desktop

{
  "mcpServers": {
    "qodercli-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qodercli-mcp/src/index.js"],
      "env": {
        "QODERCLI_PATH": "/absolute/path/to/qodercli"
      }
    }
  }
}

工具：ask-qoder

参数	类型	描述
prompt	string（必填）	要交给 qodercli 的任务或问题
cwd	string	工作目录
model	string	本次会话使用的模型；调用 list-models 可查看可用名称
reasoning_effort	string	推理力度级别（--reasoning-effort），例如 low/medium/high；具体取决于模型
permission_mode	enum	dont_ask（默认，只读）| accept_edits（自动批准文件编辑）| bypass_permissions（完全访问权限，包括 shell）| auto | default；与 approval_policy 互斥，建议使用 sandbox
approval_policy	enum	codex 风格：untrusted→只读 | on-request→自动 | never→完全访问权限
sandbox	enum	read-only | workspace-write | danger-full-access（codex 风格；控制实际生效的权限模式）
system_prompt	string	替换默认系统提示词
append_system_prompt	string	在默认系统提示词后追加指令
resume_session_id	string	恢复之前的会话
output_format	string	传递给 -o（默认值为 json）。注意：非 JSON 格式会降低结构化输出能力（session_id 等将不可用）
extra_args	string[]	在提示词前追加的原始 CLI 参数；保留参数（权限模式、系统提示词、模型、-o、-r、-w 等）会被拒绝
timeout_ms	number	超时时间（毫秒），默认值为 600000

结构化输出

ask-qoder 声明了一个 MCP outputSchema，除便于人阅读的文本外，还会返回一个 structuredContent 对象：

{
  "session_id": "77826b5c-...",   // pass back as resume_session_id
  "content": "OK",
  "is_error": false,
  "exit_code": 0,
  "duration_ms": 1280,
  "total_credits": 0.53,
  "num_turns": 1,
  "timed_out": false,
  "truncated": false
}

沙箱映射

沙箱	实际生效的权限模式	对 qodercli 的影响
（省略）	dont_ask	只读：需要权限的工具会被静默拒绝
read-only	dont_ask	此外还会添加 --disallowed-tools write_file,replace,run_shell_command，以提供纵深防御
workspace-write	accept_edits	Agent 可以在 cwd 中创建或修改文件
danger-full-access	bypass_permissions	完全访问权限，包括 shell

显式指定的 permission_mode 或 approval_policy 始终优先于 sandbox。

权限模式（已验证的语义）

模式	行为
dont_ask	只读：静默拒绝所有需要权限的工具调用。适用于无头环境的安全默认值
accept_edits	自动批准文件编辑；shell 仍受策略约束
bypass_permissions	自动批准所有操作，包括 shell
auto	qodercli 自身的自动策略
default	交互式确认——不适用于无头环境，应避免在 MCP 调用中使用

工具：list-sessions

列出本地 qodercli 会话（索引、摘要、会话 ID），以便客户端选择 resume_session_id。无需参数。

工具：list-models

列出 qodercli 当前支持的模型（通过 --list-models），以便客户端在运行时选择有效的 model 值，而不必依赖过时的信息。会同时返回文本列表和结构化的 models 数组。无需参数。

使用示例

示例 1：简单的代码解释

{ "name": "ask-qoder", "arguments": { 
  "prompt": "Explain what main.py does",
  "cwd": "/path/to/project",
  "timeout_ms": 180000 
}}

示例 2：征求第二意见

{ "name": "ask-qoder", "arguments": { 
  "prompt": "@src/service.py Review this file for security issues and suggest improvements",
  "model": "qwen-plus",
  "permission_mode": "dont_ask",
  "timeout_ms": 300000 
}}

示例 3：通过恢复会话进行多轮对话

// First call — session_id comes back in structuredContent
{ "name": "ask-qoder", "arguments": {
  "prompt": "Help me refactor this module to improve readability",
  "cwd": "/projects/backend",
  "timeout_ms": 300000 
}}
// Then reuse structuredContent.session_id:
{ "name": "ask-qoder", "arguments": {
  "prompt": "Now add error handling for database timeouts",
  "resume_session_id": "77826b5c-cd6b-4213-b423-d95b4e1deab0"
}}
// Or discover ids with list-sessions
{ "name": "list-sessions", "arguments": {} }

示例 4：针对特定重点进行代码审查

{ "name": "ask-qoder", "arguments": {
  "prompt": "Analyze performance bottlenecks in utils.py",
  "model": "qwen-max",
  "permission_mode": "default",
  "output_format": "text",
  "timeout_ms": 240000 
}}

示例 5：只读分析

{ "name": "ask-qoder", "arguments": {
  "prompt": "Audit this codebase for security issues; do not modify anything",
  "cwd": "/workspaces/repo",
  "sandbox": "read-only",
  "timeout_ms": 300000 
}}

read-only 会禁用写入和 shell 工具——适合审计和审查。

示例 6：项目范围分析

{ "name": "ask-qoder", "arguments": {
  "prompt": "Summarize the architecture of this project and identify key modules",
  "cwd": "/workspaces/repo",
  "timeout_ms": 420000,
  "model": "qwen-plus"
}}

最佳实践

1. 指定工作目录 — 在操作特定项目时，始终传入 cwd
2. 使用超时保护 — 对于复杂提示词，设置明确的 timeout_ms，且小于 60min
3. 多轮对话时续接会话 — 使用 resume_session_id 串联后续请求，而不是重复上下文
4. 模型选择 — 先调用 list-models，了解当前支持的模型；较大的模型更适合深度分析
5. 权限模式 — 服务默认采用只读模式（dont_ask）；设置 QODERCLI_DEFAULT_PERMISSION_MODE=bypass_permissions，可在个人部署中将完整（YOLO）访问设为默认。单次调用：需要创建或修改文件的任务必须设置 sandbox: "workspace-write"；访问 shell 需要设置 danger-full-access。请勿将 sandbox 与显式的 permission_mode 同时使用（后者优先）

环境变量

变量	默认值	描述
QODERCLI_PATH	qodercli	qodercli 二进制文件的路径
QODERCLI_TIMEOUT_MS	600000	默认超时时间
QODERCLI_MAX_OUTPUT_MB	50	单次调用的 stdout/stderr 上限，单位为 MB（防止 OOM）
QODERCLI_DEFAULT_PERMISSION_MODE	dont_ask	调用方未指定 permission_mode/approval_policy/sandbox 时使用的默认权限模式；设置为 bypass_permissions 可获得完整（YOLO）访问权限
HTTP_PROXY	-	qodercli 的 HTTP 代理 URL
HTTPS_PROXY	-	qodercli 的 HTTPS 代理 URL

开发

npm test        # smoke test: protocol handshake + tool invocation
node src/index.js   # run the server manually (stdio)

免责声明

这是一款非官方的第三方工具，与 Qoder 没有关联，也未获其认可或赞助。请谨慎使用 permission_mode: bypass_permissions——委托的提示词可能会修改目标工作目录中的文件。

Product Hunt 展示图库

主图库图片（1270×760，深色科技主题）：ph-gallery.png。可选的演示视频可由 GIF（docs/demo.gif）转换而来。

许可证

MIT