feat: Add mcp tools support

[yuchou87]

Add Model Context Protocol (MCP) Integration with Docker Support

Overview

This PR introduces comprehensive Model Context Protocol (MCP) integration to picoclaw, enabling dynamic tool registration from external MCP servers. Additionally, it provides production-ready Docker deployment options with full MCP runtime support.

Key Features

MCP Integration

• MCP SDK Integration: Implemented using github.com/modelcontextprotocol/go-sdk v1.3.0
• Multiple Transport Protocols: Support for stdio (subprocess), SSE, and HTTP transports
• Automatic Tool Registration: MCP tools are automatically registered to the agent with mcp_{server}_{tool} naming convention
• Environment Management: Support for both inline environment variables and .env file loading with proper priority handling
• HTTP Headers Support: Custom header injection for HTTP/SSE transport modes
• Resource Cleanup: Proper lifecycle management with automatic cleanup on agent shutdown

Docker Support

• Dual Image Strategy:
  • Minimal Image (Alpine-based): Lightweight runtime (~30MB) for basic deployments
  • Full Image (Node.js 24): Complete MCP tooling support including npx, npm, git, python3, and uv
• Separate Compose Files: Independent docker-compose.yml (minimal) and docker-compose.full.yml (full-featured)
• Makefile Integration: Convenient targets for building, running, and testing Docker containers
• MCP Tool Validation: Automated test script to verify all MCP tools are properly installed

Configuration Enhancements

• Added tools.mcp section to configuration schema
• Provided 5 example MCP server configurations in config.example.json
• Support for envFile paths with environment variable merging (envFile < config.Env priority)
• Global MCP enable/disable switch with tools.mcp.enabled

Technical Changes

Core Implementation

• pkg/mcp/manager.go (432 lines): MCP server connection manager with transport auto-detection
• pkg/tools/mcp_tool.go (119 lines): MCP tool wrapper for agent integration
• pkg/agent/loop.go: Integrated MCP manager with tool registration loop and cleanup
• pkg/config/config.go: Extended configuration schema with MCPServerConfig struct

Docker Infrastructure

• Dockerfile.full (46 lines): Node.js 24-based image with git, python3, and uv
• docker-compose.full.yml (44 lines): Full-featured compose configuration with npm-cache volume
• scripts/test-docker-mcp.sh (49 lines): Validation script for MCP tools
• Makefile: Added docker-* targets for build, run, and test operations

Testing

• pkg/mcp/manager_test.go (182 lines): 9 comprehensive tests for envFile parsing and configuration
• pkg/tools/mcp_tool_test.go (456 lines): Integration tests for MCP tool execution

Statistics

• 13 files changed: 1,543 insertions(+), 5 deletions(-)
• Major additions:
  • MCP implementation: 1,189 lines (manager + tools + tests)
  • Docker support: 139 lines (Dockerfile.full + compose + scripts)
  • Configuration examples: 57 lines

Bug Fixes

• Fixed uv installation path with proper symlinks to /usr/local/bin
• Resolved Docker Compose v2 migration (all commands use docker compose instead of docker-compose)
• Fixed "No services to build" error by using explicit service names
• Corrected test script permissions and entrypoint override for non-interactive testing
• Fixed go.mod formatting

Testing

• ✅ All existing tests passing
• ✅ 9 new MCP manager tests
• ✅ 456 lines of MCP tool integration tests
• ✅ Docker builds successful (both minimal and full images)
• ✅ MCP tools verified: npx v11.8.0, npm v11.8.0, node v24.13.1, git v2.39.5, python 3.11.2, uv

Usage Examples

Build and Run with Docker

# Build full-featured Docker image
make docker-build-full

# Run interactive agent with MCP support
make docker-run-agent-full

# Test MCP tools installation
make docker-test

Configuration Example

Add MCP servers to your config.json:

{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "filesystem": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
          "env": {}
        },
        "brave-search": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-brave-search"],
          "env": {
            "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY"
          },
          "envFile": ".env"
        }
      }
    }
  }
}

Breaking Changes

None. This is a purely additive feature that maintains full backward compatibility.

[Copilot]

Pull request overview

This PR adds Model Context Protocol (MCP) support to picoclaw by introducing an MCP connection manager, wrapping MCP tools into the existing tool system, and providing “full” Docker tooling/runtime artifacts to run MCP servers (e.g., via npx) in containers.

Changes:

• Added MCP server manager (pkg/mcp) with stdio and SSE/HTTP transports, env/envFile support, and tool discovery.
• Added MCP tool wrapper (pkg/tools) and integrated MCP tool registration + cleanup into the agent loop.
• Added Docker “full” runtime support (Dockerfile + compose + test script) and updated config examples / Makefile targets.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
scripts/test-docker-mcp.sh	Adds a Docker Compose-based validation script for MCP runtime tools (npx/npm/node/git/python/uv).
pkg/tools/mcp_tool.go	Introduces MCPTool wrapper implementing the project Tool interface.
pkg/tools/mcp_tool_test.go	Adds unit/integration-style tests for MCPTool behavior and content extraction.
pkg/mcp/manager.go	Adds MCP Manager to connect to servers, list tools, call tools, and close connections.
pkg/mcp/manager_test.go	Adds tests for .env parsing and envFile/config merge priority.
pkg/agent/loop.go	Initializes MCP manager, registers MCP tools, and attempts cleanup on Stop().
pkg/config/config.go	Extends config schema with tools.mcp and server definitions.
config/config.example.json	Adds MCP configuration examples (including envFile and headers).
Dockerfile.full	Adds a Node-based runtime image with additional tooling for MCP servers.
docker-compose.full.yml	Adds a “full” compose setup for agent and gateway using Dockerfile.full.
Makefile	Adds docker build/run/test/clean targets (minimal + full).
go.mod	Adds MCP SDK dependency and an extra indirect require line.
go.sum	Adds checksums for newly introduced dependencies.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Danieldd28]

I reviewed this PR from the perspective of PicoClaw's resource optimization goals (RAM usage > binary size). The MCP integration itself is a valuable feature, and the overall architecture is solid lazy initialization via sync.Once, parallel server startup with sync.WaitGroup, and proper cleanup in both defer and
Stop() are all well done. That said, there are several resource-related concerns worth addressing before merge.

1. Duplicate MCP Tool Instances (RAM)

Each MCP tool discovered from a server is instantiated twice -- once for the main agent and once for the subagent:

mcpTool := tools.NewMCPTool(al.mcpManager, serverName, tool)
al.tools.Register(mcpTool)
if al.subagentManager != nil {
    al.subagentManager.RegisterTool(tools.NewMCPTool(al.mcpManager, serverName, tool))
}

While the underlying MCPManager is shared (good), each MCPTool wrapper struct is allocated separately. For a setup with, say, 4 MCP servers exposing 10 tools each, that is 80 struct allocations instead of 40. Each wrapper carries a pointer to the manager, the server name string, and the full *mcp.Tool reference (which includes the input schema).

This compounds an existing architectural issue in PicoClaw where
createToolRegistry()
is already called twice (once for the agent, once for subagent), duplicating all built-in tools as well. This PR extends that pattern to MCP tools.

Recommendation: consider sharing a single read-only tool registry between the agent and subagent, or at minimum use a ToolRegistryView wrapper that filters out spawn/subagent tools instead of cloning the entire registry. If that is out of scope for this PR, it should at least be documented as tracked tech debt.

2. Full Config Reference Retained in AgentLoop (RAM)

The PR adds a new field to
AgentLoop
:

mcpConfig *config.Config

This stores a reference to the entire application config struct for lazy initialization in
Run(). While this is a pointer (so the direct cost is small), it prevents the config object from being garbage collected for the entire lifetime of the agent loop, and it couples the agent more tightly to the full config surface.

Since the only usage is al.mcpManager.LoadFromConfig(ctx, al.mcpConfig), and LoadFromConfig only reads cfg.Tools.MCP and cfg.WorkspacePath(), consider storing just the MCP-specific config:

mcpConfig     config.MCPConfig
workspacePath string

This makes the dependency explicit and allows the rest of the config to be GC'd if nothing else holds it.

3. Default Config Pre-populates Disabled Servers (RAM)

DefaultConfig() now ships with four pre-populated MCP server entries (filesystem, github, brave-search, postgres), all disabled:

MCP: MCPConfig{
    Enabled: false,
    Servers: map[string]MCPServerConfig{
        "filesystem":   { Enabled: false, Command: "npx", Args: [...] },
        "github":       { Enabled: false, Command: "npx", Args: [...], Env: {...} },
        "brave-search": { Enabled: false, Command: "npx", Args: [...], Env: {...} },
        "postgres":     { Enabled: false, Command: "npx", Args: [...] },
    },
},

Every PicoClaw instance allocates this map, its string keys, the MCPServerConfig structs, and their nested slices/maps, even if MCP is never used. The cost per instance is small (a few hundred bytes), but it is unnecessary since these examples already exist in
config/config.example.json
.

4. Dockerfile.full Image Size (Binary/Deployment)

The new Dockerfile.full switches from alpine:3.23 (the base for the existing Dockerfile) to node:24-bookworm-slim and installs Python 3, pip, venv, git, curl, and uv. This is understandable since many MCP servers are Node.js or Python processes, but it transforms PicoClaw's Docker footprint from roughly 15-20MB (Alpine + static Go binary) to an estimated 800MB+.

5. MCP Tool Schema Sent to LLM on Every Call (Token Cost)

When MCP is enabled and servers are connected, every MCP tool's schema is serialized and sent to the LLM on every chat request. For a setup with many MCP servers, this could add significant token overhead. This is inherent to how tool-use works with LLMs, but it is worth considering:

A configurable limit on the maximum number of MCP tools exposed to the LLM at once.
Or a mechanism to selectively enable/disable individual tools per server (beyond the current per-server toggle), so users can prune tools they do not need.
This is not a blocker, but something to keep in mind as MCP adoption grows.

[Leeaandrob]

@Zepan This PR directly addresses roadmap issue #290 (MCP Support — priority: high). MCP is one of the most requested features and is explicitly on the project board.

+1693 lines is substantial but MCP requires protocol implementation, transport layer, and tool registration. Worth a careful review given the scope.

Recommendation: Review and merge. This is a high-priority roadmap item. Consider whether this implementation aligns with the architecture vision before merging.