Shinzo Py

Installation

The Shinzo Python instrumentation library works with Python MCP servers built with the core MCP SDK or FastMCP. Simply install the base package:

pip install shinzo

Quick Start

Choose the example that matches your MCP SDK:

FastMCP Example

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

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:

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

Authentication Configuration (exporter_auth)

Development

Testing

Run the test suite to verify the library's behavior:

# 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:

# 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.

Contributing

Contributions are welcome! Please see the Contributing Guide for more information.