跳转到主要内容

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 server 的最短路径。适合你已经有数据接口，只想让 Claude Code、Copilot、OpenCode 或其他 MCP 客户端直接使用 HeavenBase 时使用。

​
1. 创建一个小 server

import heavenbase as hb

MCP = {"name": "heavenbase-notes", "transport": "http", "host": "127.0.0.1", "port": 7011}

workspace = hb.HeavenBase("notes-demo", backends={"main": {"type": "inmem"}})
workspace.register(
    {
        "entity_id": "demo-note",
        "name": "DemoNote",
        "desc": "通过 MCP 暴露的短笔记",
        "fields": {
            "object_id": {"type": "Identifier", "pk": True, "desc": "稳定笔记 object_id"},
            "title": {"type": "ShortText", "desc": "笔记标题"},
            "body": {"type": "LongText", "desc": "可搜索的笔记正文"},
        },
    }
)
workspace.upsert_many(
    "demo-note",
    [{"object_id": "n1", "title": "Hello", "body": "外部智能体可以通过 MCP 查询这一行。"}],
)

print(workspace.to_mcp_json(**MCP))
workspace.serve(**MCP)

​
2. 运行

python serve_notes_mcp.py
server 会监听 http://127.0.0.1:7011/mcp，并打印通用 MCP 客户端配置： 
{
    "mcpServers": {
        "heavenbase-notes": {
            "transport": "http",
            "url": "http://127.0.0.1:7011/mcp"
        }
    }
}

​
3. 给智能体的工作流

HeavenBase MCP 暴露的是小而稳定的批量优先工具集。典型工作流是：
  1. 调用 list_entities 查看工作区有哪些实体。
  2. 查询 sys-metaschema 了解字段、类型、存储放置和后端能力。
  3. 查询 sys-catalog 通过 target_entity、name、desc、tags 和 target_id 发现具体对象。
  4. 用 define_entity 新建实体；当前 MCP 工具集不暴露通用 alter_entity。
  5. 用 query 读取数据，并尽量传入精确的 select 字段。
  6. 用 upsert_many、set_many、delete_many、get_many、exists_many 做行级操作。
  7. 当你需要理解路由或后端行为时，先调用 explain。
只操作一行时，也给 *_many 工具传一项列表。

​
Further Exploration

相关资源：