README.md•7.28 kB
# MCP Server Hero
A professional Model Context Protocol (MCP) server template and framework for building robust MCP servers in Python.
## Features
- 🏗️ **Modular Architecture**: Clean separation of tools, resources, prompts, and configuration
- 🔧 **Easy Registration**: Simple APIs for registering tools, resources, and prompts
- 📝 **Type Safety**: Full type hints and validation throughout
- 🚀 **Multiple Transports**: Support for stdio and SSE (Server-Sent Events) transports
- 📊 **Professional Logging**: Built-in logging and debugging support
- 🧪 **Testing Ready**: Structured for easy testing with pytest
- 📖 **Comprehensive Examples**: Both basic and advanced usage examples
## Enterprise Features
- ⚡ **Middleware System**: Request/response processing pipeline with validation, logging, timing, and rate limiting
- 🧩 **Plugin System**: Dynamic plugin loading with dependency management
- 🔐 **Authentication & Authorization**: Flexible auth providers with permission-based access control
- 💾 **Caching System**: Multi-layer caching with TTL support and LRU eviction
- 📊 **Metrics & Monitoring**: Comprehensive performance metrics and health checks
- 🛡️ **Rate Limiting**: Token bucket rate limiting with per-client support
## Quick Start
### Installation
```bash
# Install uv package manager
make install-uv
# Install all dependencies
make install
# Or install production only
make install-prod
```
### Basic Usage
```python
from mcp_server_hero import MCPServerHero
import anyio
from mcp.server.stdio import stdio_server
async def add_numbers(a: int, b: int) -> int:
"""Add two numbers together."""
return a + b
async def main():
# Create server instance
server = MCPServerHero(name="My Server")
# Register a tool
server.add_tool(
name="add",
tool_func=add_numbers,
description="Add two numbers",
schema={
"type": "object",
"properties": {
"a": {"type": "integer"},
"b": {"type": "integer"}
},
"required": ["a", "b"]
}
)
# Run the server
async with stdio_server() as streams:
await server.run(streams[0], streams[1], server.create_initialization_options())
if __name__ == "__main__":
anyio.run(main)
```
### Enterprise Usage
```python
from mcp_server_hero import MCPServerHero
from mcp_server_hero.middleware.rate_limit import RateLimitMiddleware
from mcp_server_hero.auth.base import SimpleAuthProvider
# Create enterprise server
server = MCPServerHero("Enterprise Server", debug=True)
# Add advanced features
server.add_middleware(RateLimitMiddleware(tool_limit=100))
server.enable_auth_provider(SimpleAuthProvider())
await server.load_plugins_from_directory("plugins/")
# Initialize and run
await server.initialize()
```
## Running Examples
```bash
# Run different server examples
make run-basic # Basic function-based server
make run-advanced # Class-based server with custom components
make run-enterprise # Full-featured enterprise server
# Run with different transports
make run-server # SSE transport (web-based)
make run-stdio # Stdio transport (direct communication)
make run-debug # Debug mode with detailed logging
```
## Development
```bash
# Code quality
make check # Run all quality checks (lint + format + typecheck)
make test # Run tests
make test-cov # Run tests with coverage
# Individual quality checks
make lint # Code linting
make format # Code formatting
make typecheck # Type checking
```
## Architecture
```
src/mcp_server_hero/
├── core/ # Core server implementation
│ ├── cli.py # Command-line interface
│ ├── server.py # Main server class
│ └── version.py # Version info
├── tools/ # Tool management
├── resources/ # Resource management
├── prompts/ # Prompt management
├── middleware/ # Middleware system
│ ├── logging.py # Request/response logging
│ ├── timing.py # Performance monitoring
│ ├── validation.py # Input validation
│ └── rate_limit.py # Rate limiting
├── plugins/ # Plugin system
├── auth/ # Authentication framework
├── cache/ # Caching system
├── metrics/ # Metrics collection
├── config/ # Configuration
├── utils/ # Utilities
└── examples/ # Usage examples
```
## Components
### Tools
Tools perform actions and return results:
```python
# Simple function tool
async def my_tool(param: str) -> str:
return f"Result: {param}"
server.add_tool("my_tool", my_tool, "Description")
# Class-based tool with advanced features
from mcp_server_hero.tools.base import BaseTool
class MyTool(BaseTool):
async def execute(self, arguments):
return [TextContent(type="text", text="Result")]
```
### Resources
Resources provide read-only data:
```python
# Simple function resource
async def get_data() -> str:
return "Resource data"
server.add_resource("data://example", get_data, "Example data")
```
### Prompts
Prompts generate structured messages:
```python
# Simple function prompt
async def create_prompt(topic: str) -> str:
return f"Please explain {topic}"
server.add_prompt("explain", create_prompt, "Explanation prompt")
```
### Middleware
Process requests through a pipeline:
```python
from mcp_server_hero.middleware import ValidationMiddleware, TimingMiddleware
server.add_middleware(ValidationMiddleware())
server.add_middleware(TimingMiddleware())
```
### Plugins
Extend functionality dynamically:
```python
from mcp_server_hero.plugins.base import BasePlugin
class MyPlugin(BasePlugin):
async def initialize(self, server):
server.add_tool("plugin_tool", self.my_tool, "Plugin tool")
```
## Configuration
```python
from mcp_server_hero.config import ServerSettings
settings = ServerSettings(
name="My Server",
debug=True,
log_level="DEBUG",
timeout=60.0
)
server = MCPServerHero(settings=settings)
```
## Monitoring & Metrics
The server provides comprehensive monitoring:
```python
# Get server statistics
stats = server.get_server_stats()
# Get performance metrics
metrics = await server.get_metrics()
# Health check
health = await server.health_check()
```
## Project Commands
```bash
make help # Show all available commands
make examples # List example servers
make stats # Show project statistics
make clean # Clean build artifacts
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run `make check` to verify code quality
5. Add tests if applicable
6. Submit a pull request
## License
MIT License - see LICENSE file for details.
## MCP Protocol
This framework implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), enabling seamless integration between AI models and external data sources and tools.
For more information about MCP, visit the [official documentation](https://modelcontextprotocol.io/).