feat(engine): add private NDC nodes and ontology bridge

This commit is contained in:
Codex
2026-07-16 02:23:45 +03:00
parent 569b8762e6
commit 59e9c92415
25 changed files with 10450 additions and 12 deletions
@@ -467,9 +467,27 @@ function normalizeTypeName(value) {
function fullNodeType(value) {
const raw = cleanString(value, 240)
if (!raw) return ''
if (isPackageQualifiedNodeType(raw)) return raw
return raw.startsWith('n8n-nodes-base.') ? raw : `n8n-nodes-base.${raw}`
}
function isPackageQualifiedNodeType(value) {
return /^(?:@[a-z0-9._-]+\/)?n8n-nodes-[a-z0-9._-]+\.[a-z0-9._-]+$/i.test(cleanString(value, 240))
}
function catalogNodeRuntimeType(node) {
const explicit = [node?.runtimeType, node?.fullType, node?.publicType, node?.type]
.map((value) => cleanString(value, 240))
.find(isPackageQualifiedNodeType)
if (explicit) return explicit
const packageName = cleanString(node?.packageName || node?.package, 160)
const name = cleanString(node?.name, 160)
if (name && /^(?:@[a-z0-9._-]+\/)?n8n-nodes-[a-z0-9._-]+$/i.test(packageName)) {
return `${packageName}.${name}`
}
return fullNodeType(node?.publicType || name)
}
function cleanWebhookSegment(value, fallback) {
const out = cleanString(value, 240)
.toLowerCase()
@@ -538,7 +556,8 @@ function compactNodeDefinition(node, maxProperties = 80) {
const properties = Array.isArray(node?.properties) ? node.properties.slice(0, maxProperties) : []
return {
name: node?.name || '',
fullType: fullNodeType(node?.name || ''),
publicType: node?.publicType || node?.name || '',
fullType: catalogNodeRuntimeType(node),
displayName: node?.displayName || node?.name || '',
description: node?.description || '',
group: node?.group || [],
@@ -722,7 +741,8 @@ async function handleSearchNodes(args) {
.slice(0, limit)
.map(({ node }) => ({
name: node?.name || '',
fullType: fullNodeType(node?.name || ''),
publicType: node?.publicType || node?.name || '',
fullType: catalogNodeRuntimeType(node),
displayName: node?.displayName || node?.name || '',
description: node?.description || '',
group: node?.group || [],
@@ -737,7 +757,8 @@ async function handleGetNodeDefinition(args) {
const catalog = await loadNodeCatalog(args.schemaVersion)
const node = catalog.find((item) => (
String(item?.name || '') === nodeType ||
fullNodeType(item?.name || '') === cleanString(args.nodeType || args.type || args.name)
String(item?.publicType || '') === nodeType ||
catalogNodeRuntimeType(item) === cleanString(args.nodeType || args.type || args.name)
))
if (!node) throw new Error(`node_not_found:${nodeType}`)
return { ok: true, node: compactNodeDefinition(node, Number(args.maxProperties || 80) || 80) }
+85 -5
View File
@@ -15,7 +15,7 @@ const SUPPORTED_CONNECTION_MODES = new Set(["hub", "direct"]);
const SUPPORTED_EXECUTOR_STATUSES = new Set(["unknown", "online", "offline", "checking", "error"]);
const SUPPORTED_THREAD_STATES = new Set(["active", "archived"]);
const SUPPORTED_MESSAGE_ROLES = new Set(["user", "assistant", "system", "tool"]);
const SUPPORTED_TOOL_PACKS = new Set(["engine", "ops", "ndc-agent-core", "deploy", "docs"]);
const SUPPORTED_TOOL_PACKS = new Set(["engine", "ops", "ndc-agent-core", "ontology", "deploy", "docs"]);
const SUPPORTED_RUN_STATUSES = new Set(["running", "completed", "failed", "timeout"]);
const AI_WORKSPACE_BRIDGE_PACKAGE_NAME = "@nodedc/ai-workspace-bridge";
const AI_WORKSPACE_BRIDGE_PACKAGE_BIN = "ai-workspace-bridge";
@@ -81,6 +81,26 @@ const APP_ROUTING_CATALOG = [
requiredScopes: ["engine:workspace:read"],
deniedText: ACCESS_DENIED_TEXT,
},
{
appId: "ontology",
appTitle: "NODE.DC Ontology Core",
surface: "global",
skillId: "ontology-context",
whenToUse: [
"canonical entities",
"aliases",
"relations",
"semantic guardrails",
"data contracts",
"cross-contour context",
"Gelios domain model",
],
actionNamespaces: [],
actionIdPrefixes: [],
mcpServerNames: ["nodedc_ontology"],
requiredScopes: ["ontology:catalog:read"],
deniedText: ACCESS_DENIED_TEXT,
},
{
appId: "ops",
appTitle: "NODE.DC Ops / Tasker",
@@ -2113,18 +2133,23 @@ async function buildRunProfile({ owner, thread, executor, ownerSettings, bridgeP
|| thread.originSurface
|| "global";
const targetContexts = isPlainObject(context.contexts) ? context.contexts : {};
const enabledToolPacks = mergeToolPacks(
let enabledToolPacks = mergeToolPacks(
ownerSettings?.enabledToolPacks,
thread.enabledToolPacks,
bridgePayload?.enabledToolPacks
);
const grantResolution = await resolveRunAppGrants({ owner, context, ownerSettings });
const appGrants = summarizeRunAppGrants({ appGrants: grantResolution.appGrants });
const mcpServers = runProfileMcpServersFromAppGrants(ownerSettings, grantResolution.appGrants);
const ontologyGrant = ontologyMcpGrantForExecutor(executor);
const resolvedAppGrants = ontologyGrant
? { ...grantResolution.appGrants, ontology: ontologyGrant }
: grantResolution.appGrants;
if (ontologyGrant) enabledToolPacks = mergeToolPacks(enabledToolPacks, ["ontology"]);
const appGrants = summarizeRunAppGrants({ appGrants: resolvedAppGrants });
const mcpServers = runProfileMcpServersFromAppGrants(ownerSettings, resolvedAppGrants);
const mcpServerNames = mcpServers.map((server) => server.serverName).filter(Boolean);
const assistantActions = await assistantActionToolProfileForRun();
const appCatalog = buildRunProfileAppCatalog({
appGrants: grantResolution.appGrants,
appGrants: resolvedAppGrants,
mcpServers,
assistantActions,
});
@@ -2148,6 +2173,7 @@ async function buildRunProfile({ owner, thread, executor, ownerSettings, bridgeP
deniedAppIds: appAccess.deniedAppIds,
notGrantedAppIds: appAccess.notGrantedAppIds,
entitlementAdapters: grantResolution.diagnostics,
ontologyMcp: ontologyMcpDiagnostic(executor, ontologyGrant),
mcpServerNames,
requiredMcpServerNames,
assistantActionIds: assistantActions.actionIds,
@@ -2189,6 +2215,41 @@ async function buildRunProfile({ owner, thread, executor, ownerSettings, bridgeP
return runProfile;
}
function ontologyMcpGrantForExecutor(executor) {
if (!config.ontologyMcpEnabled) return null;
if (executor?.connectionMode !== "hub") return null;
const pairingCode = cleanPairingCode(executor?.pairingCode);
if (!pairingCode || !config.ontologyMcpPublicBaseUrl) return null;
return {
appId: "ontology",
appTitle: "NODE.DC Ontology Core",
surface: "global",
source: "platform-runtime",
status: "granted",
scopes: ["ontology:catalog:read"],
mcpServers: [{
appId: "ontology",
appTitle: "NODE.DC Ontology Core",
serverName: "nodedc_ontology",
url: `${config.ontologyMcpPublicBaseUrl}/api/ai-workspace/hub/v1/ontology-mcp/${encodeURIComponent(pairingCode)}/mcp`,
required: false,
startupTimeoutSec: 20,
toolTimeoutSec: 60,
httpHeaders: {
Accept: "application/json, text/event-stream",
"MCP-Protocol-Version": "2025-06-18",
},
}],
};
}
function ontologyMcpDiagnostic(executor, grant) {
if (grant) return { status: "granted", serverName: "nodedc_ontology", readOnly: true };
if (!config.ontologyMcpEnabled) return { status: "disabled", readOnly: true };
if (executor?.connectionMode !== "hub") return { status: "unavailable_for_direct_executor", readOnly: true };
return { status: "pairing_or_public_hub_url_required", readOnly: true };
}
async function assistantActionToolProfileForRun() {
const gatewayUrl = assistantActionGatewayUrlForRun();
const gatewayToken = optionalString(
@@ -2711,6 +2772,10 @@ function buildRunProfilePolicyPrompt({ context, diagnostics, assistantActions })
"- Interpret the user's natural-language request first; call assistant actions only after selecting a structured action id.",
"- Read assistant actions may execute after structured action selection. Privileged/write assistant actions require preview, explicit user confirmation, then execute.",
"- Ops card actions advertised in this run are valid assistant actions: use ops.card.list_recent for reading cards, ops.card.create for creating cards, and ops.card.add_comment for comments instead of refusing because direct Ops MCP tools are absent.",
...(diagnostics.mcpServerNames.includes("nodedc_ontology") ? [
"- The nodedc_ontology MCP server is the live, read-only semantic source for canonical entities, aliases, relations and guardrails. Use it before inventing workflow names, data contracts or cross-contour bindings.",
"- Ontology Core does not expose telemetry, databases, credentials, command dispatch or Studio controls. Request those only through separately granted application capabilities.",
] : []),
"- Destructive assistant actions are forbidden; offer safe alternatives such as block/disable instead of delete.",
"- MCP tokens and headers are runtime secrets and must never be printed in public answers.",
];
@@ -4465,6 +4530,11 @@ function readConfig() {
optionalString(process.env.NDC_AI_WORKSPACE_OPS_GATEWAY_BASE_URL) ||
"";
const normalizedSetupGatewayUrl = setupGatewayUrl.replace(/\/+$/, "");
const ontologyMcpPublicBaseUrl = cleanHttpEndpoint(
optionalString(process.env.AI_WORKSPACE_ONTOLOGY_MCP_PUBLIC_URL) ||
optionalString(process.env.NDC_AI_WORKSPACE_ONTOLOGY_MCP_PUBLIC_URL) ||
httpUrlFromWebSocketUrl(hubWebSocketUrl)
);
const bridgePackageSpec =
optionalString(process.env.AI_WORKSPACE_BRIDGE_PACKAGE_SPEC) ||
optionalString(process.env.NDC_AI_WORKSPACE_BRIDGE_PACKAGE_SPEC) ||
@@ -4505,6 +4575,16 @@ function readConfig() {
),
hubInternalAccessToken:
explicitHubAccessToken || (isDeployedPublicHubUrl(hubInternalHttpUrl) ? "" : sharedInternalAccessToken),
ontologyMcpEnabled: isTruthy(
optionalString(process.env.AI_WORKSPACE_ONTOLOGY_MCP_ENABLED) ||
optionalString(process.env.NDC_AI_WORKSPACE_ONTOLOGY_MCP_ENABLED) ||
"false"
) && !isFalsy(
optionalString(process.env.AI_WORKSPACE_ONTOLOGY_MCP_ENABLED) ||
optionalString(process.env.NDC_AI_WORKSPACE_ONTOLOGY_MCP_ENABLED) ||
"false"
),
ontologyMcpPublicBaseUrl,
ontologyLauncherBaseUrl: ontologyLauncherBaseUrl.replace(/\/+$/, ""),
launcherInternalAccessToken,
opsGatewayBaseUrl: opsGatewayBaseUrl.replace(/\/+$/, ""),
@@ -3457,9 +3457,27 @@ function normalizeTypeName(value) {
function fullNodeType(value) {
const raw = cleanString(value, 240)
if (!raw) return ''
if (isPackageQualifiedNodeType(raw)) return raw
return raw.startsWith('n8n-nodes-base.') ? raw : `n8n-nodes-base.${raw}`
}
function isPackageQualifiedNodeType(value) {
return /^(?:@[a-z0-9._-]+\/)?n8n-nodes-[a-z0-9._-]+\.[a-z0-9._-]+$/i.test(cleanString(value, 240))
}
function catalogNodeRuntimeType(node) {
const explicit = [node?.runtimeType, node?.fullType, node?.publicType, node?.type]
.map((value) => cleanString(value, 240))
.find(isPackageQualifiedNodeType)
if (explicit) return explicit
const packageName = cleanString(node?.packageName || node?.package, 160)
const name = cleanString(node?.name, 160)
if (name && /^(?:@[a-z0-9._-]+\/)?n8n-nodes-[a-z0-9._-]+$/i.test(packageName)) {
return `${packageName}.${name}`
}
return fullNodeType(node?.publicType || name)
}
function cleanWebhookSegment(value, fallback) {
const out = cleanString(value, 240)
.toLowerCase()
@@ -3528,7 +3546,8 @@ function compactNodeDefinition(node, maxProperties = 80) {
const properties = Array.isArray(node?.properties) ? node.properties.slice(0, maxProperties) : []
return {
name: node?.name || '',
fullType: fullNodeType(node?.name || ''),
publicType: node?.publicType || node?.name || '',
fullType: catalogNodeRuntimeType(node),
displayName: node?.displayName || node?.name || '',
description: node?.description || '',
group: node?.group || [],
@@ -3712,7 +3731,8 @@ async function handleSearchNodes(args) {
.slice(0, limit)
.map(({ node }) => ({
name: node?.name || '',
fullType: fullNodeType(node?.name || ''),
publicType: node?.publicType || node?.name || '',
fullType: catalogNodeRuntimeType(node),
displayName: node?.displayName || node?.name || '',
description: node?.description || '',
group: node?.group || [],
@@ -3727,7 +3747,8 @@ async function handleGetNodeDefinition(args) {
const catalog = await loadNodeCatalog(args.schemaVersion)
const node = catalog.find((item) => (
String(item?.name || '') === nodeType ||
fullNodeType(item?.name || '') === cleanString(args.nodeType || args.type || args.name)
String(item?.publicType || '') === nodeType ||
catalogNodeRuntimeType(item) === cleanString(args.nodeType || args.type || args.name)
))
if (!node) throw new Error(`node_not_found:${nodeType}`)
return { ok: true, node: compactNodeDefinition(node, Number(args.maxProperties || 80) || 80) }
+2 -1
View File
@@ -5,7 +5,8 @@
"type": "module",
"scripts": {
"start": "node src/server.mjs",
"dev": "node --watch src/server.mjs"
"dev": "node --watch src/server.mjs",
"smoke:ontology-mcp-proxy": "node src/scripts/smoke-ontology-mcp-proxy.mjs"
},
"dependencies": {
"express": "^5.2.1",
@@ -0,0 +1,129 @@
#!/usr/bin/env node
import assert from 'node:assert/strict'
import { spawn } from 'node:child_process'
import { once } from 'node:events'
import { createServer } from 'node:http'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { WebSocket } from 'ws'
import { createOntologyMcpServer } from '../../../ontology-core/src/mcp-server.mjs'
const INTERNAL_TOKEN = 'hub-ontology-mcp-smoke-token'
const PAIRING_CODE = 'ONTOLOGYSMOKE1'
const currentFile = fileURLToPath(import.meta.url)
const hubRoot = path.resolve(path.dirname(currentFile), '..', '..')
const ontologyPort = await availablePort()
const hubPort = await availablePort()
const ontologyServer = createOntologyMcpServer({
internalTokens: [INTERNAL_TOKEN],
allowedOrigins: [],
maxBodyBytes: 1024 * 1024,
})
const hubProcess = spawn(process.execPath, ['src/server.mjs'], {
cwd: hubRoot,
env: {
...process.env,
PORT: String(hubPort),
AI_WORKSPACE_HUB_TOKEN: INTERNAL_TOKEN,
NODEDC_INTERNAL_ACCESS_TOKEN: INTERNAL_TOKEN,
NODEDC_ONTOLOGY_CORE_URL: `http://127.0.0.1:${ontologyPort}`,
NODEDC_AI_WORKSPACE_ASSISTANT_URL: 'http://127.0.0.1:1',
},
stdio: ['ignore', 'pipe', 'pipe'],
})
let hubOutput = ''
hubProcess.stdout.on('data', (chunk) => { hubOutput += String(chunk) })
hubProcess.stderr.on('data', (chunk) => { hubOutput += String(chunk) })
let worker = null
try {
await new Promise((resolve) => ontologyServer.listen(ontologyPort, '127.0.0.1', resolve))
await waitForHub(`http://127.0.0.1:${hubPort}/healthz`, hubProcess)
worker = new WebSocket(
`ws://127.0.0.1:${hubPort}/api/ai-workspace/hub?pairingCode=${PAIRING_CODE}&machineName=ontology-smoke`,
)
await once(worker, 'open')
worker.send(JSON.stringify({
type: 'hello',
agentVersion: 'smoke',
protocolVersion: 'ai-workspace-bridge/v1',
capabilities: ['smoke'],
}))
const response = await fetch(
`http://127.0.0.1:${hubPort}/api/ai-workspace/hub/v1/ontology-mcp/${PAIRING_CODE}/mcp`,
{
method: 'POST',
headers: {
'content-type': 'application/json',
accept: 'application/json, text/event-stream',
'mcp-protocol-version': '2025-06-18',
},
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: {
name: 'ontology_get_entity',
arguments: { term: 'helius' },
},
}),
},
)
const payload = await response.json()
assert.equal(response.ok, true)
assert.equal(response.headers.get('mcp-protocol-version'), '2025-06-18')
assert.equal(payload.result.structuredContent.entity.id, 'gelios.integration')
worker.close()
await once(worker, 'close')
const offline = await fetch(
`http://127.0.0.1:${hubPort}/api/ai-workspace/hub/v1/ontology-mcp/${PAIRING_CODE}/mcp`,
{ method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' },
)
assert.equal(offline.status, 503)
console.log(JSON.stringify({
ok: true,
checks: [
'pairing_bound_hub_proxy',
'internal_bearer_replaced_by_hub',
'ontology_mcp_tool_response',
'mcp_protocol_header_forwarded',
'offline_pairing_is_rejected',
],
}, null, 2))
} finally {
if (worker && worker.readyState === WebSocket.OPEN) worker.close()
if (hubProcess.exitCode === null && !hubProcess.killed) {
hubProcess.kill('SIGTERM')
await once(hubProcess, 'exit').catch(() => {})
}
await new Promise((resolve, reject) => ontologyServer.close((error) => error ? reject(error) : resolve()))
if (hubProcess.exitCode && hubProcess.exitCode !== 0) {
throw new Error(`hub_smoke_child_failed:${hubOutput.slice(-2000)}`)
}
}
async function availablePort() {
const server = createServer()
await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
const port = server.address().port
await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()))
return port
}
async function waitForHub(url, processRef) {
for (let attempt = 0; attempt < 40; attempt += 1) {
if (processRef.exitCode !== null) throw new Error('hub_smoke_child_exited_early')
try {
const response = await fetch(url)
if (response.ok) return
} catch {}
await new Promise((resolve) => setTimeout(resolve, 100))
}
throw new Error('hub_smoke_health_timeout')
}
+63
View File
@@ -34,6 +34,7 @@ app.get("/healthz", (_req, res) => {
agentsOnline: Array.from(agentsByCode.values()).filter(isAgentOnline).length,
assistantRelays: assistantRelaysById.size,
internalApiConfigured: config.internalAccessTokens.length > 0,
ontologyMcpProxyConfigured: Boolean(config.ontologyCoreUrl && config.ontologyCoreAccessToken),
});
});
@@ -85,6 +86,7 @@ app.post("/api/ai-workspace/hub/v1/assistant-relays/:relayId/poll", requireInter
app.post("/api/ai-workspace/hub/v1/assistant-relays/:relayId/results/:callId", requireInternalApi, asyncRoute(completeAssistantRelayCall));
app.use("/api/ai-workspace/hub/v1/ndc-agent-mcp/:pairingCode", asyncRoute(proxyNdcAgentMcp));
app.use("/api/ai-workspace/hub/v1/ontology-mcp/:pairingCode", asyncRoute(proxyOntologyMcp));
app.use((error, _req, res, _next) => {
const status = Number(error?.status || 500);
@@ -288,6 +290,60 @@ async function proxyNdcAgentMcp(req, res) {
res.send(text);
}
async function proxyOntologyMcp(req, res) {
if (!config.ontologyCoreUrl || !config.ontologyCoreAccessToken) {
res.status(503).json({ ok: false, error: "ontology_mcp_proxy_not_configured" });
return;
}
const pairingCode = cleanPairingCode(req.params.pairingCode);
const agent = agentsByCode.get(pairingCode);
if (!agent || !isAgentOnline(agent)) {
res.status(503).json({ ok: false, error: "bridge_agent_offline" });
return;
}
const marker = `/api/ai-workspace/hub/v1/ontology-mcp/${encodeURIComponent(req.params.pairingCode)}`;
const suffix = String(req.originalUrl || "").startsWith(marker)
? String(req.originalUrl || "").slice(marker.length)
: String(req.url || "");
const targetUrl = `${config.ontologyCoreUrl.replace(/\/+$/, "")}${suffix || "/mcp"}`;
await proxyInternalMcpRequest(req, res, targetUrl, config.ontologyCoreAccessToken);
}
async function proxyInternalMcpRequest(req, res, targetUrl, accessToken) {
const method = String(req.method || "GET").toUpperCase();
const hasBody = !["GET", "HEAD"].includes(method);
const upstream = await fetch(targetUrl, {
method,
redirect: "manual",
headers: {
Accept: String(req.headers.accept || "application/json, text/event-stream"),
Authorization: `Bearer ${accessToken}`,
...forwardMcpHeaders(req),
...(hasBody ? { "Content-Type": "application/json" } : {}),
},
...(hasBody ? { body: JSON.stringify(req.body || {}) } : {}),
});
const contentType = upstream.headers.get("content-type") || "application/json; charset=utf-8";
const text = await upstream.text();
res.status(upstream.status);
res.setHeader("content-type", contentType);
for (const header of ["cache-control", "mcp-protocol-version", "mcp-session-id", "vary"]) {
const value = upstream.headers.get(header);
if (value) res.setHeader(header, value);
}
res.send(text);
}
function forwardMcpHeaders(req) {
const headers = {};
for (const name of ["mcp-protocol-version", "mcp-session-id", "last-event-id"]) {
const value = cleanString(req.headers[name], 1000);
if (value) headers[name] = value;
}
return headers;
}
async function proxyAssistantActions(req, res) {
if (!config.assistantInternalUrl || !config.assistantInternalAccessToken) {
res.status(503).json({ ok: false, error: "assistant_action_proxy_not_configured" });
@@ -793,6 +849,13 @@ function readConfig() {
1000,
).replace(/\/+$/, ""),
assistantInternalAccessToken: cleanString(process.env.NODEDC_INTERNAL_ACCESS_TOKEN, 1000),
ontologyCoreUrl: cleanString(
process.env.NODEDC_ONTOLOGY_CORE_URL ||
process.env.NDC_ONTOLOGY_CORE_URL ||
"http://ontology-core:18104",
1000,
).replace(/\/+$/, ""),
ontologyCoreAccessToken: cleanString(process.env.NODEDC_INTERNAL_ACCESS_TOKEN, 1000),
};
}