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

# 工具集 (Toolkit)

> MCP 工具集合：在 HeavenBase 中定义、转换与持久化工具。

<Note>
  Tool 是 Capsule 的即时视图。Capsule 是持久的可执行载荷。
</Note>

<br />

## 1. 工具集 (Toolkit) 是什么

工具集 (Toolkit) 在工具名下分组 Capsule 与服务元数据。当你希望一组函数像本地 API、MCP 服务器或模型工具调用导出目标时，使用它。

持久模型有意保持精简：

* `Capsule`：存储可执行函数 manifest
* `Tool`：命名一个 Capsule（加可选 serializer Capsule），并暴露 `run(...)` 与 `run_to_str(...)`
* `Toolkit`：排序工具、保存引用并导出服务器
* `sys-toolkit`：存储工具集 (Toolkit) manifest 与 Capsule 引用的持久实体行

每个持久化工具保留两个 Capsule 引用：主执行 Capsule 与 serializer Capsule。默认情况下 HeavenBase 使用共享 `jstr_serializer` Capsule，对 dict 与 list 结果应用紧凑 JSON 序列化。

<br />

## 2. 构建并注册工具集 (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(...)` 保存每个工具的主 Capsule 与 serializer Capsule，再将工具集 (Toolkit) manifest 存为有序 Capsule 引用。加载工具集 (Toolkit) 会惰性恢复引用的 Capsule。

`Toolkit.register(...)` 默认为 `overwrite=True`。需要显式冲突处理时使用 `on_conflict="raise"` 或 `on_conflict="skip"`。

紧凑构造可传入 list、pair 或 mapping：

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

<br />

## 3. 从其他路径加载并运行

```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
```

消费者无需导入创建工具集 (Toolkit) 的文件。它从注册表加载工具集 (Toolkit) manifest，再从各自 manifest 恢复每个 Capsule。

需要 MCP 与 Agent 客户端期望的序列化字符串边界时使用 `run_to_str(...)`：

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

测试与应用可传入 `registry_config=...` 隔离注册表存储，同时保持相同公开 API。

<br />

## 4. 架构数据流

工具集 (Toolkit) 执行是 Capsule 上的薄层：

1. `Toolkit.add(callable)` 将 callable 捕获为主 Capsule，并解析 serializer Capsule（默认 `jstr_serializer`）。
2. `toolkit.register()` 持久化每个工具的两个 Capsule，再存储含有序 Capsule 引用的 `sys-toolkit` 行。
3. `Toolkit.load(...)` 解析 manifest 并将每个引用的 Capsule 恢复为 `Tool`。
4. `Toolkit.run(name, **kwargs)` 本地调用所选主 Capsule，返回原始 Python 值。
5. `Toolkit.run_to_str(name, **kwargs)` 运行工具并通过 serializer Capsule 传递结果。
6. `Toolkit.to_fastmcp()` 用签名兼容的 FastMCP 函数包装每个 Tool，返回序列化字符串。
7. `Toolkit.to_anthropic_tools(...)` 导出带 `allowed_callers` 的独立 Anthropic programmatic tool schema。

<br />

## 5. 通过 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"
```

也可打印客户端配置：

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

用 `toolkit.serve(...)` 阻塞或后台提供。默认位于 `CM_HVNB` 的 `heavenbase.mcp`（transport、host、port、wait）。

<br />

## 6. 导入 MCP 服务器

```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 客户端代理仅用于即时执行。它们无法用 `register()` 持久化，因为闭包持有 live 服务器句柄。

<br />

## 7. 工作区工具集 (Toolkit)

每个工作区仍可成为工具集 (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())
```

工作区工具集 (Toolkit) 组装已注册的工具集 family：核心工作区 family 暴露实体定义、目录 (Catalog) 发现、CRUD、count、查询 (Query) 与 explain 工具。

Family spec 与别名会作为 `toolkit_family` 行镜像到 `sys-metaschema`；即时工作区工具集 (Toolkit) 仍无法注册，因为闭包持有 live 工作区对象。

<br />

## 8. Demo

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

demo 创建持久数学工具集 (Toolkit)，通过 `Toolkit.load(...)` 加载回来，展示 Capsule docstring 与格式转换，并检查 FastMCP 能否列出与调用工具。

<br />

## 进一步探索

<Tip>
  **相关资源：**

  * [Capsule](/zh/features/capsules) - 每个 Tool 背后的持久可执行 manifest
  * [扩展](/zh/features/extensions) - `sys-toolkit` 属于 `system` 扩展
  * [HeavenBase MCP](/zh/quickstart/heavenbase-mcp) - MCP 传输与客户端配置
  * [首个 MCP](/zh/quickstart/first-mcp) - 持久化 Capsule 工具集 (Toolkit) MCP 提供
  * [MCP 工具集 (Toolkit) 参考](/zh/reference/mcp-toolkit/overview) - 完整 API 表与 CLI 命令
</Tip>

<br />