# ToolDock

[![CI](https://github.com/jaytyagiwithai-wq/tooldock_1.0/actions/workflows/ci.yml/badge.svg)](https://github.com/jaytyagiwithai-wq/tooldock_1.0/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB.svg)](https://www.python.org/)
[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Write a typed Python function once. ToolDock exposes it as a CLI command, a
REST endpoint, and an MCP tool without adding transport code to the function.

```text
typed function -> registry -> validation -> CLI / REST / MCP
```

## Install

The distribution is named `tooldock-ai`; the Python import is `tooldock`.

```console
pip install tooldock-ai
```

Until the first PyPI release, install directly from GitHub:

```console
pip install "tooldock-ai @ git+https://github.com/jaytyagiwithai-wq/tooldock_1.0.git"
```

ToolDock requires Python 3.11 or newer.

## One function, three interfaces

Define the business function in `tools.py`:

```python
from tooldock import ToolDock

dock = ToolDock()


@dock.tool
def calculate_shipping(
    city: str,
    weight: float,
    express: bool = False,
) -> float:
    """Calculate a shipping quote."""
    rate = 20 if express else 10
    return weight * rate
```

### CLI

```python
# cli_app.py
from tooldock import build_cli
from tools import dock

app = build_cli(dock)

if __name__ == "__main__":
    app()
```

```console
python cli_app.py calculate-shipping Delhi 2.5 --express
```

Required parameters become arguments, defaults become options, booleans become
flags, and repeated values map to typed lists.

### REST

```python
# api_app.py
from tooldock import build_api
from tools import dock

app = build_api(dock, title="Shipping Tools")
```

```console
uvicorn api_app:app --reload
curl -X POST http://127.0.0.1:8000/tools/calculate-shipping \
  -H "Content-Type: application/json" \
  -d '{"city":"Delhi","weight":2.5,"express":true}'
```

FastAPI publishes OpenAPI at `/openapi.json` and interactive docs at `/docs`.

### MCP

```python
# mcp_app.py
from tooldock import build_mcp, run_mcp
from tools import dock

server = build_mcp(dock, name="Shipping Tools")

if __name__ == "__main__":
    run_mcp(server)
```

Run `python mcp_app.py` from an MCP client configuration. The server uses stdio,
so it waits silently for JSON-RPC requests rather than presenting an interactive
prompt. See [the MCP guide](docs/mcp.md) for client configuration and debugging.

## What ToolDock guarantees

- Registration is explicit: only functions decorated with `@dock.tool` are
  exposed.
- Type hints and defaults produce one shared Pydantic input contract.
- Inputs are validated before the function runs.
- Return values are checked strictly against the return annotation.
- Sync and async functions share the same public execution API.
- CLI, REST, and MCP translate the same domain errors for their environments.
- Adapters take a startup snapshot; register every tool before building them.

Unsupported signatures fail during registration. Positional-only parameters,
`*args`, `**kwargs`, missing parameter annotations, and missing return
annotations are rejected because they cannot produce a dependable cross-
interface contract.

## Error boundaries

| Failure | CLI | REST | MCP |
| --- | --- | --- | --- |
| Invalid input | Message, exit 2 | HTTP 422 | Correctable tool error |
| Invalid function output | Message, exit 1 | Safe HTTP 500 | Safe tool error |
| Function exception | Message, exit 1 | Safe HTTP 500 | Safe tool error |

REST and MCP responses do not expose runtime exception text or invalid returned
values. Applications should log chained exceptions to a protected diagnostic
sink.

## Documentation

- [Architecture](docs/architecture.md)
- [Public API](docs/api-reference.md)
- [MCP integration](docs/mcp.md)
- [Contributing](CONTRIBUTING.md)
- [Security policy](SECURITY.md)
- [Changelog](CHANGELOG.md)

## Development

```console
git clone https://github.com/jaytyagiwithai-wq/tooldock_1.0.git
cd tooldock_1.0
uv sync --group dev
uv run pytest -q
uv run ruff check src tests examples
uv run ruff format --check src tests examples
uv build
uv run twine check dist/*
```

The test suite includes a real MCP child-process round trip in addition to unit
and in-memory protocol tests.

## License

ToolDock is available under the [MIT License](LICENSE).