mcp-worker-sdk

Worker Protocol Python runtime reference implementation — a universal MCP tool runtime SDK.

Write plain Python functions with the @worker.tool decorator and automatically get standard endpoints, schema generation, parameter validation, standardized errors, lifecycle hooks, and built-in database drivers.

mcp-worker-sdk is the Python runtime binding of the language-agnostic Worker Protocol. It is Hub-agnostic: omit hub_url to run it standalone as a standard HTTP tool service that any aggregator (Hub / MCP gateway) can consume.

Install

pip install mcp-worker-sdk

With all built-in database drivers:

pip install "mcp-worker-sdk[db]"

Quick start

from mcp_worker_sdk import Worker
from mcp_worker_sdk.adapters import DBAdapter

worker = Worker(
    name="notes",
    adapter=DBAdapter("sqlite", ":memory:"),
    # hub_url="https://hub.example.com",   # optional; omit to run standalone
)


@worker.tool(
    id="notes_greet",
    title="Greet",
    description="Return a greeting for a name",
)
def greet(name: str = "World"):
    """Return a greeting.

    :param name: who to greet
    """
    return {"message": f"Hello, {name}!"}


if __name__ == "__main__":
    worker.run(port=9100)

Then:

curl http://localhost:9100/health
curl http://localhost:9100/tools
curl -X POST http://localhost:9100/execute \
  -H "Content-Type: application/json" \
  -d '{"tool_id":"notes_greet","params":{"name":"Mavis"}}'

Adapters

DBAdapter built-in drivers

postgresql (psycopg), mysql (pymysql), sqlite (sqlite3), qdrant (qdrant-client), neo4j (neo4j), redis (redis), mongodb (pymongo).

Runtime observability

GET /health returns a rich three-tier payload — live status, queue backpressure, and performance profiling — instead of a bare alive flag:

{
  "status": "busy",
  "degraded_reason": "none",
  "active_tasks": 2,
  "queue_length": 5,
  "max_concurrency": 10,
  "max_queue_length": 20,
  "avg_task_duration_ms": 150,
  "p95_duration_ms": 420,
  "estimated_wait_ms": 250,
  "success_rate": 0.998,
  "cpu_percent": 40.0,
  "memory_percent": 61.2,
  "uptime_seconds": 3600,
  "version": "1.1.0",
  "custom": {}
}

• Real bounded concurrency (max_concurrency) and queue backpressure (max_queue_length): when the queue is full, /execute replies 429 RATE_LIMITED + Retry-After.
• worker.health_metrics() returns a protocol mcp_worker_protocol.HealthMetrics object (5 base + 6 rich fields) for zero-transformation heartbeat aggregation.

CLI scaffold

mcp-worker create my-worker              # default HTTPAdapter
mcp-worker create my-worker --adapter db

License

Apache-2.0