feat: add Model Context Protocol (MCP) support

README.md

@@ -158,6 +158,8 @@ You can find more [Demos][docs-demos] and [Examples][docs-examples] in the [docu
   - Can see images referenced in prompts, screenshots of your desktop, and web pages.
 - 🔄 Self-correcting
   - Output is fed back to the assistant, allowing it to respond and self-correct.
+- 🔌 MCP Support
+  - Can run as a [Model Context Protocol][mcp] server, allowing other applications to use gptme's capabilities.
 - 🤖 Support for several LLM [providers][docs-providers]
   - Use OpenAI, Anthropic, OpenRouter, or serve locally with `llama.cpp`
 - 💬 Web UI frontend and REST API (optional, see docs for [server][docs-server])

docs/examples.rst

@@ -63,4 +63,18 @@ Generate docstrings for all functions in a file:
 
    gptme --non-interactive "Patch these files to include concise docstrings for all functions, skip functions that already have docstrings. Include: brief description, parameters." $@
 
+.. rubric:: MCP Server
+
+Run gptme as an MCP server to expose its capabilities to other applications:
+
+.. code-block:: bash
+
+   # Run with a workspace
+   gptme-mcp-server --workspace ~/workspace
+
+   # Run with verbose logging
+   gptme-mcp-server -v
+
+For detailed MCP examples and configuration, see :doc:`examples/mcp`.
+
 These examples demonstrate how gptme can be used to create simple yet powerful automation tools. Each script can be easily customized and expanded to fit specific project needs.

docs/examples/mcp.rst

@@ -0,0 +1,70 @@
+MCP Examples
+===========
+
+This page contains examples of using gptme as a Model Context Protocol (MCP) server.
+
+Claude Desktop Integration
+------------------------
+
+Here's how to configure Claude Desktop to use gptme's capabilities through MCP:
+
+1. Install gptme::
+
+    pipx install gptme
+
+2. Create configuration file:
+
+.. literalinclude:: mcp/claude_desktop_config.json
+   :language: json
+   :caption: claude_desktop_config.json
+
+3. Copy to appropriate location:
+
+   - macOS: ``~/Library/Application Support/Claude/claude_desktop_config.json``
+   - Windows: ``%APPDATA%\Claude\claude_desktop_config.json``
+
+4. Replace environment variables:
+
+   - ``${OPENAI_API_KEY}`` with your OpenAI API key
+   - ``${ANTHROPIC_API_KEY}`` with your Anthropic API key
+   - Adjust the workspace path as needed
+
+5. Restart Claude Desktop
+
+Example Usage
+-----------
+
+Once configured, you can ask Claude to use gptme's capabilities:
+
+Code Execution
+^^^^^^^^^^^^^
+
+.. code-block:: text
+
+    Can you write a Python script that generates a Mandelbrot set visualization?
+
+File Operations
+^^^^^^^^^^^^^^
+
+.. code-block:: text
+
+    Can you read my .gitconfig and suggest improvements?
+
+Web Browsing
+^^^^^^^^^^^
+
+.. code-block:: text
+
+    Can you check the ActivityWatch website and tell me what the latest version is?
+
+Security Considerations
+---------------------
+
+The MCP server:
+
+- Runs with your user permissions
+- Has access to your API keys through environment variables
+- Can access files in the configured workspace
+- Requires confirmation for sensitive operations
+
+For more details, see the :doc:`../mcp` documentation.

docs/examples/mcp/claude_desktop_config.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "gptme": {
+      "command": "gptme-mcp-server",
+      "args": ["--workspace", "~/workspace"],
+      "env": {
+        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
+        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
+      }
+    }
+  }
+}

docs/index.rst

@@ -25,6 +25,7 @@ See the `README <https://github.com/ErikBjare/gptme/blob/master/README.md>`_ fil
    config
    providers
    server
+   mcp
    automation
    cli
 

docs/mcp.rst

@@ -0,0 +1,100 @@
+MCP Support
+==========
+
+gptme can run as a Model Context Protocol (MCP) server, allowing other applications to use its capabilities through a standardized protocol.
+
+What is MCP?
+-----------
+
+The `Model Context Protocol <https://modelcontextprotocol.io/>`_ (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. It provides a standardized way for applications to:
+
+- Access resources (files, data)
+- Execute tools (commands, operations)
+- Use prompt templates
+- Request LLM completions
+
+Running as MCP Server
+-------------------
+
+To run gptme as an MCP server::
+
+    gptme-mcp-server [OPTIONS]
+
+Options:
+  -w, --workspace PATH  Path to workspace directory
+  -v, --verbose        Enable verbose logging
+  --help              Show this message and exit
+
+The server will start and listen on stdin/stdout using the MCP protocol.
+
+Integration with Claude Desktop
+----------------------------
+
+To use gptme with Claude Desktop:
+
+1. Install gptme with MCP support::
+
+    pipx install gptme
+
+2. Add to Claude Desktop config (``~/Library/Application Support/Claude/claude_desktop_config.json``)::
+
+    {
+      "mcpServers": {
+        "gptme": {
+          "command": "gptme-mcp-server",
+          "args": ["--workspace", "/path/to/workspace"]
+        }
+      }
+    }
+
+3. Restart Claude Desktop
+
+Now Claude can use all of gptme's capabilities through the MCP protocol.
+
+Available Capabilities
+-------------------
+
+The gptme MCP server exposes:
+
+- **Tools**: All gptme tools (shell, python, browser, etc.)
+- **Resources**: Access to workspace files and data
+- **Prompts**: Common prompt templates (coming soon)
+
+Implementation Details
+-------------------
+
+The MCP implementation in gptme follows the protocol specification for:
+
+- JSON-RPC message format
+- Capability negotiation
+- Resource and tool discovery
+- Error handling
+- Progress reporting
+
+For developers interested in the implementation details, see:
+
+- ``gptme/mcp/types.py`` - Core protocol types
+- ``gptme/mcp/transport.py`` - Transport layer (stdio)
+- ``gptme/mcp/server.py`` - Server implementation
+- ``gptme/mcp/__init__.py`` - gptme integration
+
+Security Considerations
+--------------------
+
+The MCP server inherits gptme's security model:
+
+- Tools run with user permissions
+- Resource access limited to workspace
+- Human approval required for sensitive operations
+- No remote code execution without approval
+
+Future Plans
+----------
+
+Planned improvements to MCP support:
+
+- Support for prompt templates
+- Enhanced resource capabilities
+- Better progress reporting
+- Additional transport options
+- More granular permissions

gptme/mcp/__init__.py

@@ -0,0 +1,145 @@
+"""
+Model Context Protocol (MCP) integration for gptme.
+
+This module provides MCP server implementation that exposes gptme's tools
+and capabilities through the standardized Model Context Protocol.
+"""
+
+import logging
+import asyncio
+from pathlib import Path
+from typing import Any
+
+from .types import (
+    ServerInfo,
+    InitializationOptions,
+    Tool,
+    McpError,
+    ErrorCode,
+)
+from .server import Server, RequestContext
+from .transport import StdioTransport
+
+from ..tools import get_tool
+from ..tools.base import ToolSpec as GptmeTool
+
+logger = logging.getLogger(__name__)
+
+
+class GptmeMcpServer(Server):
+    """MCP server implementation for gptme"""
+
+    def __init__(self, workspace: Path | None = None):
+        self.workspace = workspace
+        self.tools: dict[str, GptmeTool] = {}
+
+        # Initialize tools one by one
+        for tool_name in ["shell", "python", "browser", "vision"]:
+            if tool := get_tool(tool_name):
+                self.tools[tool_name] = tool
+
+        info = ServerInfo(
+            name="gptme",
+            version="0.1.0",  # TODO: Get from package version
+        )
+
+        options = InitializationOptions(
+            capabilities={
+                "tools": {},  # Enable tools capability
+                "resources": {},  # Enable resources capability
+            }
+        )
+
+        super().__init__(info, options)
+
+    def _tool_to_mcp(self, tool: GptmeTool) -> Tool:
+        """Convert a gptme tool to MCP tool format"""
+        return Tool(
+            name=tool.name,
+            description=tool.__doc__ or "",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "command": {"type": "string", "description": "Command to execute"}
+                },
+            },
+        )
+
+    async def _handle_list_tools(self, context: RequestContext) -> dict[str, Any]:
+        """Handle tools/list request"""
+        mcp_tools = [self._tool_to_mcp(tool) for tool in self.tools.values()]
+        return {"tools": mcp_tools}
+
+    async def _handle_call_tool(self, context: RequestContext) -> dict[str, Any]:
+        """Handle tools/call request"""
+        name = context.params.get("name")
+        if not name:
+            raise McpError(ErrorCode.INVALID_PARAMS, "Tool name required")
+
+        tool = self.tools.get(name)
+        if not tool:
+            raise McpError(ErrorCode.INVALID_PARAMS, f"Tool not found: {name}")
+
+        args = context.params.get("arguments", {})
+        command = args.get("command")
+        if not command:
+            raise McpError(ErrorCode.INVALID_PARAMS, "Command required")
+
+        try:
+            # Check if tool is executable
+            if tool.execute is None:
+                return {
+                    "content": {"type": "text", "text": "Tool not executable"},
+                    "isError": True,
+                }
+
+            # Execute tool and handle both Message and Generator[Message] returns
+            result = tool.execute(command, [], lambda _: True)
+            if result is None:
+                return {
+                    "content": {"type": "text", "text": "No output"},
+                    "isError": True,
+                }
+
+            messages = [result] if not hasattr(result, "__iter__") else list(result)
+            if not messages:
+                return {
+                    "content": {"type": "text", "text": "No output"},
+                    "isError": True,
+                }
+
+            first_msg = messages[0]
+            return {
+                "content": {
+                    "type": "text",
+                    "text": first_msg.content,
+                }
+            }
+        except Exception as e:
+            logger.exception("Error executing tool")
+            return {
+                "content": {"type": "text", "text": f"Error: {str(e)}"},
+                "isError": True,
+            }
+
+
+async def run_server(workspace: Path | None = None) -> None:
+    """Run the gptme MCP server"""
+    server = GptmeMcpServer(workspace)
+    transport = StdioTransport()
+
+    try:
+        await server.start(transport)
+    except Exception:
+        logger.exception("Server error")
+        raise
+
+
+def main() -> None:
+    """Main entry point for running the MCP server"""
+    logging.basicConfig(level=logging.INFO)
+    asyncio.run(run_server())
+
+
+if __name__ == "__main__":
+    main()