# 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:

```mermaid
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

```mermaid
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

```bash
git clone <repository-url>
cd MCP-server
```

### Step 2: Create Virtual Environment

```bash
# 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

```bash
# 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

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

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

## 🧪 Testing

### Run All Tests

```bash
pytest
```

### Run Tests with Coverage

```bash
pytest --cov=src --cov-report=html
```

### Run Specific Test

```bash
pytest tests/test_server.py::test_calculate_tool -v
```

## 🎯 Usage

### Running the Server

#### Method 1: Direct Python Execution

```bash
python -m src.server
```

#### Method 2: Using the Script

```bash
python scripts/run_server.py
```

#### Method 3: As a Module

```bash
python -m src.server
```

### Example Client Usage

Run the example client to see the server in action:

```bash
python examples/example_client.py
```

### Available Tools

The server provides the following tools:

1. **calculate**: Perform mathematical calculations
   - Input: `{"expression": "2 + 2"}`
   - Output: Calculation result

2. **fetch_url**: Fetch content from URLs
   - Input: `{"url": "https://example.com", "method": "GET"}`
   - Output: HTTP response content

3. **get_system_info**: Get system information
   - Input: `{}`
   - Output: System details and environment variables

4. **process_data**: Process and transform data
   - Input: `{"data": "hello", "operation": "uppercase"}`
   - Operations: `reverse`, `uppercase`, `lowercase`, `count`

5. **write_file**: Write content to files
   - Input: `{"filepath": "output.txt", "content": "Hello World"}`
   - Output: Confirmation message

### Available Resources

1. **Example File**: `file://example.txt` - Example file resource
2. **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

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

# Lint with ruff
ruff check src/ tests/

# Type checking with mypy
mypy src/
```

### Adding New Tools

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

Example:

```python
# 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

1. **Import Errors**: Ensure all dependencies are installed
   ```bash
   pip install -r requirements.txt
   ```

2. **Python Version**: Ensure Python 3.10+ is being used
   ```bash
   python --version
   ```

3. **Virtual Environment**: Make sure virtual environment is activated
   ```bash
   source venv/bin/activate
   ```

4. **Permission Errors**: Check file permissions for write operations

## 📝 License

See LICENSE file for details.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📚 Additional Resources

- [MCP Documentation](https://modelcontextprotocol.io)
- [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Pydantic Documentation](https://docs.pydantic.dev)

## 🎉 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