@x12i/memorix-service 3.7.6 → 3.7.8

package/dist/knowledge-upstream.d.ts

@@ -0,0 +1,13 @@
+export declare function knowledgeUpstreamUrl(env?: NodeJS.ProcessEnv): string;
+export declare function proxyJson(method: string, url: string, opts?: {
+    body?: unknown;
+    headers?: Record<string, string>;
+}): Promise<{
+    status: number;
+    body: unknown;
+}>;
+export declare function throwIfKnowledgeUpstreamError(upstream: {
+    status: number;
+    body: unknown;
+}): void;
+//# sourceMappingURL=knowledge-upstream.d.ts.map

package/dist/knowledge-upstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-upstream.d.ts","sourceRoot":"","sources":["../src/knowledge-upstream.ts"],"names":[],"mappings":"AAMA,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAMR;AAED,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC1D,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAoB5C;AAED,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1C,IAAI,CASN"}

package/dist/knowledge-upstream.js

@@ -0,0 +1,38 @@
+/**
+ * Shared Nexum explore REST (canvas) upstream helpers.
+ * Subjects stay on /api/data/content — this is the Mongo graphified-* store.
+ */
+import { ServiceError } from "./errors.js";
+export function knowledgeUpstreamUrl(env = process.env) {
+    return (env.MEMORIX_NEXUM_EXPLORE_URL?.trim() ||
+        env.NEXUM_API_URL?.trim() ||
+        "http://127.0.0.1:8080").replace(/\/+$/, "");
+}
+export async function proxyJson(method, url, opts) {
+    const res = await fetch(url, {
+        method,
+        headers: {
+            ...(opts?.body !== undefined
+                ? { "content-type": "application/json" }
+                : {}),
+            ...(opts?.headers ?? {}),
+        },
+        ...(opts?.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+        signal: AbortSignal.timeout(30_000),
+    });
+    const text = await res.text();
+    let parsed = text;
+    try {
+        parsed = text ? JSON.parse(text) : null;
+    }
+    catch {
+        /* keep text */
+    }
+    return { status: res.status, body: parsed };
+}
+export function throwIfKnowledgeUpstreamError(upstream) {
+    if (upstream.status >= 400) {
+        throw new ServiceError("KNOWLEDGE_UPSTREAM_ERROR", `knowledge upstream HTTP ${upstream.status}`, upstream.status >= 500 ? 502 : upstream.status, { upstream: upstream.body });
+    }
+}
+//# sourceMappingURL=knowledge-upstream.js.map

package/dist/knowledge-upstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-upstream.js","sourceRoot":"","sources":["../src/knowledge-upstream.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,UAAU,oBAAoB,CAClC,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,CACL,GAAG,CAAC,yBAAyB,EAAE,IAAI,EAAE;QACrC,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE;QACzB,uBAAuB,CACxB,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAc,EACd,GAAW,EACX,IAA2D;IAE3D,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,MAAM;QACN,OAAO,EAAE;YACP,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS;gBAC1B,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBACxC,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC;SACzB;QACD,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;KACpC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,MAAM,GAAY,IAAI,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,QAA2C;IAE3C,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QAC3B,MAAM,IAAI,YAAY,CACpB,0BAA0B,EAC1B,2BAA2B,QAAQ,CAAC,MAAM,EAAE,EAC5C,QAAQ,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,EAC9C,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,CAC5B,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/live-ops-nav.d.ts

@@ -0,0 +1,2 @@
+export declare function withMemorixLiveOpsNav(html: string): string;
+//# sourceMappingURL=live-ops-nav.d.ts.map

package/dist/live-ops-nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-ops-nav.d.ts","sourceRoot":"","sources":["../src/live-ops-nav.ts"],"names":[],"mappings":"AA8CA,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D"}

package/dist/live-ops-nav.js

@@ -0,0 +1,53 @@
+/**
+ * Inject Memorix operator pages into the shared `/_live` HTML
+ * (activity / graph / changes are memorix-service routes, not api-live-view).
+ */
+const NAV_MARK = 'id="memorix-ops-nav"';
+const NAV_HTML = `
+<style>
+  #memorix-ops-nav {
+    display: flex; flex-wrap: wrap; gap: 10px; align-items: stretch;
+    margin: 0 0 18px; padding: 12px 14px;
+    background: #10141b; border: 1px solid #242b38;
+  }
+  #memorix-ops-nav a {
+    display: flex; flex-direction: column; gap: 4px;
+    flex: 1 1 180px; min-width: 160px;
+    padding: 12px 14px; text-decoration: none;
+    border: 1px solid #242b38; background: #141922; color: #e8ebe6;
+    border-radius: 2px;
+  }
+  #memorix-ops-nav a:hover { border-color: #c8f082; }
+  #memorix-ops-nav a strong {
+    font-size: 13px; letter-spacing: 0.04em; text-transform: uppercase;
+    color: #c8f082; font-weight: 600;
+  }
+  #memorix-ops-nav a span {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 11px; color: #8a9288; line-height: 1.35;
+  }
+</style>
+<nav id="memorix-ops-nav" aria-label="Memorix operator pages">
+  <a href="/_live/activity">
+    <strong>Activity</strong>
+    <span>Pushed · Processed · Fetched</span>
+  </a>
+  <a href="/_live/graph">
+    <strong>Stored graph</strong>
+    <span>Browse knowledge-graph snapshots</span>
+  </a>
+  <a href="/_live/changes">
+    <strong>Data changes</strong>
+    <span>OT × CT change matrix</span>
+  </a>
+</nav>
+`;
+export function withMemorixLiveOpsNav(html) {
+    if (!html || html.includes(NAV_MARK))
+        return html;
+    if (html.includes("</header>")) {
+        return html.replace("</header>", `</header>\n${NAV_HTML}`);
+    }
+    return html;
+}
+//# sourceMappingURL=live-ops-nav.js.map

package/dist/live-ops-nav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-ops-nav.js","sourceRoot":"","sources":["../src/live-ops-nav.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,QAAQ,GAAG,sBAAsB,CAAC;AAExC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsChB,CAAC;AAEF,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,cAAc,QAAQ,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/live.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../src/live.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AA4BnC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,KAAK,oBAAoB,GAAG,CAC1B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,iBAAiB,KACxB,OAAO,CAAC,IAAI,CAAC,CAAC;AAKnB,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,GACpC,IAAI,CAEN;AAwBD,eAAO,MAAM,eAAe;;;;UApDb,CAAC;;;UAGiB,CAAC;;iEAChB,CAAC;;;;;;CAgD+B,CAAC;AAEnD,mEAAmE;AACnE,eAAO,MAAM,eAAe,cAE1B,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,cAE9B,CAAC;AAuQH,iGAAiG;AACjG,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACpC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BzB;AAslBD,iFAAiF;AACjF,eAAO,MAAM,kBAAkB;;wBAEH,oBAAoB,KAAG,OAAO,CAAC,mBAAmB,CAAC;CAsC9E,CAAC"}
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../src/live.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AA4BnC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,KAAK,oBAAoB,GAAG,CAC1B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,iBAAiB,KACxB,OAAO,CAAC,IAAI,CAAC,CAAC;AAKnB,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,GACpC,IAAI,CAEN;AAwBD,eAAO,MAAM,eAAe;;;;UA5C5B,CADA;;;UAKc,CAAC;;iEAKP,CAAC;;;;;;CAmCyC,CAAC;AAEnD,mEAAmE;AACnE,eAAO,MAAM,eAAe,cAE1B,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,cAE9B,CAAC;AAuQH,iGAAiG;AACjG,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACpC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BzB;AAslBD,iFAAiF;AACjF,eAAO,MAAM,kBAAkB;;wBAEH,oBAAoB,KAAG,OAAO,CAAC,mBAAmB,CAAC;CAsC9E,CAAC"}

package/dist/mcp/nexum-tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Read-only memorix-nexum MCP tools: knowledge-graph subjects + canvas proxy.
+ */
+import type { MemorixPlatform } from "../platform.js";
+import type { MemorixScope } from "../scope.js";
+export declare const NEXUM_MCP_TOOL_NAMES: readonly ["nexum_list_snapshots", "nexum_get_snapshot", "nexum_knowledge_status", "nexum_list_entities", "nexum_get_entity", "nexum_query"];
+export type NexumMcpToolName = (typeof NEXUM_MCP_TOOL_NAMES)[number];
+type JsonSchema = Record<string, unknown>;
+type ToolDef = {
+    name: NexumMcpToolName;
+    description: string;
+    inputSchema: JsonSchema;
+};
+export declare const NEXUM_MCP_TOOLS: ToolDef[];
+export declare function callNexumMcpTool(opts: {
+    platform: MemorixPlatform;
+    scope: MemorixScope;
+    name: string;
+    args: unknown;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export {};
+//# sourceMappingURL=nexum-tools.d.ts.map

package/dist/mcp/nexum-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexum-tools.d.ts","sourceRoot":"","sources":["../../src/mcp/nexum-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAShD,eAAO,MAAM,oBAAoB,6IAOvB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C,KAAK,OAAO,GAAG;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;CACzB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,OAAO,EA0EpC,CAAC;AAuDF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC;IACV,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC,CA6ID"}

package/dist/mcp/nexum-tools.js

@@ -0,0 +1,257 @@
+import { ServiceError } from "../errors.js";
+import { knowledgeUpstreamUrl, proxyJson, throwIfKnowledgeUpstreamError, } from "../knowledge-upstream.js";
+import { recordLooksLikeKnowledgeGraph } from "../activity-ring.js";
+export const NEXUM_MCP_TOOL_NAMES = [
+    "nexum_list_snapshots",
+    "nexum_get_snapshot",
+    "nexum_knowledge_status",
+    "nexum_list_entities",
+    "nexum_get_entity",
+    "nexum_query",
+];
+export const NEXUM_MCP_TOOLS = [
+    {
+        name: "nexum_list_snapshots",
+        description: "List Memorix knowledge-graph snapshot subjects (objectType=content, contentType=snapshots). Optional filter to data.kind=knowledge-graph.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Max records (default 50, max 200)" },
+                cursor: { type: "string" },
+                knowledgeGraphOnly: {
+                    type: "boolean",
+                    description: "When true, keep only records with data.kind=knowledge-graph",
+                },
+            },
+        },
+    },
+    {
+        name: "nexum_get_snapshot",
+        description: "Get one Memorix content/snapshots subject by recordId (knowledge-graph snapshot when indexed).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                recordId: { type: "string" },
+            },
+            required: ["recordId"],
+        },
+    },
+    {
+        name: "nexum_knowledge_status",
+        description: "Probe Nexum explore REST (canvas Mongo store) health. Separate from Memorix subjects.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "nexum_list_entities",
+        description: "List or search canvas graph entities via Nexum explore REST (graphified-* Mongo).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                graphId: { type: "string" },
+                q: { type: "string", description: "Search query; omit for visualization slice" },
+                limit: { type: "string" },
+            },
+        },
+    },
+    {
+        name: "nexum_get_entity",
+        description: "Get one canvas entity/node by id from Nexum explore REST.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entityId: { type: "string" },
+                graphId: { type: "string" },
+            },
+            required: ["entityId"],
+        },
+    },
+    {
+        name: "nexum_query",
+        description: "Neighbor query on the canvas graph (Nexum explore REST). Requires nodeId seed.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nodeId: { type: "string" },
+                graphId: { type: "string" },
+                depth: { type: "number" },
+            },
+            required: ["nodeId"],
+        },
+    },
+];
+function asRecord(args) {
+    return args && typeof args === "object" && !Array.isArray(args)
+        ? args
+        : {};
+}
+function textResult(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof payload === "string"
+                    ? payload
+                    : JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+}
+function errorResult(err) {
+    if (err instanceof ServiceError) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ code: err.code, message: err.message, details: err.details }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: err instanceof Error ? err.message : String(err),
+            },
+        ],
+        isError: true,
+    };
+}
+export async function callNexumMcpTool(opts) {
+    const { platform, scope, name } = opts;
+    const args = asRecord(opts.args);
+    try {
+        switch (name) {
+            case "nexum_list_snapshots": {
+                const ports = platform.portsFor(scope);
+                const limit = Math.min(Number(args.limit ?? 50) || 50, 200);
+                const listed = await ports.reader.listContent(scope, {
+                    objectType: "content",
+                    contentType: "snapshots",
+                    limit,
+                    cursor: typeof args.cursor === "string" ? args.cursor : undefined,
+                });
+                let items = listed.items ?? [];
+                if (args.knowledgeGraphOnly === true) {
+                    items = items.filter((r) => recordLooksLikeKnowledgeGraph(r));
+                }
+                return textResult({
+                    scope,
+                    addressing: {
+                        objectType: "content",
+                        contentType: "snapshots",
+                    },
+                    records: items,
+                    pageInfo: { nextCursor: listed.nextCursor ?? null },
+                });
+            }
+            case "nexum_get_snapshot": {
+                const recordId = String(args.recordId ?? "").trim();
+                if (!recordId) {
+                    throw new ServiceError("VALIDATION", "recordId required", 400);
+                }
+                const ports = platform.portsFor(scope);
+                const record = await ports.reader.getContent(scope, {
+                    objectType: "content",
+                    contentType: "snapshots",
+                    recordId,
+                });
+                return textResult({
+                    scope,
+                    addressing: {
+                        objectType: "content",
+                        contentType: "snapshots",
+                        recordId,
+                    },
+                    record,
+                    knowledgeGraph: recordLooksLikeKnowledgeGraph(record),
+                });
+            }
+            case "nexum_knowledge_status": {
+                const baseUrl = knowledgeUpstreamUrl();
+                let upstream = {
+                    ok: false,
+                };
+                try {
+                    const health = await proxyJson("GET", `${baseUrl}/health`);
+                    upstream = {
+                        ok: health.status >= 200 && health.status < 300,
+                        status: health.status,
+                    };
+                }
+                catch (err) {
+                    upstream = {
+                        ok: false,
+                        error: err instanceof Error ? err.message : String(err),
+                    };
+                }
+                return textResult({
+                    scope,
+                    upstreamOk: upstream.ok,
+                    upstream,
+                    exploreBaseUrl: baseUrl,
+                    note: "Canvas store (Nexum explore REST). Subjects use nexum_list_snapshots / nexum_get_snapshot.",
+                });
+            }
+            case "nexum_list_entities": {
+                const graphId = String(args.graphId ?? "default").trim() || "default";
+                const q = typeof args.q === "string" ? args.q.trim() : "";
+                const limit = String(args.limit ?? (q ? "50" : "500"));
+                const baseUrl = knowledgeUpstreamUrl();
+                const path = q
+                    ? `/v1/orgs/${encodeURIComponent(scope.orgId)}/graphs/${encodeURIComponent(graphId)}/search?q=${encodeURIComponent(q)}&limit=${encodeURIComponent(limit)}`
+                    : `/v1/orgs/${encodeURIComponent(scope.orgId)}/graphs/${encodeURIComponent(graphId)}/visualization?maximumNodes=${encodeURIComponent(limit)}`;
+                const upstream = await proxyJson("GET", `${baseUrl}${path}`);
+                throwIfKnowledgeUpstreamError(upstream);
+                return textResult({
+                    scope,
+                    graphId,
+                    result: upstream.body,
+                });
+            }
+            case "nexum_get_entity": {
+                const entityId = String(args.entityId ?? "").trim();
+                if (!entityId) {
+                    throw new ServiceError("VALIDATION", "entityId required", 400);
+                }
+                const graphId = String(args.graphId ?? "default").trim() || "default";
+                const baseUrl = knowledgeUpstreamUrl();
+                const path = `/v1/orgs/${encodeURIComponent(scope.orgId)}/graphs/${encodeURIComponent(graphId)}/nodes/${encodeURIComponent(entityId)}`;
+                const upstream = await proxyJson("GET", `${baseUrl}${path}`);
+                throwIfKnowledgeUpstreamError(upstream);
+                return textResult({
+                    scope,
+                    graphId,
+                    entityId,
+                    result: upstream.body,
+                });
+            }
+            case "nexum_query": {
+                const nodeId = String(args.nodeId ?? "").trim();
+                if (!nodeId) {
+                    throw new ServiceError("VALIDATION", "nodeId required", 400);
+                }
+                const graphId = String(args.graphId ?? "default").trim() || "default";
+                const depth = Number(args.depth ?? 1);
+                const baseUrl = knowledgeUpstreamUrl();
+                const path = `/v1/orgs/${encodeURIComponent(scope.orgId)}/graphs/${encodeURIComponent(graphId)}/nodes/${encodeURIComponent(nodeId)}/neighbors?depth=${encodeURIComponent(String(depth))}`;
+                const upstream = await proxyJson("GET", `${baseUrl}${path}`);
+                throwIfKnowledgeUpstreamError(upstream);
+                return textResult({
+                    scope,
+                    graphId,
+                    seed: nodeId,
+                    depth,
+                    result: upstream.body,
+                });
+            }
+            default:
+                throw new ServiceError("VALIDATION", `Unknown tool: ${name}`, 400);
+        }
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+//# sourceMappingURL=nexum-tools.js.map

package/dist/mcp/nexum-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexum-tools.js","sourceRoot":"","sources":["../../src/mcp/nexum-tools.ts"],"names":[],"mappings":"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"}

package/dist/mcp/service-public-url.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Absolute base URL for agent-facing links (MCP copy snippets, OpenAPI).
+ * Prefer public advertise URL, then MEMORIX_SERVICE_URL; never advertise 0.0.0.0.
+ */
+export declare function memorixServicePublicUrl(env?: NodeJS.ProcessEnv): string;
+export declare function nexumMcpPublicUrl(env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=service-public-url.d.ts.map

package/dist/mcp/service-public-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-public-url.d.ts","sourceRoot":"","sources":["../../src/mcp/service-public-url.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAWR;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAER"}

package/dist/mcp/service-public-url.js

@@ -0,0 +1,19 @@
+/**
+ * Absolute base URL for agent-facing links (MCP copy snippets, OpenAPI).
+ * Prefer public advertise URL, then MEMORIX_SERVICE_URL; never advertise 0.0.0.0.
+ */
+export function memorixServicePublicUrl(env = process.env) {
+    const fromEnv = env.MEMORIX_PUBLIC_URL?.trim() ||
+        env.MEMORIX_SERVICE_PUBLIC_URL?.trim() ||
+        env.MEMORIX_SERVICE_URL?.trim();
+    if (fromEnv)
+        return fromEnv.replace(/\/+$/, "");
+    const port = Number(env.MEMORIX_SERVICE_PORT ?? 5100);
+    const rawHost = env.MEMORIX_SERVICE_HOST?.trim() || "127.0.0.1";
+    const host = rawHost === "0.0.0.0" || rawHost === "::" ? "127.0.0.1" : rawHost;
+    return `http://${host}:${Number.isFinite(port) ? port : 5100}`;
+}
+export function nexumMcpPublicUrl(env = process.env) {
+    return `${memorixServicePublicUrl(env)}/mcp/nexum`;
+}
+//# sourceMappingURL=service-public-url.js.map

package/dist/mcp/service-public-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-public-url.js","sourceRoot":"","sources":["../../src/mcp/service-public-url.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,OAAO,GACX,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE;QAC9B,GAAG,CAAC,0BAA0B,EAAE,IAAI,EAAE;QACtC,GAAG,CAAC,mBAAmB,EAAE,IAAI,EAAE,CAAC;IAClC,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,oBAAoB,IAAI,IAAI,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,GAAG,CAAC,oBAAoB,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC;IAChE,MAAM,IAAI,GACR,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC;IACpE,OAAO,UAAU,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,GAAG,uBAAuB,CAAC,GAAG,CAAC,YAAY,CAAC;AACrD,CAAC"}