czechfabric-sdk 0.1.0

Async Python SDK for CzechFabric MCP server

🇨🇿 CzechFabric SDK

Async Python SDK for accessing CzechFabric MCP server

---

✨ Overview

This SDK provides a robust, type-safe, async interface for interacting with a CzechFabric MCP server via FastMCP.

Features:

• ✅ Async operations
• ✅ Automatic retries with exponential backoff
• ✅ In-memory caching
• ✅ Structured logging
• ✅ Rich error handling

---

🏗 Installation

pip install czechfabric-sdk

Or install locally:

pip install .

---

⚡ Quickstart

import asyncio
from czechfabric_sdk.client import CzechFabricClient

async def main():
    client = CzechFabricClient(
        api_key="YOUR_API_KEY",
        base_url="https://mcp-server.example.com/mcp"
    )

    trip = await client.plan_trip("Prague", "Brno")
    print("Trip Plan:\n", trip)

    departures = await client.get_departures("Florenc")
    print("Departures:\n", departures)

    geocode = await client.geocode("Karlovo náměstí")
    print("Geocode:\n", geocode)

if __name__ == "__main__":
    asyncio.run(main())

---

🚀 API Reference

CzechFabricClient

Initialization

client = CzechFabricClient(
    api_key: str,
    base_url: str,
    timeout: float = 30.0
)

Param	Type	Description
api_key	str	Your API key for authentication
base_url	str	MCP server base URL
timeout	float	Default timeout per request (sec)

---

Methods

✅ plan_trip(from_place, to_place)

• Plan a trip between two places.

✅ get_departures(stop_name)

• Retrieve departures for a given stop.

✅ geocode(name, use_cache=True)

• Geocode a place name.

All methods are async and return str.

---

⚠️ Error Handling

This SDK raises clear, specific exceptions:

• InvalidAPIKeyError – invalid or missing API key
• RateLimitExceededError – rate limit exceeded
• ToolExecutionError – generic execution failure
• NetworkError – connectivity issues

Example:

from czechfabric_sdk.exceptions import InvalidAPIKeyError

try:
    await client.plan_trip("A", "B")
except InvalidAPIKeyError:
    print("Your API key is invalid.")

---

🧠 Caching

By default, geocode() uses in-memory caching via async_lru. To disable cache:

await client.geocode("Prague", use_cache=False)

---

🧪 Testing

Install dev dependencies:

pip install pytest pytest-asyncio

Run tests:

pytest

---

🛠 Development

To build and publish:

python -m build
twine upload dist/*

Or trigger CI/CD by pushing a tag:

git tag v0.1.0
git push --tags

---

📄 License

MIT License © 2025 Czech Fabric

---

🤝 Contributing

Issues and PRs welcome!