## Installation
The Shinzo Python instrumentation library works with Python MCP servers built with the core MCP SDK or FastMCP. Simply install the base package:
```bash
pip install shinzo
```
## Quick Start
Choose the example that matches your MCP SDK:
### FastMCP Example
```python
from mcp.server.fastmcp import FastMCP
from shinzo import instrument_server
# Create FastMCP server
mcp = FastMCP(name="my-mcp-server")
# Instrument it with Shinzo
observability = instrument_server(
mcp,
config={
"server_name": "my-mcp-server",
"server_version": "1.0.0",
"exporter_auth": {
"type": "bearer",
"token": "your-api-token"
}
}
)
# Define your tools
@mcp.tool()
def get_weather(city: str) -> str:
"""Get weather for a city."""
return f"Weather for {city}: Sunny"
# Run the server
if __name__ == "__main__":
mcp.run()
```
### MCP SDK Example
```python
from mcp.server import Server
from shinzo import instrument_server
# Create your MCP server
server = Server("my-mcp-server")
# Instrument it with Shinzo
observability = instrument_server(
server,
config={
"server_name": "my-mcp-server",
"server_version": "1.0.0",
"exporter_auth": {
"type": "bearer",
"token": "your-api-token"
}
}
)
# Define your tools
@server.call_tool()
async def get_weather(city: str) -> str:
return f"Weather for {city}: Sunny"
# Clean shutdown
async def shutdown():
await observability.shutdown()
```
## SDK Compatibility
Shinzo automatically detects and instruments your MCP server regardless of which SDK you use:
| SDK | Detection Method | Decorator | Use Case |
|-----|-----------------|-----------|----------|
| **FastMCP** | `server.tool` attribute | `@mcp.tool()` | Simpler API, modern Python patterns, recommended for new projects |
| **Traditional MCP** | `server.call_tool` attribute | `@server.call_tool()` | Standard MCP specification, more configuration options |
Both SDKs receive the same comprehensive instrumentation with no additional configuration needed.
## Features
- ๐ **Automatic Instrumentation** - Zero-code changes for basic tracing across both FastMCP and Traditional MCP
- ๐ **Rich Metrics** - Track request duration, error rates, and custom metrics
- ๐ **PII Sanitization** - Built-in sensitive data protection
- ๐ฏ **Session Tracking** - Correlate all requests in a user session
- โก **High Performance** - Minimal overhead with efficient batching
- ๐ ๏ธ **Flexible Configuration** - Customize sampling, exporters, and processors
## Configuration
| Setting | Required | Type | Default | Description |
|---------|----------|------|---------|-------------|
| `server_name` | โ
| `str` | - | Name of your MCP server |
| `server_version` | โ
| `str` | - | Version of your MCP server |
| `exporter_endpoint` | โ | `str` | `"https://api.app.shinzo.ai/telemetry/ingest_http"` | OTLP endpoint URL for telemetry export |
| `exporter_auth` | โ | `AuthConfig` | `None` | Authentication configuration for the exporter |
| `exporter_type` | โ | `"otlp-http"` \| `"console"` | `"otlp-http"` | Type of exporter to use |
| `sampling_rate` | โ | `float` | `1.0` | Trace sampling rate (0.0-1.0) |
| `enable_metrics` | โ | `bool` | `True` | Enable metrics collection |
| `enable_tracing` | โ | `bool` | `True` | Enable distributed tracing |
| `enable_pii_sanitization` | โ | `bool` | `False` | Enable automatic PII sanitization |
| `enable_argument_collection` | โ | `bool` | `True` | Collect and include tool arguments in telemetry |
| `metric_export_interval_ms` | โ | `int` | `60000` | Interval for exporting metrics (milliseconds) |
| `batch_timeout_ms` | โ | `int` | `30000` | Timeout for batching telemetry data (milliseconds) |
| `data_processors` | โ | `list[Callable]` | `None` | Custom data processors for telemetry attributes |
| `pii_sanitizer` | โ | `PIISanitizer` | `None` | Custom PII sanitizer instance |
### Authentication Configuration (`exporter_auth`)
| Setting | Required | Type | Description |
|---------|----------|------|-------------|
| `type` | โ
| `"bearer"` \| `"apiKey"` \| `"basic"` | Authentication method |
| `token` | โ | `str` | Bearer token (required when `type="bearer"`) |
| `api_key` | โ | `str` | API key (required when `type="apiKey"`) |
| `username` | โ | `str` | Username (required when `type="basic"`) |
| `password` | โ | `str` | Password (required when `type="basic"`) |
## Development
### Testing
Run the test suite to verify the library's behavior:
```bash
# Run all tests
python -m pytest tests/
# Run with coverage report
python -m pytest tests/ --cov=shinzo --cov-report=term-missing
# Run specific test file
python -m pytest tests/test_config.py -v
# Or use make
make test
```
The test suite validates:
- โ
Configuration validation and error handling
- โ
PII sanitization for emails and sensitive data
- โ
Authentication configuration (bearer, basic, API key)
- โ
Sampling rate validation
### Linting
Run all linting checks before submitting a PR:
```bash
# Run all linting checks (black, ruff, mypy)
make lint-all
# Or run individual checks
make format # Format code with black
make lint # Run ruff linter
make type-check # Run mypy type checker
```
This ensures your code passes all CI validation checks locally before pushing.
## License
This package is distributed under the [MIT License](./LICENSE.md).
## Contributing
Contributions are welcome! Please see the [Contributing Guide](./CONTRIBUTING.md) for more information.
