77 lines
4.1 KiB
Markdown
77 lines
4.1 KiB
Markdown
# AI Workspace ↔ Ontology Core MCP
|
|
|
|
## Purpose
|
|
|
|
This is the read-only semantic path for a NODE.DC AI Workspace run:
|
|
|
|
```text
|
|
Codex worker
|
|
-> dynamic per-run MCP configuration
|
|
-> public AI Workspace Hub (pairing-bound route)
|
|
-> internal Ontology Core MCP
|
|
-> freshly loaded ontology catalog and domain packages
|
|
```
|
|
|
|
`ai-workspace-assistant` creates this MCP server entry at run-profile time for every Hub-connected executor when `AI_WORKSPACE_ONTOLOGY_MCP_ENABLED=true`. It is a platform runtime grant (`ontology:catalog:read`), not a user-owned installer secret and not a hard-coded copy of ontology rules in a prompt.
|
|
|
|
The worker receives only a pairing-bound Hub URL. The Hub verifies that the pairing agent is online and replaces any external authorization with the platform-internal token before forwarding to `ontology-core`. Ontology Core is internal-only and has no host port or reverse-proxy route.
|
|
|
|
## Read-only MCP surface
|
|
|
|
`nodedc_ontology` exposes only these tools:
|
|
|
|
- `ontology_status` — catalog counts, domain packages and a safe catalog hash;
|
|
- `ontology_search` — canonical entities, relations and aliases;
|
|
- `ontology_get_entity` — entity definition, aliases, relations and guardrails;
|
|
- `ontology_get_guardrails` — semantic/safety rules and blocked conflations;
|
|
- `ontology_resolve_context` — semantic route advice with source identifiers removed.
|
|
|
|
It intentionally does not expose filesystem paths, evidence ledgers, credentials, raw payloads, live telemetry, databases, command dispatch, workflow mutation or Studio controls.
|
|
|
|
## Boundary for Gelios and future data services
|
|
|
|
Ontology Core describes the canonical meanings and constraints:
|
|
|
|
```text
|
|
gelios.unit -> gelios.telemetry_snapshot -> gelios.position_fix -> map.moving_object
|
|
```
|
|
|
|
It does **not** serve the Gelios database or provider API. The future Gelios Gateway/Data API is a distinct capability with its own scope checks, data contract and transport. That capability may later be supplied to an AI Workspace run as another dynamic MCP server. Ontology then gives the assistant the names, relations, guardrails and allowed data-contract route; the data capability enforces access and returns live data.
|
|
|
|
This preserves one-way responsibility:
|
|
|
|
- Ontology Core: semantics, contracts, aliases, guardrails and context advice.
|
|
- Gelios Gateway/Data API: access-scoped telemetry and history reads.
|
|
- Command Gateway: separate red-domain command route, explicit confirmation and audit.
|
|
- Engine L2: workflow orchestration using granted capabilities.
|
|
- Studio: later presentation consumer, outside this implementation.
|
|
|
|
## Live catalog updates without AI Workspace rule redeploy
|
|
|
|
`loadCatalog()` runs for each Ontology MCP tool call; it does not cache the merged catalog. Therefore a new or edited domain package is visible to existing AI Workspace rules as soon as the catalog content is updated in the running Ontology Core container or mounted runtime catalog directory.
|
|
|
|
For a catalog-only release, update/restart **Ontology Core only**. The AI Workspace Assistant, Hub and Codex worker configuration do not need a rules redeploy because the MCP tool names and route stay stable. `NODEDC_ONTOLOGY_CATALOG_ROOT` may point Ontology Core at a separately managed catalog directory when a runtime-mounted catalog is required.
|
|
|
|
A Hub/Assistant rollout is needed only if the MCP transport, authorization contract or tool definitions themselves change.
|
|
|
|
## Safety properties
|
|
|
|
- The MCP server accepts only internal bearer authentication from AI Hub.
|
|
- A browser `Origin` is rejected by default; allow specific origins only through `ONTOLOGY_MCP_ALLOWED_ORIGINS` if an intentional browser transport is introduced.
|
|
- The Hub does not pass browser cookies or external `Authorization` downstream.
|
|
- The Hub route is pairing-bound and is unavailable when the worker is offline.
|
|
- All current tools are read-only. There is no generic ontology write API.
|
|
|
|
## Validation
|
|
|
|
```text
|
|
cd platform/services/ontology-core
|
|
npm run validate
|
|
npm run smoke:mcp
|
|
|
|
cd ../../
|
|
node --check services/ai-workspace-assistant/src/server.mjs
|
|
node --check services/ai-workspace-hub/src/server.mjs
|
|
docker compose --env-file infra/.env -f infra/docker-compose.dev.yml config
|
|
```
|