qodercli-mcp

Ein minimaler MCP-Server, der qodercli (Qoder CLI) umschließt und jedem MCP-Client ermöglicht, Codierungsaufgaben an einen lokalen Qoder-Agenten zu delegieren.

Ein minimaler MCP-Server, der das lokale qodercli (Qoder CLI) als MCP-Tool verpackt, sodass jeder MCP-Client (Qoder IDE, Claude Code, Cursor usw.) Qoder wie einen Unter-Agenten aufrufen kann.

Warum / 为什么

Manche CLI-Agenten bieten einen offiziellen MCP-Server-Modus an (z. B. codex mcp-server), aber qodercli fungiert derzeit nur als MCP-Client. Dieses Projekt schließt diese Lücke mit einem dünnen Wrapper: Es startet qodercli -p <prompt> im Hintergrund und streamt das Ergebnis über MCP stdio zurück.

Einige CLI-Agenten bieten einen offiziellen MCP-Server-Modus (z. B. codex mcp-server), aber qodercli kann derzeit nur als MCP-Client agieren. Dieses Projekt füllt diese Lücke mit einer dünnen Wrapperschicht: Es ruft intern qodercli -p <prompt> auf und gibt das Ergebnis über MCP stdio zurück.

Funktionen / 功能

• ask-qoder-Tool – delegiert eine Eingabeaufforderung an qodercli

• ask-qoder-Tool – delegiert eine Aufgabe an qodercli

• Strukturierte Ausgabe (session_id, is_error, duration_ms, total_credits, num_turns) über -o json-Parsing

• Strukturierte Ausgabe (session_id, is_error, duration_ms, total_credits, num_turns), automatische Analyse von -o json

• list-sessions-Tool zum Auffinden fortsetzbarer Sitzungen

• list-sessions-Tool zum Auffinden fortsetzbarer Sitzungen

• list-models-Tool zur Laufzeit-Modellerkennung (keine veralteten Modelllisten)

• list-models-Tool zum Erkennen verfügbarer Modelle zur Laufzeit (keine veraltete Liste)

• reasoning_effort-Parameter (--reasoning-effort)

• reasoning_effort-Parameter (durchgereicht --reasoning-effort)

• Server-instructions im MCP-Initialisierungsergebnis führen den Client zur Nutzung

• MCP-Initialisierungsergebnis enthält Serveranweisungen, die den Client zur korrekten Nutzung führen

• Codex-ähnliche sandbox-Stufen (read-only / workspace-write / danger-full-access)

• Codex-ähnliche sandbox-Stufen (read-only / workspace-write / danger-full-access)

• System-Prompt-Injektion (system_prompt / append_system_prompt)

• System-Prompt-Injektion (system_prompt / append_system_prompt)

• Arbeitsverzeichnis, Modell, Berechtigungsmodus, Ausgabeformatsteuerung

• Unterstützt Arbeitsverzeichnis, Modell, Berechtigungsmodus, Ausgabeformat

• Sitzungsfortsetzung (resume_session_id) für mehrstufige Delegation

• Unterstützt Sitzungsfortsetzung (resume_session_id) für mehrstufige Delegation

• Timeout-Schutz mit SIGKILL-Fallback

• Timeout-Schutz (automatischer SIGKILL bei Timeout)

• Proxy-Kontingentunterstützung (HTTP_PROXY / HTTPS_PROXY-Injektion)

• Proxy-Kontingentunterstützung (HTTP_PROXY / HTTPS_PROXY-Injektion)

• Kein Build-Schritt – reines ESM JavaScript, Node.js >= 18

• Kein Build erforderlich – reines ESM JavaScript, Node.js >= 18

Voraussetzungen / 前置条件

1. Node.js >= 18

2. qodercli installiert und angemeldet (qodercli login)

Installation / 安装

Option A – npx (empfohlen / 推荐): kein Klonen erforderlich, der MCP-Client lädt das Paket bei der ersten Verwendung herunter. Kein Klonen erforderlich, der MCP-Client lädt das Paket bei der ersten Verwendung automatisch herunter:

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

Option B – aus dem Quellcode (für Entwicklung / 开发用):

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

MCP-Client-Konfiguration / MCP 客户端配置

Qoder IDE

Fügen Sie zu ~/.qoder/mcp.json hinzu. Bevorzugen Sie den absoluten Pfad von node und setzen Sie QODERCLI_PATH explizit (nvm-verwaltete Binärdateien fehlen oft im PATH, der von MCP-Kindprozessen gesehen wird):

Proxy-Unterstützung: Um Ihr Qoder-CLI-Proxy-Kontingent zu nutzen, fügen Sie HTTP_PROXY und/oder HTTPS_PROXY zur Umgebung des Servers hinzu. Wenn diese auf MCP-Serverebene gesetzt sind, werden sie an alle qodercli-Unterprozesse weitergegeben.

Fügen Sie zu ~/.qoder/mcp.json hinzu. Es wird empfohlen, den absoluten Pfad von node zu verwenden und QODERCLI_PATH explizit zu setzen (im PATH von MCP-Kindprozessen fehlen oft die von nvm verwalteten Binärdateien):

Proxy-Unterstützung: Um Ihr Qoder-CLI-Proxy-Kontingent zu nutzen, können Sie HTTP_PROXY und/oder HTTPS_PROXY in den Umgebungsvariablen des Servers hinzufügen. Wenn diese Variablen auf MCP-Serverebene gesetzt werden, werden sie an alle qodercli-Unterprozesse weitergegeben.

{
  "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"
      }
    }
  }
}

Entwickler, die einen lokalen Checkout anstelle des veröffentlichten Pakets verwenden (Option B), sollten command/args durch den absoluten node-Pfad und /path/to/qodercli-mcp/src/index.js ersetzen (nvm-verwaltetes node fehlt oft im PATH, der von MCP-Kindprozessen gesehen wird). Entwickler, die den lokalen Quellcode anstelle des veröffentlichten Pakets (Option B) verwenden, ersetzen bitte command/args durch den absoluten node-Pfad und /path/to/qodercli-mcp/src/index.js (im PATH der MCP-Kindprozesse fehlt oft das von nvm verwaltete node).

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"
      }
    }
  }
}

Tool: ask-qoder

Strukturierte Ausgabe / 结构化输出

ask-qoder deklariert ein MCP outputSchema und gibt zusätzlich zum menschenlesbaren Text ein structuredContent-Objekt zurück:

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
}

Sandbox-Mapping / 沙箱映射

Explizites permission_mode oder approval_policy hat immer Vorrang vor sandbox. Explizit gesetztes permission_mode / approval_policy hat Vorrang vor sandbox.

Berechtigungsmodi (verifizierte Semantik) / 权限模式（实测语义）

Tool: list-sessions

Listet lokale qodercli-Sitzungen auf (Index, Zusammenfassung, Sitzungs-ID), sodass ein Client eine resume_session_id auswählen kann. Erwartet keine Argumente.

Listet lokale qodercli-Sitzungen auf (Index, Zusammenfassung, Sitzungs-ID), damit der Client eine resume_session_id auswählen kann. Keine Argumente.

Tool: list-models

Listet die derzeit von qodercli unterstützten Modelle auf (über --list-models), sodass ein Client zur Laufzeit einen gültigen model-Wert auswählen kann, anstatt sich auf veraltetes Wissen zu verlassen. Gibt sowohl eine Textliste als auch ein strukturiertes models-Array zurück. Erwartet keine Argumente.

Listet die derzeit von qodercli unterstützten Modelle auf, damit der Client zur Laufzeit einen gültigen model-Wert auswählen kann (ohne veraltetes Wissen). Gibt eine Textliste und ein strukturiertes models-Array zurück. Keine Argumente.

Anwendungsbeispiele / 使用示例

Beispiel 1: Einfache Code-Erklärung / 简单代码解释

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

Das Ergebnis liefert eine Erklärung in natürlicher Sprache, um das Verständnis der Dateifunktion zu unterstützen.

Das Ergebnis gibt eine natürliche Spracherklärung zurück, um das Verständnis der Dateifunktion zu unterstützen.

Beispiel 2: Zweite Meinung einholen / 获取第二意见

{ "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 
}}

Qoder gibt Sicherheitsempfehlungen und Verbesserungsvorschläge.

Qoder gibt Sicherheitsvorschläge und Verbesserungspläne.

Beispiel 3: Mehrstufige Konversation per Fortsetzung / 多轮对话续接

// First call — session_id comes back in structuredContent
// 首次调用 —— session_id 会在 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:
// 然后把 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 / 或用 list-sessions 查找历史会话 ID
{ "name": "list-sessions", "arguments": {} }

Durch resume_session_id können mehrstufige interaktive Iterationen zur Optimierung realisiert werden.

Über resume_session_id können mehrstufige interaktive iterative Optimierungen realisiert werden.

Beispiel 4: Code-Review mit spezifischem Fokus / 针对性代码审查

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

Geeignet für Szenarien der Leistungsanalyse und Optimierungsvorschläge.

Geeignet für Leistungsanalyse und Optimierungsvorschläge.

Beispiel 5: Schreibgeschützte Analyse / 只读分析

{ "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 deaktiviert Dateischreib- und Shell-Tools, geeignet für Audit-/Review-Szenarien.

read-only deaktiviert Dateischreib- und Shell-Tools, geeignet für Audit-/Review-Szenarien.

Beispiel 6: Projektweite Analyse / 项目范围分析

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

Geeignet für schnelle Erfassung und Architekturverständnis großer Projekte.

Geeignet für schnelle Erfassung und Architekturverständnis großer Projekte.

Best Practices / 最佳实践

1. Specify working directory — Always pass cwd when operating on a specific project 操作特定项目时务必指定 cwd

2. Use timeout protection — For complex prompts, set explicit timeout_ms shorter than 60min 复杂任务设置 timeout_ms（建议 5–10 分钟），避免挂起

3. Resume for multi-turn — Chain follow-ups via resume_session_id instead of repeating context 后续追问用 resume_session_id 续接会话，避免重复上下文

4. Model selection — Call list-models first to discover currently supported models; larger models are better for deep analysis 先调 list-models 查询当前可用模型；深度分析建议选择大模型

5. Permission mode — The server default is read-only (dont_ask); set QODERCLI_DEFAULT_PERMISSION_MODE=bypass_permissions to make full (YOLO) access the default for personal deployments. Per-call: tasks that must create/modify files need sandbox: "workspace-write"; shell access needs danger-full-access. Do not combine sandbox with an explicit permission_mode (the latter wins) 服务器默认只读（dont_ask）；个人部署可用 QODERCLI_DEFAULT_PERMISSION_MODE=bypass_permissions 将全开（YOLO）设为默认。单次调用：需要改文件设 sandbox: "workspace-write"，需要 shell 用 danger-full-access；勿与显式 permission_mode 混用（后者优先生效）

Environment variables / 环境变量

Development / 开发

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

Disclaimer / 免责声明

This is an unofficial, third-party tool. It is not affiliated with, endorsed, or sponsored by Qoder. Use permission_mode: bypass_permissions with care — delegated prompts may modify files in the target working directory.

本项目为非官方第三方工具，与 Qoder 官方无关。请谨慎使用 bypass_permissions 权限模式——委托的任务可能修改目标工作目录中的文件。

License

MIT