SILVER
/
NODEDC_PLATFORM
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NODEDC_PLATFORM/docs/AI_WORKSPACE_ONTOLOGY_MCP.md

4.1 KiB
Raw Blame History

AI Workspace ↔ Ontology Core MCP

Purpose

This is the read-only semantic path for a NODE.DC AI Workspace run:

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:

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

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