HeavenBase MCP

最好的画布，是空白的画布。

在本教程中，我们创建一个空的 HeavenBase 工作区，并将其暴露为 MCP 服务器。这样，任何使用 HeavenBase MCP 的 agent 都能把它当作数据平面与结构化记忆服务。由 agent 决定如何存储观察结果、存储什么、以及如何查询；MCP 服务器负责其余部分。教程结束时，我们将运行一个玩具电商场景：agent 即时定义 Product、Customer、Order 实体，并通过日常操作维护数据库，例如添加商品、注册客户、记录订单。最后，agent 回答业务分析问题，例如「售价低于 $100 的商品占比多少？」以及「根据 Alice 的订单历史，我该向她推荐什么？」

1. 创建空工作区

创建一个 Python 文件：

# serve_space.py
import heavenbase as hb

# If you've already run this tutorial once, this drops the existing workspace so you can start fresh.
# Remove this line if you want the workspace to persist across server restarts.
hb.HeavenBase("my-space", preset="debug").drop()

ws = hb.HeavenBase("my-space", preset="debug")

print(
    ws.to_mcp_json(
        name="my-space-mcp",
        profile="agent",
        transport="http",
        host="127.0.0.1",
        port=7001
    )
)

ws.serve(
    name="my-space-mcp",
    profile="agent",
    transport="http",
    host="127.0.0.1",
    port=7001
)

无需实体、字段或 schema。HeavenBase 的通用 MCP 工具会动态处理一切。

hb.HeavenBase("my-space", preset="debug").drop() 会在服务器启动前清空演示工作区。教程需要可重复执行请保留此行；若希望工作区数据在服务器重启后仍保留，请删除该行。

preset 参数控制后端配置。debug 预设使用 SQLite 与内存存储，便于轻量、免 Docker 搭建。local-lts 预设使用本机 Postgres、LanceDB 与 Elasticsearch，更稳健且仍在本机运行。两种预设均支持完整 MCP 工具集：debug 侧重易用，local-lts 在更大数据量下性能更好。 profile 参数选择服务器暴露的工作区 MCP 工具集。HeavenBase 内置目前提供 full（可信管理流程）、agent（首日 schema 与数据工作）、memory（笔记式记忆）与 memstate（项目级记忆状态）。本页使用 profile="agent"，因为 agent 可用其定义实体、检查 schema、upsert 行、patch 行、计数、查询并解释路由，同时省略批量操作、存在性检查与删除。

2. 运行

python serve_space.py

服务器会打印客户端配置并开始监听：

{
  "mcpServers": {
    "my-space-mcp": {
      "transport": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

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

Transport	Python serve call	Client endpoint
Streamable HTTP	`transport="http"`	`http://127.0.0.1:7001/mcp`
SSE	`transport="sse"`	`http://127.0.0.1:7001/sse`
stdio	`transport="stdio"`	command transport, no URL

在 Python 中，对 ws.to_mcp_json(...) 与 ws.serve(...) 传入相同 transport。例如，仅支持 SSE 的客户端需要 /sse 时，两处均使用 transport="sse"。

工作区 MCP 服务器绑定实时工作区对象。外部 agent 使用时请保持 serve_space.py 运行。与持久化的 Toolkit 注册表引用不同，空工作区 MCP 服务器是暴露该脚本所创建工作区的常驻进程。

3. 连接你的 Agent

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

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

claude mcp add --transport http my-space-mcp http://127.0.0.1:7001/mcp
claude mcp list

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

{
  "mcpServers": {
    "my-space-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

开启新的 Claude Code 会话，运行 /mcp，在让 agent 使用算术工具前确认 my-space-mcp 已连接。

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

Name: my-space-mcp
Select Streamable HTTP
URL: http://127.0.0.1:7001/mcp

Config file (~/.codex/config.toml):

[mcp_servers.my-space-mcp]
url = "http://127.0.0.1:7001/mcp"

CLI:

codex mcp add my-space-mcp --url http://127.0.0.1:7001/mcp
codex mcp list

若添加 HTTP MCP 服务器后 Codex 构建仍不显示，请在 ~/.codex/config.toml 中启用 experimental_use_rmcp_client 功能：

[features]
experimental_use_rmcp_client = true

开启新的 Codex 会话，或在 TUI 中运行 /mcp，确认 my-space-mcp 出现且已发现其工具。

服务器仅属于一个仓库时用项目级配置，希望在所有项目中可用时用全局配置：

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

粘贴以下配置：

{
  "mcpServers": {
    "my-space-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

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

Name: my-space-mcp
Type: http
URL: http://127.0.0.1:7001/mcp

重新加载 Cursor 或打开新对话，在 MCP 设置面板中确认 my-space-mcp 已启用。

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

URL: http://127.0.0.1:7001/mcp
Name: my-space-mcp

工作区级配置请添加 .vscode/mcp.json。VS Code 使用 servers 键，而非 mcpServers：

{
  "servers": {
    "my-space-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

重新加载 VS Code 窗口，或从命令面板运行 MCP: List Servers，确认 my-space-mcp 正在运行。

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

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

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

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

{
  "mcp": {
    "servers": {
      "my-space-mcp": {
        "url": "http://127.0.0.1:7001/mcp",
        "transport": "streamable-http"
      }
    }
  }
}

或用 CLI 写入相同条目：

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

OpenClaw 会热应用大部分 MCP 配置变更。若已有会话已加载工具，请开启新的 agent 会话。

在 ~/.hermes/config.yaml 中添加 HTTP 服务器：

mcp_servers:
  my-space-mcp:
    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": {
    "my-space-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}

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

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

hb llm chat --mcp quickstart.my-space-mcp "How many entities do I have now in the workspace?"
hb llm session --mcp quickstart.my-space-mcp

也可让 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.my-space-mcp --transport http

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

import heavenbase as hb

async with MCPServerStreamableHttp(
    name="my-space-mcp",
    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.my-space-mcp --transport sse 启动 HeavenBase，并连接 http://127.0.0.1:7001/sse。

4. Agent Profile 与工作区 MCP 工具

本教程使用 profile="agent"，即 HeavenBase 面向首日工作区的默认 MCP 表面。它暴露一套经精选的 schema 与数据工具集，由 Catalog 与 MetaSchema 支撑：智能体 (Agent) 通过 schema 工具检查工作区结构，并通过 Catalog 感知的列举与描述发现具体行。

Tool	能力说明
`define_entity`	根据 JSON 兼容 schema 创建实体定义。写入描述字段、逻辑类型与路由的 MetaSchema 行。
`list_entities`	列出工作区中已注册的实体 id——智能体在定位具体数据前使用的 schema 侧目录。
`describe_entity`	从 MetaSchema 返回某一实体的字段、逻辑类型、路由计划与放置元数据。在智能体需要某一实体完整形态时，于 `list_entities` 之后使用。
`upsert`	为某一实体插入或替换一行。成功的非系统写入会更新 Catalog 行，便于后续发现。
`get`	按对象 ID 获取一行。
`set`	修补一行并返回更新后的行。
`count`	统计某一实体的行数。
`query`	运行带过滤、投影、排序与限制的 JSON 查询 (Query)。
`explain`	展示查询的路由与处理器计划。

agent profile 有意省略批量变更、批量读取、存在性检查与删除。仅在可信管理流程中使用 profile="full"。保持面向模型的 profile 精简，并通过应用代码承载破坏性操作。同一工作区可暴露多个 MCP 工具集，每个使用不同 profile：

workspace = hb.HeavenBase("support", preset="debug")
agent_tools = workspace.to_mcp(name="support-agent", profile="agent")
admin_tools = workspace.to_mcp(name="support-admin", profile="full")
memory = workspace.to_mcp(name="support-memory", profile="memory")
memstate = workspace.to_mcp(name="support-memstate", profile="memstate")

agent profile 足以让首日智能体定义 schema、写入与修补行、读取上下文、统计行数、查询并检查路由计划。memory profile 是五工具笔记表面（remember、recall、search_memory、list_memory、set_memory）。memstate profile 用于带版本的项目记忆（memstate_* 动词）。full profile 为可信代码路径增加批量操作、存在性检查与删除。启用可选 database 扩展时，HeavenBase 还提供 database profile，用于读/查询流程以及 run_snippet 与 suggest_sql。

5. 动手体验：玩具电商场景

按顺序将下方每条提示复制到 agent 对话中。每个代码块是一条可粘贴发送的消息。

设置工作区上下文

告诉 agent 使用哪个 MCP 服务器：

Use the `my-space-mcp` MCP for maintaining an e-commerce knowledgebase.

开启新会话时，建议先粘贴此提示，以设定最小工作区上下文。

定义业务模型

请 agent 逐个创建核心实体：

Create a Product entity schema with name, price, category (textual), and availability (default to true).

Create a Customer entity schema with name, email, address (textual), profile (list of texts about the customer).

Create an Order entity schema with order_id, customer_id (reference), product_id (reference), quantity. One order row holds one product; use multiple rows when an order has multiple products.

日常运营

向工作区写入目录商品、客户与订单：

Add a product: "Ergonomic Keyboard" priced at $89.99 in category "electronics".

Add a product: "27-inch 4K Monitor" priced at $349.00 in category "electronics".

Add a product: "Bamboo Desk Organizer" priced at $24.50 in category "office".

Bob (bob@gmail.com, 456 Oak St) registered but hasn't ordered anything yet.

Bob searched for "chair" and didn't find anything.

Alice (alice@gmail.com, 123 Maple St) ordered 2 keyboards and 1 monitor.

Add a product: "Mesh Office Chair" priced at $199.99 in category "office".

Add a product: "Wooden Chair" priced at $39.99 in category "office".

Add a product: "Wireless Mouse" priced at $49.99 in category "electronics".

Update Bob's address to 789 Pine St.

Wood chair is out of stock.

分析问题

提出分析问题。每条提示下方为预期答案。

What percentage of products in my store cost less than $100?

66.67% (4 out of 6 products)

List all products in the electronics category sorted by price ascending.

Wireless Mouse ($49.99), Ergonomic Keyboard ($89.99), 27-inch 4K Monitor ($349.00)

What's the best-selling product based on total quantity ordered?

Ergonomic Keyboard (2)

How many active customers (at least one order) do I have?

1 (Alice)

What products should I recommend to Alice and Bob based on their profiles and order history? Write a short recommendation pop-up for each of them.

Hi Alice — complete your desk setup
You already run a keyboard-and-monitor setup. Add a Wireless Mouse ($49.99) for a matched input stack, and a Bamboo Desk Organizer ($24.50) to tidy cables and accessories.
Suggested add-ons: Wireless Mouse · Bamboo Desk Organizer

Hi Bob — we found chairs for you
You searched for a chair earlier. The Wooden Chair isn’t available right now, but the Mesh Office Chair ($199.99) is — ergonomic mesh for long sessions.
Suggested for you: Mesh Office Chair

现在你拥有供 agent 使用的持久、可查询、结构化记忆平面。这个电商玩具示例全程无需你编写任何 CRUD 函数或业务逻辑：agent 检查可用工具、即时定义实体、写入数据，并通过同一 MCP 接口运行查询。

进一步探索

相关资源：

首个 MCP - 通用 MCP 算术工具包演示
30 分钟开发者工作坊：任务清单管理器 - 构建 Sublinear，一款 Agent 式任务清单管理器
工作区 - 工作区生命周期与配置
MCP 工具集 (Toolkit) 参考 - 工作区 MCP 工具、profile 与 CLI
后端 - SQLite、PostgreSQL、MySQL 等

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

1. 创建空工作区

2. 运行

3. 连接你的 Agent

4. Agent Profile 与工作区 MCP 工具

5. 动手体验：玩具电商场景

进一步探索

​1. 创建空工作区

​2. 运行

​3. 连接你的 Agent

​4. Agent Profile 与工作区 MCP 工具

​5. 动手体验：玩具电商场景

​进一步探索

1. 创建空工作区

2. 运行

3. 连接你的 Agent

4. Agent Profile 与工作区 MCP 工具

5. 动手体验：玩具电商场景

进一步探索