83 lines
4.2 KiB
Markdown
83 lines
4.2 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 external providers and runtime data
|
|
|
|
Ontology Core describes the canonical meanings and constraints:
|
|
|
|
```text
|
|
gelios.unit -> gelios.telemetry_snapshot -> gelios.position_fix -> map.moving_object
|
|
```
|
|
|
|
It does **not** serve provider runtime data or call a provider API. Provider
|
|
access and mapping belong to the granted NDC L2 workflow; shared current and
|
|
history products belong to the provider-neutral External Data Plane. A scoped
|
|
Data Product read capability may later be supplied to an AI Workspace run as a
|
|
separate dynamic MCP server. Ontology supplies meanings, relations, guardrails
|
|
and the allowed 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.
|
|
- External Data Plane: access-scoped Data Product snapshots and updates.
|
|
- Command Gateway: separate red-domain command route, explicit confirmation and audit.
|
|
- NDC L2 workflow: provider access, collection and mapping using granted capabilities.
|
|
- Foundry: 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
|
|
```
|