Toolkits - HeavenBase

A Tool is a live view over a Capsule. The Capsule is the durable executable payload.

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.

2. Build and Register a Toolkit

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:

toolkit = hb.Toolkit("math-tools", {"add": add, "fibonacci": fibonacci}, namespace="demo")

3. Load and Run From Another Path

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:

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.

4. Architecture Data Flow

Toolkit execution is a thin layer over Capsules:

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

5. Serve Through MCP

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:

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).

6. Import an MCP Server

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.

7. Workspace Toolkits

Every workspace can still become a Toolkit:

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.

8. Demo

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.

Further Exploration

Related resources:

Capsules - Durable executable manifests behind each Tool
Extensions - sys-toolkit is part of the system extension
HeavenBase MCP - MCP transport and client configuration
First MCP - Persisted Capsule Toolkit MCP serving
MCP toolkit reference - Full API tables and CLI commands

​1. What a Toolkit Is

​2. Build and Register a Toolkit

​3. Load and Run From Another Path

​4. Architecture Data Flow

​5. Serve Through MCP

​6. Import an MCP Server

​7. Workspace Toolkits

​8. Demo

​Further Exploration

1. What a Toolkit Is

2. Build and Register a Toolkit

3. Load and Run From Another Path

4. Architecture Data Flow

5. Serve Through MCP

6. Import an MCP Server

7. Workspace Toolkits

8. Demo

Further Exploration