cli-agent-mcp

中文文档

Unified MCP (Model Context Protocol) server for CLI AI agents. Provides a single interface to invoke Codex, Gemini, Claude, OpenCode CLI tools, and Nano Banana Pro image generation.

Why cli-agent-mcp?

This is more than a CLI wrapper — it’s an orchestration pattern for multi-model collaboration.

Can’t articulate your requirements clearly? Let Claude orchestrate. Describe what you want, and it will decompose your vague idea into concrete tasks for the right agent. The act of delegation forces clarity.

Planning a grand product vision? Each model brings a unique lens:

• Codex: The critic. Its analytical eye catches what you missed, challenges assumptions, finds edge cases.
• Gemini: The creative. Divergent thinking, unexpected connections, the spark you didn’t know you needed.
• Claude: The scribe. Faithful execution, clear documentation, turning ideas into working code.
• Banana: The artist. High-fidelity image generation for UI mockups, product visuals, and creative assets.

Want persistent results? Use handoff_file to capture agent outputs, then let Claude synthesize insights across multiple analyses.

We don’t just wrap CLIs — we provide a thinking framework for human-AI collaboration.

Features

• Unified Interface: Single MCP server exposing multiple CLI agents
• GUI Dashboard: Real-time task monitoring with pywebview
• Request Isolation: Per-request execution context for safe concurrent usage
• Signal Handling: Graceful cancellation via SIGINT without killing the server
• Debug Logging: Comprehensive subprocess output capture for debugging

Screenshot

Installation

# Install from PyPI (when published)
uvx cli-agent-mcp

# Install from GitHub
uvx --from git+https://github.com/shiharuharu/cli-agent-mcp.git cli-agent-mcp

# Install from source (editable mode for development)
uvx --from /path/to/cli-agent-mcp cli-agent-mcp

# Or use pip
pip install -e .

Configuration

Configure via environment variables:

Tools

codex

Invoke OpenAI Codex CLI agent for deep code analysis and critical review.

Best for: Code review, bug hunting, security analysis

gemini

Invoke Google Gemini CLI agent for UI design and comprehensive analysis.

Best for: UI mockups, image analysis, requirement discovery, full-text analysis

claude

Invoke Anthropic Claude CLI agent for code implementation.

Best for: Feature implementation, refactoring, code generation

opencode

Invoke OpenCode CLI agent for full-stack development.

Best for: Rapid prototyping, multi-framework projects

banana

Generate high-fidelity images via the Nano Banana Pro API.

Best for: UI mockups, product visuals, infographics, architectural renders, character art

Nano Banana Pro has exceptional understanding and visual expression capabilities—your prompt creativity is the only limit, not the model.

Environment Variables:

Prompt Best Practices:

• Explicitly request an image (e.g., start with “Generate an image:” or include "output":"image")
• Use structured specs (JSON / XML tags / labeled sections) for complex requests
• Use MUST/STRICT/CRITICAL for non-negotiable constraints
• Add negative constraints (e.g., “no watermark”, “no distorted hands”)

image

Generate images via OpenRouter-compatible or OpenAI-compatible endpoints.

Best for: General image generation when you need compatibility with various providers. For best results with Gemini models, use the banana tool instead.

Environment Variables:

*_parallel_with_template

Batch task execution using simple placeholder templates. Available for all CLI agents:

• codex_parallel_with_template
• gemini_parallel_with_template
• claude_parallel_with_template
• opencode_parallel_with_template

Best for: Batch code review, batch file processing, batch analysis with structured data

Template Syntax:

Supported:
  {{ name }}              # Simple variable substitution
  {{ vars.file_path }}    # Dotted dict path (nested dict lookup)
  {{{{                    # Escape to output {{
  }}}}                    # Escape to output }}

NOT supported:
  {{ a | default(...) }}  # Filters
  {{ foo.bar() }}         # Function calls
  {{ a + b }}             # Expressions
  {% if %}...{% endif %}  # Conditionals
  {% for %}...{% endfor %} # Loops

Auto-injected variables (available in templates, override same-named keys in variables[i]):

• task_index: 1-based index of current task
• task_count: Total number of tasks
• vars: The original variables[i] dict

Example: Batch Code Review

{
  "template": "Review {{ file_path }} focusing on {{ focus }}. Task {{ task_index }}/{{ task_count }}.",
  "variables": [
    {"file_path": "src/handlers/cli.py", "focus": "error handling"},
    {"file_path": "src/handlers/parallel.py", "focus": "concurrency safety"},
    {"file_path": "src/server.py", "focus": "input validation"}
  ],
  "task_note_template": "[Review] {{ file_path }}",
  "workspace": "/path/to/project",
  "handoff_file": ".agent-handoff/review_batch.md",
  "parallel_max_concurrency": 3
}

get_gui_url

Get the GUI dashboard URL. Returns the HTTP URL where the live event viewer is accessible.

No parameters required.

Prompt Injection

Some parameters automatically inject additional content into the prompt using `` XML tags. These tags make it easy to debug and identify system-injected content.

report_mode

When report_mode is set, output format requirements are injected:

  
    This response will be saved as a standalone document.
    Write so it can be understood WITHOUT any prior conversation context.
    Do NOT reference "above", "previous messages", or "as discussed".
    Use the same language as the user's request.
  
  
    
    
    
    
  
  Write with enough detail to be useful standalone, but avoid unnecessary filler.

context_paths

When context_paths is provided, reference paths are injected:

  
    These paths are provided as reference for project structure.
    You may use them to understand naming conventions and file organization.
  
  
    /src/api/handlers.py
    /config/settings.json
  

Stateless Design

Important: Each tool call is stateless - the agent has NO memory of previous calls.

• New conversation (no continuation_id): Include ALL relevant context in your prompt - background, specifics, constraints, and prior findings.
• Continuing conversation (with continuation_id): The agent retains context from that session, so you can be brief.

If your request references prior context (e.g., “fix that bug”, “continue the work”), you must either:

1. Provide continuation_id from a previous response, OR
2. Expand the reference into concrete details

Handoff File

handoff_file is REQUIRED for all CLI tools. The server appends each tool output to this file after execution.

Behavior (always):

• Append-only (never overwrite)
• Wrapped as `` with agent, continuation_id, task_note, task_index, status
• task_index: single task = 0; parallel tasks = 1..N
• On failure, still appends with status="error" and an Error: ... message

Safety notes:

• Avoid concurrent writes to the same path (outputs may interleave)
• Avoid double-write conflict: do NOT point handoff_file at a file the agent is asked to edit
• Recommended: use .agent-handoff/ (e.g., .agent-handoff/handoff_chain.md)

Example wrapper:

... agent response (Markdown) ...

Migration: save_file → handoff_file

save_file, save_file_with_wrapper, and save_file_with_append_mode were removed. Use handoff_file instead (required; always append; always wrapper).

Response Format

All responses are wrapped in XML format:

Success Response

  ...  
  
    Agent's response content...
  
  session-id-here
  ...  

Error Response

Error responses include partial progress to enable retry:

  Error message
  ...  
  ...    
  session-id
  Task failed. Above is the output collected so far. You can send 'continue' with this continuation_id to retry.
  ...

Permission Levels

Debug Mode

Enable debug mode to get detailed execution information:

# Enable debug info in responses
export CAM_DEBUG=true

# Enable detailed log file
export CAM_LOG_DEBUG=true

When CAM_LOG_DEBUG=true, logs are written to:

/tmp/cli-agent-mcp/cam_debug_YYYYMMDD_HHMMSS.log

Debug output includes:

• Full subprocess command
• Complete stdout/stderr output
• Return codes
• MCP request/response summaries

MCP Configuration

Add to your MCP client configuration (e.g., Claude Desktop claude_desktop_config.json):

Basic Configuration

{
  "mcpServers": {
    "cli-agent-mcp": {
      "command": "uvx",
      "args": ["cli-agent-mcp"]
    }
  }
}

Install from GitHub

{
  "mcpServers": {
    "cli-agent-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/shiharuharu/cli-agent-mcp.git",
        "cli-agent-mcp"
      ]
    }
  }
}

With Debug Mode

{
  "mcpServers": {
    "cli-agent-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/shiharuharu/cli-agent-mcp.git",
        "cli-agent-mcp"
      ],
      "env": {
        "CAM_DEBUG": "true",
        "CAM_LOG_DEBUG": "true"
      }
    }
  }
}

Disable GUI

{
  "mcpServers": {
    "cli-agent-mcp": {
      "command": "uvx",
      "args": ["cli-agent-mcp"],
      "env": {
        "CAM_GUI": "false"
      }
    }
  }
}

Limit Available Tools

{
  "mcpServers": {
    "cli-agent-mcp": {
      "command": "uvx",
      "args": ["cli-agent-mcp"],
      "env": {
        "CAM_ENABLE": "claude,gemini"
      }
    }
  }
}

Disable Image Tools

{
  "mcpServers": {
    "cli-agent-mcp": {
      "command": "uvx",
      "args": ["cli-agent-mcp"],
      "env": {
        "CAM_DISABLE": "banana,image"
      }
    }
  }
}

Project Structure

cli-agent-mcp/
├── src/cli_agent_mcp/
│   ├── __init__.py          # Package exports
│   ├── __main__.py          # Entry point
│   ├── app.py               # Server lifecycle (run_server, main)
│   ├── server.py            # MCP protocol adapter (create_server)
│   ├── tool_schema.py       # Tool descriptions and JSON schemas
│   ├── config.py            # Configuration management
│   ├── gui_manager.py       # GUI dashboard manager
│   ├── orchestrator.py      # Request registry
│   ├── signal_manager.py    # Signal handling (SIGINT/SIGTERM)
│   ├── handlers/            # Tool handlers
│   │   ├── base.py          # ToolContext, ToolHandler base class
│   │   ├── cli.py           # CLI tools (codex/gemini/claude/opencode)
│   │   ├── parallel.py      # Parallel execution (*_parallel tools)
│   │   ├── parallel_with_template.py  # Template-based parallel (*_parallel_with_template)
│   │   └── image_tools.py   # Image tools (banana/image)
│   ├── utils/               # Utility functions
│   │   ├── xml_wrapper.py   # XML escaping and wrapper building
│   │   ├── prompt_injection.py  # Prompt injection helpers
│   │   └── simple_template.py   # Simple placeholder template engine
│   └── shared/              # Shared modules
│       ├── invokers/        # CLI invoker implementations
│       ├── parsers/         # Output parsers
│       ├── gui/             # GUI components
│       └── response_formatter.py  # Response formatting
└── tests/

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

License

MIT