Orionbelt Semantic Layer

OrionBelt® 语义层 MCP

轻量级 MCP 服务，通过委托调用 OrionBelt® 语义层 REST API

轻量级 MCP 服务，通过 HTTP 将所有业务逻辑委托给 OrionBelt® 语义层 REST API。没有内嵌引擎——纯 API 转发。

架构

OrionBelt® Semantic Layer 平台支持两种部署模式。此 MCP 服务同时支持这两种模式：

• 独立部署 — 将 OrionBelt® Semantic Layer API 部署到任意位置（Cloud Run、Docker、本地主机），然后通过 API_BASE_URL 将此 MCP 服务指向它。
• 托管部署 — 连接到公开的 Cloud Run 部署，无需本地设置（请参阅下文的托管 MCP 服务）。

┌────────────┐       ┌──────────────────────────────────────────────────────┐
│ LLM Client │       │                OrionBelt® Platform                   │
│            │       │                                                      │
│  Claude,   │──MCP──│──> server.py  ──HTTP /v1──>  Semantic Layer REST API │
│  Cursor,   │       │    (FastMCP                   (FastAPI: parse OBML,  │
│  any MCP   │       │     + httpx)                   validate, compile     │
│  client    │       │                                to SQL)               │
└────────────┘       └──────────────────────────────────────────────────────┘

• 不包含业务逻辑 — 所有工具调用均委托给 REST API（v1 端点）
• 双模式 — 启动时自动检测单模型或多模型 API 模式
• 自动会话管理 — 首次调用工具时创建 API 会话，并缓存 ID（多模型模式）
• 26 个工具（单模型模式）或 30 个工具（多模型模式），用于查询（QueryObject）、执行、批处理、发现、维度值搜索、可组合性（ACR）、示例、图表、RDF/SPARQL、工件和查询的沿袭、业务规则（列表、说明、评估）、本体链接（概念映射、命名空间、未映射工件）、OSI 导出、模型验证（离线或针对实时数据源），以及 OBML 参考资料 + 函数目录 + JSON 架构。（总计有 31 个不同的工具；API 模式决定启用哪个子集——它们有 25 个工具重叠——并且任何客户端都不会同时看到全部 31 个工具。）在设计时阶段以及禁用查询执行时，可见工具集会进一步缩小（请参阅设计时与运行时工具切换）
• 5 个提示词 + 2 个资源，用于 OBML / OBSQL 参考资料、业务规则和使用指南

在线演示

OrionBelt® Semantic Layer API 提供公开演示，地址如下：

API 端点： https://orionbelt.ralforion.com — Swagger UI | ReDoc | Gradio UI

在 .env 文件中设置 API_BASE_URL=https://orionbelt.ralforion.com 即可使用（请参阅 .env.example）。

安装

uv sync

开发环境（包含 pytest、respx、ruff）：

uv sync --all-groups

使用方法

stdio（默认）

uv run server.py

HTTP 传输

MCP_TRANSPORT=http uv run python server.py

HTTP 传输默认以无状态模式运行（MCP_STATELESS_HTTP=true）： 每个请求都是独立完整的，不使用 Mcp-Session-Id，不支持流恢复，也不会发送由服务端发起的消息。这里没有任何功能需要此类状态——工具阶段根据显式加载的模型状态确定，而非根据连接确定，并且没有工具会发送进度、采样或引导请求，因此实例可以部署在负载均衡器后方，无需会话粘性。设置 MCP_STATELESS_HTTP=false 可恢复每连接会话；sse 始终以有状态模式运行，因为它是每连接的长连接流。

请注意，这里说的仅是传输层会话。上游 API 会话和已加载模型集合仍然是进程全局的，由实例的所有客户端共享，不受此标志影响。

传输安全

HTTP/SSE 传输不终止 TLS，也不验证调用方身份——它要求前置入口同时完成这两项工作。这是两项独立的工作，默认情况下没有任何平台会替你全部完成。

在预期的部署环境 Cloud Run 上，TLS 是自动启用的：服务 URL 通过 HTTPS 提供服务，纯 HTTP 会转发到容器。**访问控制则不是自动启用的。**这是部署时需要选择的配置，可通过以下三种方式之一确定——授予 IAM 调用方权限、限制 --ingress，或在前面部署一个带身份验证的负载均衡器。如果这些方式都没有启用，--allow-unauthenticated 会让任何知道服务 URL 的人都能通过 HTTPS 访问服务，无需凭据。加密不等于受限。

这一点很重要，因为两段链路的安全情况各不相同：

链路	安全性
MCP 客户端 → 此服务	stdio：通过管道连接到子进程，完全不使用套接字。http/sse：取决于前置入口提供的保护——如果没有入口，则没有保护
此服务 → API	当 API_BASE_URL 为 https://（默认值）时，始终使用 TLS；证书会根据 httpx 的默认 CA 证书包（certifi）验证，或根据私有 CA 的 API_CA_CERT 验证；API_CLIENT_CERT 会添加客户端证书以启用双向 TLS。没有 verify=False，除非使用 http:// URL，否则无法禁用验证

应避免直接暴露 HTTP 传输。任何能够访问该端口的对象都可以调用所有已注册的工具——包括启用了相应功能的 execute_query——使用此服务自身的 API_KEY 调用 API，且传输通道上的内容可被读取。凭据本身不会经过这段链路，但凭据赋予的访问权限会经过。

检测到这种情况时，服务会在启动时发出警告：使用 http/sse 传输、绑定到非回环地址、运行在 Cloud Run 之外，且未设置 MCP_BEHIND_PROXY=true。将 MCP_SERVER_HOST 绑定到回环地址，在前面部署带身份验证的 TLS 入口，或设置 MCP_BEHIND_PROXY=true，以声明存在服务无法检测到的代理。

在 Cloud Run 上，服务会记录一条信息提示，而不是发出上述警告，指出仍由你负责的部分：TLS 已处理，访问控制取决于你的部署配置。这里没有警告，不代表服务已受到访问限制——进程无法读取自身的 IAM 策略或入口设置。请确认上述三种方式之一已就绪；如果已就绪，设置 MCP_BEHIND_PROXY=true 即可记录这一配置并关闭提示。

API 自身的 *_TLS_* 设置属于服务端配置，此处不会读取其中任何一项。PGWIRE_TLS_* 和 FLIGHT_TLS_*（2.28.0）用于保护此服务从不连接的监听器。API_TLS_*（2.29.0）让 REST API 自身通过 HTTPS 提供服务，而 API_TLS_CLIENT_CA 会让它要求客户端证书——以下设置就是为此而设的。

与 API 之间的 TLS

如果 API 使用私有 CA 签发的证书提供 HTTPS，或要求双向 TLS——即 API 上设置了 API_TLS_CLIENT_CA，或前置网关要求客户端证书——请将相关材料配置到此服务：

API_BASE_URL=https://obsl.internal:8000
API_CA_CERT=/certs/ca.crt            # trust this CA instead of the default store
API_CLIENT_CERT=/certs/mcp.crt       # present this certificate…
API_CLIENT_KEY=/certs/mcp.key        # …with this key (omit if it is in the same PEM)

无论使用哪种传输方式，证书都会在服务启动时加载。因此，如果路径不存在、不可读，或文件内容与其声明不符，启动就会中止，并指出相关设置和文件，而不会等到 HTTP 客户端内部出现 SSL 错误时才暴露问题。启动横幅中的 API TLS: 行会报告最终使用的链路配置。

• API_CA_CERT 会替换默认信任存储，而不是扩展它。 如果未设置，验证会使用 httpx 的默认配置（certifi，或 SSL_CERT_FILE / SSL_CERT_DIR），添加客户端证书不会改变这一点。
• **这些设置要求 API_BASE_URL 使用 https://。**使用 http:// 时不会进行握手，因此不会提供或验证任何内容；服务会拒绝此配置，而不会将其留作 TLS 配置处理。
• **服务会拒绝受密码保护的密钥，不会提示输入密码。**使用 stdio 时，标准输入就是 MCP 管道，因此 OpenSSL 的终端提示会破坏协议或导致程序挂起。请提供已解密的密钥，并通过文件权限或机密挂载保护它。

MCP 客户端配置

添加到 MCP 客户端配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "orionbelt": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/path/to/orionbelt-semantic-layer-mcp"
    }
  }
}

配置

环境变量或 .env 文件（pydantic-settings）。默认值请参见 .env.example。

变量	默认值	描述
API_BASE_URL	—（必填）	OrionBelt® Semantic Layer REST API URL
API_KEY	—（未设置）	API 凭据；仅当 API 以 AUTH_MODE=api_key 运行时才必需
API_KEY_HEADER	X-API-Key	发送凭据所用的标头；必须与 API 的 API_KEY_HEADER 匹配
API_CA_CERT	—（未设置）	用于验证 API 的 PEM CA 证书包，会替换默认信任存储；适用于私有 CA。需要 https:// API_BASE_URL——参见 与 API 的 TLS
API_CLIENT_CERT	—（未设置）	提交给 API 的 PEM 客户端证书，用于双向 TLS（API 上的 API_TLS_CLIENT_CA，或要求提供客户端证书的网关）
API_CLIENT_KEY	—（未设置）	API_CLIENT_CERT 的 PEM 私钥；如果密钥在同一文件中，则省略。仅支持未加密密钥
MCP_TRANSPORT	stdio	stdio、http 或 sse
MCP_SERVER_HOST	localhost	HTTP/SSE 的绑定主机
MCP_SERVER_PORT	9000	HTTP/SSE 的绑定端口
MCP_BEHIND_PROXY	false	确认 HTTP 传输前方有一个负责终止 TLS 并且验证调用方的入口——两者都必须满足，不能只满足其一。仅用于消除暴露警告——不会授予服务任何能力，也不会改变任何行为
MCP_STATELESS_HTTP	true	运行 HTTP 传输时不使用按连接划分的 MCP 会话（没有 Mcp-Session-Id，也不支持流恢复），以便实例在无需会话亲和性的情况下进行扩缩容。对 stdio 无效；在 sse 模式下强制关闭
LOG_LEVEL	INFO	日志级别
API_TIMEOUT	30	HTTP 超时时间，单位为秒

工具

模型生命周期

MCP 工具	描述
get_obml_reference()	返回完整的 OBML 格式规范
load_model(model? | osi_yaml?, dedup=True)	解析、验证并存储模型（返回 health 和 model_load）。传入 model（OBML JSON）或 osi_yaml（OSI YAML，由服务端转换为 OBML）
validate_model(model? | model_yaml?, extends?, inherits?, online=False, dialect?)	验证模型，但不加载模型。online=True 还会探测已配置数据源中的每个已声明表和列，并报告结构检查无法发现的漂移（DATASOURCE_*）。extends / inherits 仅适用于多模型模式——无状态路由的单模型模式不使用这两者，因此会拒绝它们，而不是静默丢弃
describe_model(model_id)	检查数据对象、维度、度量和指标
remove_model(model_id)	从当前会话中移除模型
list_models()	列出当前会话中加载的所有模型
export_model_to_osi(model_id, ...)	将已加载的模型导出为 OSI YAML

模型发现

MCP 工具	描述
find_artefacts(model_id, query?, kind?, name?)	查找构件。提供 query → 模糊排序搜索（解析模糊术语：精确匹配／同义词／模糊匹配）。不提供 query → 精确确定性查找（所有构件、某一类型的构件，或某个指定构件的完整记录）
explain_artefact(model_id, name)	说明维度、度量或指标的沿袭关系
search_values(dimension, search?, where_json?, limit?, dialect?, model_id?)	维度值搜索 — 在编写筛选条件前确认筛选值（Germany 与 DE、GERMANY）。提供 search → 按精确匹配／前缀／包含／模糊匹配排序；不提供 → 列出可用值，或返回日期／数字维度的最小值和最大值。该操作会运行查询，因此需要执行查询；对于声明 valueSearch: false 的维度，将拒绝搜索
get_lineage(name? | query_json?, kind?, dialect?, output_format="text", model_id)	维度、度量、指标或业务规则的沿袭图，也可以是整个查询的沿袭图，其中包含规划器选择的联接（包括 pathName 和角色联接），追溯至其读取的表。kind 为可选项（会尝试所有类型；若规则名称与度量相同，则两者都会返回）。output_format：text、mermaid、turtle（基于 OBSL 图的 IRI，使用 prov:wasDerivedFrom；与 get_model_graph 合并）或 json
list_examples(model_id, intent?)	列出编写好的示例查询（可按意图标签筛选）
get_example(model_id, name)	获取单个示例，包含查询和编译后的 SQL 预览
get_join_graph(model_id)	以邻接表形式返回联接图
find_composables(query_json?, anchors?, anchor_type?, model_id?)	ACR — 根据进行中的查询或指定的锚点，返回仍可组合成有效且无扇出的结果的维度／度量／指标（以及 CFL 候选项）。保证可编译

查询、执行与图表

MCP 工具	描述
execute_query(...)	编译并执行 QueryObject，返回 SQL 和行
run_batch(queries, ...)	一次性加载模型并并行运行 N 个查询
get_model_diagram(model_id)	为已加载的模型生成 Mermaid ER 图

语义图（RDF / SPARQL）

MCP 工具	描述
get_model_graph(model_id)	以 OBSL-Core RDF（Turtle）形式返回模型
query_model_graph_by_sparql(query, ...)	运行只读 SPARQL 查询（SELECT / ASK）

业务规则

MCP 工具	描述
list_rules(model_id)	模型的 rules:，包含按类型、级别（行级 / 聚合级）、严重性和可执行性划分的统计信息
explain_rule(name, model_id)	一条规则的完整信息：定义、读取内容、背后的表、依赖项、本体链接，以及编译生成的 SQL
evaluate_rule(name, limit?, dialect?, format_values?, model_id)	运行一条规则并列出其结果：分类 / 资格规则的成员，以及验证 / 约束规则的违规项。需要启用查询执行
evaluate_rules(types?, severities?, executable_only?, max_rules?, limit=5, dry_run?, dialect?, model_id)	运行所有规则（或一个子集）并生成报告，其中包含每条规则的状态、计数、结果示例和错误；dry_run=True 只编译规则，即使禁用了查询执行也能使用

本体链接（外部概念映射）

MCP 工具	描述
find_concept_mappings(concept?, namespace?, relation?, types?, model_id)	列出每个 externalConceptMappings 条目及其工件、SKOS 关系、展开后的 IRI 和来源；可按概念、命名空间、关系或工件类型筛选
list_concept_namespaces(model_id)	模型链接到的外部本体，按使用频率从高到低排列，并列出未被任何映射使用的已声明前缀
list_unmapped_artefacts(types?, model_id)	可映射范围内仍未建立链接的工件

参考资料

MCP 工具	描述
get_obml_reference()	OBML（模型编写）语法参考
get_function_catalog()	可用于 OBML 表达式的可移植标量函数，以及其固定的跨方言语义
get_json_schema(name)	obml（模型）或 query（QueryObject）的 JSON Schema

实用工具

MCP 工具	描述
list_dialects()	列出可用的 SQL 方言及其功能

设计时与运行时的工具切换

服务会呈现一个按阶段限定的工具界面：不会一次性列出所有 工具，而是只显示适用于模型生命周期当前阶段的工具。大约一半的工具只有在加载模型后才有意义（execute_query、describe_model、find_artefacts 等），其余工具用于编写模型或查阅参考资料（get_obml_reference、get_function_catalog、 get_json_schema、validate_model、list_dialects）。拆分工具可以缩小工具界面，并避免一类错误——在未加载模型时调用查询工具。

按阶段切换的三个类别

工具分为三个类别。可见的工具集会在加载／卸载转换时切换，而非叠加——运行阶段不会显示设计／参考工具：

类别	列出时机	工具
始终可用	始终（两个阶段均可用）	load_model、remove_model（转换动词——在运行阶段仍保持可用，以便在会话中途加载第二个模型，最多可加载 max_models_per_session 个）；run_batch 和 validate_model（自包含——各自以内联方式接收模型，因此都不需要此前的会话状态）；get_json_schema（QueryObject／OBML 架构——两个阶段都需要）
仅设计阶段	仅在未加载模型时	get_obml_reference、get_function_catalog、list_dialects
仅运行阶段	仅在已加载模型时	describe_model、get_model_diagram、find_artefacts、explain_artefact、search_values、get_lineage、execute_query、list_examples、get_example、get_model_graph、get_join_graph、find_composables、query_model_graph_by_sparql、list_rules、explain_rule、evaluate_rule、evaluate_rules、find_concept_mappings、list_concept_namespaces、list_unmapped_artefacts、list_models、export_model_to_osi

                       load_model  (returns "re-list" signal)
   ┌─────────────────┐ ────────────────────────────────▶ ┌───────────────┐
   │ design phase    │                                   │ run phase     │
   │ always + design │ ◀───────────────────────────────  │ always + run  │
   └─────────────────┘  remove_model (last model) / TTL  └───────────────┘
                        expiry — back to design phase

因此，设计阶段 → 始终可用 + 仅设计阶段，运行阶段 → 始终可用 + 仅运行阶段。 加载模型后，设计／参考工具会被隐藏，让运行阶段的工具集专注于查询。

重新列出工具

MCP tools/list 响应会按当前阶段筛选。由于无状态 MCP 规范使推送通知（notifications/tools/list_changed）并不可靠，因此转换采用拉取式：load_model（设计阶段 → 运行阶段）和 remove_model（运行阶段 → 设计阶段，且仅在没有剩余模型时）会返回一条简短提示，告知客户端重新列出工具并获取切换后的工具集。

防止过早调用

如果客户端在设计阶段仍调用仅限运行阶段的动词（例如，尚未重新列出工具的过期主机），服务端会返回结构化错误，而非不透明的失败：

尚未加载模型——“execute_query”是一个运行时工具，目前尚不可用。请先调用 load_model，然后重新列出工具。

能力门控（与阶段正交）

除了生命周期阶段之外，服务也可能因为被_配置_为不支持某项功能而隐藏工具。运行查询的工具——execute_query、 evaluate_rule 和 search_values——受 API 的 query_execute 能力门控：服务以仅编译模式运行时，这些工具会从 tools/list 中移除，调用其中任何一个都会返回结构化错误。这与阶段机制相结合——只有在其所处阶段处于活动状态_且_相应能力已启用时，才会列出某个动词。这一机制采用通用能力注册表，因此未来表示“服务在此处无法执行某项操作”的标记，也会以相同方式隐藏对应工具。

单模型模式

当 API 以单模型模式运行时，模型会在启动时预加载，因此服务始终处于运行时阶段——从第一个请求开始就会列出所有适用的工具，且无需执行 load_model 步骤。

缓存提示说明。2026-07-28 MCP 规范在 tools/list 中添加了 ttlMs / cacheScope 提示（SEP-2549）。目前我们有意暂不设置这些字段——它们仍是候选发布版本，而且 FastMCP 的 list-tools 钩子只公开工具列表，不公开结果封装。与此同时，上文明确的重新列出信号是主要的（也是规范推荐的）转换机制。

支持的 SQL 方言

postgres、snowflake、clickhouse、databricks、dremio、bigquery、duckdb

工作流

1. 获取参考资料——调用 get_obml_reference() 了解 OBML 语法
2. 加载模型——调用 load_model(model_yaml) 获取 model_id
3. 探索——调用 describe_model(model_id)，或使用发现工具（find_artefacts、explain_artefact、get_lineage）
4. 执行——调用 execute_query(model_id, query_json='{"select": {"dimensions": [...], "measures": [...]}}') 编译并运行 SQL，返回行（需要在 API 上设置 QUERY_EXECUTE=true；有关 QueryObject 的结构，请参阅 get_json_schema("query")）

集成指南

将 OrionBelt® Semantic Layer MCP 服务与热门 AI Agent 框架和自动化平台搭配使用：

框架	传输方式	指南
OpenAI Agents SDK	stdio、HTTP、SSE	docs/integrations/openai-agents-sdk.md
LangChain	stdio、HTTP	docs/integrations/langchain.md
Google ADK	stdio、HTTP、SSE	docs/integrations/google-adk.md
n8n	HTTP、SSE	docs/integrations/n8n.md
CrewAI	stdio、HTTP	docs/integrations/crewai.md

每份指南都包含快速入门示例、多 Agent 模式，以及连接托管演示和可自托管部署的选项。

开发

# Run tests
uv run pytest

# Lint and format
uv run ruff check server.py
uv run ruff format server.py tests/

# Set up pre-commit hooks (recommended)
./scripts/setup-hooks.sh

固定 GitHub Actions 版本

.github/workflows 中的每个 uses: 都固定到 40 个字符的提交 SHA，并附有注释，注明该 SHA 对应的确切补丁版本：

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

像 v7 这样的标签可以被移动——操作的所有者可以随时将其指向其他提交，因此 @v7 会运行作业启动时它所指向的提交。SHA 则无法移动。每个工作流也都以只读权限启动（permissions: contents: read），仅在需要写入权限的单个作业中授予写入范围（只有 PyPI 发布作业具有 id-token: write）。

不过，固定版本会让每个引用难以辨读，而且没有机制能确保 SHA 与其旁边的注释相符：拉取请求可能把哈希替换成来自分叉仓库的哈希，却保留 # v7.0.1 不变，让差异看起来像一次常规依赖更新。scripts/check-action-pins.sh 可弥补这一缺口。它要求使用真实的 SHA、所有者在 ALLOWED_OWNERS 允许列表中，并且版本注释注明确切的补丁版本；随后通过 git ls-remote 在上游解析该标签，如果其指向的提交与固定的 SHA 不一致，就会报错。

./scripts/check-action-pins.sh            # every check, including upstream lookups
./scripts/check-action-pins.sh --offline  # skip the network; SHA and comment format only

它会作为 CI 中的 pins 作业运行，并且在两个由标签触发的发布工作流中，都会在检出代码后的第一个步骤再次运行，确保发布内容不会由固定版本未经验证的步骤构建。升级操作时，必须同时更新 SHA 和注释；新增操作时，应谨慎将其所有者加入 ALLOWED_OWNERS，因为无论是谁发布了标签，固定版本都会依据该标签进行验证。

发布流程

发布脚本（scripts/release.sh）包含全面的发布前检查，以避免 v2.8.2 格式问题之类的状况：

• 代码格式检查 - 确保 ruff format 通过
• Lint 检查 - 确保 ruff check 通过
• CI 状态检查 - 如果 CI 未通过，会发出警告
• 测试套件 - 运行所有测试
• 版本一致性 - 验证各文件中的版本号
• 更新日志 - 确保存在更新日志条目

提供了提交前钩子，可尽早发现问题。运行 ./scripts/setup-hooks.sh 进行安装。

托管 MCP 服务

此 MCP 服务的公开托管实例运行在 Google Cloud Run 上，并连接到实时 OrionBelt® Semantic Layer 演示 API。无需本地安装，也无需 API 密钥。

端点

https://orionbelt.ralforion.com/mcp

Streamable HTTP（MCP 规范 2025-03-26）。有状态——客户端应发送 initialize 握手，并重复使用返回的 Mcp-Session-Id 标头。

使用 Claude Desktop 快速开始

Claude Desktop 的配置架构仅接受 stdio 启动器——若要连接远程 MCP 服务，请使用 mcp-remote stdio↔HTTP 桥接工具（由 npx 自动获取，无需手动安装）。

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），并添加：

{
  "mcpServers": {
    "orionbelt": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://orionbelt.ralforion.com/mcp",
        "--transport",
        "http"
      ]
    }
  }
}

完全退出 Claude Desktop（macOS 上按 ⌘Q——仅关闭窗口还不够），然后重新打开。OrionBelt® 工具随后会显示在工具菜单中。

或者，在较新版本的 Claude Desktop 中：Settings → Connectors → Add custom connector，粘贴上面的 URL。无需编辑文件或使用 npx。

为什么使用 mcp-remote？ Claude Desktop 的 claude_desktop_config.json 配置架构目前只会验证 stdio 条目（command + args）。直接使用 {"url": "…"} 条目会被拒绝，并显示 "not valid MCP server configurations and were skipped"。mcp-remote 会运行本地 stdio 桥接工具，将请求转发到 HTTPS 端点，因此 Claude Desktop 会将其视为普通 stdio 服务。Claude Code 原生支持 {"type": "url", "url": "…"}——见下文。

使用 Claude Code 快速开始

在任意仓库的 .mcp.json 中添加（或全局添加到 ~/.config/claude-code/.mcp.json）：

{
  "mcpServers": {
    "orionbelt": {
      "type": "url",
      "url": "https://orionbelt.ralforion.com/mcp"
    }
  }
}

其他 MCP 客户端

任何支持 Streamable HTTP 传输（MCP 规范 2025-03-26）的客户端都可以连接到上面的 URL。该端点接受带有 Accept: application/json, text/event-stream 的 POST /mcp 请求。请参阅 tests/cloudrun/test_mcp_cloudrun.sh，其中提供了一个仅使用 Python 标准库的冒烟测试，可完整执行握手流程。

说明

• 托管实例在空闲时会缩容至零，因此冷却一段时间后的首次请求会多花约 1–2 秒。
• 它连接到公开演示 API https://orionbelt.ralforion.com——使用相同的数据和方言，无需身份验证。请勿通过它加载生产数据。
• 如需自托管，请参阅上文的安装部分和 Dockerfile。

许可证

版权所有 2026 RALFORION d.o.o.

依据 Apache License 2.0 版授权。详情请参阅 LICENSE。

第三方许可证

PyPI 软件包仅包含 server.py——其依赖项已声明，但未打包，因此不会再分发任何第三方代码。

Docker 镜像确实包含这些依赖项，并在以下三个位置附带其许可证：

镜像中的位置	涵盖内容
/app/.venv/lib/*/site-packages/*.dist-info/licenses/	各 Python 软件包，保留作者发布时的原样
/app/THIRD_PARTY_NOTICES.md	汇总到一个文件中的相同文本
/usr/share/doc/*/copyright	从 python:3.14-slim 继承的 Debian 基础软件包

汇总文件已提交为 THIRD_PARTY_NOTICES.md，并复制到镜像中， 因此无需拉取任何内容即可读取；依赖项变更导致其内容改变时，也会在同一差异中接受审查。CI 会在每个 PR 上根据锁定的软件包集合重新生成该文件，并在提交版本不同时失败，从而避免内容偏离。要读取镜像实际附带的版本——这是任何给定标签的权威版本：

docker run --rm --entrypoint cat ralforion/orionbelt-semantic-layer-mcp:latest \
    /app/THIRD_PARTY_NOTICES.md

在 Linux 上使用 scripts/third_party_notices.py 重新生成。该脚本会针对镜像的目标平台解析依赖，而不是针对你的主机；在 macOS 上按主机平台解析时，会在不提示的情况下漏掉 jeepney 和 SecretStorage。

Python 依赖项均采用宽松许可证，但有两个例外；这两项已记录在 scripts/third_party_notices.py 的 ACKNOWLEDGED 中，而非留待读者自行推断：certifi 采用 MPL-2.0，docutils 提供的许可证选项中包括 GPL。MPL-2.0 是文件级著佐权，仅适用于文件本身，不适用于导入这些文件的程序，因此将其未经修改地与本声明一同分发即可满足要求。必须在发布前以书面形式选定 docutils 的许可证选项；在完成选择之前，生成器会报错。其他所有依赖项均采用 MIT、BSD、Apache-2.0、ISC、Unlicense 或 PSF-2.0，且这些许可证均不适用于服务端自身的代码。

Debian 基础镜像则是另一回事。 python:3.14-slim 会带入约 87 个系统软件包，其中许多采用 GPL/LGPL（coreutils、libc6、bash 等），所有基于 Debian 的镜像都如此。这些是未经修改的上游软件包，仅作为普通操作系统组件调用，并未链接到此服务中，也不是从此服务衍生而来；其许可证和书面要约文本随镜像一同存放在 /usr/share/doc/ 和 /usr/share/common-licenses/ 下。如果你的分发政策要求完全避免这些软件包，请基于 distroless 或 Alpine 基础镜像重新构建 FROM。

---

版权所有 © 2026 RALFORION d.o.o.
OrionBelt® 是 RALFORION d.o.o. 的注册商标。