CzechFabric SDK

Complete Python SDK for CzechFabric MCP - Perfect mirror of backend system

The CzechFabric SDK provides a complete, type-safe interface to all CzechFabric backend tools. All 13 tools are implemented with exact parameter and schema matching.

Features

• ✅ 13 Tools - Complete coverage of all backend tools
• ✅ Type-Safe - Full Pydantic models matching backend exactly
• ✅ Format Support - TONE (40-60% token savings), JSON, and both formats
• ✅ Async & Sync - Use async/await or synchronous wrappers
• ✅ Validation - Input validation before API calls
• ✅ Error Handling - Comprehensive exception types
• ✅ Version Checking - Automatic compatibility checks
• ✅ Production Ready - Comprehensive testing and documentation

Installation

pip install czechfabric-sdk

Quick Start

Async Usage

import asyncio
from czechfabric_sdk import CzechFabricClient, TransportMode

async def main():
    client = CzechFabricClient(
        api_key="your-api-key",
        base_url="https://mcp.czechfabric.cz"
    )
    
    # Get departures
    result = await client.get_departures(
        stop_name="Anděl",
        mode=TransportMode.METRO,
        max_results=10,
        format="json"
    )
    print(result)

asyncio.run(main())

Sync Usage

from czechfabric_sdk import SyncCzechFabricClient, TransportMode

client = SyncCzechFabricClient(
    api_key="your-api-key",
    base_url="https://mcp.czechfabric.cz"
)

# Get departures
result = client.get_departures(
    stop_name="Anděl",
    mode=TransportMode.METRO,
    max_results=10
)
print(result)

Helper Methods

# Domain-organized helpers
await client.tools.transport.get_departures("Anděl")
await client.tools.air_quality.current("Karlovo náměstí")
await client.tools.routing.plan_route("A", "B")

Tools

Transport (9 tools)

• Departures: get_departures(), departures_by_coordinates(), suggest_departure_stops_nearby()
• Geocoding: geocode(), reverse_geocode()
• Stops: find_all_stops_near(), get_stop_metadata(), list_all_stops()
• Routing: plan_route_mapycz()

Air Quality (4 tools)

• get_air_quality_near_location() - Current air quality near location
• get_air_quality_by_district() - Air quality by district
• get_air_quality_history() - Historical data
• list_air_quality_components() - List all pollutants

Response Formats

All tools support three response formats:

• tone (default) - Token-efficient TONE format string
• json - Standard JSON dict
• both - Full Pydantic model with both formats

Error Handling

from czechfabric_sdk.exceptions import (
    InvalidAPIKeyError,
    RateLimitExceededError,
    ValidationError,
    NetworkError
)

try:
    result = await client.get_departures("Anděl")
except InvalidAPIKeyError:
    print("Invalid API key")
except RateLimitExceededError:
    print("Rate limit exceeded")
except ValidationError as e:
    print(f"Validation error: {e}")
except NetworkError as e:
    print(f"Network error: {e}")

Version Compatibility

The SDK automatically checks backend compatibility:

# Strict mode - fails on version mismatch
client = CzechFabricClient(
    api_key="key",
    base_url="https://mcp.czechfabric.cz",
    strict_mode=True  # Raises error on mismatch
)

# Normal mode - warns on mismatch
client = CzechFabricClient(
    api_key="key",
    base_url="https://mcp.czechfabric.cz",
    check_version=True  # Warns on mismatch (default)
)

Documentation

• Full Documentation: https://czechfabric.cz/docs/sdk
• API Reference: See docs/ directory
• Examples: See examples.md
• Changelog: See CHANGELOG.md

Requirements

• Python 3.9 or higher
• Valid CzechFabric API key
• Internet connection

Development

# Clone repository
git clone https://github.com/czechfabric/czechfabric-sdk.git
cd czechfabric-sdk

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run linting
ruff check czechfabric_sdk

# Run type checking
mypy czechfabric_sdk

License

MIT License - see LICENSE file.

Support

• GitHub Issues: https://github.com/czechfabric/czechfabric-sdk/issues
• Email: support@czechfabric.cz
• Documentation: https://czechfabric.cz/docs/sdk

Contributing

Contributions welcome! Please see our contributing guidelines.

Made with ❤️ for the Czech Republic