> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Toolkits

> MCP tool collections: define, convert, and persist tools in HeavenBase.

<Note>
  A Tool is a live view over a Capsule. The Capsule is the durable executable payload.
</Note>

<br />

## 1. What a Toolkit Is

A Toolkit groups Capsules under tool names and serving metadata. Use it when you want a set of functions to behave like a local API, an MCP server, or an export target for model tool calling.

The durable model is intentionally small:

* `Capsule`: stores the executable function manifest
* `Tool`: names one Capsule (plus an optional serializer Capsule) and exposes `run(...)` and `run_to_str(...)`
* `Toolkit`: orders tools, saves references, and exports servers
* `sys-toolkit`: persistent entity row storing the Toolkit manifest and Capsule references

Each persisted tool keeps two Capsule references: a main execution Capsule and a serializer Capsule. By default, HeavenBase uses the shared `jstr_serializer` Capsule, which applies compact JSON serialization for dict and list results.

<br />

## 2. Build and Register a Toolkit

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

def add(left: int, right: int) -> int:
    return left + right

def fibonacci(number: int) -> int:
    previous = 0
    current = 1
    for _ in range(number):
        previous, current = current, previous + current
    return previous

toolkit = hb.Toolkit("math-tools", namespace="demo", version="1")

@toolkit.tool(name="add")
def add_tool(left: int, right: int) -> int:
    return add(left, right)

toolkit.add(fibonacci, name="fibonacci", namespace="demo", version="1")

toolkit_id = toolkit.register()
```

`toolkit.register(...)` saves each tool's main Capsule and serializer Capsule, then stores the Toolkit manifest as ordered Capsule references. Loading a Toolkit restores the referenced Capsules lazily.

`Toolkit.register(...)` defaults to `overwrite=True`. Use `on_conflict="raise"` or `on_conflict="skip"` when you need explicit conflict handling.

For compact construction, pass a list, pairs, or a mapping:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
toolkit = hb.Toolkit("math-tools", {"add": add, "fibonacci": fibonacci}, namespace="demo")
```

<br />

## 3. Load and Run From Another Path

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
loaded = hb.Toolkit.load(name="math-tools", namespace="demo", version="1")
assert loaded.run("add", left=2, right=3) == 5
assert loaded.run("fibonacci", number=10) == 55
```

The consumer does not need to import the file that created the Toolkit. It loads the Toolkit manifest from the registry, then restores each Capsule from its manifest.

Use `run_to_str(...)` when you need the serialized string boundary that MCP and agent clients expect:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
assert loaded.run_to_str("add", left=2, right=3) == "5"
```

Tests and applications can pass `registry_config=...` to isolate registry storage while keeping the same public API.

<br />

## 4. Architecture Data Flow

Toolkit execution is a thin layer over Capsules:

1. `Toolkit.add(callable)` captures the callable as a main Capsule and resolves a serializer Capsule (default `jstr_serializer`).
2. `toolkit.register()` persists both Capsules for each tool and then stores a `sys-toolkit` row containing ordered Capsule references.
3. `Toolkit.load(...)` resolves the manifest and restores each referenced Capsule into a `Tool`.
4. `Toolkit.run(name, **kwargs)` calls the selected main Capsule locally and returns the raw Python value.
5. `Toolkit.run_to_str(name, **kwargs)` runs the tool and passes the result through its serializer Capsule.
6. `Toolkit.to_fastmcp()` wraps each Tool with a signature-compatible FastMCP function that returns serialized strings.
7. `Toolkit.to_anthropic_tools(...)` exports a separate Anthropic programmatic tool schema with `allowed_callers`.

<br />

## 5. Serve Through MCP

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from fastmcp import Client

server = loaded.to_fastmcp()

async with Client(server) as client:
    tools = await client.list_tools()
    result = await client.call_tool("add", {"left": 2, "right": 3})
    assert result.content[0].text == "5"
```

You can also print client configuration:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
print(loaded.to_mcp_json(transport="http", host="127.0.0.1", port=7011))
```

Block and serve with `toolkit.serve(...)`. Defaults live under `heavenbase.mcp` in `CM_HVNB` (transport, host, port, wait).

<br />

## 6. Import an MCP Server

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
client_toolkit = hb.Toolkit.from_fastmcp(server, name="math-client")
assert client_toolkit.run_to_str("add", left=2, right=3) == "5"
```

FastMCP client proxies are runtime-only. They cannot be persisted with `register()` because they close over a live server handle.

<br />

## 7. Workspace Toolkits

Every workspace can still become a Toolkit:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
workspace = hb.HeavenBase("notes", backends={"main": {"type": "inmem"}})
toolkit = workspace.to_mcp(name="notes")

print(toolkit.list_tools())
```

Workspace Toolkits assemble registered toolkit families: the core workspace family exposes entity definition, Catalog discovery, CRUD, count, query, and explain tools.

Family specs and aliases mirror into `sys-metaschema` as `toolkit_family` rows; runtime workspace Toolkits still cannot be registered because they close over a live workspace object.

<br />

## 8. Demo

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rtk uv run python demos/developer/05_capsules_toolkits_mcp.py
```

The demo creates a persisted math Toolkit, loads it back through `Toolkit.load(...)`, shows Capsule docstring and format conversion, and checks that FastMCP can list and call the tools.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Capsules](/features/capsules) - Durable executable manifests behind each Tool
  * [Extensions](/features/extensions) - `sys-toolkit` is part of the `system` extension
  * [HeavenBase MCP](/quickstart/heavenbase-mcp) - MCP transport and client configuration
  * [First MCP](/quickstart/first-mcp) - Persisted Capsule Toolkit MCP serving
  * [MCP toolkit reference](/reference/mcp-toolkit) - Full API tables and CLI commands
</Tip>

<br />