CLI Agent MCP

Instructions

Implementation Reference

• src/cli_agent_mcp/server.py:402-419 (registration)

  Registers the 'claude' tool (among others) in the MCP server's list_tools() method if allowed by config. Uses TOOL_DESCRIPTIONS['claude'] for description and create_tool_schema('claude') for input schema.
  async def list_tools() -> list[Tool]: """列出可用工具。""" tools = [] for cli_type in ["codex", "gemini", "claude", "opencode"]: if config.is_tool_allowed(cli_type): tools.append( Tool( name=cli_type, description=TOOL_DESCRIPTIONS[cli_type], inputSchema=create_tool_schema(cli_type), ) ) # DEBUG: 记录工具列表请求（通常是客户端初始化后的第一个调用） logger.debug( f"[MCP] list_tools called, returning {len(tools)} tools: " f"{[t.name for t in tools]}" ) return tools
• shared/invokers/claude.py:38-151 (handler)

  ClaudeInvoker class provides the core execution handler for the 'claude' tool: builds the claude CLI command based on parameters, runs it as subprocess, processes events with ClaudeParser, and returns ExecutionResult.
  class ClaudeInvoker(CLIInvoker): """Claude CLI 调用器。 封装 Claude CLI 的调用逻辑，包括： - 命令行参数构建 - Permission 到 --tools 参数映射 - system_prompt / append_system_prompt 支持 Example: invoker = ClaudeInvoker() result = await invoker.execute(ClaudeParams( prompt="Review authentication module", workspace=Path("/path/to/repo"), append_system_prompt="Focus on OWASP Top 10 vulnerabilities.", )) """ def __init__( self, claude_path: str = "claude", event_callback: EventCallback | None = None, parser: Any | None = None, ) -> None: """初始化 Claude 调用器。 Args: claude_path: claude 可执行文件路径，默认 "claude" event_callback: 事件回调函数 parser: 自定义解析器 """ super().__init__(event_callback=event_callback, parser=parser) self._claude_path = claude_path @property def cli_type(self) -> CLIType: return CLIType.CLAUDE def validate_params(self, params: CommonParams) -> None: """验证 Claude 特有参数。""" super().validate_params(params) if isinstance(params, ClaudeParams): # 不能同时指定 system_prompt 和 append_system_prompt if params.system_prompt and params.append_system_prompt: raise ValueError( "Cannot specify both system_prompt and append_system_prompt. " "Use system_prompt to completely override, or append_system_prompt to add to existing." ) def build_command(self, params: CommonParams) -> list[str]: """构建 Claude CLI 命令。 Args: params: 调用参数 Returns: 命令行参数列表 """ cmd = [self._claude_path] # 硬编码：非交互模式 cmd.append("-p") # 硬编码：流式 JSON 输出（需要 --verbose） cmd.extend(["--output-format", "stream-json"]) cmd.append("--verbose") # stream-json 在 -p 模式下需要 --verbose # 工作目录 cmd.extend(["--add-dir", str(params.workspace.absolute())]) # Permission 映射到 tools 参数 # read-only: 只允许读取类工具 # workspace-write: 允许编辑和 Bash # unlimited: 使用默认工具集 tools_value = PERMISSION_MAP_CLAUDE.get(params.permission, "Read,Grep,Glob") cmd.extend(["--tools", tools_value]) # 可选：模型 if params.model: cmd.extend(["--model", params.model]) # Claude 特有：系统提示词 if isinstance(params, ClaudeParams): if params.system_prompt: cmd.extend(["--system-prompt", params.system_prompt]) elif params.append_system_prompt: cmd.extend(["--append-system-prompt", params.append_system_prompt]) # Agent 选择 if params.agent: cmd.extend(["--agent", params.agent]) # 会话恢复 if params.session_id: cmd.extend(["--resume", params.session_id]) # Prompt 通过 stdin 传递，不作为命令行参数 return cmd def _process_event(self, event: Any, params: CommonParams) -> None: """处理 Claude 特有的事件。 Claude 的 session_id 在 system/init 事件中。 """ super()._process_event(event, params) if not self._session_id: raw = event.raw if raw.get("type") == "system" and raw.get("subtype") == "init": session_id = raw.get("session_id", "") if session_id: self._session_id = session_id
• src/cli_agent_mcp/server.py:299-330 (schema)

  create_tool_schema('claude') generates the input JSON schema for the 'claude' tool by combining common properties with CLAUDE_PROPERTIES (system_prompt, append_system_prompt, agent).
  def create_tool_schema(cli_type: str) -> dict[str, Any]: """创建工具的 JSON Schema。 参数顺序： 1. prompt, workspace (必填) 2. permission, model, save_file, full_output (常用) 3. 特有参数 (image / system_prompt / append_system_prompt / file / agent) 4. session_id, task_note, debug (末尾) """ # 按顺序构建 properties properties: dict[str, Any] = {} # 1. 公共参数（必填 + 常用） properties.update(COMMON_PROPERTIES) # 2. 特有参数 if cli_type == "codex": properties.update(CODEX_PROPERTIES) elif cli_type == "claude": properties.update(CLAUDE_PROPERTIES) elif cli_type == "opencode": properties.update(OPENCODE_PROPERTIES) # 3. 末尾参数 properties.update(TAIL_PROPERTIES) return { "type": "object", "properties": properties, "required": ["prompt", "workspace"], }
• src/cli_agent_mcp/server.py:221-248 (schema)

  CLAUDE_PROPERTIES defines Claude-specific input schema properties: system_prompt, append_system_prompt, agent.
  CLAUDE_PROPERTIES = { "system_prompt": { "type": "string", "default": "", "description": ( "Complete replacement for the default system prompt. " "Use only when you need full control over agent behavior. " "Prefer append_system_prompt for most cases." ), }, "append_system_prompt": { "type": "string", "default": "", "description": ( "Additional instructions appended to the default system prompt. " "Recommended way to customize behavior. " "Example: 'Focus on performance optimization, avoid adding new dependencies'" ), }, "agent": { "type": "string", "default": "", "description": ( "Specify an agent for the current session (overrides the default agent setting). " "Use predefined agent names configured in Claude Code settings." ), }, }
• shared/invokers/__init__.py:98-127 (helper)

  create_invoker('claude') factory returns the ClaudeInvoker instance used in tool execution.
  def create_invoker( cli_type: CLIType | str, event_callback: EventCallback | None = None, ) -> CLIInvoker: """创建指定 CLI 的调用器实例。 Args: cli_type: CLI 类型 event_callback: 可选的事件回调函数 Returns: 对应的调用器实例 Raises: ValueError: 不支持的 CLI 类型 """ if isinstance(cli_type, str): cli_type = CLIType(cli_type.lower()) if cli_type == CLIType.CODEX: return CodexInvoker(event_callback=event_callback) elif cli_type == CLIType.GEMINI: return GeminiInvoker(event_callback=event_callback) elif cli_type == CLIType.CLAUDE: return ClaudeInvoker(event_callback=event_callback) elif cli_type == CLIType.OPENCODE: return OpencodeInvoker(event_callback=event_callback) else: raise ValueError(f"Unsupported CLI type: {cli_type}")
• shared/invokers/types.py:132-147 (helper)

  ClaudeParams dataclass defines the typed parameters for Claude tool calls.
  @dataclass class ClaudeParams(CommonParams): """Claude CLI 参数。 继承公共参数，增加 Claude 特有参数。 Attributes: system_prompt: 覆盖默认系统提示词 append_system_prompt: 追加到默认系统提示词末尾 agent: 指定 agent 名称（覆盖默认 agent 设置） """ system_prompt: str = "" append_system_prompt: str = "" agent: str = ""
• src/cli_agent_mcp/server.py:98-114 (registration)

  TOOL_DESCRIPTIONS['claude'] provides the detailed description used when registering the tool.
  "claude": """Invoke Anthropic Claude CLI agent for code implementation. CAPABILITIES: - Strongest code writing and implementation abilities - Excellent at translating requirements into working code - Good at following patterns and conventions LIMITATIONS: - May leave compatibility shims or legacy code paths - Sometimes adds unnecessary backwards-compatibility BEST PRACTICES: - Be explicit about target: "Replace old implementation completely" - Specify cleanup: "Remove deprecated code paths" - Use for: Feature implementation, refactoring, code generation SUPPORTS: Custom system prompts via system_prompt or append_system_prompt, agent selection via agent parameter""",