qodercli-mcp

Un servidor MCP mínimo que envuelve qodercli (Qoder CLI), permitiendo que cualquier cliente MCP delegue tareas de codificación a un agente Qoder local.

Un servidor MCP mínimo que envuelve el qodercli local (Qoder CLI) como herramienta MCP, permitiendo que cualquier cliente MCP (Qoder IDE, Claude Code, Cursor, etc.) invoque a Qoder como si fuera un sub-agente.

Por qué

Algunos agentes CLI incluyen un modo oficial de servidor MCP (por ejemplo, codex mcp-server), pero qodercli actualmente solo actúa como cliente MCP. Este proyecto llena ese vacío con un envoltorio delgado: internamente ejecuta qodercli -p <prompt> y transmite el resultado de vuelta a través de MCP stdio.

Algunos agentes CLI incluyen un modo oficial de servidor MCP (por ejemplo, codex mcp-server), pero qodercli actualmente solo puede actuar como cliente MCP. Este proyecto llena ese vacío con una capa delgada de envoltura: internamente invoca qodercli -p <prompt> y devuelve el resultado a través de MCP stdio.

Características

• Herramienta ask-qoder — delega un prompt a qodercli

• Herramienta ask-qoder — delega tareas a qodercli

• Salida estructurada (session_id, is_error, duration_ms, total_credits, num_turns) mediante análisis de -o json

• Salida estructurada (session_id, is_error, duration_ms, total_credits, num_turns), analizada automáticamente desde -o json

• Herramienta list-sessions para descubrir sesiones reanudables

• Herramienta list-sessions, para descubrir sesiones que se pueden reanudar

• Herramienta list-models para descubrimiento de modelos en tiempo de ejecución (sin listas de modelos obsoletas)

• Herramienta list-models, descubrimiento de modelos disponibles en tiempo de ejecución (no depende de listas obsoletas)

• Parámetro reasoning_effort (--reasoning-effort)

• Parámetro reasoning_effort (transparente a --reasoning-effort)

• Las instructions del servidor en el resultado de inicialización de MCP guían a los clientes sobre su uso

• Las instrucciones del servidor en el resultado de inicialización de MCP guían al cliente para invocarlo correctamente

• Niveles de sandbox estilo Codex (read-only / workspace-write / danger-full-access)

• Niveles de sandbox similares a codex (read-only / workspace-write / danger-full-access)

• Inyección de prompt del sistema (system_prompt / append_system_prompt)

• Inyección de prompt del sistema (system_prompt / append_system_prompt)

• Directorio de trabajo, modelo, modo de permisos, control de formato de salida

• Soporta especificar directorio de trabajo, modelo, modo de permisos, formato de salida

• Reanudación de sesión (resume_session_id) para delegación de múltiples turnos

• Soporta reanudación de sesión (resume_session_id), permitiendo delegación en múltiples rondas

• Protección de tiempo de espera con fallback SIGKILL

• Protección de tiempo de espera (SIGKILL automático al exceder el tiempo)

• Soporte de cuota de proxy (inyección de HTTP_PROXY / HTTPS_PROXY)

• Soporte de cuota de proxy (inyección de HTTP_PROXY / HTTPS_PROXY)

• Sin paso de compilación — JavaScript ESM puro, Node.js >= 18

• Sin necesidad de compilación — JavaScript ESM puro, Node.js >= 18

Prerrequisitos

1. Node.js >= 18

2. qodercli instalado y con sesión iniciada (qodercli login)

Instalación

Opción A — npx (recomendada): sin necesidad de clonar, el cliente MCP descarga el paquete en el primer uso. Sin necesidad de clonar, el cliente MCP descarga automáticamente la primera vez que se usa:

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

Opción B — desde fuente (para desarrollo):

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

Configuración del cliente MCP

Qoder IDE

Agregar a ~/.qoder/mcp.json. Preferir la ruta absoluta de node y establecer QODERCLI_PATH explícitamente (los binarios administrados por nvm a menudo faltan en el PATH visto por los procesos hijos de MCP):

Soporte de proxy: Para usar la cuota de proxy de Qoder CLI, agregue HTTP_PROXY y/o HTTPS_PROXY al entorno del servidor. Cuando se establecen a nivel del servidor MCP, se pasarán a todos los subprocesos de qodercli.

Agregar a ~/.qoder/mcp.json. Se recomienda usar la ruta absoluta de node y establecer explícitamente QODERCLI_PATH (el PATH de los procesos hijos de MCP a menudo carece de los directorios binarios administrados por nvm):

Soporte de proxy: Para usar la cuota de proxy de Qoder CLI, puede agregar HTTP_PROXY y/o HTTPS_PROXY en las variables de entorno del servidor. Cuando estas variables se establecen a nivel del servidor MCP, se pasan a todos los subprocesos de 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"
      }
    }
  }
}

Los desarrolladores que ejecuten una copia local en lugar del paquete publicado (Opción B) deben reemplazar command/args con la ruta absoluta de node y /path/to/qodercli-mcp/src/index.js (el node administrado por nvm a menudo falta en el PATH visto por los procesos hijos de MCP). Los desarrolladores que usen el código fuente local (Opción B) deben reemplazar command/args con la ruta absoluta de node y /path/to/qodercli-mcp/src/index.js (el PATH de los procesos hijos de MCP a menudo carece del directorio binario administrado por nvm).

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

Herramienta: ask-qoder

Salida estructurada

ask-qoder declara un outputSchema de MCP y devuelve, además del texto legible, un objeto structuredContent:

ask-qoder declara un outputSchema de MCP, además del texto legible, devuelve un objeto 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
}

Mapeo de sandbox

permission_mode o approval_policy explícito siempre prevalece sobre sandbox. El permission_mode o approval_policy establecido explícitamente tiene prioridad sobre sandbox.

Modos de permiso (semántica verificada)

Herramienta: list-sessions

Lista las sesiones locales de qodercli (índice, resumen, id de sesión) para que un cliente pueda elegir un resume_session_id. No toma argumentos.

Lista las sesiones locales de qodercli (número, resumen, ID de sesión), facilitando la selección de resume_session_id. Sin parámetros.

Herramienta: list-models

Lista los modelos actualmente soportados por qodercli (mediante --list-models), para que un cliente pueda elegir un valor model válido en tiempo de ejecución en lugar de basarse en conocimiento obsoleto. Devuelve tanto una lista de texto como un array estructurado models. No toma argumentos.

Lista los modelos actualmente soportados por qodercli, para seleccionar un valor model válido en tiempo de ejecución (no depende de conocimiento obsoleto). Devuelve una lista de texto y un array estructurado models. Sin parámetros.

Ejemplos de uso

Ejemplo 1: Explicación simple de código

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

El resultado devuelve una explicación en lenguaje natural que ayuda a entender la función del archivo.

Ejemplo 2: Solicitar una segunda opinión

{ "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 ofrece sugerencias de seguridad y mejoras.

Ejemplo 3: Conversación de múltiples turnos mediante reanudación

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

Mediante resume_session_id se puede lograr una optimización iterativa interactiva de múltiples rondas.

Ejemplo 4: Revisión de código con enfoque específico

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

Adecuado para escenarios de análisis de rendimiento y sugerencias de optimización.

Ejemplo 5: Análisis de solo lectura

{ "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 deshabilita herramientas de escritura de archivos y shell, adecuado para escenarios de auditoría/revisión.

Ejemplo 6: Análisis a nivel de proyecto

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

Adecuado para proyectos grandes para una comprensión rápida de la arquitectura.

Mejores prácticas

1. Especificar directorio de trabajo — Siempre pasa cwd al operar en un proyecto específico 操作特定项目时务必指定 cwd

2. Usar protección de tiempo de espera — Para indicaciones complejas, establece un timeout_ms explícito, menor a 60 minutos 复杂任务设置 timeout_ms（建议 5–10 分钟），避免挂起

3. Reanudar para múltiples turnos — Encadena seguimientos mediante resume_session_id en lugar de repetir el contexto 后续追问用 resume_session_id 续接会话，避免重复上下文

4. Selección de modelo — Llama primero a list-models para descubrir los modelos actualmente compatibles; los modelos más grandes son mejores para análisis profundos 先调 list-models 查询当前可用模型；深度分析建议选择大模型

5. Modo de permisos — El valor predeterminado del servidor es solo lectura (dont_ask); establece QODERCLI_DEFAULT_PERMISSION_MODE=bypass_permissions para que el acceso completo (YOLO) sea el predeterminado en despliegues personales. Por llamada: las tareas que deben crear/modificar archivos necesitan sandbox: "workspace-write"; el acceso a shell necesita danger-full-access. No combines sandbox con un permission_mode explícito (este último tiene prioridad) 服务器默认只读（dont_ask）；个人部署可用 QODERCLI_DEFAULT_PERMISSION_MODE=bypass_permissions 将全开（YOLO）设为默认。单次调用：需要改文件设 sandbox: "workspace-write"，需要 shell 用 danger-full-access；勿与显式 permission_mode 混用（后者优先生效）

Variables de entorno / 环境变量

Desarrollo / 开发

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

Descargo de responsabilidad / 免责声明

Esta es una herramienta no oficial de terceros. No está afiliada, respaldada ni patrocinada por Qoder. Usa permission_mode: bypass_permissions con cuidado — las indicaciones delegadas pueden modificar archivos en el directorio de trabajo de destino.

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

Licencia

MIT