CLI Agent MCP

cli代理mcp

中文文档

用于CLI AI代理的统一MCP（模型上下文协议）服务器。提供一个接口来调用Codex、Gemini、Claude、OpenCode CLI工具和Nano Banana Pro图像生成。

为什么选择cli代理mcp？

这不仅仅是一个CLI包装器——它是一个 编排模式 用于多模型协作。

你不能清楚地表达你的要求吗？ 让克劳德来编排。描述你想要什么，它会将你模糊的想法分解为适合代理人的具体任务。授权行为迫使事情变得清晰。

规划一个宏伟的产品愿景？ 每个型号都有一个独特的镜头：

• 法典：评论家。它的分析眼光捕捉到你错过的东西，挑战假设，发现边缘案例。
• 双子座：创意。发散思维，意想不到的联系，你不知道自己需要的火花。
• 克劳德：抄写员。忠实的执行，清晰的文档，将想法转化为可工作的代码。
• 香蕉：艺术家。为UI模型、产品视觉效果和创意资产生成高保真图像。

想要持续的结果？ 使用 handoff_file 捕获代理输出，然后让Claude综合多个分析的见解。

我们不只是包装CLIs——我们提供 思维框架 用于人类与人工智能的协作。

特性

• 统一接口：单个MCP服务器暴露多个CLI代理
• GUI仪表板：使用pywebview进行实时任务监控
• 请求隔离：用于安全并发使用的每个请求执行上下文
• 信号处理：通过信号情报优雅地取消，而不会杀死服务器
• 调试日志：用于调试的全面子流程输出捕获

截图

CLI Agent MCP GUI

安装

# 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 .

配置

通过环境变量进行配置：

工具

法典

调用OpenAI Codex CLI代理进行深度代码分析和关键审查。

最佳：代码审查、bug查找、安全分析

双子座

调用Google Gemini CLI代理进行UI设计和全面分析。

最佳：UI模型、图像分析、需求发现、全文分析

克劳德

调用Anthropic Claude CLI代理进行代码实现。

最佳：功能实现、重构、代码生成

开源代码

调用OpenCode CLI代理进行全栈开发。

最佳：快速原型制作、多框架项目

香蕉

通过Nano Banana Pro API生成高保真图像。

最佳：UI模型、产品视觉效果、信息图表、建筑渲染、角色艺术

Nano Banana Pro具有出色的理解力和视觉表达能力——你的快速创造力是唯一的限制，而不是模型。

环境变量：

提示最佳实践：

• 明确请求图像（例如，以“生成图像：”开头或包含 "output":"image")
• 对复杂的请求使用结构化规范（JSON/XML标签/标记部分）
• 使用 MUST/STRICT/CRITICAL 对于不可协商的约束
• 添加负面约束（例如，“无水印”、“无失真手”）

图像

通过OpenRouter兼容或OpenAI兼容的端点生成图像。

最佳：当您需要与各种提供商兼容时，可以生成通用图像。为了获得Gemini模型的最佳效果，请使用 banana 工具代替。

环境变量：

\*\_与模板并行

使用简单的占位符模板批量执行任务。适用于所有CLI代理：

• codex_parallel_with_template
• gemini_parallel_with_template
• claude_parallel_with_template
• opencode_parallel_with_template

最佳：批代码审查、批文件处理、结构化数据批分析

模板语法:

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

自动注入变量 （在模板中可用，覆盖变量\[i\]中的同名键）：

• task_index：当前任务的基于1的索引
• task_count：任务总数
• vars：原始变量\[i\]dict

示例：批处理代码审核

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

获取url

获取GUI仪表板URL。返回可访问实时事件查看器的HTTP URL。

无需参数。

提示注入

一些参数使用以下命令自动向提示中注入额外内容 `` XML标签。这些标签使调试和识别系统注入的内容变得容易。

report_mode

当 report_mode 设置后，注入输出格式要求：

  
    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.
  
  
    
3-7 bullet points with key findings and conclusions

    
Restate the task/problem so readers understand without chat history

    
Step-by-step reasoning with evidence; include file:line references

    
Actionable next steps ordered by priority

  
  Write with enough detail to be useful standalone, but avoid unnecessary filler.

context_paths

当 context_paths 注入参考路径：

  
    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

  

无状态设计

重要：每个工具调用都是无状态的——代理对以前的调用没有记忆。

• 新对话 （没有 continuation_id)：在你的提示中包括所有相关的背景、细节、限制和先前的发现。
• 继续对话 （与 continuation_id)：代理保留该会话的上下文，因此您可以简短。

如果您的请求引用了之前的上下文（例如，“修复该错误”、“继续工作”），您必须：

1. 提供 continuation_id 根据之前的回复，或
2. 将参考扩展到具体细节

交接文件

handoff_file 所有CLI工具都需要。服务器在执行后将每个工具输出附加到此文件中。

行为（始终）：

• 仅附加（从不覆盖）
• 包装为 ` 和 agent, continuation_id, task_note, task_index, status`
• task_index：单个任务= 0；并行任务= 1..N
• 失败时，仍附加 status="error" 和a Error: ... 消息

安全注意事项：

• 避免对同一路径进行并发写入（输出可能会交错）
• 避免双重写入冲突：不要指向 handoff_file 在要求代理编辑的文件中
• 推荐：使用 .agent-handoff/ （例如。， .agent-handoff/handoff_chain.md)

包装示例：

... agent response (Markdown) ...

迁移： save_file → handoff_file

save_file, save_file_with_wrapper，以及 save_file_with_append_mode 被移除。使用 handoff_file 相反（必需；始终附加；始终包装）。

响应格式

所有响应都以XML格式包装：

成功响应

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

错误响应

错误响应包括允许重试的部分进度：

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

权限级别

调试模式

启用调试模式以获取详细的执行信息：

# Enable debug info in responses
export CAM_DEBUG=true

# Enable detailed log file
export CAM_LOG_DEBUG=true

当 CAM_LOG_DEBUG=true，日志将写入：

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

调试输出包括：

• 完整子流程命令
• 完成stdout/stderr输出
• 返回代码
• MCP请求/响应摘要

MCP配置

添加到您的MCP客户端配置中（例如，Claude Desktop claude_desktop_config.json):

基本配置

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

从GitHub安装

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

具有调试模式

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

禁用GUI

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

限制可用工具

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

禁用图像工具

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

项目结构

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/

发展

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

# Run tests
pytest

许可证

麻省理工学院