Skip to main content
Glama
ToolDock

ToolDock

ToolDock

CI Python 3.11+ MIT 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.

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.

Related MCP server: FastAPI Apcore MCP Server

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

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables turning any Python function into an auto-registered MCP tool and serving them over a FastMCP server with auto-discovery, optional auth, and request context.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables developers to expose pico-ioc component methods as Model Context Protocol tools, resources, and prompts, deriving input schemas from method signatures and resolving every call through the dependency-injection container. Supports stdio and streamable-HTTP transports and detects duplicate tool, resource, or prompt names at startup.
      MIT