跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://ahvn.top/llms.txt

Use this file to discover all available pages before exploring further.

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__ 成为工具名称，文档字符串成为工具描述。若需自定义名称，请改用 {"alias": fn}。HeavenBase 会自动捕获源代码、类型注解与 import 引用。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 传输方式。每个服务器进程使用一种传输，客户端连接对应端点：
TransportServe commandClient endpoint
Streamable HTTPhb mcp serve quickstart.math-tools --transport httphttp://127.0.0.1:7001/mcp
SSEhb mcp serve quickstart.math-tools --transport ssehttp://127.0.0.1:7001/sse
stdiohb mcp stdio quickstart.math-toolscommand 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 使用算术工具。

​
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 恢复：无需脚本、无需重新定义、不会丢失。

​
进一步探索

下一步：