feat(mcp-proxy): implement F099 MCP proxy stdio subprocess for tool interception

[pocky]

Summary

• Implement F099: MCP proxy stdio subprocess that intercepts and controls tool calls between AWF agents and MCP servers, enabling workflow-level tool filtering, routing, and auditing
• Add awf mcp serve command that spawns a stdio MCP server wrapping AWF plugins, letting any MCP-capable agent (Claude, Gemini, Codex, Copilot, OpenAI-compatible) use AWF tools via standard protocol
• Introduce a full builtin tool suite (bash, glob, grep, read, write, edit) exposed through the MCP proxy layer, with per-step mcp_proxy configuration controlling which tools are available and how operations are routed
• Lay down the supporting infrastructure: pkg/mcpserver JSON-RPC server, internal/application/tools routing/proxy service, internal/infrastructure/tools plugin adapter and schema mapper, plus comprehensive test coverage across all layers

Changes

Domain

• internal/domain/workflow/mcp_proxy.go: New MCPProxy entity defining proxy configuration (enabled flag, allowed tools, plugin bindings, operation routing)
• internal/domain/workflow/mcp_proxy_test.go: Unit tests for MCPProxy entity
• internal/domain/workflow/step.go: Add MCPProxy field to Step entity
• internal/domain/workflow/step_mcp_proxy_validation_test.go: Validation tests for mcp_proxy step config
• internal/domain/workflow/validation_errors.go: New validation error codes for mcp_proxy configuration
• internal/domain/workflow/validation_errors_test.go: Tests for new error codes
• internal/domain/workflow/workflow.go: Wire mcp_proxy validation into workflow-level validation
• internal/domain/ports/tool_provider.go: New ToolProvider port interface
• internal/domain/ports/tool_provider_test.go: Tests for ToolProvider port
• internal/domain/ports/cli_executor.go: Extend CLIExecutor port with MCP proxy capability
• internal/domain/ports/cli_executor_test.go: Update tests for extended executor
• internal/domain/errors/codes.go: New error codes for tool proxy and MCP operations
• internal/domain/errors/codes_test.go: Tests for new error codes

Application

• internal/application/execution_tool_proxy.go: New ExecutionToolProxy coordinating tool interception during step execution
• internal/application/execution_tool_proxy_test.go: Unit tests for tool proxy coordination
• internal/application/execution_service_settoolproxy_test.go: Tests for SetToolProxy wiring on ExecutionService
• internal/application/execution_service.go: Wire tool proxy into step execution lifecycle
• internal/application/execution_setup.go: Initialize and configure tool proxy during execution setup
• internal/application/conversation_manager.go: Pass tool proxy context into conversation execution
• internal/application/service.go: Expose SetToolProxy and tool proxy lifecycle on ApplicationService
• internal/application/tools/proxy_service.go: New ProxyService managing tool routing decisions
• internal/application/tools/proxy_service_test.go: Tests for ProxyService routing logic
• internal/application/tools/router.go: New Router dispatching tool calls to correct provider or builtin
• internal/application/tools/router_test.go: Tests for Router dispatch
• internal/application/tools/config.go: Tool proxy configuration types
• internal/application/tools/doc.go: Package documentation
• internal/application/tools/architecture_test.go: Architecture conformance tests

Infrastructure — Agents (MCP wiring per provider)

• internal/infrastructure/agents/base_cli_provider.go: Add MCP proxy subprocess launch and stdio handshake to base provider
• internal/infrastructure/agents/base_cli_provider_conversation_mcp_test.go: Tests for base provider MCP conversation mode
• internal/infrastructure/agents/claude_provider.go: Wire --mcp-config flag with proxy server address for Claude
• internal/infrastructure/agents/claude_provider_mcp_test.go: Claude MCP flag assembly tests
• internal/infrastructure/agents/gemini_provider.go: Wire MCP proxy config for Gemini
• internal/infrastructure/agents/gemini_provider_mcp_test.go: Gemini MCP tests
• internal/infrastructure/agents/codex_provider.go: Wire MCP proxy for Codex with warning for unsupported stdio
• internal/infrastructure/agents/codex_provider_mcp_test.go: Codex MCP warning tests
• internal/infrastructure/agents/copilot_provider.go: Wire MCP proxy config for Copilot
• internal/infrastructure/agents/copilot_provider_mcp_test.go: Copilot MCP tests
• internal/infrastructure/agents/openai_compatible_provider.go: Full MCP tool call support for OpenAI-compatible providers via API-level tool injection
• internal/infrastructure/agents/openai_compatible_provider_mcp_test.go: OpenAI-compatible MCP tests
• internal/infrastructure/agents/openai_compatible_tools.go: Tool schema serialization for OpenAI tool_calls protocol
• internal/infrastructure/agents/openai_compatible_tools_test.go: Schema serialization tests
• internal/infrastructure/agents/opencode_provider.go: Wire MCP proxy for Opencode via workspace config
• internal/infrastructure/agents/opencode_provider_mcp_test.go: Opencode MCP tests
• internal/infrastructure/agents/opencode_provider_unit_test.go: Refactor unit tests after workspace config extraction
• internal/infrastructure/agents/opencode_workspace_config.go: Extract Opencode workspace config generation (MCP server entries)
• internal/infrastructure/agents/opencode_workspace_config_test.go: Workspace config generation tests
• internal/infrastructure/agents/opencode_workspace_config_windows.go: Windows-compatible workspace config path resolution
• internal/infrastructure/agents/mcp_proxy_name.go: Deterministic proxy server name generation
• internal/infrastructure/agents/mcp_proxy_name_test.go: Tests for proxy name generation
• internal/infrastructure/agents/mcp_proxy_purge.go: Cleanup logic for stale proxy config files after execution
• internal/infrastructure/agents/mcp_proxy_purge_test.go: Purge lifecycle tests
• internal/infrastructure/agents/cli_executor.go: Extend CLIExecutor to spawn and track proxy subprocess
• internal/infrastructure/agents/cli_executor_test.go: CLIExecutor proxy subprocess tests
• internal/infrastructure/agents/options.go: Add ToolProxy option to agent option set
• internal/infrastructure/agents/provider_options_test.go: Tests for tool proxy option wiring
• internal/infrastructure/agents/registry.go: Register tool proxy capability flag on agents
• internal/infrastructure/agents/registry_test.go: Update registry tests for new capability

Infrastructure — Tools

• internal/infrastructure/tools/builtins/bash.go: Builtin bash tool implementation
• internal/infrastructure/tools/builtins/bash_test.go: Bash tool tests
• internal/infrastructure/tools/builtins/edit.go: Builtin edit tool implementation
• internal/infrastructure/tools/builtins/edit_test.go: Edit tool tests
• internal/infrastructure/tools/builtins/glob.go: Builtin glob tool implementation
• internal/infrastructure/tools/builtins/glob_test.go: Glob tool tests
• internal/infrastructure/tools/builtins/grep.go: Builtin grep tool implementation
• internal/infrastructure/tools/builtins/grep_test.go: Grep tool tests
• internal/infrastructure/tools/builtins/read.go: Builtin read tool implementation
• internal/infrastructure/tools/builtins/read_test.go: Read tool tests
• internal/infrastructure/tools/builtins/write.go: Builtin write tool implementation
• internal/infrastructure/tools/builtins/write_test.go: Write tool tests
• internal/infrastructure/tools/builtins/provider.go: BuiltinProvider registering all builtin tools
• internal/infrastructure/tools/builtins/provider_test.go: BuiltinProvider tests
• internal/infrastructure/tools/plugin_adapter.go: Adapter bridging plugin RPC tools into ToolProvider interface
• internal/infrastructure/tools/plugin_adapter_test.go: Plugin adapter tests
• internal/infrastructure/tools/schema_mapper.go: Map AWF tool schemas to MCP JSON Schema format
• internal/infrastructure/tools/schema_mapper_test.go: Schema mapper tests
• internal/infrastructure/tools/doc.go: Package documentation

Infrastructure — Other

• internal/infrastructure/repository/yaml_mapper.go: Parse mcp_proxy YAML stanza into domain entity
• internal/infrastructure/repository/yaml_mapper_mcp_proxy_test.go: YAML mapper tests for mcp_proxy
• internal/infrastructure/repository/yaml_repository.go: Register mcp_proxy types in repository
• internal/infrastructure/repository/yaml_repository_test.go: Repository loading tests
• internal/infrastructure/repository/yaml_types.go: Add YAMLMCPProxy and related YAML struct types
• internal/infrastructure/errors/hint_generators_test.go: Update hint generator tests for new error codes
• internal/infrastructure/notify/desktop.go: Minor desktop notification update
• internal/infrastructure/pluginmgr/rpc_manager.go: Expose plugin tool schemas over RPC for proxy adapter
• internal/infrastructure/pluginmgr/rpc_manager_test.go: Update RPC manager tests
• internal/infrastructure/pluginmgr/stream_manager_test.go: Update stream manager tests

CLI Interface

• internal/interfaces/cli/mcp_serve.go: New awf mcp serve command — starts stdio MCP server wrapping configured plugins
• internal/interfaces/cli/mcp_serve_test.go: Tests for mcp serve command lifecycle
• internal/interfaces/cli/mcp_serve_helpers_test.go: Test helpers for mcp serve
• internal/interfaces/cli/mcp_serve_plugin_test.go: Plugin bridge integration tests for mcp serve
• internal/interfaces/cli/validate_mcp_proxy_test.go: Validation command tests for mcp_proxy step config
• internal/interfaces/cli/root.go: Register mcp serve subcommand
• internal/interfaces/cli/run.go: Pass tool proxy config into run execution path
• internal/interfaces/cli/run_help.go: Update help text
• internal/interfaces/cli/run_notify_config_test.go: Add notify config test
• internal/interfaces/cli/run_pack_wiring_test.go: Update pack wiring test
• internal/interfaces/cli/resume.go: Pass tool proxy into resume execution path
• internal/interfaces/cli/validate.go: Validate mcp_proxy config in validate command
• internal/interfaces/cli/ui/output.go: Add tool call display events to output renderer
• internal/interfaces/cli/history_internal_test.go: Minor fix
• internal/interfaces/cli/list_internal_test.go: Minor fix

Public Package — MCP Server

• pkg/mcpserver/server.go: JSON-RPC 2.0 stdio MCP server implementation
• pkg/mcpserver/server_test.go: Comprehensive server tests
• pkg/mcpserver/protocol.go: MCP protocol message types and JSON-RPC framing
• pkg/mcpserver/protocol_test.go: Protocol serialization tests
• pkg/mcpserver/types.go: Shared MCP type definitions
• pkg/mcpserver/doc.go: Package documentation
• pkg/mcpserver/architecture_test.go: Architecture conformance tests

Public Package — Plugin SDK

• pkg/plugin/sdk/grpc_plugin.go: Extend plugin SDK with tool schema advertisement over gRPC
• pkg/plugin/sdk/grpc_plugin_test.go: gRPC plugin SDK tests
• pkg/plugin/sdk/sdk.go: Expose tool provider interface from SDK
• pkg/plugin/sdk/doc.go: SDK package documentation

Examples & Fixtures

• examples/plugins/awf-plugin-echo/main.go: Update echo plugin to implement tool provider interface
• examples/plugins/awf-plugin-echo/main_test.go: Echo plugin tests
• tests/fixtures/mcp_proxy/mcp-proxy-*.yaml: Validation test fixtures for valid and invalid mcp_proxy configs
• tests/integration/mcp/end_to_end_claude_test.go: End-to-end Claude + MCP proxy test
• tests/integration/mcp/mcp_jsonrpc_e2e_test.go: JSON-RPC protocol end-to-end tests
• tests/integration/mcp/plugin_bridge_test.go: Plugin bridge integration tests
• tests/integration/mcp/subprocess_lifecycle_test.go: Proxy subprocess lifecycle tests

Mocks & Test Utilities

• internal/testutil/mocks/mocks.go: Add mocks for ToolProvider, ProxyService, and MCPServer interfaces

Docs & Config

• docs/ADR/017-mcp-proxy-stdio-subprocess-for-tool-interception.md: ADR documenting the stdio subprocess design decision
• docs/user-guide/mcp-proxy.md: New user guide for mcp_proxy step configuration
• docs/user-guide/agent-steps.md: Document mcp_proxy field in agent steps
• docs/user-guide/plugins.md: Document plugin tool provider capability
• docs/user-guide/workflow-syntax.md: Add mcp_proxy to workflow syntax reference
• docs/development/creating-agent-provider.md: Add MCP proxy integration section for provider authors
• docs/reference/error-codes.md: Document new tool proxy and MCP error codes
• docs/README.md: Link new mcp-proxy guide
• README.md: Mention MCP proxy capability in feature list
• CLAUDE.md: Add architecture rules for MCP proxy patterns
• .go-arch-lint.yml: Register new packages and their dependency rules
• .gitignore: Ignore generated proxy config temp files
• .zpm/kb/default/journal.wal: ZPM knowledge base journal
• .zpm/mounts.json: ZPM mount configuration

Test plan

• make build succeeds and awf mcp serve --help displays the new subcommand
• awf validate rejects invalid mcp_proxy step configs (unknown plugin, name collision, unsupported Codex warning) using fixtures in tests/fixtures/mcp_proxy/
• make test passes with zero failures; make test-race reports no data races in proxy subprocess and MCP server code
• Integration: run tests/integration/mcp/subprocess_lifecycle_test.go to verify proxy subprocess starts, handles JSON-RPC tool calls, and shuts down cleanly

Closes #353

---

Generated with awf commit workflow