Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ahvn.top/llms.txt

Use this file to discover all available pages before exploring further.

Workspace MCP exposes data operations. Capsule Toolkits expose reviewed Python functions.

​
1. When to use this page

Use a Capsule Toolkit when the agent needs stable application functions such as math, project operations, parsers, validators, or domain tools. A Toolkit can be called locally, registered in a HeavenBase registry, exported as a FastMCP server, and imported back as a local Toolkit client. Use Workspace MCP when the agent needs generic entity, CRUD, query, explain, or memory tools for one workspace.

​
2. Create a Toolkit

import heavenbase as hb

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

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

toolkit.register()
You can also pass tools directly: 
toolkit = hb.Toolkit("math-tools", {"add": add, "mul": mul}, namespace="demo")
The default namespace comes from heavenbase.toolkit.namespace, then heavenbase.capsule.namespace, then default.

​
3. Serve through MCP

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

toolkit.serve(transport="http", host="127.0.0.1", port=7011, wait=True)
For client configuration: 
print(toolkit.to_mcp_json(transport="http", host="127.0.0.1", port=7011))
FastMCP serves native Python return values. Scalar results appear under structured_content["result"] in FastMCP client responses.

​
4. Import MCP as a Toolkit client

client_toolkit = hb.Toolkit.from_fastmcp(server, name="math-client")
result = client_toolkit.run("add", left=2, right=3)
The imported Toolkit calls the MCP server through fastmcp.Client. It is runtime-only and should not be registered as a durable Toolkit because it closes over a live server or transport.

​
5. CLI

hb mcp list
hb mcp show demo/math-tools:1
hb mcp tools demo/math-tools:1
hb mcp call demo/math-tools:1 add --args '{"left":2,"right":3}'
hb mcp mcp-json demo/math-tools:1 --transport http --host 127.0.0.1 --port 7011
hb mcp mcp-json demo/math-tools:1 --transport stdio
hb mcp stdio demo/math-tools:1
hb mcp serve demo/math-tools:1 --transport http --host 127.0.0.1 --port 7011
hb mcp remove demo/math-tools:1
The Capsule/Toolkit registry is initialized by hb setup; users do not need a separate MCP setup step. Use --registry-db file:<path> when a test or demo should target an isolated SQLite registry. Stdio MCP configs use hb mcp stdio <namespace/name:version> so the client process imports HeavenBase in the active Python environment and serves the registered Toolkit directly from the registry.

​
6. How the pieces fit

The export path is:
  1. CapsuleManifest stores signature and schema.
  2. Tool exposes the Capsule under a tool name.
  3. Toolkit.to_fastmcp() builds wrappers with evaluated annotations and the original callable signature.
  4. FastMCP serves the wrappers over the selected transport.
Keep Capsule registries trusted. Loading a Capsule restores executable Python code, so the registry should be treated like a source code repository.

​
Further Exploration

Related resources: