ToolDock

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.

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

Install

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

pip install tooldock-ai

Until the first PyPI release, install directly from GitHub:

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:

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

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

app = build_cli(dock)

if __name__ == "__main__":
    app()

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

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

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

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

# 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 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
• Public API
• MCP integration
• Contributing
• Security policy
• Changelog

Development

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.