MCP Toolkit 参考 - HeavenBase

MCP 是门口；Toolkit 决定哪些房间装门把手。

1. 动机

运行时 Toolkit 可以包装实时对象、工作区闭包或远程 FastMCP 服务器。这些值现在可以服务工具，却不一定能在以后恢复。持久 Toolkit 必须引用持久 Capsule，并属于一个显式应用工作区。因此 HeavenBase 把构造、持久化、profile 组装与传输保留为不同操作。同一个 Tool 契约跨越这些操作，而每个边界仍然可检查。

2. 使用 Tool API

API	用途
`Tool(callable_or_capsule, name=...)`	包装 callable 或已有 Capsule。
`@Tool` / `@Tool(name=...)`	裸装饰器或配置装饰器构造。
`tool(args, *kwargs)`	本地调用包装函数。
`tool.run(args, *kwargs)`	显式本地调用。
`tool.set_serializer(...)`	设置 callable 或 Capsule 输出序列化器。
`tool.run_to_str(args, *kwargs)`	调用并序列化结果。
`tool.to_openai_tool()`	导出 OpenAI 兼容工具定义。

import heavenbase as hb


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

除非你提供显式输入或输出模式元数据，否则 Tool 模式从 Capsule 签名派生。

3. 使用 Capsule API

API	用途
`Capsule(callable, ...)`	捕获 callable，并保持函数式行为。
`@Capsule(...)`	配置装饰器捕获。
`Capsule.from_func(...)`	显式 callable 捕获。
`Capsule.from_code(...)`	捕获可信源码文本；捕获时执行一次。
`Capsule.from_manifest(...)`	从 manifest 映射恢复。
`Capsule.from_str(...)`	恢复 JSON 或 YAML manifest 字符串。
`capsule.verify()`	在不执行时检查已存载荷指纹。
`capsule.to_func()`	恢复 callable。
`capsule.run(...)` / `capsule(...)`	恢复并调用。
`capsule.to_str(format)`	渲染 `json`、`yaml`、`source` 或 `docstring`。
`capsule.register(...)`	存入高级 Context 私有 Capsule 注册表。
`Capsule.load/list/delete(...)`	管理独立 Capsule 行。

include_cloudpickle 默认为 False。即使指纹验证成功，恢复与执行仍是可信代码操作。

4. 使用 Toolkit API

API	用途
`Toolkit(name, tools, namespace=..., version=...)`	构造有序 Toolkit。
`toolkit.add(...)` / `add_many(...)`	添加 Tool、Capsule 或 callable 值。
`@toolkit.tool(...)`	把函数加入 Toolkit 的装饰器。
`toolkit.list_tools()`	按声明顺序返回工具名。
`toolkit.run(name, ...)`	运行一个 Tool 并返回 Python 值。
`toolkit.run_to_str(name, ...)`	运行并序列化一个 Tool 结果。
`toolkit.register(ws=..., on_conflict=...)`	在一个工作区持久化 Toolkit 与引用 Capsule。
`Toolkit.load(..., ws=...)`	加载 Toolkit 并惰性恢复 Capsule。
`Toolkit.list(..., ws=...)`	列出一个工作区中的 Toolkit 行。
`Toolkit.describe(..., ws=...)`	返回一条原始 Toolkit 行。
`Toolkit.delete(id, ws=...)`	Tombstone 或移除一条 Toolkit 行。
`toolkit.to_fastmcp()`	构建进程内 FastMCP 服务器。
`Toolkit.from_fastmcp(...)`	在实时服务器上构建运行时客户端 Toolkit。
`toolkit.to_mcp_json(...)`	返回 MCP 客户端配置 JSON。
`toolkit.serve(...)`	服务 Toolkit。
`toolkit.to_anthropic_tools(...)`	导出 Anthropic programmatic tool 定义。

ws = hb.HeavenBase("math-app", preset="debug")
toolkit = hb.Toolkit("math", {"add": add}, namespace="demo")
toolkit_id = toolkit.register(ws=ws)

loaded = hb.Toolkit.load(toolkit_id, ws=ws)
assert loaded.run("add", left=2, right=3) == 5

Toolkit 持久化调用省略 ws= 时会使用仅加载已有项的 hb.HeavenBase.load()。它绝不会创建工作区。

5. 理解工作区自有数据行

Entity id	内容
`sys-capsule`	Capsule 身份、manifest、能力、指纹、状态、原因、时间戳
`sys-toolkit`	Toolkit 身份、有序主/serializer Capsule 引用、服务元数据、状态、原因、时间戳

Capsule 是必需 Extension 根。Toolkit 是打包默认根。Toolkit.register(ws=...) 确保工作区拥有 Toolkit 与引用的 Capsule 行。独立 Capsule.register() 使用高级 Context 私有隐藏存储做机器/领域管理。不要把该存储与应用 Toolkit 持久化混为一谈。

6. 使用工作区 MCP 工具

workspace.to_mcp(profile=...) 与 workspace.serve(profile=...) 组装 Registry 支持的 Toolkit family。核心工作区 family 包括：

工具组	工具
模式	`define_entity`, `list_entities`, `describe_entity`
写入	`upsert`, `upsert_many`, `set`, `set_many`
读取	`get`, `get_many`, `exists`, `exists_many`, `count`
删除	`delete`, `delete_many`
查询	`query`, `explain`

这里没有通用 alter_entity 或 undefine_entity MCP 工具。实体迁移、物理清理、Catalog 变更与恢复需要显式领域策略，之后才适合交给智能体。

7. 选择 Profile

Profile 是 mcp_profile Registry 记录。它们组合精确工具名、Toolkit family、Entity 与 Skill 范围、一个序列化器、依赖与可选 extends。

Profile	预期界面
`agent`	精选检查、读取、写入、查询、解释与可选 Skill 工具
`full`	面向可信管理的所有可用工作区工具
`memory`	`remember`, `recall`, `search_memory`, `list_memory`, `set_memory`
`memstate`	版本化 `memstate_*` 键路径操作
`database`	读取/查询组加受控数据库 helper

外部模块可以通过 meta.yaml 发布自己的 Toolkit family 与 profile。所属 Context 会在工作区组装前解析它们；可选 family 只通过声明的 workspace_requires 激活。

8. 使用 MCP CLI

所有 Toolkit 命令都接受或解析一个已有工作区：

命令	用途
`hb mcp setup --workspace ID`	在已有工作区启用 Toolkit 存储。
`hb mcp list --workspace ID`	列出 Toolkit 行。
`hb mcp capsules --workspace ID`	列出 Capsule 行。
`hb mcp show REF --workspace ID`	显示一条 Toolkit 记录。
`hb mcp tools REF --workspace ID`	列出一个 Toolkit 的工具。
`hb mcp call REF TOOL --args JSON --workspace ID`	调用一个工具。
`hb mcp remove REF --workspace ID`	移除或 tombstone 一条 Toolkit 行。
`hb mcp mcp-json REF --workspace ID`	打印客户端配置。
`hb mcp stdio REF --workspace ID`	通过 stdio 服务已注册 Toolkit。
`hb mcp serve REF --workspace ID`	通过所选传输服务已注册 Toolkit。

REF 接受 Toolkit id、name 或 namespace/name:version。

9. 服务并验证

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},
    )

对于工作区 profile：

ws.serve(
    name="math-workspace",
    profile="agent",
    transport="http",
    host="127.0.0.1",
    port=7001,
    wait=True,
)

传输默认值位于 heavenbase.mcp。把未认证 HTTP 保留在 loopback。若无需长生命周期网络服务器，本地编码智能体集成请使用 stdio。

10. 导出 Anthropic Programmatic Tools

tool_defs = loaded.to_anthropic_tools(
    allowed_callers=["code_execution"],
)

这条导出路径与 MCP connector tools 分离。每条定义包含 allowed_callers、名称、描述与输入模式。从 code execution 调用时，执行适配器应返回字符串。

11. 应用信任检查清单

审核 Capsule source、层、模式与序列化器。
除非已审核本地代码确实需要，否则关闭二进制回退。
在显式应用工作区持久化具体 Toolkit。
使用支持任务的最小 profile。
给外部工具加命名空间，并拒绝冲突。
在 Tool 或所属 API 边界验证不可信参数。
让文件系统、凭据、网络与破坏性权威保持显式。
通过目标传输测试真实 list/call 行为。

摘要

Tool、Capsule 与 Toolkit API 共享一个 callable 执行模型。
持久 Toolkit 与 Capsule 属于显式应用工作区。
Profile、serializer 与传输配置让 MCP 权威可检查。

进一步探索

相关资源：

Capsule - 检查捕获、恢复与信任
Toolkit - 构建并持久化工具集合
HeavenBase MCP - 配置工作区服务
首个 MCP - 完成小型 MCP 演练
扩展 - 发布外部 family 与 profile

​1. 动机

​2. 使用 Tool API

​3. 使用 Capsule API

​4. 使用 Toolkit API

​5. 理解工作区自有数据行

​6. 使用工作区 MCP 工具

​7. 选择 Profile

​8. 使用 MCP CLI

​9. 服务并验证

​10. 导出 Anthropic Programmatic Tools

​11. 应用信任检查清单

​摘要

​进一步探索

1. 动机

2. 使用 Tool API

3. 使用 Capsule API

4. 使用 Toolkit API

5. 理解工作区自有数据行

6. 使用工作区 MCP 工具

7. 选择 Profile

8. 使用 MCP CLI

9. 服务并验证

10. 导出 Anthropic Programmatic Tools

11. 应用信任检查清单

摘要

进一步探索