From 20916c5713b3a047f4a8a33194f751f36e3c8a7a Mon Sep 17 00:00:00 2001 From: Mathieu Virbel Date: Wed, 12 Mar 2025 18:45:06 -0600 Subject: [PATCH] docs(mcp): add specification for MCP server support --- .../specs/1_SPECIFICATIONS.md | 0 docs/specs/2_MCP_SERVER.md | 134 ++++++++++++++++++ 2 files changed, 134 insertions(+) rename SPECIFICATIONS.md => docs/specs/1_SPECIFICATIONS.md (100%) create mode 100644 docs/specs/2_MCP_SERVER.md diff --git a/SPECIFICATIONS.md b/docs/specs/1_SPECIFICATIONS.md similarity index 100% rename from SPECIFICATIONS.md rename to docs/specs/1_SPECIFICATIONS.md diff --git a/docs/specs/2_MCP_SERVER.md b/docs/specs/2_MCP_SERVER.md new file mode 100644 index 0000000..4e76631 --- /dev/null +++ b/docs/specs/2_MCP_SERVER.md @@ -0,0 +1,134 @@ +# MCP Server Specification + +## Overview + +This document specifies the implementation for Model Control Protocol (MCP) server support in the Monadical Container (MC) system. The MCP server feature allows users to connect, build, and manage external MCP servers that can be attached to MC sessions. + +An MCP server is a local (stdio) or remote (HTTP SSE server) service that can be accessed by a driver (such as Goose or Claude Code) to extend the LLM's capabilities through tool calls. + +## Key Features + +1. Support multiple types of MCP servers: + - Remote HTTP SSE servers + - Local container-based servers + - Local container with MCP proxy for stdio-to-SSE conversion + +2. Persistent MCP containers that can be: + - Started/stopped independently of sessions + - Connected to multiple sessions + - Automatically started when referenced in a session creation + +3. Management of MCP server configurations and containers + +## MCP Configuration Model + +The MCP configuration will be stored in the user configuration file and will include: + +```yaml +mcps: + - name: github + type: docker + image: mcp/github + command: "github-mcp" + env: + - GITHUB_TOKEN: "your-token-here" + + - name: proxy-example + type: proxy + base_image: ghcr.io/mcp/github:latest + proxy_image: ghcr.io/sparfenyuk/mcp-proxy:latest + command: "github-mcp" + proxy_options: + sse_port: 8080 + sse_host: "0.0.0.0" + allow_origin: "*" + env: + - GITHUB_TOKEN: "your-token-here" + + - name: remote-mcp + type: remote + url: "http://mcp-server.example.com/sse" + headers: + - Authorization: "Bearer your-token-here" +``` + +## CLI Commands + +### MCP Management + +``` +mc mcp list # List all configured MCP servers and their status +mc mcp status # Show detailed status of a specific MCP server +mc mcp start # Start an MCP server container +mc mcp stop # Stop an MCP server container +mc mcp restart # Restart an MCP server container +mc mcp logs # Show logs for an MCP server container +``` + +### MCP Configuration + +``` +mc mcp remote add [--header KEY=VALUE...] # Add a remote MCP server +mc mcp docker add [--command CMD] [--env KEY=VALUE...] # Add a Docker-based MCP +mc mcp proxy add [--proxy-image IMG] [--command CMD] [--sse-port PORT] [--sse-host HOST] [--allow-origin ORIGIN] [--env KEY=VALUE...] # Add a proxied MCP +mc mcp remove # Remove an MCP configuration +``` + +### Session Integration + +``` +mc session create [--mcp ] # Create a session with an MCP server attached +``` + +## Implementation Details + +### MCP Container Management + +1. MCP containers will have their own dedicated Docker network +2. Session containers will be attached to both their session network and the MCP network when using an MCP +3. MCP containers will be persistent across sessions unless explicitly stopped +4. MCP containers will be named with a prefix to identify them (`mc_mcp_`) + +### Docker-based MCP Servers + +For Docker-based MCP servers: +1. Pull the specified image +2. Create a dedicated network if it doesn't exist +3. Run the container with the specified environment variables and command + +### Proxy-based MCP Servers + +For proxy-based MCP servers: +1. Create a custom Dockerfile that: + - Uses the specified proxy image as the base + - Installs Docker-in-Docker capabilities + - Sets up the base MCP server image + - Configures the entrypoint to run the MCP proxy with the right parameters +2. Build the custom image +3. Run the container with the appropriate environment variables + +### Remote MCP Servers + +For remote MCP servers: +1. Store the URL and headers +2. Provide these to the session container when connecting + +## Session Integration + +When a session is created with an MCP server: +1. If the MCP server is not running, start it automatically +2. Connect the session container to the MCP server's network +3. Set the appropriate environment variables in the session to enable MCP connectivity + +## Security Considerations + +1. MCP server credentials and tokens should be handled securely through environment variables +2. Network isolation should be maintained between different MCP servers +3. Consider options for access control between sessions and MCP servers + +## Future Enhancements + +1. Support for MCP server version management +2. Health checking and automatic restart capabilities +3. Support for MCP server clusters or load balancing +4. Integration with monitoring systems \ No newline at end of file