首个 MCP

没有主人的工具，只是一个四处找麻烦的函数。

HeavenBase 可以把普通 Python 函数变成 MCP 工具，但真正重要的边界是所有权。已注册的 Toolkit 及其引用的每个 Capsule 都属于一个显式的应用工作区 (Workspace)。该工作区让创建、检查、提供服务与删除始终指向同一持久状态。不存在进程全局的 Toolkit 数据库；另一个进程必须打开同一个已注册工作区，才能加载这些工具。

1. 动机

全局注册表会让简短演示显得方便，直到两个应用都注册 math-tools、一个应用删除另一个的修订，或服务器悄悄打开错误的数据库。 HeavenBase 改为显式指定工作区：

toolkit.register(ws=workspace)
loaded = hb.Toolkit.load(
    name="math-tools", namespace="quickstart", version="1", ws=workspace
)

工作区拥有 Toolkit 行、引用的 Capsule 行及其后端生命周期。你的 Python 函数仍是普通函数；HeavenBase 在其外部添加持久身份与 MCP 适配器。

2. 创建工作区拥有的 Toolkit

创建 math_tools.py：

import heavenbase as hb


def add(left: int, right: int) -> int:
    """Add two numbers."""
    return left + right


def multiply(left: int, right: int) -> int:
    """Multiply two numbers."""
    return left * right


workspace = hb.HeavenBase("math-demo", preset="debug")
toolkit = hb.Toolkit(
    "math-tools",
    {"add": add, "multiply": multiply},
    namespace="quickstart",
    version="1",
    description="Small arithmetic tools",
)
toolkit.register(
    ws=workspace,
    overwrite=True,
    reason="initial quickstart tools",
)

运行一次：

python math_tools.py

注册会把可调用对象的源代码、签名、注解、导入、序列化器与 Toolkit 元数据捕获为工作区拥有的行。稳定引用为 quickstart/math-tools:1。

Capsule 恢复会执行捕获的 Python。只注册和加载你信任的代码，并把访问所属工作区视为代码执行权限。

3. 从另一个进程加载并提供服务

提供服务的进程显式打开同一个工作区：

import heavenbase as hb


workspace = hb.HeavenBase.load("math-demo")
toolkit = hb.Toolkit.load(
    name="math-tools",
    namespace="quickstart",
    version="1",
    ws=workspace,
)

print(toolkit.to_mcp_json())
toolkit.serve(wait=True)

即使删除 math_tools.py，你仍可运行这段代码，因为工作区保留了捕获的 Capsule。该进程仍需使用同一 HeavenBase 主目录、工作区注册与工件存储；持久化以工作区为作用域，而非环境隐式提供或神奇地跨机器共享。服务器默认监听 http://127.0.0.1:7001/mcp。每个进程使用一种传输：

Transport	Command	Client endpoint
Streamable HTTP	`hb mcp serve quickstart.math-tools --workspace math-demo --transport http`	`http://127.0.0.1:7001/mcp`
SSE	`hb mcp serve quickstart.math-tools --workspace math-demo --transport sse`	`http://127.0.0.1:7001/sse`
stdio	`hb mcp stdio quickstart.math-tools --workspace math-demo`	命令传输

4. 用 CLI 检查并提供服务

每条 Toolkit 命令都接受所属工作区：

hb mcp list --workspace math-demo
hb mcp tools quickstart.math-tools --workspace math-demo
hb mcp call quickstart.math-tools add \
  --workspace math-demo \
  --args '{"left": 2, "right": 3}'
hb mcp mcp-json quickstart.math-tools --workspace math-demo

调用会打印 5。无需服务脚本即可启动 HTTP 服务器：

hb mcp serve quickstart.math-tools --workspace math-demo

同一所有权规则也适用于 Python：

rows = hb.Toolkit.list(ws=workspace, namespace="quickstart")
hb.Toolkit.delete(rows[0]["object_id"], ws=workspace)

删除 Toolkit 默认会把其行标记为墓碑。删除工作区是范围更广的生命周期操作，因为工作区还拥有相关数据与 Capsule 行。

5. 连接客户端

保持服务器运行，然后为一个客户端配置其 Streamable HTTP URL。

Claude Code
Codex
VS Code

添加并验证服务器：

claude mcp add --transport http math-tools http://127.0.0.1:7001/mcp
claude mcp list

开启新会话并运行 /mcp，检查发现的工具。

将此表加入 ~/.codex/config.toml 或受信任项目的 .codex/config.toml：

[mcp_servers.math-tools]
url = "http://127.0.0.1:7001/mcp"

保存后重启应用或扩展，或在 Codex CLI 中运行 /mcp 检查服务器。

创建 .vscode/mcp.json：

{
  "servers": {
    "math-tools": {
      "type": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

从命令面板运行 MCP: List Servers，检查或重启服务器。

对其他客户端，先使用 hb mcp mcp-json quickstart.math-tools --workspace math-demo 输出的 JSON，只调整客户端专属的外层键。

6. 动手试试

向已连接的智能体提问：

Use the math-tools MCP server to calculate 42 * 73, then add 19.

智能体从签名与文档字符串发现 multiply 和 add，调用它们，并应返回 3085。

总结

具体 Toolkit 及其引用的 Capsule 属于显式工作区。
注册结果可以比源文件长寿，但加载仍需同一工作区权限。
Python 与 CLI 操作使用相同的工作区拥有行。
工作区绑定工具是受信任的可执行代码，而非惰性数据。

进一步探索

相关资源：

HeavenBase MCP - 直接暴露一个实时工作区
Toolkit - 理解 Toolkit 身份与 profile
Capsule - 检查可调用对象捕获与恢复
MCP Toolkit 参考 - 查看 CLI 与服务契约
Claude Code MCP - 配置 Claude Code
Codex MCP - 配置 Codex 客户端
VS Code MCP - 配置 VS Code

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

1. 动机

2. 创建工作区拥有的 Toolkit

3. 从另一个进程加载并提供服务

4. 用 CLI 检查并提供服务

5. 连接客户端

6. 动手试试

总结

进一步探索

​1. 动机

​2. 创建工作区拥有的 Toolkit

​3. 从另一个进程加载并提供服务

​4. 用 CLI 检查并提供服务

​5. 连接客户端

​6. 动手试试

​总结

​进一步探索

1. 动机

2. 创建工作区拥有的 Toolkit

3. 从另一个进程加载并提供服务

4. 用 CLI 检查并提供服务

5. 连接客户端

6. 动手试试

总结

进一步探索