recallx 1.0.0

package/app/cli/src/format.js

@@ -0,0 +1,242 @@
+function pad(label, value) {
+  return `${label}: ${value ?? ""}`;
+}
+
+export function renderJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+export function renderText(value) {
+  if (value == null) {
+    return "";
+  }
+
+  if (typeof value === "string") {
+    return `${value}\n`;
+  }
+
+  if (Array.isArray(value)) {
+    return `${value.map((item) => `- ${renderInline(item)}`).join("\n")}\n`;
+  }
+
+  if (typeof value === "object") {
+    return `${Object.entries(value)
+      .map(([key, entry]) => `${key}: ${renderInline(entry)}`)
+      .join("\n")}\n`;
+  }
+
+  return `${String(value)}\n`;
+}
+
+export function renderNode(node) {
+  const lines = [
+    `${node.title || node.id}`,
+    pad("id", node.id),
+    pad("type", node.type),
+    pad("status", node.status),
+    pad("canonicality", node.canonicality),
+    pad("summary", node.summary),
+    pad("source", node.sourceLabel || node.source_label || ""),
+  ];
+
+  if (Array.isArray(node.tags) && node.tags.length > 0) {
+    lines.push(pad("tags", node.tags.join(", ")));
+  }
+
+  if (node.body) {
+    lines.push("");
+    lines.push(node.body);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderSearchResults(data) {
+  const items = data?.items || [];
+  if (!items.length) {
+    return "No results.\n";
+  }
+
+  return `${items
+    .map((item, index) => {
+      const summary = item.summary ? `\n  ${item.summary}` : "";
+      return `${index + 1}. ${item.title || item.id} (${item.type || "node"})\n  id: ${item.id}\n  status: ${item.status || ""}${summary}`;
+    })
+    .join("\n\n")}\n`;
+}
+
+export function renderActivitySearchResults(data) {
+  const items = data?.items || [];
+  if (!items.length) {
+    return "No activity results.\n";
+  }
+
+  return `${items
+    .map((item, index) => {
+      const headline = item.targetNodeTitle || item.targetNodeId;
+      const body = item.body ? `\n  ${item.body}` : "";
+      return `${index + 1}. ${headline} (${item.activityType})\n  id: ${item.id}\n  target: ${item.targetNodeId}\n  created: ${item.createdAt}${body}`;
+    })
+    .join("\n\n")}\n`;
+}
+
+export function renderWorkspaceSearchResults(data) {
+  const items = data?.items || [];
+  if (!items.length) {
+    return "No workspace results.\n";
+  }
+
+  return `${items
+    .map((item, index) => {
+      if (item.resultType === "activity" && item.activity) {
+        const headline = item.activity.targetNodeTitle || item.activity.targetNodeId;
+        const body = item.activity.body ? `\n  ${item.activity.body}` : "";
+        return `${index + 1}. [activity] ${headline} (${item.activity.activityType})\n  id: ${item.activity.id}\n  target: ${item.activity.targetNodeId}\n  created: ${item.activity.createdAt}${body}`;
+      }
+
+      const node = item.node || {};
+      const summary = node.summary ? `\n  ${node.summary}` : "";
+      return `${index + 1}. [node] ${node.title || node.id} (${node.type || "node"})\n  id: ${node.id}\n  status: ${node.status || ""}${summary}`;
+    })
+    .join("\n\n")}\n`;
+}
+
+export function renderRelated(data) {
+  const items = data?.items || data?.related || [];
+  if (!items.length) {
+    return "No related nodes.\n";
+  }
+
+  return `${items
+    .map((item, index) => {
+      const node = item?.node || item;
+      const relation = item?.relation || item;
+      return `${index + 1}. ${node?.title || node?.nodeId || node?.id} (${relation?.relationType || node?.type || ""})`;
+    })
+    .join("\n")}\n`;
+}
+
+export function renderGovernanceIssues(data) {
+  const items = data?.items || [];
+  if (!items.length) {
+    return "No governance issues.\n";
+  }
+
+  return `${items
+    .map(
+      (item, index) =>
+        `${index + 1}. ${item.title || item.entityId}\n  entity: ${item.entityType || ""}:${item.entityId || ""}\n  state: ${item.state || ""}\n  confidence: ${item.confidence ?? ""}\n  reasons: ${Array.isArray(item.reasons) ? item.reasons.join(", ") : ""}`,
+    )
+    .join("\n\n")}\n`;
+}
+
+export function renderWorkspaces(data) {
+  const items = data?.items || [];
+  if (!items.length) {
+    return "No workspaces.\n";
+  }
+
+  return `${items
+    .map((item, index) => {
+      const marker = item.isCurrent ? "*" : " ";
+      return `${index + 1}. ${marker} ${item.workspaceName}\n  root: ${item.rootPath}\n  auth: ${item.authMode || ""}`;
+    })
+    .join("\n\n")}\n`;
+}
+
+export function renderBundleMarkdown(bundle) {
+  const lines = [];
+  lines.push(`# ${bundle.target?.title || bundle.target?.id || "Context bundle"}`);
+  lines.push("");
+  lines.push(`- mode: ${bundle.mode || ""}`);
+  lines.push(`- preset: ${bundle.preset || ""}`);
+  if (bundle.summary) {
+    lines.push("");
+    lines.push(bundle.summary);
+  }
+  if (Array.isArray(bundle.items) && bundle.items.length > 0) {
+    lines.push("");
+    lines.push("## Items");
+    for (const item of bundle.items) {
+      lines.push(`- ${item.title || item.nodeId || item.id}${item.summary ? `: ${item.summary}` : ""}`);
+    }
+  }
+  if (Array.isArray(bundle.sources) && bundle.sources.length > 0) {
+    lines.push("");
+    lines.push("## Sources");
+    for (const source of bundle.sources) {
+      lines.push(`- ${source.nodeId || source.id}${source.sourceLabel ? ` (${source.sourceLabel})` : ""}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderTelemetrySummary(data) {
+  const lines = [
+    `since: ${data?.since || ""}`,
+    `logs: ${data?.logsPath || ""}`,
+    `events: ${data?.totalEvents ?? 0}`,
+  ];
+
+  const slow = Array.isArray(data?.slowOperations) ? data.slowOperations : [];
+  if (slow.length > 0) {
+    lines.push("");
+    lines.push("Slow operations:");
+    for (const item of slow.slice(0, 5)) {
+      lines.push(`- [${item.surface}] ${item.operation} p95=${item.p95DurationMs ?? ""}ms errors=${item.errorCount}/${item.count}`);
+    }
+  }
+
+  const mcpFailures = Array.isArray(data?.mcpToolFailures) ? data.mcpToolFailures : [];
+  if (mcpFailures.length > 0) {
+    lines.push("");
+    lines.push("MCP failures:");
+    for (const item of mcpFailures.slice(0, 5)) {
+      lines.push(`- ${item.operation}: ${item.count}`);
+    }
+  }
+
+  if (data?.ftsFallbackRate) {
+    lines.push("");
+    lines.push(
+      `fts fallback: ${data.ftsFallbackRate.fallbackCount}/${data.ftsFallbackRate.sampleCount} (${data.ftsFallbackRate.ratio ?? "n/a"})`
+    );
+  }
+  if (data?.semanticAugmentationRate) {
+    lines.push(
+      `semantic augmentation: ${data.semanticAugmentationRate.usedCount}/${data.semanticAugmentationRate.sampleCount} (${data.semanticAugmentationRate.ratio ?? "n/a"})`
+    );
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderTelemetryErrors(data) {
+  const items = data?.items || [];
+  if (!items.length) {
+    return "No telemetry errors.\n";
+  }
+
+  return `${items
+    .map(
+      (item, index) =>
+        `${index + 1}. [${item.surface}] ${item.operation}\n  ts: ${item.ts}\n  trace: ${item.traceId}\n  error: ${item.errorKind || ""}/${item.errorCode || ""}\n  status: ${item.statusCode ?? ""}\n  durationMs: ${item.durationMs ?? ""}`
+    )
+    .join("\n\n")}\n`;
+}
+
+function renderInline(value) {
+  if (value == null) {
+    return "";
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(renderInline).join(", ");
+  }
+
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+
+  return String(value);
+}

package/app/cli/src/http.js

@@ -0,0 +1,35 @@
+import { buildApiRequestInit, buildApiUrl, parseApiJsonBody } from "../../shared/request-runtime.js";
+const DEFAULT_API_BASE = "http://127.0.0.1:8787/api/v1";
+export function getApiBase(argvOptions = {}, env = process.env) {
+    return (argvOptions.api ||
+        env.RECALLX_API_URL ||
+        DEFAULT_API_BASE);
+}
+export function getAuthToken(argvOptions = {}, env = process.env) {
+    return argvOptions.token || env.RECALLX_TOKEN || "";
+}
+export async function requestJson(apiBase, path, { method = "GET", token, body } = {}) {
+    const response = await fetch(buildApiUrl(apiBase, path), buildApiRequestInit({ method, token, body }));
+    let payload = null;
+    let parseError = null;
+    try {
+        payload = await parseApiJsonBody(response);
+    }
+    catch (error) {
+        parseError = error;
+    }
+    if (!response.ok) {
+        const error = payload?.error;
+        const code = error?.code || `HTTP_${response.status}`;
+        const message = error?.message || response.statusText || "Request failed";
+        throw new Error(`${code}: ${message}`);
+    }
+    if (parseError) {
+        throw new Error("INVALID_RESPONSE: RecallX API returned non-JSON output.");
+    }
+    if (payload && payload.ok === false) {
+        const error = payload.error || {};
+        throw new Error(`${error.code || "INTERNAL_ERROR"}: ${error.message || "Request failed"}`);
+    }
+    return payload ?? {};
+}

package/app/mcp/api-client.js

@@ -0,0 +1,101 @@
+import { buildApiRequestInit, buildApiUrl, parseApiJsonBody } from "../shared/request-runtime.js";
+import { currentTelemetryContext } from "../server/observability.js";
+export class RecallXApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(message, options) {
+        super(message);
+        this.name = "RecallXApiError";
+        this.status = options?.status ?? 500;
+        this.code = options?.code ?? "RECALLX_API_ERROR";
+        this.details = options?.details;
+    }
+}
+function isApiErrorEnvelope(payload) {
+    return Boolean(payload &&
+        typeof payload === "object" &&
+        "ok" in payload &&
+        payload.ok === false &&
+        "error" in payload &&
+        payload.error &&
+        typeof payload.error === "object");
+}
+export class RecallXApiClient {
+    baseUrl;
+    apiToken;
+    constructor(baseUrl, apiToken) {
+        this.baseUrl = baseUrl;
+        this.apiToken = apiToken ?? null;
+    }
+    async get(path) {
+        return this.request("GET", path);
+    }
+    async post(path, body) {
+        return this.request("POST", path, body);
+    }
+    async patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    async request(method, path, body) {
+        const headers = new Headers();
+        const telemetryContext = currentTelemetryContext();
+        if (telemetryContext?.traceId) {
+            headers.set("x-recallx-trace-id", telemetryContext.traceId);
+        }
+        if (telemetryContext?.toolName) {
+            headers.set("x-recallx-mcp-tool", telemetryContext.toolName);
+        }
+        let response;
+        try {
+            response = await fetch(buildApiUrl(this.baseUrl, path), buildApiRequestInit({
+                method,
+                token: this.apiToken,
+                body,
+                headers
+            }));
+        }
+        catch (error) {
+            throw new RecallXApiError("Failed to reach the local RecallX API.", {
+                status: 503,
+                code: "NETWORK_ERROR",
+                details: error
+            });
+        }
+        let payload;
+        try {
+            payload = await parseApiJsonBody(response);
+        }
+        catch (error) {
+            throw new RecallXApiError("RecallX API returned non-JSON output.", {
+                status: response.status,
+                code: "INVALID_RESPONSE",
+                details: error
+            });
+        }
+        if (!payload || typeof payload !== "object") {
+            throw new RecallXApiError("RecallX API returned an empty response.", {
+                status: response.status,
+                code: "EMPTY_RESPONSE"
+            });
+        }
+        if ("ok" in payload && payload.ok === true) {
+            return payload.data;
+        }
+        if (isApiErrorEnvelope(payload)) {
+            throw new RecallXApiError(payload.error.message, {
+                status: response.status,
+                code: payload.error.code,
+                details: payload.error.details
+            });
+        }
+        if (!response.ok) {
+            throw new RecallXApiError(`RecallX API request failed with status ${response.status}.`, {
+                status: response.status,
+                code: "HTTP_ERROR",
+                details: payload
+            });
+        }
+        return payload;
+    }
+}

package/app/mcp/index.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { RecallXApiClient } from "./api-client.js";
+import { createRecallXMcpServer } from "./server.js";
+import { RECALLX_VERSION } from "../shared/version.js";
+function createApiClient() {
+    return new RecallXApiClient(process.env.RECALLX_API_URL ?? "http://127.0.0.1:8787/api/v1", process.env.RECALLX_API_TOKEN);
+}
+function createObservabilityStateReader() {
+    let cachedState = null;
+    let cachedAt = 0;
+    let inFlight = null;
+    const cacheTtlMs = 5_000;
+    return async function readObservabilityState() {
+        const now = Date.now();
+        if (cachedState && now - cachedAt < cacheTtlMs) {
+            return cachedState;
+        }
+        if (inFlight) {
+            return inFlight;
+        }
+        inFlight = resolveObservabilityState()
+            .then((state) => {
+            cachedState = state;
+            cachedAt = Date.now();
+            return state;
+        })
+            .finally(() => {
+            inFlight = null;
+        });
+        return inFlight;
+    };
+}
+async function resolveObservabilityState() {
+    try {
+        const client = createApiClient();
+        const [workspacePayload, settingsPayload] = await Promise.all([
+            client.get("/workspace"),
+            client.get("/settings?keys=observability.enabled,observability.retentionDays,observability.slowRequestMs,observability.capturePayloadShape")
+        ]);
+        const workspace = workspacePayload ?? {};
+        const values = (settingsPayload.values ?? {});
+        return {
+            enabled: values["observability.enabled"] === true,
+            workspaceRoot: typeof workspace.rootPath === "string" ? workspace.rootPath : process.cwd(),
+            workspaceName: typeof workspace.workspaceName === "string" ? workspace.workspaceName : "RecallX MCP",
+            retentionDays: typeof values["observability.retentionDays"] === "number" ? values["observability.retentionDays"] : 14,
+            slowRequestMs: typeof values["observability.slowRequestMs"] === "number" ? values["observability.slowRequestMs"] : 250,
+            capturePayloadShape: values["observability.capturePayloadShape"] !== false
+        };
+    }
+    catch {
+        return {
+            enabled: false,
+            workspaceRoot: process.cwd(),
+            workspaceName: "RecallX MCP",
+            retentionDays: 14,
+            slowRequestMs: 250,
+            capturePayloadShape: true
+        };
+    }
+}
+function printHelp() {
+    console.error(`RecallX MCP server
+
+Usage:
+  npm run mcp
+  npm run dev:mcp
+  node dist/server/app/mcp/index.js --api http://127.0.0.1:8787/api/v1
+  recallx-mcp --api http://127.0.0.1:8787/api/v1
+
+Environment:
+  RECALLX_API_URL             Local RecallX API base URL (default: http://127.0.0.1:8787/api/v1)
+  RECALLX_API_TOKEN           Optional bearer token for auth-enabled RecallX instances
+  RECALLX_MCP_SOURCE_LABEL    Default provenance label for writes (default: RecallX MCP)
+  RECALLX_MCP_TOOL_NAME       Default provenance tool name (default: recallx-mcp)
+`);
+}
+function parseArgs(argv) {
+    const options = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith("--")) {
+            continue;
+        }
+        const key = arg.slice(2);
+        const next = argv[index + 1];
+        if (!next || next.startsWith("--")) {
+            options[key] = true;
+            continue;
+        }
+        options[key] = next;
+        index += 1;
+    }
+    return options;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        printHelp();
+        return;
+    }
+    if (typeof args.api === "string") {
+        process.env.RECALLX_API_URL = args.api;
+    }
+    if (typeof args.token === "string") {
+        process.env.RECALLX_API_TOKEN = args.token;
+    }
+    if (typeof args["source-label"] === "string") {
+        process.env.RECALLX_MCP_SOURCE_LABEL = args["source-label"];
+    }
+    if (typeof args["tool-name"] === "string") {
+        process.env.RECALLX_MCP_TOOL_NAME = args["tool-name"];
+    }
+    const readObservabilityState = createObservabilityStateReader();
+    const server = createRecallXMcpServer({
+        serverVersion: RECALLX_VERSION,
+        observabilityState: await readObservabilityState(),
+        getObservabilityState: readObservabilityState
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`RecallX MCP connected over stdio -> ${process.env.RECALLX_API_URL ?? "http://127.0.0.1:8787/api/v1"}`);
+}
+main().catch((error) => {
+    console.error("RecallX MCP failed to start:", error);
+    process.exit(1);
+});