cwilkins-godaddy/mcp-py

Python MCP Server

A simple MCP (Model Context Protocol) server implementation in Python.

Architecture Overview

Features

• StdIO-based communication (for Claude Code integration)
• Modular tool-based API system
• Configuration-driven tool management
• Asynchronous operation
• Comprehensive test suite

Requirements

• Python 3.7+
• pyyaml
• pytest (for testing)

Installation

pip install pyyaml pytest pytest-asyncio

Usage

Starting the server

python src/mcp_stdio_server.py

Running the test client

python src/mcp_stdio_client.py  # StdIO client

Configuration

The server can be configured using the config.yaml file in the project root:

# Server settings
server:
  host: localhost
  port: 8765
  log_level: INFO

# Tool settings
tools:
  hello_world:
    enabled: true  # Enable or disable specific tools

Adding new tools

To create a new tool:

1. Create a new Python file in src/tools/
2. Create a class that inherits from Tool
3. Implement the required methods:
   • name property (required)
   • description property (optional)
   • enabled property (optional, defaults to True)
   • execute method (required)

Example:

from tools import Tool

class MyNewTool(Tool):
    @property
    def name(self):
        return "my_new_tool"
        
    @property
    def description(self):
        return "Description of my new tool"
        
    async def execute(self, params, client_id):
        # Tool implementation here
        result = {"key": "value"}
        return result

The tool will be automatically discovered and registered when the server starts!

Testing

Run the test suite with:

pytest

Or for more detailed output:

pytest -v

Protocol

The MCP server uses a simple JSON-based protocol:

Tool Call Request

{
  "id": "unique-request-id",
  "type": "tool_call",
  "tool": "tool_name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

List Tools Request

{
  "id": "unique-request-id",
  "type": "list_tools"
}

List Tools Response

{
  "id": "unique-request-id",
  "type": "tool_response",
  "status": "success",
  "result": {
    "tools": [
      {
        "name": "tool_name",
        "description": "Tool description",
        "class": "ToolClassName"
      }
    ]
  }
}

Tool Response

{
  "id": "unique-request-id",
  "type": "tool_response",
  "status": "success",
  "result": {
    "key1": "value1",
    "key2": "value2"
  }
}

Error Response

{
  "id": "unique-request-id",
  "type": "error",
  "error": "Error message"
}

Available Tools

• hello_world - Returns a simple greeting message
• echo - Echoes back the "message" parameter
• calculate - Performs basic arithmetic operations:
  • Parameters:
    • operation: One of "add", "subtract", "multiply", "divide"
    • x: First number
    • y: Second number
  • Returns: Result of the operation including the input parameters
• random_number - Generates random numbers:
  • Parameters:
    • min: Minimum value (default: 0)
    • max: Maximum value (default: 100)
    • count: Number of random values to generate (default: 1)
  • Returns: List of random numbers and the input parameters