ontology

<p align="center"> <a href="https://ibl.ai"><img src="https://ibl.ai/images/iblai-logo.png" alt="ibl.ai" width="300"></a> </p> <h1 align="center">iblai/ontology</h1> <p align="center"><strong>本地知识层，使组织现有的系统能够被 AI 代理通过 MCP 查询，无需数据提取。</strong></p> <p align="center"> <img src="https://img.shields.io/badge/coverage-85%25-brightgreen.svg" alt="覆盖率 85%"> <img src="https://img.shields.io/badge/tests-163%20passing-brightgreen.svg" alt="测试"> <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"> <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="许可证：MIT"> <img src="https://img.shields.io/badge/protocol-MCP-8A2BE2.svg" alt="MCP"> <a href="https://github.com/googleapis/mcp-toolbox"><img src="https://img.shields.io/badge/inbound-MCP%20Toolbox-4285F4.svg" alt="MCP 工具箱"></a> <img src="https://img.shields.io/badge/identity-Entra%20ID-0078D4.svg" alt="Microsoft Entra ID"> </p> --- ## 什么是 iblai/ontology iblai/ontology 是一个**统一的知识层，运行在您的网络内**。它使您已经运行的系统 —— SIS/ERP 数据库（PeopleSoft、Oracle、Postgres）、数据仓库（Snowflake）和 SaaS 应用（Canvas、Salesforce、ServiceNow、Workday、Jira 等）—— 能够被 AI 代理通过 **模型上下文协议（MCP）** 查询。 传统的方法是通过 VPN 隧道将数据提取到供应商云中。iblai/ontology 则相反：**无需数据提取，无需 VPN 连接到我们的云，无需第三方基础设施持有您的数据**。代理运行时（模型执行的位置）是一个独立的关注点，可以在任何地方运行；知识层 —— 数据、缓存、权限 —— 保留在本地，并通过 MCP 暴露，以便任何**授权**的运行时都可以连接。 > **您将拥有您的数据，我们可能甚至无法访问它。** 它是**领域无关的**：相同的堆栈服务于大学（高等教育系统）和企业（CRM/ITSM/HCM/数据仓库），并为两者提供了内置的默认值（参见 [内置服务目录](#内置服务目录)）。 ## 如何连接（MCP 进，MCP 出） ``` 您的网络（本地） ┌──────────────────────────────────────────────────────────────┐ │ 源系统 │ │ PeopleSoft/Oracle · Snowflake · Postgres Canvas · Salesforce │ │ │ （SQL，只读） │ （REST） │ │ ▼ ▼ │ │ ┌───────────────────────────┐ ┌──────────────────────────┐ │ │ │ Google MCP 工具箱 │ │ 自定义 MCP 服务器 │ │ │ │ （数据库）[1] │ │ （API）[1] │ │ │ └─────────────┬─────────────┘ └────────────┬─────────────┘ │ │ └───────────────┬───────────────┘ │ │ [2] 同步 → 文本记忆（MD）+ Postgres 缓存 + 向量 │ │ │ │ │ [3] 身份验证：Entra ID JWT + roles.yaml（X-Iblai-Role） │ │ │ │ │ [4] iblai/ontology 暴露为一个 MCP 服务器（HTTPS） │ └────────────────────────────────┬───────────────────────────────┘ │ 通过 HTTPS 的 MCP，角色范围 ▼ 外部：代理运行时（ibl.ai 或任何地方）—— 转发用户的 Entra token 每个请求，从不存储机构数据。 ``` - **流入** 使用 [**Google MCP 工具箱用于数据库**](https://github.com/googleapis/mcp-toolbox)：数据库通过 `config/tools.yaml` 暴露为 MCP 工具（`kind: source | tool | toolset`）。REST 系统获取轻量级自定义 MCP 服务器（`mcp-servers/`）。运行 `ontology mcp validate` 以检查 `tools.yaml` 是否符合工具箱模式。 - **流出**，iblai/ontology 本身就是**一个 MCP 服务器**（`streamable_http`，在您的防火墙后 + Entra ID）。任何 MCP 客户端 —— ibl.ai 代理运行时、Claude、Cursor、自定义应用 —— 连接并获取根据调用者角色范围的结果。 完整设计： **[docs/architecture.md](docs/architecture.md)**。 ## 快速开始 ```bash pip install -e ".[dev]" # 核心 CLI + 测试 ontology --help ontology config init # 搭建部署（config/，sql/，compose） ``` 混合堆栈 —— 一个精简的、无 Django 的 CLI + 配置层（在全新检出上运行）和一个用于长期服务的 Django + Celery 后端。根据需要安装额外功能： ```bash pip install -e ".[django]" # 后端服务（网关，同步，发现） pip install -e ".[llm]" # BYOK 模式分析（anthropic / openai） pip install -e ".[db]" # 源驱动程序（oracle，postgres，mysql，mssql） pip install -e ".[vector]" # ChromaDB 向量索引 ``` 名称：发行版 **`iblai-ontology`** · 导入包 **`iblai_ontology`** · 命令 **`ontology`**. ## 端到端 ### 1 · 发现服务 — 两种方式 **A. 实时数据库** — 连接，验证只读，内省，分析，配置： ```bash ontology service add --from peoplesoft \ --host psft-db.internal.edu --database CSPRD --user iblai_readonly ``` `--from <catalog-key>` 预填充连接形状（驱动程序，端口，环境）从 [内置目录](#内置服务目录)。管道首先运行一个**只读安全套件** —— 七个写入尝试必须全部被拒绝 —— 然后内省模式并生成配置。 **B. 从 SKILL.md** — 用没有实时连接的 API 源种子： ```bash ontology service add --skill canvas # 或：ontology skill import canvas ontology skill list # 所有供应商技能（高等教育 + 企业） ``` 这会解析技能的连接环境和关键操作到发现种子（只读操作成为建议的 MCP 工具）。 ### 2 · 解析模式并查看连接 ```bash ontology service schema peoplesoft # 已发现的表，按行数排序 ontology service connection peoplesoft # 存储的连接（机密已删除） ``` ```text $ ontology service schema peoplesoft peoplesoft — oracle | 847 tables, 12,400,000 rows Top 20 tables ┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┓ ┃ 模式 ┃ 表 ┃ 行数 ┃ 列数 ┃ ┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━┩ │ SYSADM │ PS_STDNT_CAR_TERM │ 2,345,678 │ 24 │ │ SYSADM │ PS_STDNT_ENRL │ 1,876,543 │ 31 │ └────────┴────────────────────┴───────────┴─────────┘ ``` ### 3 · 测试 ```bash ontology service test peoplesoft # 7 测试只读安全套件 ontology mcp validate # tools.yaml 是否符合 MCP 工具箱模式 ontology mcp test get-student-enrollment --params '{"student_id":"001234567"}' ``` ```text $ ontology service test peoplesoft [PASS] CREATE TABLE blocked [PASS] INSERT blocked [PASS] UPDATE blocked [PASS] DELETE blocked [PASS] DROP TABLE blocked [PASS] ALTER blocked [PASS] TRUNCATE blocked 所有安全检查通过。 # 凭证确认只读 ``` ### 4 · 配置，同步，服务 ```bash ontology service approve peoplesoft # 缓存模式，工具，同步计划 ontology sync run peoplesoft # 拉取 → 缓存 + 文本记忆 + 向量 ontology deploy up # 启动堆栈（compose） ``` 然后在您的代理平台上注册 iblai/ontology 作为 MCP 服务器（参见 [docs/platform-integration.md](docs/platform-integration.md)）： ```bash ontology platform register --url https://ontology.your-org.edu/mcp ontology platform connect --server 14 --scope user --role FinancialAidCounselor ``` ## 内置服务目录 `ontology catalog list` 提供了 22 个系统跨两个领域的默认设置（连接形状，适配器，默认工具集，同步节奏和上游 SKILL.md）。使用 `ontology service add --from <key>` 或 `ontology skill import <key>` 种子任一。 **高等教育** — [iblai/higher-education-agents](https://github.com/iblai/higher-education-agents) | 键 | 系统 | 类型 | 技能 | |---|---|---|---| | `peoplesoft` | PeopleSoft（Oracle） | 数据库 | — | | `banner` | Ellucian Banner | API | [SKILL.md](https://github.com/iblai/higher-education-agents/blob/main/skills/banner/SKILL.md) | | `canvas` | Instructure Canvas LMS | API | [SKILL.md](https://github.com/iblai/higher-education-agents/blob/main/skills/canvas/SKILL.md) | | `slate` | Technolutions Slate CRM | API | [SKILL.md](https://github.com/iblai/higher-education-agents/blob/main/skills/slate/SKILL.md) | | `workday` | Workday HCM / Student | API | [SKILL.md](https://github.com/iblai/higher-education-agents/blob/main/skills/workday/SKILL.md) | | `eab-navigate` | EAB Navigate | API | [SKILL.md](https://github.com/iblai/higher-education-agents/blob/main/skills/eab-navigate/SKILL.md) | | `salesforce-education-cloud` | Salesforce Education Cloud | API | [SKILL.md](https://github.com/iblai/higher-education-agents/blob/main/skills/salesforce-education-cloud/SKILL.md) | | `servicenow` | ServiceNow ITSM | API | [SKILL.md](https://github.com/iblai/higher-education-agents/blob/main/skills/servicenow/SKILL.md) | | `civitas-learning` | Civitas Learning | API | [SKILL.md](https://github.com/iblai/higher-education-agents/blob/main/skills/civitas-learning/SKILL.md) | | `handshake` | Handshake Careers | API | [SKILL.md](https://github.com/iblai/higher-education-agents/blob/main/skills/handshake/SKILL.md) | | `blackbaud-raisers-edge` | Blackbaud Raiser's Edge NXT | API | [SKILL.md](https://github.com/iblai/higher-education-agents/blob/main/skills/blackbaud-raisers-edge/SKILL.md) | **企业** — [iblai/enterprise-agents](https://github.com/iblai/enterprise-agents) | 键 | 系统 | 类型 | 技能 | |---|---|---|---| | `snowflake` | Snowflake 数据仓库 | 数据库 | [SKILL.md](https://github.com/iblai/enterprise-agents/blob/main/skills/snowflake/SKILL.md) | | `salesforce` | Salesforce CRM / Sales Cloud | API | [SKILL.md](https://github.com/iblai/enterprise-agents/blob/main/skills/salesforce/SKILL.md) | | `hubspot` | HubSpot CRM | API | [SKILL.md](https://github.com/iblai/enterprise-agents/blob/main/skills/hubspot/SKILL.md) | | `servicenow-itsm` | ServiceNow ITSM | API | [SKILL.md](https://github.com/iblai/enterprise-agents/blob/main/skills/servicenow/SKILL.md) | | `jira` | Jira | API | [SKILL.md](https://github.com/iblai/enterprise-agents/blob/main/skills/jira/SKILL.md) | | `confluence` | Confluence | API | [SKILL.md](https://github.com/iblai/enterprise-agents/blob/main/skills/confluence/SKILL.md) | | `github` | GitHub | API | [SKILL.md](https://github.com/iblai/enterprise-agents/blob/main/skills/github/SKILL.md) | | `okta` | Okta Identity | API | [SKILL.md](https://github.com/iblai/enterprise-agents/blob/main/skills/okta/SKILL.md) | | `slack` | Slack | API | [SKILL.md](https://github.com/iblai/enterprise-agents/blob/main/skills/slack/SKILL.md) | | `zendesk` | Zendesk | API | [SKILL.md](https://github.com/iblai/enterprise-agents/blob/main/skills/zendesk/SKILL.md) | | `zoom` | Zoom | API | [SKILL.md](https://github.com/iblai/enterprise-agents/blob/main/skills/zoom/SKILL.md) | ```bash ontology catalog show snowflake # 连接形状，环境，默认工具集，节奏，技能 ``` ## 实用工具 ```bash ontology doctor # 诊断：配置有效性，驱动程序，每个服务的环境，Entra ontology health # PostgreSQL 缓存，MCP 服务器，同步引擎，文本记忆存储 ontology catalog list # 内置服务默认设置（--domain 高等教育|企业） ontology mcp validate # tools.yaml ↔ Google MCP 工具箱模式 ``` ## CLI 参考 | 组 | 命令 | 目的 | |---|---|---| | `service` | `add` · `list` · `status` · `test` · `schema` · `connection` · `discover` · `approve` · `sync` · `remove` | 源集成（发现 + 配置） | | `skill` | `list` · `import` | 检查/种子发现从 SKILL.md | | `catalog` | `list` · `show` | 浏览内置服务默认设置 | | `config` | `init` · `show` · `set` · `llm` · `validate` | 配置管理 | | `sync` | `run` · `status` · `history` · `schedule` | 同步操作 | | `roles` | `list` · `show` · `validate` | 角色和权限管理 | | `mcp` | `status` · `tools` · `toolsets` · `validate` · `test` | MCP 服务器管理 | | `platform` | `register` · `connect` · `attach` | 与 ibl.ai 平台注册 | | `health` / `doctor` | （子检查） | 诊断 | | `deploy` | `up` · `down` · `logs` · `restart` · `status` | Docker Compose 生命周期 | 完整参考： **[docs/components/07-cli.md](docs/components/07-cli.md)**。 ## 安全状况 - ** everywhere 只读。** v1 中没有源写入。在触摸任何数据之前，安全套件尝试七个写入操作，并要求**所有七个都被拒绝** —— 否则它拒绝继续并打印补救 SQL。 - **数据保留在本地。** 源凭证从不离开您的网络；代理运行时在运行时查询，按认证用户范围。 - **通过 Entra ID 进行身份验证。** 每个 MCP 请求都携带用户的 Entra ID JWT；网关验证它并根据 `roles.yaml` 解析调用者的角色。参见 [docs/identity.md](docs/identity.md)。 - **凭证隔离和隔离。** 每个传入的 MCP 服务器都有其自己的凭证范围；连接机密在存储时被加密。 ## 文档 | 文档 | 涵盖 | |---|---| | [docs/architecture.md](docs/architecture.md) | 完整计划：定位，图表，七个组件，设计决策，推出 | | [docs/components/01-mcp-inbound.md](docs/components/01-mcp-inbound.md) | MCP 工具箱 + 自定义 MCP 服务器，`tools.yaml` | | [docs/components/02-knowledge-materialization.md](docs/components/02-knowledge-materialization.md) | 同步模式，文本记忆，Postgres 缓存，向量索引 | | [docs/components/03-identity.md](docs/components/03-identity.md) · [docs/identity.md](docs/identity.md) | Entra ID 流，`roles.yaml`，选项 A 与 B | | [docs/components/04-mcp-outbound.md](docs/components/04-mcp-outbound.md) · [docs/platform-integration.md](docs/platform-integration.md) | 输出 MCP 服务器 + ibl.ai 平台集成 | | [docs/components/05-service-discovery.md](docs/components/05-service-discovery.md) | 安全套件，内省，BYOK LLM，适配器 | | [docs/components/06-provisioning.md](docs/components/06-provisioning.md) | 6 步幂等管道 | | [docs/components/07-cli.md](docs/components/07-cli.md) | 完整 CLI 参考 | | [docs/deployment.md](docs/deployment.md) | Docker Compose 堆栈，网络，Caddyfile，`.env`，推出 | ## 许可证 MIT — 参见 [LICENSE](./LICENSE)。