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 save_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:

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 <mcp-injection> XML tags. These tags make it easy to debug and identify system-injected content.

report_mode

When save_file and report_mode are both set, output format requirements are injected:

<your prompt>

<mcp-injection type="output-format">
  <output-requirements>
    <rule>This response will be saved as a standalone document.</rule>
    <rule>Write so it can be understood WITHOUT any prior conversation context.</rule>
    <rule>Do NOT reference "above", "previous messages", or "as discussed".</rule>
    <rule>Use the same language as the user's request.</rule>
  </output-requirements>
  <structure>
    <section name="Summary">3-7 bullet points with key findings and conclusions</section>
    <section name="Context">Restate the task/problem so readers understand without chat history</section>
    <section name="Analysis">Step-by-step reasoning with evidence; include file:line references</section>
    <section name="Recommendations">Actionable next steps ordered by priority</section>
  </structure>
  <note>Write with enough detail to be useful standalone, but avoid unnecessary filler.</note>
</mcp-injection>

context_paths

When context_paths is provided, reference paths are injected:

<your prompt>

<mcp-injection type="reference-paths">
  <description>
    These paths are provided as reference for project structure.
    You may use them to understand naming conventions and file organization.
  </description>
  <paths>
    <path>/src/api/handlers.py</path>
    <path>/config/settings.json</path>
  </paths>
</mcp-injection>

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

File Output Options

save_file_with_wrapper

When enabled, output is wrapped with XML tags containing metadata:

<agent-output agent="gemini" continuation_id="abc123">
... agent response ...
</agent-output>

save_file_with_append_mode

When enabled, new output is appended to existing file instead of overwriting. Combined with save_file_with_wrapper, enables multi-agent collaboration:

<agent-output agent="codex" continuation_id="...">
Critical analysis of the codebase...
</agent-output>

<agent-output agent="gemini" continuation_id="...">
Creative suggestions for improvement...
</agent-output>

<agent-output agent="claude" continuation_id="...">
Implementation summary...
</agent-output>

Response Format

All responses are wrapped in XML format:

Success Response

<response>
  <thought_process>...</thought_process>  <!-- Only when verbose_output=true -->
  <answer>
    Agent's response content...
  </answer>
  <continuation_id>session-id-here</continuation_id>
  <debug_info>...</debug_info>  <!-- Only when debug=true -->
</response>

Error Response

Error responses include partial progress to enable retry:

<response>
  <error>Error message</error>
  <thought_process>...</thought_process>  <!-- Collected steps before error -->
  <partial_answer>...</partial_answer>    <!-- Partial output if any -->
  <continuation_id>session-id</continuation_id>
  <hint>Task failed. Above is the output collected so far. You can send 'continue' with this continuation_id to retry.</hint>
  <debug_info>...</debug_info>
</response>

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)
│   │   └── image_tools.py   # Image tools (banana/image)
│   ├── utils/               # Utility functions
│   │   ├── xml_wrapper.py   # XML escaping and wrapper building
│   │   └── prompt_injection.py  # Prompt injection helpers
│   └── 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