Metadata-Version: 2.4
Name: chuk-mcp-server
Version: 0.1.1
Summary: Add your description here
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: asyncio>=3.4.3
Requires-Dist: chuk-mcp>=0.5.1
Requires-Dist: httptools>=0.6.4
Requires-Dist: orjson>=3.10.18
Requires-Dist: pydantic>=2.11.7
Requires-Dist: starlette>=0.47.1
Requires-Dist: uvicorn>=0.35.0
Requires-Dist: uvloop>=0.21.0

# ChukMCPServer

A developer-friendly MCP (Model Context Protocol) framework with clean APIs, robust error handling, and production-ready performance.

## 🚀 Features

- **🧩 Clean API**: Simple decorators similar to FastAPI
- **⚡ High Performance**: 2,000+ RPS with sub-millisecond latency
- **🛡️ Type Safety**: Automatic schema generation from Python type hints
- **🔍 Inspector Compatible**: Perfect integration with MCP Inspector
- **📊 Rich Resources**: Support for JSON, Markdown, and custom MIME types
- **🌊 Async Native**: Advanced concurrent and streaming capabilities
- **🏗️ Modular Architecture**: Registry-driven design for extensibility
- **🚀 Production Ready**: Comprehensive error handling and session management

## 📦 Installation

```bash
pip install chuk-mcp-server
```

## 🎯 Quick Start

### Traditional Server (High RPS)

```python
from chuk_mcp_server import ChukMCPServer

# Create server
mcp = ChukMCPServer(name="My MCP Server", version="1.0.0")

@mcp.tool
def hello(name: str) -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"

@mcp.tool
def add(x: int, y: int) -> int:
    """Add two numbers."""
    return x + y

@mcp.resource("config://settings")
def get_settings() -> dict:
    """Get server configuration."""
    return {"app": "my_server", "version": "1.0.0"}

if __name__ == "__main__":
    mcp.run(port=8000)
```

### Async Native Server (Concurrent Operations)

```python
from chuk_mcp_server import ChukMCPServer
import asyncio

mcp = ChukMCPServer(name="Async MCP Server", version="2.0.0")

@mcp.tool
async def concurrent_requests(urls: list[str]) -> dict:
    """Make multiple concurrent HTTP requests."""
    async def fetch(url):
        # Simulate HTTP request
        await asyncio.sleep(0.1)
        return {"url": url, "status": "success"}
    
    results = await asyncio.gather(*[fetch(url) for url in urls])
    return {"results": results, "total": len(results)}

@mcp.tool
async def stream_processor(items: list[str]) -> dict:
    """Process items using async streaming."""
    async def process_item(item):
        await asyncio.sleep(0.05)
        return f"processed_{item}"
    
    results = await asyncio.gather(*[process_item(item) for item in items])
    return {"processed": results}

if __name__ == "__main__":
    mcp.run(port=8001)
```

## 🎭 Architecture

ChukMCPServer uses a modular, registry-driven architecture:

```
┌─────────────────────────────────────────────────────────┐
│                    ChukMCPServer                        │
├─────────────────────────────────────────────────────────┤
│  🎯 Core Framework (types.py, core.py)                 │
│  • Clean decorator API                                 │
│  • Type-safe parameter handling                        │
│  • Union type support                                  │
├─────────────────────────────────────────────────────────┤
│  📋 Registry System                                     │
│  • MCP Registry (tools, resources, prompts)            │
│  • HTTP Registry (endpoints, middleware)               │
│  • Tag-based search and discovery                      │
├─────────────────────────────────────────────────────────┤
│  🌐 Protocol Layer (protocol.py)                       │
│  • MCP JSON-RPC handling                              │
│  • Session management                                  │
│  • SSE streaming support                               │
├─────────────────────────────────────────────────────────┤
│  📡 HTTP Server (http_server.py)                       │
│  • Starlette + uvicorn                                │
│  • Auto-registered endpoints                           │
│  • CORS and middleware support                         │
├─────────────────────────────────────────────────────────┤
│  🧱 chuk_mcp Integration                                │
│  • Direct type usage (no conversion layers)            │
│  • Robust protocol implementation                      │
│  • Production-grade error handling                     │
└─────────────────────────────────────────────────────────┘
```

## 📊 Performance

### Traditional Server Performance
- **RPS**: 10,000+ requests per second
- **Latency**: 0.5ms average response time
- **Use Case**: High-frequency simple operations
- **Grade**: S+ (Exceptional)

### Async Native Server Performance
- **RPS**: 2,400+ requests per second (peak at 5 concurrent connections)
- **Latency**: 0.85ms best case, variable for complex operations
- **Use Case**: Concurrent workflows and complex async operations
- **Grade**: A+ (Excellent for concurrent operations)

## 🔍 MCP Inspector Integration

ChukMCPServer works perfectly with [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

1. **Start your server**:
   ```bash
   python my_server.py  # Runs on http://localhost:8000
   ```

2. **Use MCP Inspector**:
   - Transport Type: **Streamable HTTP**
   - URL: `http://localhost:8000/mcp`
   - All tools and resources will be automatically discovered

3. **For development with proxy**:
   ```bash
   # Use proxy on port 8011 for Inspector
   # URL: http://localhost:8011/mcp/inspector
   ```

## 🛠️ Advanced Features

### Type Safety and Parameter Conversion

```python
from typing import Union, List

@mcp.tool
def smart_calculator(
    expression: str,
    precision: Union[str, int] = 2,
    format_output: bool = True
) -> str:
    """
    ChukMCPServer automatically handles:
    - String "2" → int 2
    - String "true" → bool True
    - JSON arrays → Python lists
    """
    # Your tool logic here
    pass
```

### Rich Resources with Multiple MIME Types

```python
@mcp.resource("docs://readme", mime_type="text/markdown")
def get_documentation() -> str:
    return "# My API Documentation\n\nThis is **markdown** content!"

@mcp.resource("data://metrics", mime_type="application/json")
def get_metrics() -> dict:
    return {
        "cpu_usage": 45.2,
        "memory_usage": 67.8,
        "requests_per_second": 1250
    }

@mcp.resource("config://settings", mime_type="application/json")
def get_config() -> dict:
    return {"debug": False, "max_connections": 1000}
```

### Custom HTTP Endpoints

```python
@mcp.endpoint("/api/health", methods=["GET"])
async def health_check(request):
    return JSONResponse({"status": "healthy", "timestamp": time.time()})

@mcp.endpoint("/api/metrics", methods=["GET", "POST"])
async def metrics_endpoint(request):
    # Custom endpoint logic
    return JSONResponse({"metrics": "data"})
```

### Registry Management

```python
# Search components by tags
tools = mcp.search_tools_by_tag("math")
resources = mcp.search_resources_by_tag("config")

# Get component information
info = mcp.get_component_info("calculator")

# Runtime registration
mcp.add_tool(my_tool_handler, tags=["utility", "text"])
mcp.add_resource(my_resource_handler, tags=["config", "system"])
```

## 🚀 Examples

### Production Server Example

See [`examples/production_server.py`](examples/production_server.py) for a comprehensive traditional server with:
- 7 production-ready tools
- 4 rich resources
- Type-safe parameter handling
- Comprehensive documentation

### Async Native Example

See [`examples/async_production_server.py`](examples/async_production_server.py) for advanced async capabilities:
- Concurrent API requests
- Stream processing with async generators
- Real-time monitoring
- Distributed task coordination
- File processing with concurrent batches

### Quick Examples

```bash
# Run traditional server (high RPS)
python examples/production_server.py

# Run async native server (concurrent operations)
python examples/async_production_server.py

# Run standalone async demo
python examples/standalone_async_e2e_demo.py
```

## 🧪 Testing and Benchmarks

### Quick Benchmark

```bash
# Benchmark traditional server
python benchmarks/quick_benchmark.py http://localhost:8000/mcp "Traditional Server"

# Benchmark async server
python benchmarks/quick_benchmark.py http://localhost:8001/mcp "Async Native Server"
```

### Comprehensive Performance Testing

```bash
# Full performance analysis
python benchmarks/mcp_performance_test.py http://localhost:8000/mcp
```

### Expected Results

**Traditional Server:**
```
📊 QUICK BENCHMARK RESULTS
Tools List: 68.8 RPS | 14.5ms avg
Tool Call (hello): 1,870 RPS | 0.5ms avg
Performance Rating: 🚀 Excellent
```

**Async Native Server:**
```
📊 PERFORMANCE ANALYSIS
Peak RPS: 2,402.4 (at 5 concurrent connections)
Best Latency: 0.85ms
Success Rate: 100%
Performance Rating: A+ (Excellent for concurrent operations)
```

## 📋 API Reference

### Core ChukMCPServer

```python
from chuk_mcp_server import ChukMCPServer

# Create server
mcp = ChukMCPServer(
    name="My Server",
    version="1.0.0", 
    title="Optional Title",
    description="Server description",
    tools=True,         # Enable tools capability
    resources=True,     # Enable resources capability
    prompts=False,      # Enable prompts capability
    logging=False       # Enable logging capability
)

# Decorators
@mcp.tool                              # Basic tool
@mcp.tool(name="custom", description="...")  # Custom tool
@mcp.resource("uri://path")           # Basic resource
@mcp.resource("uri://path", mime_type="application/json")  # JSON resource
@mcp.endpoint("/path", methods=["GET"]) # Custom HTTP endpoint

# Manual registration
mcp.add_tool(tool_handler)
mcp.add_resource(resource_handler)
mcp.add_endpoint("/path", handler_func)

# Information and search
mcp.info()                            # Server information
mcp.get_tools()                       # List all tools
mcp.search_tools_by_tag("math")       # Search by tag

# Run server
mcp.run(host="localhost", port=8000, debug=False)
```

### Tool Types and Parameters

```python
from typing import Union, List, Optional

@mcp.tool
def example_tool(
    # Basic types
    name: str,                    # String parameter
    count: int,                   # Integer parameter
    ratio: float,                 # Float parameter
    enabled: bool,                # Boolean parameter
    
    # Optional with defaults
    timeout: int = 30,            # Optional with default
    format: str = "json",         # Optional string
    
    # Union types (flexible input)
    delay: Union[str, int, float] = 1.0,  # Accepts multiple types
    items: Union[str, List[str]] = [],    # String or list
    
    # Complex types
    config: dict = None,          # Dictionary parameter
    tags: List[str] = None        # List parameter
) -> dict:
    """
    ChukMCPServer automatically:
    - Generates JSON schema from type hints
    - Validates parameter types
    - Converts string inputs to appropriate types
    - Handles optional parameters and defaults
    """
    return {"processed": True}
```

## 🏗️ Development

### Project Structure

```
chuk_mcp_server/
├── __init__.py              # Main exports
├── core.py                  # ChukMCPServer class
├── types.py                 # Type system and handlers
├── protocol.py              # MCP protocol implementation
├── http_server.py           # HTTP server with Starlette
├── endpoint_registry.py     # HTTP endpoint management
├── mcp_registry.py          # MCP component management
├── decorators.py            # Simple decorators
└── endpoints/               # Modular endpoint handlers
    ├── __init__.py
    ├── mcp.py               # Core MCP endpoint
    ├── health.py            # Health check endpoint
    └── info.py              # Server info endpoint

examples/
├── production_server.py     # Traditional server example
├── async_production_server.py  # Async native example
└── standalone_async_e2e_demo.py  # Comprehensive async demo

benchmarks/
├── quick_benchmark.py       # Quick performance test
└── mcp_performance_test.py  # Comprehensive performance analysis
```

### Contributing

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Make your changes** with tests
4. **Run the test suite**: `python -m pytest`
5. **Submit a pull request**

### Running Tests

```bash
# Run examples
python examples/production_server.py
python examples/async_production_server.py

# Run benchmarks
python benchmarks/quick_benchmark.py http://localhost:8000/mcp
python benchmarks/mcp_performance_test.py http://localhost:8000/mcp

# Test with MCP Inspector
# 1. Start server: python examples/production_server.py
# 2. Open Inspector: https://github.com/modelcontextprotocol/inspector
# 3. Connect to: http://localhost:8000/mcp
```

## 🔧 Configuration

### Server Configuration

```python
# Basic configuration
mcp = ChukMCPServer(
    name="Production Server",
    version="1.0.0",
    tools=True,
    resources=True
)

# Advanced configuration with capabilities
from chuk_mcp_server import Capabilities

mcp = ChukMCPServer(
    name="Advanced Server",
    capabilities=Capabilities(
        tools=True,
        resources=True,
        prompts=True,
        logging=True,
        experimental={"feature_x": True}
    )
)
```

### HTTP Server Options

```python
# Development
mcp.run(host="localhost", port=8000, debug=True)

# Production
mcp.run(host="0.0.0.0", port=8000, debug=False)
```

## 📚 Documentation

### Auto-Generated Documentation

ChukMCPServer automatically generates comprehensive documentation:

- **`GET /`**: HTML server information
- **`GET /docs`**: Markdown documentation
- **`GET /health`**: Health check with diagnostics
- **`GET /registry/mcp`**: MCP component registry info
- **`GET /registry/endpoints`**: HTTP endpoint registry info

### Tool Documentation

```python
@mcp.tool
def calculate(expression: str, precision: int = 2) -> str:
    """
    Safely evaluate mathematical expressions.
    
    Supports basic operations and math functions like sin, cos, sqrt, etc.
    
    Args:
        expression: Mathematical expression to evaluate (e.g., 'sqrt(16) + 2 * 3')
        precision: Number of decimal places in result
        
    Returns:
        Formatted calculation result
        
    Examples:
        calculate("2 + 2") → "2 + 2 = 4"
        calculate("sqrt(16)", precision=0) → "sqrt(16) = 4"
    """
    # Implementation
```

## 🚀 Deployment

### Docker

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "production_server.py"]
```

### Environment Variables

```bash
# Server configuration
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
export MCP_DEBUG=false

# Run server
python production_server.py
```

## 🤝 Integration Examples

### With FastAPI

```python
from fastapi import FastAPI
from chuk_mcp_server import ChukMCPServer

app = FastAPI()
mcp = ChukMCPServer(name="FastAPI + MCP")

@mcp.tool
def api_tool(data: str) -> str:
    return f"Processed: {data}"

# Mount MCP server
app.mount("/mcp", mcp.app)

# Regular FastAPI routes
@app.get("/api/status")
def status():
    return {"status": "ok"}
```

### With Existing Servers

```python
# Add MCP to existing HTTP server
from starlette.applications import Starlette
from starlette.routing import Mount

mcp = ChukMCPServer()
# ... configure MCP tools/resources

app = Starlette(routes=[
    Mount("/mcp", mcp.app),
    # ... other routes
])
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built on [chuk_mcp](https://github.com/chrishayuk/chuk-mcp) for robust MCP protocol implementation
- Inspired by [FastAPI](https://fastapi.tiangolo.com/) for clean decorator-based APIs
- Compatible with [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for development

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/your-org/chuk-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/chuk-mcp-server/discussions)
- **Documentation**: [Full Documentation](https://chuk-mcp-server.readthedocs.io/)

---

**Built with ❤️ for the MCP community**
