HeavenBase MCP

空工作区是一块白板，只是背后藏着一个查询规划器。

本教程把一个 HeavenBase 工作区暴露为实时 MCP 服务器。智能体可以定义实体、写入行、检查 schema 与查询数据，而你无需编写传输层或 CRUD 包装器。这个表面不同于已注册 Toolkit。workspace.serve(...) 闭包捕获一个实时工作区对象，并且只在该进程运行时可用。已注册 Toolkit 则把可调用 Capsule 持久化为工作区行，之后可以按引用加载。

1. 动机

向智能体提供数据库密码只会暴露存储，却没有解释领域。编写自定义 MCP 服务器能够解释领域，但往往重复 schema 验证、路由、查询解析与序列化。 HeavenBase 直接暴露它已经拥有的工作区：

workspace = hb.HeavenBase("my-space", preset="debug")
workspace.serve(profile="agent", wait=True)

profile 限制面向模型的表面，而每个工具仍使用与 Python 代码相同的实体、Catalog、MetaSchema、路由计划与后端权限。

2. 创建并提供空工作区

创建 serve_space.py：

import heavenbase as hb


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

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

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

运行：

python serve_space.py

debug 预设为教程提供本地 SQLite 支撑的工作区，无需 Docker。重新运行脚本会再次打开已注册工作区并保留数据。

不要把 workspace.drop() 放进服务器脚本，除非每次启动都应销毁工作区。只有在确实要删除其拥有的数据时，才先停止服务器，再显式删除工作区。

服务器监听 http://127.0.0.1:7001/mcp。外部客户端使用工具时，请保持此进程运行。

3. 理解实时边界

workspace.to_mcp(...)、workspace.to_mcp_json(...) 与 workspace.serve(...) 会创建一个闭包捕获当前工作区对象的仅执行期 Toolkit。该 Toolkit 无法注册为持久 Capsule Toolkit，因为它的函数依赖实时工作区与后端对象。持久状态仍会保留在工作区中；MCP 传输本身不会保留。

Surface	Owner	Survives server exit	How it is reopened
工作区数据与 schema	`my-space` 工作区	是	`hb.HeavenBase.load("my-space")`
实时工作区 MCP Toolkit	`serve_space.py` 进程	否	再次运行 `workspace.serve(...)`
已注册 Capsule Toolkit	显式工作区行	是	`hb.Toolkit.load(..., ws=workspace)`

需要持久可调用工具时使用首个 MCP。希望智能体操作一个实时应用工作区时使用本页。

4. 选择显式 Profile

profile 是经过允许列表约束的 MCP 表面，不是启用所有扩展的请求。

Profile	Intended surface	Requirement
`agent`	定义与检查实体；upsert、get、patch、count、query 与 explain	内置 `toolkit` 扩展
`full`	包含批量操作与删除的可信管理表面	内置 `toolkit` 扩展
`memory`	五个笔记记忆工具	启用 `memory`
`memstate`	带版本的项目键路径记忆	启用 `memory`
`database`	浏览已摄取 schema 并运行只读 SQL 片段	启用 `database`

本教程使用 agent。它省略批量变更、存在性检查与删除，同时保留首日 schema 与数据工作需要的工具。选择可选 profile 前，先启用对应根扩展：

memory_workspace = hb.HeavenBase("memory-space", preset="debug")
memory_workspace.enable_extension("memory")
memory_tools = memory_workspace.to_mcp(profile="memory")

database_workspace = hb.HeavenBase("database-space", preset="debug")
database_workspace.enable_extension("database")
database_tools = database_workspace.to_mcp(profile="database")

启用 memory 不会悄悄启用 database，选择 profile="database" 也不会替你安装 database 扩展。工作区清单会记录你显式选择的根。

5. 连接客户端

在一个客户端中配置正在运行的 Streamable HTTP 端点。

Claude Code
Codex
VS Code

添加并验证服务器：

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

开启新会话并运行 /mcp，然后再让智能体使用工作区。

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

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

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

创建 .vscode/mcp.json：

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

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

workspace.to_mcp_json(...) 打印的 JSON 可作为采用常见 mcpServers 结构的客户端的可移植起点。

6. 尝试一家小商店

按顺序发送以下提示。

定义模型

Use `my-space-mcp`. Define Product with name, price, category, and available;
define Customer with name and email; define Order with customer_id, product_id,
and quantity. Show me the resulting entity summaries.

添加数据

Add two products: an Ergonomic Keyboard for 89.99 and a 4K Monitor for 349.00,
both in electronics and available. Add Alice, then record an order in which
Alice buys two keyboards.

提出问题

Query the workspace and tell me which product is the best seller by quantity.
Explain which entities and rows support the answer.

智能体通过 MetaSchema 定义 schema、写入具体行、通过 Catalog 感知工具发现它们，并通过与 Python 调用方相同的路由系统执行查询。

总结

工作区 MCP 闭包捕获一个实时工作区，必须由运行中的进程提供服务。
工作区数据独立于该传输进程持久化。
profile 暴露经过选择的工具集；可选 profile 需要先启用对应扩展。
已注册 Capsule Toolkit 是另一种持久化机制，具有显式工作区所有权。

进一步探索

相关资源：

首个 MCP - 在工作区中持久化可调用工具
工作区 - 理解工作区所有权与生命周期
MCP Toolkit 参考 - 查看 profile 与工具契约
记忆智能体工作坊 - 显式启用并使用记忆
数据分析工作坊 - 显式启用数据库分析
Claude Code MCP - 配置 Claude Code
Codex MCP - 配置 Codex 客户端
VS Code MCP - 配置 VS Code

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

1. 动机

2. 创建并提供空工作区

3. 理解实时边界

4. 选择显式 Profile

5. 连接客户端

6. 尝试一家小商店

总结

进一步探索

​1. 动机

​2. 创建并提供空工作区

​3. 理解实时边界

​4. 选择显式 Profile

​5. 连接客户端

​6. 尝试一家小商店

​总结

​进一步探索

1. 动机

2. 创建并提供空工作区

3. 理解实时边界

4. 选择显式 Profile

5. 连接客户端

6. 尝试一家小商店

总结

进一步探索