MCP 工具集 (Toolkit) 参考

工具集 (Toolkit) API

import heavenbase as hb

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

Method	Purpose
`Toolkit.add(item, name=...)`	添加 callable、`Capsule` 或 `Tool`。
`Toolkit.tool(name=...)`	将函数添加到工具集 (Toolkit) 的装饰器。
`Toolkit.run(tool_name, **kwargs)`	本地运行一个工具。
`Toolkit.register(registry_config=..., on_conflict=...)`	保存每个工具的主 Capsule 与 serializer Capsule，再存储工具集 (Toolkit) manifest。默认为 `overwrite=True`。
`Toolkit.run_to_str(tool_name, **kwargs)`	运行一个工具并通过 serializer Capsule 返回序列化字符串。
`Toolkit.load(..., registry_config=...)`	按 id 或 namespace/name/version 从注册表记录加载工具集 (Toolkit)。
`Toolkit.to_fastmcp()`	构建进程内 FastMCP 服务器。
`Toolkit.from_fastmcp(server, name=...)`	将 FastMCP 服务器导入为工具集 (Toolkit) 客户端。
`Toolkit.to_mcp_json(...)`	返回 MCP 客户端配置 JSON。
`Toolkit.serve(...)`	运行 FastMCP 服务器。
`Toolkit.to_anthropic_tools(...)`	导出带 `allowed_callers` 的 programmatic tool 定义。

Capsule API

Method	Purpose
`Capsule.from_func(func, ...)`	将 callable 捕获为 Capsule manifest。
`capsule.register(registry_config=...)`	在默认或配置的注册表中存储 Capsule。
`Capsule.load(..., registry_config=...)`	按 id 或 namespace/name/version 加载。
`capsule.to_func()`	用 source、import path、再受信任二进制回退恢复 callable。
`capsule.run(**kwargs)`	恢复并调用函数。
`capsule(args, *kwargs)`	像被包装的 Python 函数一样调用 Capsule。
`capsule.to_str(“json"	"yaml"	"source"	"docstring”)`	将 Capsule manifest 或 callable 元数据转换为文本表示。
`Capsule.from_str(text, format="json")`	从 JSON 或 YAML manifest 字符串恢复 Capsule。

CLI

Command	Purpose
`hb setup`	初始化全局 HeavenBase 配置、默认工作区与 Capsule/工具集 (Toolkit) 注册表。
`hb mcp list`	列出已注册工具集 (Toolkit)。
`hb mcp capsules`	列出已注册 Capsule。
`hb mcp show REF`	显示一条工具集 (Toolkit) 记录。
`hb mcp tools REF`	列出工具集 (Toolkit) 中的工具。
`hb mcp call REF TOOL --args JSON`	从控制台调用一个工具。
`hb mcp mcp-json REF`	打印 MCP 客户端配置 JSON。
`hb mcp serve REF`	将工具集 (Toolkit) 作为 MCP 提供。
`hb mcp remove REF`	对工具集 (Toolkit) 注册表行做 tombstone。

Callable 序列化

内部 callable 序列化位于 heavenbase.extensions.system.capsule.serialize：

from heavenbase.extensions.system.capsule.serialize import CallableSerialization

payload = CallableSerialization.from_func(add, include_cloudpickle=False).to_dict()
capsule = CallableSerialization.from_dict(payload).to_capsule()

通用 JSON 序列化对 callable 使用相同策略；无法捕获的 callable 回退为轻量引用。

注册表与元数据实体

Capsule 与工具集 (Toolkit) 作为必需 system 扩展拥有的系统实体持久化：

Entity id	Contents
`sys-capsule`	活跃 Capsule manifest 行，含身份、manifest 载荷、能力、指纹，以及覆盖时的 `last_reason`。
`sys-toolkit`	活跃工具集 (Toolkit) manifest，每个工具有序的主 Capsule 与 serializer Capsule 引用。

工作区还会将 mcp_profile、mcp_serializer、toolkit_family、storage_profile、sql_dialect 与 database_dialect 元数据镜像到 sys-metaschema 行。

工作区 MCP 工具

workspace.to_mcp(...) 与 workspace.serve(...) 会组装已注册的工具集 family，并暴露这些核心工作区工具：

Tool	Purpose
`define_entity`	从 JSON 创建新实体 (Entity) 定义。
`list_entities`	列出已注册实体 id。
`describe_entity`	返回一个实体定义与路由 (Routing) 计划。
`upsert`	插入或替换一行。
`upsert_many`	插入或替换多行并按输入顺序返回 id。
`get`	按 id 获取一行。
`get_many`	按 id 顺序获取多行。
`set`	应用一行补丁。
`set_many`	应用多行补丁并按输入顺序返回 id。
`delete`	删除一个目标。
`delete_many`	按输入顺序删除多个目标。
`exists`	检查一个 id。
`exists_many`	按输入顺序检查多个 id。
`count`	统计一种实体类型的行数。
`query`	执行 JSON 查询 (Query) spec。
`explain`	解释 JSON 查询 (Query) 的路由与处理器 (Handler) 选择。

HeavenBase 尚未暴露通用 MCP alter_entity 或 undefine_entity 工具，因为在智能体 (Agent) 能安全变更或删除实体定义之前，实体迁移、物理清理、目录 (Catalog) 更新与恢复语义必须显式化。

工作区 MCP profile

MCP 暴露使用声明式 ProfileSpec 对象（配置位于 heavenbase.mcp.profiles.<name> 或 hb.ext.register_profile）。Profile 组合工具组、工具集 family（WorkspaceToolkitFamilySpec）、实体/Skill 范围与已注册 serializer。

Profile	Tools	Serializer	Owner
`full`	全部工作区工具	`jstr`	system toolkit
`agent`	精选 inspect/read/write/query 面，外加可选 `list_skills` / `read_skill`	`markdown`	system + `agent` extension
`memory`	`remember`、`recall`、`search_memory`、`list_memory`、`set_memory`	`jstr`	`memory` extension
`memstate`	`memstate_*` 动词	`jstr`	`memory` extension
`database`	read/query 组外加 `run_snippet`、`suggest_sql`	`jstr`	`database` extension

Profile、serializer 与 family spec 会镜像到 sys-metaschema 并按工作区重新加载；可选扩展 family 在首次使用时自动启用其扩展。简单 memory 工作流：remember 记摘要或决策，recall/list_memory 精确检索与浏览，search_memory 模糊查找，set_memory 精确键修正。 Memstate 风格 memory 工作流使用 profile="memstate"。它将键前缀为 project.<project_id>.<keypath>，用 memstate_get 返回当前行，为 memstate_history 保留先前版本，写入时报告冲突的前值，用 memstate_delete 创建 tombstone。

提供选项

workspace.serve(
    name="notes",
    transport="http",
    host="127.0.0.1",
    port=7001,
    wait=True,
)

默认位于 heavenbase.mcp：

Config key	Default
`heavenbase.mcp.transport`	`http`
`heavenbase.mcp.host`	`127.0.0.1`
`heavenbase.mcp.port`	`7001`
`heavenbase.mcp.wait`	`true`

健康检查

用 FastMCP 客户端验证服务器能否列出并调用工具：

from fastmcp import Client

server = toolkit.to_fastmcp()

async with Client(server) as client:
    tools = await client.list_tools()
    result = await client.call_tool("add", {"left": 2, "right": 3})

result.structured_content 在标量 Python 返回值下于 result 键包含工具返回值。

Anthropic programmatic tools

Anthropic programmatic tool calling 是与 MCP connector tools 独立的导出路径：

tool_defs = toolkit.to_anthropic_tools(allowed_callers=["code_execution"])

每条定义包含 allowed_callers、name、description 与 input_schema。从 code execution 调用时，工具执行适配器应返回字符串。

​工具集 (Toolkit) API

​Capsule API

​CLI

​Callable 序列化

​注册表与元数据实体

​工作区 MCP 工具

​工作区 MCP profile

​提供选项

​健康检查

​Anthropic programmatic tools

​相关页面