mcp-worker-protocol

Protocol foundation for the MCP Worker platform — shared Pydantic models, standardized error codes, and an async/sync Hub HTTP client.

mcp-worker-protocol is the protocol base layer shared by MCP worker runtimes and host agents. It owns the cross-service contract — data models, errors, headers, and Hub communication — so the layers above it can stay focused on business behavior.

Installation

pip install mcp-worker-protocol

Import name uses an underscore: mcp_worker_protocol.

Quickstart

from mcp_worker_protocol import (
    ToolSchema,
    ParametersSchema,
    PropertyDefinition,
    HubClient,
)

tool = ToolSchema(
    tool_id="my_hello",
    title="Hello World",
    description="Return a greeting",
    parameters_schema=ParametersSchema(
        properties={"name": PropertyDefinition(type="string", default="World")},
        required=[],
    ),
)

client = HubClient("https://hub.example.com", api_key="mcp_sk_xxx")
client.register_tools([tool], jwt_token="<jwt>")

Five lines to a serializable, validated MCP tool definition and a working Hub client.

What's inside

Generate schemas from type hints

from mcp_worker_protocol import schema_from_signature

def search(collection: str, top_k: int = 5):
    """Semantic search
    :param collection: Collection name
    :param top_k: Number of results
    """

schema = schema_from_signature(search)
# schema.required == ["collection"]
# schema.properties["top_k"].default == 5

Handle errors by contract

from mcp_worker_protocol import HubError, NetworkError

try:
    client.send_heartbeat(heartbeat)
except HubError as exc:
    print(exc.code, exc.http_status, exc.detail)
except NetworkError:
    # transport-level failure
    ...

Error codes

Compatibility

• Python 3.10+
• Runtime dependencies: pydantic>=2.0, httpx>=0.24 — nothing else.
• New model fields are backward-compatible (defaulted), and serialization omits None values via exclude_none=True.

Development

pip install -e ".[dev]"
pytest

License

Apache License 2.0