Metadata-Version: 2.4
Name: mcp-worker-protocol
Version: 1.0.0
Summary: Protocol foundation for the MCP Worker platform: shared Pydantic models, error codes, and an async/sync Hub HTTP client.
Author: Mavis AI Platform
License: Apache-2.0
Keywords: mcp,protocol,worker,pydantic,httpx,hub
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# mcp-worker-protocol

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

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://www.apache.org/licenses/LICENSE-2.0)
[![Tests](https://img.shields.io/badge/tests-94%20passed-brightgreen)](#)

`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

```bash
pip install mcp-worker-protocol
```

> Import name uses an underscore: `mcp_worker_protocol`.

---

## Quickstart

```python
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

| Module | Responsibility |
|--------|----------------|
| `models` | Pydantic models: `ToolSchema`, `ParametersSchema`, `PropertyDefinition`, `Heartbeat`, `TaskReport`, `ErrorInfo`, and more |
| `errors` | Eight standard error codes, `HubError` hierarchy, and HTTP-status mapping |
| `utils` | `schema_from_signature` — derive a JSON Schema from Python type hints |
| `hub_client` | `HubClient` (sync) and `AsyncHubClient` (async) with retry + error mapping |

### Generate schemas from type hints

```python
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

```python
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

| Code | HTTP | Meaning |
|------|------|---------|
| `INVALID_PARAMS` | 422 | Invalid parameters |
| `NOT_FOUND` | 404 | Tool or resource not found |
| `TIMEOUT` | 504 | Execution timeout |
| `PERMISSION_DENIED` | 403 | Not authorized |
| `WORKER_OFFLINE` | 503 | Worker offline |
| `WORKER_ERROR` | 502 | Worker internal error |
| `INTERNAL_ERROR` | 500 | Hub internal error |
| `RATE_LIMITED` | 429 | Rate limited |

---

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

```bash
pip install -e ".[dev]"
pytest
```

---

## License

[Apache License 2.0](LICENSE)
