mcp-common
Advanced tools
Oneiric-Native foundation library providing battle-tested patterns for MCP (Model Context Protocol) servers, with YAML configuration, Rich UI, and CLI lifecycle management
mcp-common is an Oneiric-native foundation library for building production-grade MCP (Model Context Protocol) servers. It provides battle-tested patterns extracted from 9 production servers including crackerjack, session-mgmt-mcp, and fastblocks.
🎯 What This Library Provides:
Design Principles:
See examples/ for complete production-ready examples:
Demonstrates the CLI factory for standardized server lifecycle management:
cd examples
python cli_server.py start
python cli_server.py status
python cli_server.py health
python cli_server.py stop
Demonstrates HTTP adapters and FastMCP integration:
cd examples
python weather_server.py
Full documentation: examples/README.md
pip install mcp-common>=0.3.6
This automatically installs Pydantic, Rich, and all required dependencies.
If you plan to run an MCP server (e.g., the examples), install a protocol host such as FastMCP separately:
pip install fastmcp
# or
uv add fastmcp
# my_server/settings.py
from mcp_common.config import MCPBaseSettings
from pydantic import Field
class MyServerSettings(MCPBaseSettings):
"""Server configuration following Oneiric pattern.
Loads from (priority order):
1. settings/local.yaml (gitignored)
2. settings/my-server.yaml
3. Environment variables MY_SERVER_*
4. Defaults below
"""
api_key: str = Field(description="API key for service")
timeout: int = Field(default=30, description="Request timeout")
# my_server/main.py
from fastmcp import FastMCP # Optional: install fastmcp separately
from mcp_common import ServerPanels, HTTPClientAdapter, HTTPClientSettings
from my_server.settings import MyServerSettings
# Initialize
mcp = FastMCP("MyServer")
settings = MyServerSettings.load("my-server")
# Initialize HTTP adapter
http_settings = HTTPClientSettings(timeout=settings.timeout)
http_adapter = HTTPClientAdapter(settings=http_settings)
# Define tools
@mcp.tool()
async def call_api():
# Use the global adapter instance
response = await http_adapter.get("https://api.example.com")
return response.json()
# Run server
if __name__ == "__main__":
# Display startup panel
ServerPanels.startup_success(
server_name="My MCP Server",
version="1.0.0",
features=["HTTP Client", "YAML Configuration"],
)
mcp.run()
Connection Pooling with httpx:
from mcp_common import HTTPClientAdapter, HTTPClientSettings
# Configure HTTP adapter
http_settings = HTTPClientSettings(
timeout=30,
max_connections=50,
retry_attempts=3,
)
# Create adapter
http_adapter = HTTPClientAdapter(settings=http_settings)
# Make requests
response = await http_adapter.get("https://api.example.com")
Note: Rate limiting is not provided by this library. If you use FastMCP, its built-in RateLimitingMiddleware can be enabled; otherwise, use project-specific configuration.
Production-Ready Server Lifecycle Management:
The MCPServerCLIFactory provides standardized CLI commands for managing MCP server lifecycles, inspired by Oneiric's operational patterns. It handles process management, health monitoring, and graceful shutdown out of the box.
Features:
start, stop, restart, status, healthQuick Example:
from mcp_common.cli import MCPServerCLIFactory, MCPServerSettings
# 1. Load settings (YAML + env vars)
settings = MCPServerSettings.load("my-server")
# 2. Define lifecycle handlers
def start_server():
print("Server initialized!")
# Your server startup logic here
def stop_server(pid: int):
print(f"Stopping PID {pid}")
# Your cleanup logic here
def check_health():
# Return current health snapshot
return RuntimeHealthSnapshot(
orchestrator_pid=os.getpid(),
watchers_running=True,
)
# 3. Create CLI factory
factory = MCPServerCLIFactory(
server_name="my-server",
settings=settings,
start_handler=start_server,
stop_handler=stop_server,
health_probe_handler=check_health,
)
# 4. Create and run Typer app
app = factory.create_app()
if __name__ == "__main__":
app()
Command Usage:
# Start server (creates PID file and health snapshot)
python my_server.py start
# Check status (lightweight process check)
python my_server.py status
# Output: Server running (PID 12345, snapshot age: 2.3s, fresh: True)
# View health (detailed health information)
python my_server.py health
# Live health probe
python my_server.py health --probe
# Stop server (graceful shutdown with SIGTERM)
python my_server.py stop
# Force stop with timeout
python my_server.py stop --timeout 5 --force
# Restart (stop + start)
python my_server.py restart
# JSON output for automation
python my_server.py status --json
Configuration:
Settings are loaded from multiple sources (priority order):
settings/local.yaml (gitignored, for development)settings/{server-name}.yaml (checked into repo)MCP_SERVER_*MCPServerSettingsExample settings/my-server.yaml:
server_name: "My MCP Server"
cache_root: .oneiric_cache
health_ttl_seconds: 60.0
log_level: INFO
Exit Codes:
0 - Success1 - General error2 - Server not running (status/stop)3 - Server already running (start)4 - Health check failed5 - Configuration error6 - Permission error7 - Timeout8 - Stale PID file (use --force)Full Example:
See examples/cli_server.py for a complete working example with custom commands and health probes.
~ → home directory)from mcp_common.config import MCPBaseSettings
class ServerSettings(MCPBaseSettings):
api_key: str # Required
timeout: int = 30 # Optional with default
# Load with layered configuration
settings = ServerSettings.load("my-server")
# Loads from:
# 1. settings/my-server.yaml
# 2. settings/local.yaml
# 3. Environment variables MY_SERVER_*
# 4. Defaults
mcp-common uses standard Python logging. Configure as needed for your server:
import logging
# Configure logging
logging.basicConfig(
level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
logger = logging.getLogger(__name__)
logger.info("Server started")
from mcp_common.ui import ServerPanels
ServerPanels.startup_success(
server_name="Mailgun MCP",
http_endpoint="http://localhost:8000",
features=["Rate Limiting", "Security Filters"],
)
from mcp_common.testing import MockMCPClient, mock_http_response
async def test_tool():
with mock_http_response(status=200, json={"ok": True}):
result = await my_tool()
assert result["success"]
See examples/ for a complete production-ready Weather MCP server demonstrating mcp-common patterns.
.load()Before: 100 requests in 45 seconds, 500MB memory
After: 100 requests in 4 seconds, 50MB memory
Result: 11x faster, 10x less memory
Without: 1000 requests in 1.2 seconds
With: 1000 requests in 1.25 seconds
Result: +4% overhead (negligible vs network I/O)
from mcp_common.config import MCPBaseSettings
from pydantic import Field
class MySettings(MCPBaseSettings):
api_key: str = Field(description="API key")
timeout: int = Field(default=30, description="Timeout")
# Load from settings/my-server.yaml + env vars
settings = MySettings.load("my-server")
# Access configuration
print(f"Using API key: {settings.get_masked_key()}")
from mcp_common import HTTPClientAdapter, HTTPClientSettings
# Configure HTTP client
http_settings = HTTPClientSettings(
timeout=30,
max_connections=50,
retry_attempts=3,
)
# Create adapter
http = HTTPClientAdapter(settings=http_settings)
# Make requests
@mcp.tool()
async def call_api():
response = await http.get("https://api.example.com/data")
return response.json()
# Cleanup when done
await http._cleanup_resources()
from mcp_common import ServerPanels
# Startup panel
ServerPanels.startup_success(
server_name="My Server",
version="1.0.0",
features=["Feature 1", "Feature 2"],
)
# Error panel
ServerPanels.error(
title="API Error",
message="Failed to connect",
suggestion="Check your API key",
)
# Status table
ServerPanels.status_table(
title="Health Check",
rows=[
("API", "✅ Healthy", "200 OK"),
("Database", "⚠️ Degraded", "Slow queries"),
],
)
git clone https://github.com/lesaker/mcp-common.git
cd mcp-common
pip install -e ".[dev]"
# Run all tests with coverage
pytest --cov=mcp_common --cov-report=html
# Run specific test
pytest tests/test_http_adapter.py -v
# Run with ACB integration tests
pytest tests/integration/ -v
# Format code
ruff format
# Lint code
ruff check
# Type checking
mypy mcp_common tests
# Run all quality checks
crackerjack --all
Recent Versions:
Compatibility:
Current Status:
BSD-3-Clause License - See LICENSE for details
Contributions are welcome! Please:
examples/README.md for usage patternsruff format && ruff check && mypy && pytest)Built with patterns extracted from 9 production MCP servers:
Primary Pattern Sources:
Additional Contributors:
For support, please check the documentation in the docs/ directory or create an issue in the repository.
Ready to get started? Check out examples/ for working examples demonstrating all features!
FAQs
Oneiric-Native foundation library providing battle-tested patterns for MCP (Model Context Protocol) servers, with YAML configuration, Rich UI, and CLI lifecycle management
We found that mcp-common demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The planned feature introduces a review step before releases go live, following the Shai-Hulud attacks and a rocky migration off classic tokens that disrupted maintainer workflows.
Security News
GitHub postponed a new billing model for self-hosted Actions after developer pushback, but moved forward with hosted runner price cuts on January 1.
Research
Destructive malware is rising across open source registries, using delays and kill switches to wipe code, break builds, and disrupt CI/CD.