MCP Server POC

A cutting-edge Proof of Concept (POC) implementation of a Model Context Protocol (MCP) server using Python and modern technologies. This server provides tools and resources that can be accessed by AI assistants and other MCP clients.

🏗️ Architecture

The MCP Server follows a modular architecture with clear separation of concerns:

graph TB
    subgraph "Client Layer"
        AI[AI Assistant/Client]
        CLI[CLI Client]
    end
    
    subgraph "Transport Layer"
        STDIO[STDIO Transport]
        HTTP[HTTP Transport - Future]
    end
    
    subgraph "MCP Server Core"
        SERVER[MCP Server Instance]
        HANDLER[Request Handler]
        TOOLS[Tools Registry]
        RESOURCES[Resources Registry]
    end
    
    subgraph "Tool Implementations"
        CALC[Calculate Tool]
        FETCH[Fetch URL Tool]
        SYSINFO[System Info Tool]
        PROCESS[Process Data Tool]
        FILE[File Operations Tool]
    end
    
    subgraph "Resource Providers"
        FILE_RES[File Resources]
        CONFIG_RES[Config Resources]
    end
    
    subgraph "External Services"
        HTTP_API[HTTP APIs]
        FILE_SYS[File System]
    end
    
    AI --> STDIO
    CLI --> STDIO
    STDIO --> SERVER
    SERVER --> HANDLER
    HANDLER --> TOOLS
    HANDLER --> RESOURCES
    TOOLS --> CALC
    TOOLS --> FETCH
    TOOLS --> SYSINFO
    TOOLS --> PROCESS
    TOOLS --> FILE
    RESOURCES --> FILE_RES
    RESOURCES --> CONFIG_RES
    FETCH --> HTTP_API
    FILE --> FILE_SYS
    FILE_RES --> FILE_SYS

Workflow Diagram

sequenceDiagram
    participant Client
    participant Transport
    participant Server
    participant Tool
    participant Resource
    
    Client->>Transport: Initialize Connection
    Transport->>Server: Connection Established
    Client->>Server: List Tools Request
    Server->>Client: Tools List Response
    Client->>Server: List Resources Request
    Server->>Client: Resources List Response
    Client->>Server: Call Tool Request
    Server->>Tool: Execute Tool
    Tool->>Server: Tool Result
    Server->>Client: Tool Response
    Client->>Server: Read Resource Request
    Server->>Resource: Fetch Resource
    Resource->>Server: Resource Data
    Server->>Client: Resource Response

🚀 Features

Modern Python Stack: Built with Python 3.10+ and async/await patterns
Type Safety: Full type hints with Pydantic models
High Performance: Uses uvloop for enhanced async performance
Comprehensive Tools: Multiple example tools demonstrating various capabilities
Resource Management: File and configuration resource providers
Testing: Complete test suite with pytest
Configuration: Environment-based configuration management

📋 Prerequisites

Python 3.10 or higher
pip or poetry for package management
Git (for cloning the repository)

🛠️ Installation

Step 1: Clone the Repository

git clone <repository-url>
cd MCP-server

Step 2: Create Virtual Environment

# Using venv
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Or using conda
conda create -n mcp-server python=3.10
conda activate mcp-server

Step 3: Install Dependencies

# Using pip
pip install -r requirements.txt

# For development (includes testing tools)
pip install -r requirements-dev.txt

# Or using poetry (if you prefer)
poetry install

Step 4: Configure Environment

# Copy example environment file
cp .env.example .env

# Edit .env file with your settings (optional)
# nano .env

🧪 Testing

Run All Tests

pytest

Run Tests with Coverage

pytest --cov=src --cov-report=html

Run Specific Test

pytest tests/test_server.py::test_calculate_tool -v

🎯 Usage

Running the Server

Method 1: Direct Python Execution

python -m src.server

Method 2: Using the Script

python scripts/run_server.py

Method 3: As a Module

python -m src.server

Example Client Usage

Run the example client to see the server in action:

python examples/example_client.py

Available Tools

The server provides the following tools:

calculate: Perform mathematical calculations
- Input: {"expression": "2 + 2"}
- Output: Calculation result
fetch_url: Fetch content from URLs
- Input: {"url": "https://example.com", "method": "GET"}
- Output: HTTP response content
get_system_info: Get system information
- Input: {}
- Output: System details and environment variables
process_data: Process and transform data
- Input: {"data": "hello", "operation": "uppercase"}
- Operations: reverse, uppercase, lowercase, count
write_file: Write content to files
- Input: {"filepath": "output.txt", "content": "Hello World"}
- Output: Confirmation message

Available Resources

Example File: file://example.txt - Example file resource
Server Configuration: config://server-config - Current server configuration

📁 Project Structure

MCP-server/
├── src/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main MCP server implementation
│   └── config.py            # Configuration management
├── tests/
│   ├── __init__.py
│   └── test_server.py       # Unit tests
├── examples/
│   └── example_client.py    # Example client implementation
├── scripts/
│   └── run_server.py        # Server runner script
├── .env.example             # Example environment configuration
├── .gitignore               # Git ignore rules
├── pyproject.toml           # Project metadata and dependencies
├── pytest.ini              # Pytest configuration
├── requirements.txt         # Production dependencies
├── requirements-dev.txt     # Development dependencies
└── README.md               # This file

🔧 Configuration

The server can be configured using environment variables:

MCP_SERVER_NAME: Server name (default: mcp-server-poc)
MCP_SERVER_VERSION: Server version (default: 0.1.0)
LOG_LEVEL: Logging level (default: INFO)
ENABLE_METRICS: Enable metrics collection (default: true)

🧩 Technology Stack

MCP SDK: Official Model Context Protocol SDK for Python
Pydantic: Data validation and settings management
httpx: Modern async HTTP client
aiofiles: Async file operations
uvloop: High-performance event loop
pytest: Testing framework
python-dotenv: Environment variable management

🔍 Development

Code Formatting

# Format code with black
black src/ tests/ examples/

# Lint with ruff
ruff check src/ tests/

# Type checking with mypy
mypy src/

Adding New Tools

Add tool definition in list_tools() function
Implement tool logic in call_tool() function
Add tests in tests/test_server.py

Example:

# In list_tools()
Tool(
    name="my_new_tool",
    description="Description of my tool",
    inputSchema={
        "type": "object",
        "properties": {
            "param": {"type": "string"}
        },
        "required": ["param"]
    }
)

# In call_tool()
elif name == "my_new_tool":
    param = arguments.get("param")
    # Your tool logic here
    return [TextContent(type="text", text=f"Result: {result}")]

🐛 Troubleshooting

Common Issues

Import Errors: Ensure all dependencies are installed
```
pip install -r requirements.txt
```
Python Version: Ensure Python 3.10+ is being used
```
python --version
```
Virtual Environment: Make sure virtual environment is activated
```
source venv/bin/activate
```
Permission Errors: Check file permissions for write operations

📝 License

See LICENSE file for details.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📚 Additional Resources

🎉 Next Steps

Add more sophisticated tools (database queries, API integrations)
Implement authentication and authorization
Add metrics and monitoring
Support for streaming responses
WebSocket transport support
Resource caching and optimization

Note: This is a POC project. For production use, consider adding:

Proper error handling and logging
Security measures (authentication, input validation)
Rate limiting
Comprehensive monitoring
Documentation generation
CI/CD pipelines