Metadata-Version: 2.5
Name: mcp-worker-sdk
Version: 1.0.0
Summary: Worker Protocol Python runtime reference implementation — a universal MCP tool runtime SDK.
Author: mcp-worker-sdk developers
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.110.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: mcp-worker-protocol>=1.0.0
Requires-Dist: uvicorn>=0.27.0
Provides-Extra: db
Requires-Dist: neo4j>=5.20; extra == 'db'
Requires-Dist: psycopg>=3.1; extra == 'db'
Requires-Dist: pymongo>=4.6; extra == 'db'
Requires-Dist: pymysql>=1.1; extra == 'db'
Requires-Dist: qdrant-client>=1.9; extra == 'db'
Requires-Dist: redis>=5.0; extra == 'db'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: metrics
Requires-Dist: psutil>=5.9; extra == 'metrics'
Provides-Extra: mongodb
Requires-Dist: pymongo>=4.6; extra == 'mongodb'
Provides-Extra: mysql
Requires-Dist: pymysql>=1.1; extra == 'mysql'
Provides-Extra: neo4j
Requires-Dist: neo4j>=5.20; extra == 'neo4j'
Provides-Extra: postgresql
Requires-Dist: psycopg>=3.1; extra == 'postgresql'
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.9; extra == 'qdrant'
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == 'redis'
Description-Content-Type: text/markdown

# 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

```bash
pip install mcp-worker-sdk
```

With all built-in database drivers:

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

---

## Quick start

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

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

| Adapter | Purpose |
|---------|---------|
| `ShellAdapter` | Command-line / sandbox / code execution |
| `DBAdapter` | Relational / vector / graph / KV / document databases (7 built-in drivers) |
| `MacAdapter` | macOS GUI / AppleScript / screenshots / mouse & keyboard |
| `HTTPAdapter` | Cloud API forwarding (auth, signing hooks, pagination, JSONPath) |
| `MCPClientAdapter` | Wrap a third-party MCP server |
| `CustomAdapter` | Fully custom execution |

### DBAdapter built-in drivers

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

---

## CLI scaffold

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

---

## License

Apache-2.0