qodercli-mcp

qodercli-mcp

英語 | 简体中文

Qoder CLI に足りなかった MCP サーバーモード — あらゆる MCP クライアント（Qoder IDE、Claude Code、Cursor…）からローカルの Qoder エージェントにコーディングタスクを委任できます。

ローカルの qodercli（Qoder CLI）を MCP ツールとしてラップする、最小限の MCP サーバーです。あらゆる MCP クライアント（Qoder IDE、Claude Code、Cursor、…）から Qoder をサブエージェントのように呼び出せます。

30秒のデモ：MCP クライアント ⇄ qodercli-mcp ⇄ qodercli — initialize → tools/list → list-models（実際の出力であり、早送りではありません）

クイックスタート

npx で設定不要です。MCP クライアントの設定（~/.qoder/mcp.json、claude_desktop_config.json、…）に次を追加します。

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

3つのツールを公開します。

ツール	用途
ask-qoder	タスクを qodercli に委任
list-sessions	再開可能なセッションを検出
list-models	実行時のモデル検出

主な特長：検証済みの権限セマンティクス（以下を参照。たとえば dont_ask は読み取り専用です）、 codex スタイルの sandbox／approval_policy、構造化出力（session_id／duration_ms／total_credits）。

すべての設定オプションについては、インストールを参照してください。

概要

一部の CLI エージェントは公式の 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 (required)	qodercli に対するタスクまたは質問
cwd	string	作業ディレクトリ
model	string	このセッションで使用するモデル。利用可能な名前を確認するには list-models を呼び出します
reasoning_effort	string	推論の労力レベル（--reasoning-effort）。例：low／medium／high。モデルによって異なります
permission_mode	enum	dont_ask（デフォルト、読み取り専用）| accept_edits（ファイル編集を自動承認）| bypass_permissions（シェルを含むフルアクセス）| 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
}

サンドボックスのマッピング

sandbox	実効的な権限モード	qodercli への効果
（省略）	dont_ask	読み取り専用：権限が必要なツールは通知なしで拒否されます
read-only	dont_ask	さらに、追加の防御策として --disallowed-tools write_file,replace,run_shell_command を指定します
workspace-write	accept_edits	エージェントは cwd 内のファイルを作成・変更できます
danger-full-access	bypass_permissions	シェルを含むフルアクセス

明示的に指定された permission_mode または approval_policy は、常に sandbox より優先されます。

権限モード（検証済みの動作）

モード	動作
dont_ask	読み取り専用：権限が必要なツール呼び出しはすべて通知なしで拒否されます。ヘッドレス環境で安全なデフォルトです
accept_edits	ファイル編集を自動承認します。シェルは引き続きポリシーに従います
bypass_permissions	シェルを含むすべてを自動承認します
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 は書き込み／シェルツールを無効にします。監査やレビューに適しています。

例 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）です。個人でのデプロイ時にフル（YOLO）アクセスをデフォルトにするには、QODERCLI_DEFAULT_PERMISSION_MODE=bypass_permissions を設定してください。呼び出しごとの設定では、ファイルを作成・変更する必要があるタスクには sandbox: "workspace-write" が必要です。シェルへのアクセスには 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 を省略した場合のデフォルトの権限モード。フル（YOLO）アクセスには bypass_permissions を設定します
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