@smartergpt/lex-mcp 2.9.1 → 3.0.0

package/README.md

@@ -2,7 +2,8 @@
 
 Thin MCP stdio wrapper for [@smartergpt/lex](https://github.com/Guffawaffle/lex) episodic memory.
 
-Lex owns all capabilities. This package owns delivery over [Model Context Protocol](https://modelcontextprotocol.io/).
+Lex owns all capabilities and authority decisions. This package owns delivery
+over [Model Context Protocol](https://modelcontextprotocol.io/).
 
 ## Release Contract
 
@@ -12,12 +13,51 @@ exact version, reports that version through MCP `serverInfo`, and supports the
 same Node range as Lex (`>=20 <25`). Publish the matching Lex release before
 publishing this wrapper.
 
-## Quick Start
+Prepublication CI applies the staged wrapper version only to its disposable Lex
+checkout, then builds, installs, and packs that local source. After Lex is
+published, refresh this repository's registry lock with
+`npm install --package-lock-only --ignore-scripts`, verify no `file:` dependency
+was introduced, commit the resulting integrity, and only then tag or publish
+Lex MCP. The release workflow enforces that post-publish integrity gate.
+
+## Local Compatibility Launch
 
 ```bash
 npx @smartergpt/lex-mcp
 ```
 
+The executable is the backwards-compatible, local single-workspace launch. It
+uses the current directory or `LEX_WORKSPACE_ROOT` for project discovery and
+delegates local store configuration to Lex. Those values configure the local
+process; they do not establish canonical authority, grants, or a tenant scope.
+
+## Trusted Lex 3 Host
+
+Multi-tenant and cross-workspace hosts compose authority explicitly with Lex,
+then pass Lex's MCP options through this package unchanged:
+
+```js
+import { startLexMcpStdio } from "@smartergpt/lex-mcp";
+import { createPostgresTrustedRuntimeHost } from "@smartergpt/lex/runtime-scope";
+
+const host = createPostgresTrustedRuntimeHost({
+  authorityPool, // read-only runtime authority connection
+  selection, // authenticated tenant/workspace selection owned by this host
+  frameStoreBinder, // scope-bound PostgreSQL frame store binder
+  process: capturedProcessEvidence,
+  runtimeId,
+  traceId,
+  emitDiagnostics,
+});
+
+const transport = startLexMcpStdio({ serverOptions: host.mcp });
+```
+
+The host must supply its pools, authenticated selection, process evidence, and
+IDs. Neither Lex nor this wrapper reconstructs trusted authority from
+environment variables. See Lex's runtime-scope documentation for the complete
+host composition and PostgreSQL RLS contracts.
+
 ## Configuration
 
 ### VS Code / Copilot
@@ -59,18 +99,37 @@ Add to `claude_desktop_config.json`:
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx @smartergpt/lex-mcp
 ```
 
-## Environment Variables
+## Compatibility-Launcher Environment Variables
 
-| Variable             | Description                                  | Default                     |
-| -------------------- | -------------------------------------------- | --------------------------- |
-| `LEX_WORKSPACE_ROOT` | Project root directory (compat env var name) | Current directory           |
-| `LEX_DB_PATH`        | SQLite database path (canonical)             | `.smartergpt/lex/memory.db` |
-| `LEX_MEMORY_DB`      | Alias for `LEX_DB_PATH` (compat only)        | —                           |
-| `LEX_DEBUG`          | Enable debug logging to stderr               | Off                         |
+| Variable                | Description                                       | Default                     |
+| ----------------------- | ------------------------------------------------- | --------------------------- |
+| `LEX_WORKSPACE_ROOT`    | Local project root                                | Current directory           |
+| `LEX_STORE`             | Compatibility frame backend (`sqlite`/`postgres`) | `sqlite`                    |
+| `LEX_DATABASE_URL`      | Compatibility PostgreSQL connection URL           | —                           |
+| `LEX_POSTGRES_PASSWORD` | Password for a credential-free compatibility URL  | —                           |
+| `LEX_POSTGRES_POOL_MAX` | Compatibility PostgreSQL pool size                | `10`                        |
+| `LEX_DB_PATH`           | SQLite database path; ignored by PostgreSQL       | `.smartergpt/lex/memory.db` |
+| `LEX_MEMORY_DB`         | Alias for `LEX_DB_PATH` (compat only)             | —                           |
+| `LEX_DEBUG`             | Enable debug logging to stderr                    | Off                         |
 
 When both `LEX_DB_PATH` and `LEX_MEMORY_DB` are set, `LEX_DB_PATH` wins.
 
-For multi-root workspaces, set the same absolute `LEX_DB_PATH` for direct Lex, this MCP wrapper, and AXF-routed Lex. The wrapper delegates `.lex.config.json`, environment, and default-store resolution to Lex core, so installed launches now honor caller-project config files. Use `system_introspect` to compare canonical store paths and `path-v1` identities across launch paths.
+For multi-root compatibility launches using SQLite, set the same absolute
+`LEX_DB_PATH` for direct Lex, this MCP wrapper, and AXF-routed Lex. The wrapper
+delegates `.lex.config.json`, environment, and local store resolution to Lex
+core, so installed launches honor caller-project config files. Shared trusted
+PostgreSQL deployments must instead inject canonical authority and a scoped
+store binder as shown above; environment configuration alone is never a trusted
+multi-tenant bootstrap.
+
+## Agent Output
+
+Agents can request `format: "compact"` on supported frame and introspection
+tools to avoid redundant presentation metadata. Runtime-scope diagnostics are
+absent by default and appear only when a caller explicitly requests
+`diagnostics: "summary"` or `"full"` and has the required authority. Output
+format and diagnostics affect presentation only; they never change scope or
+authorization outcomes.
 
 ## Tools
 

package/index.mjs

@@ -8,111 +8,51 @@
  * Usage:
  *   npx @smartergpt/lex-mcp
  *
- * Environment Variables:
- *   LEX_WORKSPACE_ROOT - Project root directory (compat env var name, default: cwd)
+ * Compatibility-launch environment variables:
+ *   LEX_WORKSPACE_ROOT - Project root directory (default: cwd)
  *   LEX_DB_PATH        - SQLite database path (default: .smartergpt/lex/memory.db)
  *   LEX_MEMORY_DB      - Alias for LEX_DB_PATH (for backwards compatibility)
  *   LEX_DEBUG          - Enable debug logging to stderr
  */
 
-import { MCPServer } from "@smartergpt/lex/mcp-server";
+import { startLexMcpStdio } from "./stdio.mjs";
 
 // Project root defaults to current working directory.
 const projectRoot = process.env.LEX_WORKSPACE_ROOT || process.cwd();
 
-// Set LEX_WORKSPACE_ROOT for modules that need it
-if (!process.env.LEX_WORKSPACE_ROOT) {
-  process.env.LEX_WORKSPACE_ROOT = projectRoot;
-}
-
-// Initialize MCP server
-let mcpServer;
+// This executable preserves the local, single-workspace compatibility launch.
+// Environment and cwd select local configuration; they never establish trusted
+// Lex 3 authority. Trusted hosts import startLexMcpStdio and inject host.mcp.
+let transport;
 try {
-  // Lex core owns env, .lex.config.json, and default-path precedence. Passing
-  // only the caller root prevents the delivery wrapper from masking config.
-  mcpServer = new MCPServer({ repoRoot: projectRoot });
+  transport = startLexMcpStdio({
+    serverOptions: { repoRoot: projectRoot },
+    debug: Boolean(process.env.LEX_DEBUG),
+  });
   if (process.env.LEX_DEBUG) {
     console.error(`[LEX-MCP] Project root: ${projectRoot}`);
+    console.error("[LEX-MCP] Ready (stdio compatibility mode)");
   }
 } catch (error) {
   console.error(`[LEX-MCP] Failed to initialize: ${error.message}`);
   process.exit(1);
 }
 
-if (process.env.LEX_DEBUG) {
-  console.error(`[LEX-MCP] Ready (stdio mode)`);
-}
-
-// MCP stdio protocol handler (JSON-RPC 2.0 over newline-delimited JSON)
-process.stdin.setEncoding("utf8");
-let buffer = "";
-
-process.stdin.on("data", async (chunk) => {
-  buffer += chunk;
-  const lines = buffer.split("\n");
-  buffer = lines.pop() || "";
-
-  for (const line of lines) {
-    if (!line.trim()) continue;
-
-    let request;
-    try {
-      request = JSON.parse(line);
-
-      // MCP notifications have no `id` — silently ignore them per spec
-      if (request.id === undefined || request.id === null) {
-        if (process.env.LEX_DEBUG) {
-          console.error(`[LEX-MCP] Notification: ${request.method}`);
-        }
-        continue;
-      }
-
-      const response = await mcpServer.handleRequest(request);
-
-      // MCP protocol response format
-      if (response.error) {
-        console.log(
-          JSON.stringify({
-            jsonrpc: "2.0",
-            id: request.id,
-            error: response.error,
-          }),
-        );
-      } else {
-        console.log(
-          JSON.stringify({
-            jsonrpc: "2.0",
-            id: request.id,
-            result: response,
-          }),
-        );
-      }
-    } catch (error) {
-      console.log(
-        JSON.stringify({
-          jsonrpc: "2.0",
-          id: request?.id || null,
-          error: {
-            message: error.message,
-            code: error.code || "PARSE_ERROR",
-          },
-        }),
-      );
-    }
-  }
-});
-
 // Graceful shutdown
-process.on("SIGINT", () => {
-  if (mcpServer) mcpServer.close();
-  process.exit(0);
-});
-
-process.on("SIGTERM", () => {
-  if (mcpServer) mcpServer.close();
-  process.exit(0);
-});
-
-if (process.env.LEX_DEBUG) {
-  console.error("[LEX-MCP] Ready (stdio mode)");
+let shuttingDown = false;
+async function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  try {
+    await transport?.close();
+    process.exit(0);
+  } catch (error) {
+    console.error(
+      `[LEX-MCP] Failed to shut down: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exit(1);
+  }
 }
+
+process.on("SIGINT", () => void shutdown());
+process.on("SIGTERM", () => void shutdown());

package/package.json

@@ -1,16 +1,32 @@
 {
   "name": "@smartergpt/lex-mcp",
-  "version": "2.9.1",
+  "version": "3.0.0",
   "description": "MCP server for Lex episodic memory - stdio transport wrapper",
   "mcpName": "dev.smartergpt/lex",
   "type": "module",
+  "main": "./stdio.mjs",
+  "types": "./stdio.d.ts",
+  "exports": {
+    ".": {
+      "types": "./stdio.d.ts",
+      "import": "./stdio.mjs"
+    },
+    "./stdio": {
+      "types": "./stdio.d.ts",
+      "import": "./stdio.mjs"
+    }
+  },
   "bin": "./index.mjs",
   "files": [
     "index.mjs",
+    "stdio.mjs",
+    "stdio.d.ts",
     "README.md"
   ],
   "scripts": {
-    "test": "node test-contract.mjs && node test-mcp-server.mjs --local --clean",
+    "test": "npm run test:types && node test-stdio.mjs && node test-contract.mjs && node test-mcp-server.mjs --local --clean",
+    "test:types": "tsc --noEmit --skipLibCheck --module NodeNext --moduleResolution NodeNext --target ES2022 stdio.d.ts test-types.mts",
+    "test:stdio": "node test-stdio.mjs",
     "test:contract": "node test-contract.mjs",
     "test:contract:verbose": "node test-contract.mjs --verbose",
     "test:mcp": "node test-mcp-server.mjs --local --clean",
@@ -22,7 +38,7 @@
     "link:local": "rm -rf node_modules/@smartergpt/lex && mkdir -p node_modules/@smartergpt && ln -s /srv/lex-mcp/lex node_modules/@smartergpt/lex"
   },
   "dependencies": {
-    "@smartergpt/lex": "2.9.1"
+    "@smartergpt/lex": "3.0.0"
   },
   "publishConfig": {
     "access": "public",

package/stdio.d.ts

@@ -0,0 +1,27 @@
+import type { Readable, Writable } from "node:stream";
+import type { MCPServer, MCPServerOptions } from "@smartergpt/lex/mcp-server";
+
+export type LexMcpRequestServer = Pick<MCPServer, "handleRequest" | "close">;
+
+export interface LexMcpStdioOptions {
+  /** Explicit Lex configuration, including a trusted host's unmodified `host.mcp`. */
+  serverOptions: MCPServerOptions;
+  input?: Readable;
+  output?: Writable;
+  errorOutput?: Writable;
+  debug?: boolean;
+  /** Optional embedding/test seam. Receives `serverOptions` by identity. */
+  serverFactory?: (serverOptions: MCPServerOptions) => LexMcpRequestServer;
+}
+
+export interface LexMcpStdioTransport {
+  readonly server: LexMcpRequestServer;
+  /** Resolve once received records are handled; after EOF, includes server close. */
+  idle(): Promise<void>;
+  /** Stop input, flush a trailing record, drain requests, and close Lex once. */
+  close(): Promise<void>;
+}
+
+export function startLexMcpStdio(
+  options: LexMcpStdioOptions,
+): LexMcpStdioTransport;

package/stdio.mjs

@@ -0,0 +1,253 @@
+/**
+ * Newline-delimited JSON-RPC transport for Lex's MCP server.
+ *
+ * This module deliberately owns transport only. Canonical authority, workspace
+ * selection, and scope-bound stores must be composed by the trusted host and
+ * passed through `serverOptions`; they are never reconstructed from ambient
+ * process state here.
+ */
+
+import { MCPServer } from "@smartergpt/lex/mcp-server";
+
+/** @typedef {import("@smartergpt/lex/mcp-server").MCPServerOptions} MCPServerOptions */
+
+const JSON_RPC_PARSE_ERROR = -32700;
+const JSON_RPC_INVALID_REQUEST = -32600;
+const JSON_RPC_APPLICATION_ERROR = -32000;
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function applicationError(error) {
+  const record = isRecord(error) ? error : {};
+  const sourceCode = record.code;
+  const code = Number.isInteger(sourceCode)
+    ? sourceCode
+    : JSON_RPC_APPLICATION_ERROR;
+  const message =
+    typeof record.message === "string" ? record.message : errorMessage(error);
+
+  const data = isRecord(record.data)
+    ? { ...record.data }
+    : record.data === undefined
+      ? {}
+      : { details: record.data };
+  if (typeof sourceCode === "string") {
+    data.lexCode = sourceCode;
+  }
+  for (const field of ["context", "nextActions", "metadata"]) {
+    if (record[field] !== undefined) data[field] = record[field];
+  }
+
+  return {
+    code,
+    message,
+    ...(Object.keys(data).length === 0 ? {} : { data }),
+  };
+}
+
+function isValidRequestEnvelope(request) {
+  return (
+    isRecord(request) &&
+    request.jsonrpc === "2.0" &&
+    typeof request.method === "string" &&
+    request.method.length > 0
+  );
+}
+
+function isValidRequestId(id) {
+  return (
+    typeof id === "string" || (typeof id === "number" && Number.isFinite(id))
+  );
+}
+
+/**
+ * Start a Lex MCP server on newline-delimited JSON stdio.
+ *
+ * Trusted Lex 3 hosts pass the unmodified `host.mcp` object returned by
+ * `createPostgresTrustedRuntimeHost`. The optional `serverFactory` is intended
+ * for embedding and transport tests; it receives the same options object by
+ * identity.
+ *
+ * @param {object} options
+ * @param {MCPServerOptions} options.serverOptions
+ * @param {NodeJS.ReadableStream} [options.input]
+ * @param {NodeJS.WritableStream} [options.output]
+ * @param {NodeJS.WritableStream} [options.errorOutput]
+ * @param {boolean} [options.debug]
+ * @param {(serverOptions: MCPServerOptions) => Pick<MCPServer, "handleRequest" | "close">} [options.serverFactory]
+ */
+export function startLexMcpStdio({
+  serverOptions,
+  input = process.stdin,
+  output = process.stdout,
+  errorOutput = process.stderr,
+  debug = false,
+  serverFactory = (options) => new MCPServer(options),
+}) {
+  if (!serverOptions || typeof serverOptions !== "object") {
+    throw new TypeError(
+      "serverOptions must be an explicit MCPServerOptions object",
+    );
+  }
+
+  const mcpServer = serverFactory(serverOptions);
+  if (
+    !mcpServer ||
+    typeof mcpServer.handleRequest !== "function" ||
+    typeof mcpServer.close !== "function"
+  ) {
+    throw new TypeError(
+      "serverFactory must return an MCPServer-compatible server",
+    );
+  }
+
+  input.setEncoding?.("utf8");
+  let buffer = "";
+  let work = Promise.resolve();
+  let closePromise;
+
+  const writeResponse = (response) => {
+    output.write(`${JSON.stringify(response)}\n`);
+  };
+
+  const handleLine = async (line) => {
+    if (!line.trim()) return;
+
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      writeResponse({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: JSON_RPC_PARSE_ERROR, message: "Parse error" },
+      });
+      return;
+    }
+
+    if (!isValidRequestEnvelope(request)) {
+      writeResponse({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: JSON_RPC_INVALID_REQUEST, message: "Invalid Request" },
+      });
+      return;
+    }
+
+    // Only an absent id denotes a notification. JSON-RPC permits clients to
+    // send null, but Lex 3 treats it as invalid so request/response ownership
+    // remains unambiguous.
+    if (!Object.hasOwn(request, "id")) {
+      if (debug) {
+        errorOutput.write(`[LEX-MCP] Notification: ${request.method}\n`);
+      }
+      try {
+        // Notifications participate in the same serialized dispatch stream as
+        // requests, but JSON-RPC forbids returning either a result or an error
+        // response for them.
+        await mcpServer.handleRequest(request);
+      } catch (error) {
+        errorOutput.write(
+          `[LEX-MCP] Notification failed (${request.method}): ${errorMessage(error)}\n`,
+        );
+      }
+      return;
+    }
+
+    if (!isValidRequestId(request.id)) {
+      writeResponse({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: JSON_RPC_INVALID_REQUEST, message: "Invalid Request" },
+      });
+      return;
+    }
+
+    try {
+      const response = await mcpServer.handleRequest(request);
+      if (!isRecord(response)) {
+        throw new TypeError("Lex returned an invalid MCP response");
+      }
+      writeResponse(
+        response.error
+          ? {
+              jsonrpc: "2.0",
+              id: request.id,
+              error: applicationError(response.error),
+            }
+          : { jsonrpc: "2.0", id: request.id, result: response },
+      );
+    } catch (error) {
+      writeResponse({
+        jsonrpc: "2.0",
+        id: request.id,
+        error: applicationError(error),
+      });
+    }
+  };
+
+  const enqueueLine = (line) => {
+    work = work.then(() => handleLine(line));
+  };
+
+  const flushBuffer = () => {
+    if (!buffer.trim()) {
+      buffer = "";
+      return;
+    }
+    const line = buffer;
+    buffer = "";
+    enqueueLine(line);
+  };
+
+  const onData = (chunk) => {
+    buffer += String(chunk);
+    const lines = buffer.split("\n");
+    buffer = lines.pop() || "";
+
+    // Serialize requests in wire order. This avoids interleaving responses or
+    // request-local scope stores when multiple lines arrive in one chunk.
+    for (const line of lines) {
+      enqueueLine(line);
+    }
+  };
+
+  const close = () => {
+    if (closePromise) return closePromise;
+
+    input.off?.("data", onData);
+    input.off?.("end", onEnd);
+    flushBuffer();
+    closePromise = (async () => {
+      try {
+        await work;
+      } finally {
+        await mcpServer.close();
+      }
+    })();
+    return closePromise;
+  };
+
+  // EOF is the transport lifecycle boundary: accept a final record without a
+  // newline, drain every queued request, then close the Lex server exactly once.
+  const onEnd = () => {
+    void close().catch((error) => {
+      errorOutput.write(`[LEX-MCP] Failed to close: ${errorMessage(error)}\n`);
+    });
+  };
+
+  input.on("data", onData);
+  input.on("end", onEnd);
+
+  return Object.freeze({
+    server: mcpServer,
+    idle: () => closePromise ?? work,
+    close,
+  });
+}