首个 MCP

MCP 服务器让你不必重复造轮子。我们也希望你不必重复安装轮子。

大多数 MCP 服务器会定义函数然后启动进程。HeavenBase 增加了注册表持久化：Toolkit 的源代码、签名、文档字符串与修订历史都会记录在 Capsule 注册表中。注册一次后，即便原始 .py 文件已删除，你也可以通过简短脚本或 CLI 提供服务。

1. 演示：创建数学 Toolkit

定义普通函数并以列表传入。HeavenBase 使用每个函数的 __name__ 作为工具名称：

# math_tools.py
import heavenbase as hb


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


def sub(left: int, right: int) -> int:
    """Subtract right from left."""
    return left - right


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


def div(left: int, right: int) -> float:
    """Divide left by right."""
    return left / right


def mod(left: int, right: int) -> int:
    """Return left modulo right."""
    return left % right


def fibonacci(n: int) -> list[int]:
    """Return the first n Fibonacci numbers."""
    a, b = 0, 1
    result = []
    for _ in range(n):
        result.append(a)
        a, b = b, a + b
    return result

if __name__ == "__main__":
    toolkit = hb.Toolkit(
        "math-tools",
        [add, sub, mul, div, mod, fibonacci],
        description="Basic arithmetic and sequence operations",
        namespace="quickstart",
        version="1",
    )

    toolkit.register(overwrite=True, reason="initial quickstart math tools")

传入函数列表是最简单的形式：函数的 __name__ 成为工具名称，文档字符串成为工具描述。若需自定义名称，可传入字典，例如 {"add": add, "mul": mul}。HeavenBase 会自动捕获源代码、类型注解与 import 引用。namespace="quickstart" 参数将此演示工具集 (Toolkit) 归入 quickstart 注册表前缀，便于 hb mcp list 与 serve 命令定位 quickstart.math-tools。reason 值是人类可读的注册表修订说明，便于日后查看 Toolkit 历史。

2. 运行一次以持久化

python math_tools.py

此时 Toolkit 已校验并写入注册表。你可以删除 math_tools.py；这些函数现已存在于注册表中。这种持久化是关键区别。注册完成后，可在另一脚本中提供服务、重启后继续，或在共享注册表数据库时在另一台机器上提供服务。

3. 在任意位置加载并提供服务

Toolkit 持久化后，加载与提供服务无需函数定义，也无需从原始模块 import：

# serve_math.py
import heavenbase as hb

loaded = hb.Toolkit.load(name="math-tools", namespace="quickstart", version="1")
print(loaded.to_mcp_json())
loaded.serve(wait=True)

python serve_math.py

服务器会打印 MCP 配置并在 http://127.0.0.1:7001/mcp 监听：

{
  "mcpServers": {
    "math-tools": {
      "transport": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

HeavenBase 支持常见的 MCP 传输方式。每个服务器进程使用一种传输，客户端连接对应端点：

Transport	Serve command	Client endpoint
Streamable HTTP	`hb mcp serve quickstart.math-tools --transport http`	`http://127.0.0.1:7001/mcp`
SSE	`hb mcp serve quickstart.math-tools --transport sse`	`http://127.0.0.1:7001/sse`
stdio	`hb mcp stdio quickstart.math-tools`	command transport, no URL

在 Python 中，当仅支持 SSE 的客户端需要 /sse 时，向 loaded.to_mcp_json(transport="sse") 与 loaded.serve(transport="sse", wait=True) 传入相同传输参数。

将注册与服务拆成两个脚本是有意为之：这表明 Toolkit 比创建它的脚本更长寿。HeavenBase 的注册表将创建与服务解耦，因此同一已注册的 Toolkit 可由任何能读取注册表 DB 的进程提供服务。若更看重便利，也可在一个文件中合并两步。

4. 直接从 CLI 提供服务

完全跳过服务器脚本。CLI 可加载并提供任何已持久化的 Toolkit：

hb mcp serve quickstart.math-tools

无需编写服务器代码即可列出、检查并调用工具：

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

call 命令应打印 5；mcp-json 应打印与上文相同的 HTTP 配置。

5. 连接你的 Agent

将服务器添加到你常用的编程 Agent：

使用 Claude Code CLI 添加 HTTP 服务器：

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

Claude Code 将本地作用域的 MCP 服务器存储在 ~/.claude.json。若需在仓库内共享，请在项目根目录用相同命令加 --scope project，或创建 .mcp.json：

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

启动新的 Claude Code 会话，运行 /mcp，确认 math-tools 已连接，再请 Agent 使用算术工具。

Codex 支持三种方式：CLI、配置文件与 GUI（Codex App 或 IDE 扩展）。GUI（Codex App）：Settings > MCP servers > + Add server，然后填写：

Name: math-tools
选择 Streamable HTTP
URL: http://127.0.0.1:7001/mcp

配置文件（~/.codex/config.toml）：

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

CLI：

codex mcp add math-tools --url http://127.0.0.1:7001/mcp
codex mcp list

若你的 Codex 版本在添加后未显示 HTTP MCP 服务器，请在 ~/.codex/config.toml 中启用 experimental_use_rmcp_client 功能：

[features]
experimental_use_rmcp_client = true

启动新的 Codex 会话，或在 TUI 中运行 /mcp，确认 math-tools 出现并已发现其工具。

若服务器只属于一个仓库，使用项目级配置；若希望全局可用，使用全局配置：

Project: .cursor/mcp.json
Global: ~/.cursor/mcp.json

粘贴以下配置：

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

也可打开 Cursor Settings > Features > MCP > Add new global MCP server，然后填写：

Name: math-tools
Type: http
URL: http://127.0.0.1:7001/mcp

重新加载 Cursor 或打开新对话，然后在 MCP 设置面板中确认 math-tools 已启用。

按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），运行 MCP: Add Server，选择 HTTP，然后填写：

URL: http://127.0.0.1:7001/mcp
Name: math-tools

若需工作区作用域，添加 .vscode/mcp.json。VS Code 使用 servers 键，而非 mcpServers：

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

重新加载 VS Code 窗口，或从命令面板运行 MCP: List Servers，然后确认 math-tools 正在运行。

将远程 MCP 服务器添加到项目 opencode.json / opencode.jsonc，或添加到全局配置 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "math-tools": {
      "type": "remote",
      "url": "http://127.0.0.1:7001/mcp",
      "enabled": true
    }
  }
}

在 Windows 上，全局配置使用 %APPDATA%\opencode\config.jsonc。重启 OpenCode 或运行 opencode mcp list 确认服务器可用，然后在提示中引用 math-tools。

在 ~/.openclaw/openclaw.json 的 mcp.servers 下添加服务器：

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

或用 CLI 写入相同条目：

openclaw config set mcp.servers.math-tools '{"url":"http://127.0.0.1:7001/mcp","transport":"streamable-http"}'
openclaw mcp list

OpenClaw 会热应用大多数 MCP 配置变更。若已有会话已加载工具，请启动新的 Agent 会话。

将 HTTP 服务器添加到 ~/.hermes/config.yaml：

mcp_servers:
  math-tools:
    url: "http://127.0.0.1:7001/mcp"
    enabled: true

保存文件后重新加载或重启 Hermes，然后请其列出可用 MCP 工具，确认算术工具已出现。

在 LM Studio 中打开 Program/Developer 面板，选择 Install > Edit mcp.json，并添加服务器。LM Studio 采用与 Cursor 相同的 mcp.json 写法：

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

保存文件，若 LM Studio 显示开关则启用服务器，并开启工具使用的新对话。

HeavenBase 自带 LLM 聊天/会话界面，可用 --mcp 直接从注册表连接 MCP 服务器：

hb llm chat --mcp quickstart.math-tools "What's 42 * 73?"
hb llm session --mcp quickstart.math-tools

也可让 HeavenBase 指向正在运行的 HTTP MCP 端点：

hb llm session --mcp http://127.0.0.1:7001/mcp

在交互式会话中，用 /mcp SOURCE 添加另一个 MCP 源。

安装 SDK，用 Streamable HTTP 启动 HeavenBase 服务器，然后用 MCPServerStreamableHttp 连接：

pip install openai-agents
hb mcp serve quickstart.math-tools --transport http

from agents import Agent, ModelSettings, OpenAIChatCompletionsModel, Runner
from agents.mcp import MCPServerStreamableHttp

import heavenbase as hb

async with MCPServerStreamableHttp(
    name="math-tools",
    params={"url": "http://127.0.0.1:7001/mcp"},
    cache_tools_list=True,
) as server:
    llm = hb.LLM(preset="chat")
    model_args = llm.to_args()
    model_name = model_args.pop("model")

    agent = Agent(
        name="MathAgent",
        instructions="Use the MCP math tools when they help.",
        model=OpenAIChatCompletionsModel(
            model=model_name,
            openai_client=llm.to_aclient(),
        ),
        model_settings=ModelSettings(**model_args),
        mcp_servers=[server],
        mcp_config={"include_server_in_tool_names": False},
    )

    result = await Runner.run(agent, "What's 42 * 73?")
    print(result.final_output)

若你的 SDK 版本仅提供 MCPServerSse，请用 hb mcp serve quickstart.math-tools --transport sse 启动 HeavenBase，并连接 http://127.0.0.1:7001/sse。

6. 动手试试

连接后，请 Agent 使用数学工具：

> What's 42 * 73?
> Compute the first 15 Fibonacci numbers.
> What is the 63rd Fibonacci number modulo 10000?
> Is 97 a prime number? (use mod to check divisibility)
> Calculate (85 + 37) * 12 / 4

Agent 通过 MCP 发现每个工具的名称、描述与参数 schema，再按需调用。

由于 Toolkit 已持久化，你可以停止服务器、重启，然后用 hb mcp serve quickstart.math-tools 恢复：无需脚本、无需重新定义、不会丢失。

进一步探索

下一步：

HeavenBase MCP - 通过 MCP 暴露工作区，无需编写实体代码
30 分钟开发者工作坊：任务清单管理器 - 构建 Sublinear，一款 Agent 化任务清单管理器
工具集 (Toolkit) - 工具集 (Toolkit) 架构、MCP 提供与导入
Capsule - 持久化任意 Python 函数
MCP 工具集 (Toolkit) 参考 - 完整工具列表与服务选项

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

1. 演示：创建数学 Toolkit

2. 运行一次以持久化

3. 在任意位置加载并提供服务

4. 直接从 CLI 提供服务

5. 连接你的 Agent

6. 动手试试

进一步探索

​1. 演示：创建数学 Toolkit

​2. 运行一次以持久化

​3. 在任意位置加载并提供服务

​4. 直接从 CLI 提供服务

​5. 连接你的 Agent

​6. 动手试试

​进一步探索

1. 演示：创建数学 Toolkit

2. 运行一次以持久化

3. 在任意位置加载并提供服务

4. 直接从 CLI 提供服务

5. 连接你的 Agent

6. 动手试试

进一步探索