# MCP Server - Model Context Protocol Implementation

A comprehensive Python backend implementing the Model Context Protocol (MCP) with JSON-RPC 2.0, Azure OpenAI integration, and Server-Sent Events streaming capabilities.

## Features

- **Complete MCP Protocol Support**: JSON-RPC 2.0 compliant implementation
- **Azure OpenAI Integration**: Seamless connection to Azure OpenAI services
- **Streaming Responses**: Real-time streaming via Server-Sent Events (SSE)
- **Resource Management**: File system resource discovery and access
- **Tool Execution**: Extensible tool registry with validation
- **Authentication**: JWT-based authentication system
- **Monitoring**: Prometheus metrics collection
- **Web Interface**: Built-in testing and management interface

## Architecture

```
├── app/
│   ├── core/
│   │   ├── config.py          # Configuration management
│   │   ├── errors.py          # Custom exception classes
│   │   └── logging.py         # Structured logging setup
│   ├── protocol/
│   │   ├── enums.py           # MCP protocol enumerations
│   │   └── models.py          # Pydantic models for MCP
│   ├── services/
│   │   ├── llm.py             # Azure OpenAI service
│   │   ├── resources.py       # Resource management
│   │   └── tools.py           # Tool registry and execution
│   ├── transport/
│   │   └── http.py            # HTTP transport layer
│   ├── auth.py                # JWT authentication
│   └── metrics.py             # Prometheus metrics
├── static/
│   └── app.js                 # Frontend JavaScript
├── templates/
│   └── index.html             # Web interface
├── main.py                    # Application entry point
└── server.py                  # Flask app configuration
```

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd mcp-server
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Set up environment variables:
```bash
# Required for Azure OpenAI
export OPENAI_API_KEY="your-azure-openai-api-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export AZURE_OPENAI_DEPLOYMENT="your-deployment-name"
export AZURE_OPENAI_API_VERSION="2024-08-01-preview"

# Optional configurations
export JWT_SECRET="your-jwt-secret"
export SESSION_SECRET="your-session-secret"
```

## Configuration

The server supports both Azure OpenAI and standard OpenAI configurations:

### Azure OpenAI (Recommended)
```python
USE_AZURE_OPENAI = True
AZURE_OPENAI_ENDPOINT = "https://your-resource.openai.azure.com"
AZURE_OPENAI_DEPLOYMENT = "gpt-4o"
AZURE_OPENAI_API_VERSION = "2024-08-01-preview"
```

### Standard OpenAI
```python
USE_AZURE_OPENAI = False
OPENAI_MODEL = "gpt-4o"
```

## Running the Server

### Development
```bash
python main.py
```

### Production
```bash
gunicorn --bind 0.0.0.0:5000 --reuse-port --reload main:app
```

The server will be available at `http://localhost:5000`

## API Endpoints

### MCP Protocol
- `POST /rpc` - JSON-RPC 2.0 endpoint for MCP requests
- `GET /events` - Server-Sent Events for streaming responses

### Management
- `GET /` - Web interface for testing and management
- `GET /health` - Health check endpoint
- `GET /metrics` - Prometheus metrics

## Authentication

The server uses JWT-based authentication. Include the token in requests:

```bash
# HTTP Headers
Authorization: Bearer <token>

# Query Parameters (for SSE)
?token=<token>
```

Default development token: `devtoken`

## MCP Protocol Support

### Capabilities
- **Resources**: File system resource discovery and reading
- **Tools**: Extensible tool execution with validation
- **Sampling**: LLM completion requests (streaming and non-streaming)
- **Logging**: Structured JSON logging

### Example Requests

#### Initialize Connection
```json
{
  "jsonrpc": "2.0",
  "id": "init",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {"name": "test-client", "version": "1.0.0"}
  }
}
```

#### List Resources
```json
{
  "jsonrpc": "2.0",
  "id": "resources",
  "method": "resources/list",
  "params": {}
}
```

#### Execute Tool
```json
{
  "jsonrpc": "2.0",
  "id": "tool",
  "method": "tools/call",
  "params": {
    "name": "calculate",
    "arguments": {"operation": "add", "a": 5, "b": 3}
  }
}
```

#### LLM Completion
```json
{
  "jsonrpc": "2.0",
  "id": "completion",
  "method": "sampling/createMessage",
  "params": {
    "messages": [{"content": {"type": "text", "text": "Hello, world!"}}],
    "maxTokens": 100
  }
}
```

## Extending the Server

### Adding New Tools
```python
from app.services.tools import mcp_tool

@mcp_tool("my_tool", {
    "type": "object",
    "properties": {
        "param1": {"type": "string"},
        "param2": {"type": "number"}
    },
    "required": ["param1"]
})
async def my_custom_tool(param1: str, param2: float = 0.0):
    """Custom tool implementation"""
    return {"result": f"Processed {param1} with {param2}"}
```

### Custom Resource Handlers
```python
from app.services.resources import ResourceService

class CustomResourceService(ResourceService):
    async def list_resources(self, base_path: str = "."):
        # Custom resource discovery logic
        pass
```

## Monitoring

The server includes comprehensive monitoring:

- **Prometheus Metrics**: Request counts, response times, error rates
- **Structured Logging**: JSON-formatted logs with correlation IDs
- **Health Checks**: Application and dependency status

## Security

- Environment-based configuration (no hardcoded secrets)
- JWT authentication with configurable secrets
- Input validation on all endpoints
- Rate limiting headers from Azure OpenAI

## Development

### Running Tests
```bash
# Test the API endpoints
curl -X POST http://localhost:5000/rpc \
  -H "Authorization: Bearer devtoken" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"test","method":"initialize","params":{}}'

# Test streaming
curl -N "http://localhost:5000/events?token=devtoken&prompt=Hello&stream=true"
```

### Adding Dependencies
```bash
pip install <package-name>
pip freeze > requirements.txt
```

## Troubleshooting

### Common Issues

1. **Azure OpenAI Connection Errors**
   - Verify `AZURE_OPENAI_ENDPOINT` and `AZURE_OPENAI_DEPLOYMENT`
   - Check API key permissions
   - Ensure correct API version

2. **Authentication Failures**
   - Verify JWT token format
   - Check token expiration
   - Ensure correct secret configuration

3. **Streaming Issues**
   - Use query parameters for SSE authentication
   - Check network connectivity for long-running streams

### Debug Logging
Enable debug logging by setting:
```bash
export DEBUG=true
```

## License

This project is licensed under the MIT License.

## Contributing

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

## Support

For issues and questions:
- Check the troubleshooting section
- Review the API documentation
- Open an issue on GitHub