@softure-ai/mcp-access 0.1.12 → 0.1.13

package/src/server/tools.ts

@@ -0,0 +1,72 @@
+// Tool results for the app's MCP server and the boundary that keeps failures safe: the assistant gets
+// a value, a `PublicError`'s message or a hint, never a thrown error's text (a failed query carries
+// its SQL and parameters). The log gets the error's kind only (`errorLogLabel`).
+import { isCallToolResult, type CallToolResult } from "@modelcontextprotocol/server";
+import { errorLogLabel, getPublicMessage, safeError } from "@softure-ai/core";
+
+/** What the assistant reads for an error code: the app's own text per code, e.g. `{ "orders.not_found": "No order with that number." }`. */
+export type ToolErrorHints = Readonly<Record<string, string>>;
+
+export interface ToolErrorOptions {
+  /** Texts per error code; a code without one is answered as the code itself. */
+  readonly hints?: ToolErrorHints;
+  /** The tool's name in the log line. */
+  readonly label?: string;
+}
+
+/** For failures the tool did not expect: what `safeError` makes of them, unless a hint replaces it. */
+const DEFAULT_FAILURE_TEXT: ToolErrorHints = {
+  "core.database_failed": "The database could not answer; try again later.",
+  "core.unexpected": "The tool failed; try again later.",
+};
+
+/** A successful tool answer: a string as text, anything else as JSON text. */
+export function toolResult(value: unknown): CallToolResult {
+  return { content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value) ?? "null" }] };
+}
+
+/** A failed tool answer the assistant reads and may act on. */
+export function toolError(message: string): CallToolResult {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+/**
+ * Runs a tool's work and answers it safely. A `CallToolResult` passes as is; a result value is unwrapped
+ * (`{ ok: true, value }` → `toolResult(value)`, `{ ok: false, error }` → `toolError` with the hint for the
+ * code, else the code); any other value becomes `toolResult`. A thrown `PublicError` gives its message;
+ * anything else is logged by kind and answered with the hint for its `safeError` code, else a fixed text.
+ */
+export async function withToolErrors(work: () => unknown, options: ToolErrorOptions = {}): Promise<CallToolResult> {
+  try {
+    return answerValue(await work(), options.hints);
+  } catch (error) {
+    return answerFailure(error, options);
+  }
+}
+
+/** The answer for a value a tool or an action returned. */
+export function answerValue(value: unknown, hints: ToolErrorHints = {}): CallToolResult {
+  if (isCallToolResult(value)) return value;
+  if (isResult(value)) return value.ok ? toolResult(value.value) : toolError(describeCode(value.error, hints));
+  return toolResult(value);
+}
+
+function answerFailure(error: unknown, options: ToolErrorOptions): CallToolResult {
+  const publicMessage = getPublicMessage(error);
+  if (publicMessage !== null) return toolError(publicMessage);
+  console.error(`@softure-ai/mcp-access: tool ${options.label ?? "call"} failed: ${errorLogLabel(error)}`);
+  const code = safeError(error).error;
+  return toolError(options.hints?.[code] ?? DEFAULT_FAILURE_TEXT[code] ?? code);
+}
+
+/** The text for an error code: the app's hint, else the code. */
+export function describeCode(code: string, hints: ToolErrorHints): string {
+  return Object.hasOwn(hints, code) ? (hints[code] ?? code) : code;
+}
+
+/** Core's result shape: `{ ok: true, value }` or `{ ok: false, error }` with a string code. */
+function isResult(value: unknown): value is { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly error: string } {
+  if (typeof value !== "object" || value === null || !("ok" in value)) return false;
+  if (value.ok === true) return "value" in value;
+  return value.ok === false && "error" in value && typeof value.error === "string";
+}

package/src/stdio/index.ts

@@ -0,0 +1,12 @@
+// `@softure-ai/mcp-access/stdio`: the app's MCP server over stdio for a local assistant, with the
+// account from the environment. `/stdio/register` lets a factory that imports `server-only` run here.
+export {
+  DEFAULT_MCP_USER_ID_ENV,
+  serveMcpStdio,
+  STDIO_TOKEN_ID,
+  type McpStdioError,
+  type McpStdioErrorCode,
+  type McpStdioHandle,
+  type McpStdioResult,
+  type ServeMcpStdioOptions,
+} from "./serve.js";

package/src/stdio/register.ts

@@ -0,0 +1,11 @@
+// `node --import @softure-ai/mcp-access/stdio/register` (or `tsx --import …`): resolves `server-only` to
+// an empty module, so an MCP server factory written for Next (which marks its files with
+// `import "server-only"`) runs in a plain Node process. Nothing else is resolved differently; unlike
+// `--conditions=react-server`, React keeps its regular build.
+import { registerHooks } from "node:module";
+
+const EMPTY_MODULE = "data:text/javascript,export%20%7B%7D%3B";
+
+registerHooks({
+  resolve: (specifier, context, nextResolve) => (specifier === "server-only" ? { url: EMPTY_MODULE, format: "module", shortCircuit: true } : nextResolve(specifier, context)),
+});

package/src/stdio/serve.ts

@@ -0,0 +1,133 @@
+// The app's MCP server over stdio, for a local assistant (Claude Code, Claude Desktop) on the machine
+// that holds the database. There is no token: the account comes from the environment or, on a
+// database with exactly one account, is that account. The app's factory is the one the endpoint uses.
+//
+//   // scripts/mcp-stdio.ts, run with `tsx --import @softure-ai/mcp-access/stdio/register scripts/mcp-stdio.ts`
+//   const started = await serveMcpStdio({ config, createServer });
+//   if (!started.ok) { console.error(started.error.message); process.exitCode = 1; }
+import type { Transport } from "@modelcontextprotocol/server";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { users } from "@softure-ai/auth";
+import { errorLogLabel, type SoftureConfig, type SoftureDatabaseConfig } from "@softure-ai/core";
+import { openCommandDatabase, type CommandDatabase } from "@softure-ai/db";
+import { eq } from "drizzle-orm";
+import type { McpServerIdentity } from "../contract.js";
+import type { McpServerFactory } from "../server/endpoint.js";
+import { getMcpAccessOptions } from "../server/options.js";
+
+/** The variable naming the account to serve, unless the entry is told another one. */
+export const DEFAULT_MCP_USER_ID_ENV = "MCP_USER_ID";
+
+/** The token id the factory receives over stdio, where there is no token. */
+export const STDIO_TOKEN_ID = "stdio";
+
+const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export type McpStdioErrorCode = "mcp-access.stdio_no_database" | "mcp-access.stdio_no_account" | "mcp-access.stdio_account_ambiguous" | "mcp-access.stdio_account_unknown";
+
+/** Why the entry did not start, with a message for the person running it (stderr: stdout is the protocol). */
+export interface McpStdioError {
+  readonly code: McpStdioErrorCode;
+  readonly message: string;
+}
+
+export interface McpStdioHandle {
+  /** Who the server runs as. */
+  readonly identity: McpServerIdentity;
+  /** Ends the connection and closes the database. Also happens when the client closes stdin. */
+  readonly close: () => Promise<void>;
+}
+
+export type McpStdioResult = { readonly ok: true; readonly value: McpStdioHandle } | { readonly ok: false; readonly error: McpStdioError };
+
+export interface ServeMcpStdioOptions {
+  readonly config: SoftureConfig;
+  readonly createServer: McpServerFactory;
+  /** The environment variable with the account's id. Default: `MCP_USER_ID`. */
+  readonly userIdEnv?: string;
+  /** Registers write tools, when the app's `allowWrites` is on too. Default: false, read only. */
+  readonly allowWrites?: boolean;
+  /** Default: `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Default: stdin and stdout of this process. */
+  readonly transport?: Transport;
+  /** Default: the config's `database.handle`, else a connection on `database.url`. */
+  readonly openDatabase?: (database: SoftureDatabaseConfig) => Promise<CommandDatabase>;
+}
+
+/** Resolves the account, then serves the app's server for it over stdio until the client goes away. */
+export async function serveMcpStdio(options: ServeMcpStdioOptions): Promise<McpStdioResult> {
+  const { config } = options;
+  if (config.database === null) return refuse("mcp-access.stdio_no_database", "softure.config.ts has no database; mcp-access needs one");
+  const userIdEnv = options.userIdEnv ?? DEFAULT_MCP_USER_ID_ENV;
+  const env = options.env ?? process.env;
+  const database = await (options.openDatabase ?? ((settings) => openCommandDatabase(settings, { max: 1 })))(config.database);
+
+  let userId: string | McpStdioError;
+  try {
+    userId = await resolveAccount(database, env[userIdEnv]?.trim() ?? "", userIdEnv);
+  } catch (error) {
+    await database.close();
+    throw new Error(`@softure-ai/mcp-access: looking up the account to serve failed: ${errorLogLabel(error)}`, { cause: error });
+  }
+  if (typeof userId !== "string") {
+    await database.close();
+    return { ok: false, error: userId };
+  }
+
+  const identity: McpServerIdentity = {
+    userId,
+    canWrite: (options.allowWrites ?? false) && getMcpAccessOptions(config).allowWrites,
+    tokenId: STDIO_TOKEN_ID,
+  };
+  let closed = false;
+  const closeDatabase = async () => {
+    if (closed) return;
+    closed = true;
+    await database.close();
+  };
+  const transport = options.transport ?? new StdioServerTransport();
+  const handle = serveStdio(() => options.createServer(identity), {
+    transport,
+    onerror: (error) => console.error(`@softure-ai/mcp-access: the stdio connection reported: ${errorLogLabel(error)}`),
+  });
+  // serveStdio has set its own handler by now; the database follows the connection, so a client that
+  // closes stdin leaves no open pool keeping the process alive.
+  const servedOnClose = transport.onclose;
+  transport.onclose = () => {
+    servedOnClose?.();
+    void closeDatabase();
+  };
+  return {
+    ok: true,
+    value: {
+      identity,
+      close: async () => {
+        await handle.close();
+        await closeDatabase();
+      },
+    },
+  };
+}
+
+/** The account id, or why there is none. Never the first of several accounts: that could be another person's data. */
+async function resolveAccount(database: CommandDatabase, requested: string, userIdEnv: string): Promise<string | McpStdioError> {
+  const { db } = database.handle;
+  if (requested !== "") {
+    const unknown = { code: "mcp-access.stdio_account_unknown", message: `@softure-ai/mcp-access: ${userIdEnv} names no account` } as const;
+    if (!UUID_SHAPE.test(requested)) return unknown;
+    const found = await db.select({ id: users.id }).from(users).where(eq(users.id, requested)).limit(1);
+    return found[0]?.id ?? unknown;
+  }
+  const accounts = await db.select({ id: users.id }).from(users).limit(2);
+  const [only, second] = accounts;
+  if (only === undefined) return { code: "mcp-access.stdio_no_account", message: "@softure-ai/mcp-access: the database has no account to serve" };
+  if (second !== undefined) {
+    return { code: "mcp-access.stdio_account_ambiguous", message: `@softure-ai/mcp-access: the database has several accounts; set ${userIdEnv} to the id of the one to serve` };
+  }
+  return only.id;
+}
+
+function refuse(code: McpStdioErrorCode, reason: string): McpStdioResult {
+  return { ok: false, error: { code, message: `@softure-ai/mcp-access: ${reason}` } };
+}

package/src/testing/catalog.ts

@@ -0,0 +1,74 @@
+// Catalog parity: the tools listed in softure.config.ts (the token page shows them, agent docs read
+// them) against the tools the app's MCP server really registers, for a read-only and a write identity.
+// Framework-free: `expectToolCatalogMatchesServer` throws, so it works in any test runner.
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import type { SoftureConfig } from "@softure-ai/core";
+import type { McpServerIdentity } from "../contract.js";
+import type { McpServerFactory } from "../server/endpoint.js";
+import { getMcpAccessOptions } from "../server/options.js";
+
+export interface ToolCatalogDifferences {
+  /** Configured tools the server does not register for the identity that should get them. */
+  readonly missing: readonly string[];
+  /** Tools the server registers that the catalog does not list. */
+  readonly unlisted: readonly string[];
+  /** Configured write tools the server gives a read-only identity. */
+  readonly writeForReaders: readonly string[];
+}
+
+const READER: McpServerIdentity = { userId: "00000000-0000-4000-8000-000000000001", canWrite: false, tokenId: "catalog-check" };
+const WRITER: McpServerIdentity = { ...READER, canWrite: true };
+
+/** Every difference between the configured catalog and the server, each list in the catalog's order, then the server's. */
+export async function getToolCatalogDifferences(config: SoftureConfig, createServer: McpServerFactory): Promise<ToolCatalogDifferences> {
+  const catalog = getMcpAccessOptions(config).tools;
+  const forReaders = await listServerTools(createServer, READER);
+  const forWriters = await listServerTools(createServer, WRITER);
+  const listed = new Set(catalog.map((tool) => tool.name));
+  return {
+    missing: catalog.filter((tool) => !(tool.access === "read" ? forReaders.includes(tool.name) && forWriters.includes(tool.name) : forWriters.includes(tool.name))).map((tool) => tool.name),
+    unlisted: [...new Set([...forReaders, ...forWriters])].filter((name) => !listed.has(name)),
+    writeForReaders: catalog.filter((tool) => tool.access === "write" && forReaders.includes(tool.name)).map((tool) => tool.name),
+  };
+}
+
+/** Throws a list of every difference, e.g. in a unit test next to the server. */
+export async function expectToolCatalogMatchesServer(config: SoftureConfig, createServer: McpServerFactory): Promise<void> {
+  const differences = await getToolCatalogDifferences(config, createServer);
+  const problems = [
+    differences.missing.length > 0 ? `missing from the server: ${differences.missing.join(", ")}` : null,
+    differences.unlisted.length > 0 ? `registered but not in the catalog: ${differences.unlisted.join(", ")}` : null,
+    differences.writeForReaders.length > 0 ? `write tools a read-only token gets: ${differences.writeForReaders.join(", ")}` : null,
+  ].filter((problem) => problem !== null);
+  if (problems.length > 0) {
+    throw new Error(`@softure-ai/mcp-access: the tool catalog in softure.config.ts does not match the MCP server: ${problems.join("; ")}`);
+  }
+}
+
+/** The tool names a fresh server lists for the identity, asked the way the endpoint serves it. */
+async function listServerTools(createServer: McpServerFactory, identity: McpServerIdentity): Promise<string[]> {
+  const handler = createMcpHandler(() => createServer(identity), { responseMode: "json" });
+  const response = await handler.fetch(
+    new Request("http://localhost/api/mcp", {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
+    }),
+  );
+  const answer = readAnswer(await response.text());
+  if (answer.result?.tools === undefined) {
+    throw new Error(`@softure-ai/mcp-access: listing the server's tools failed: ${typeof answer.error?.message === "string" ? answer.error.message : `HTTP ${String(response.status)}`}`);
+  }
+  return answer.result.tools.map((tool) => (typeof tool.name === "string" ? tool.name : "")).filter((name) => name !== "");
+}
+
+interface ToolsListAnswer {
+  readonly result?: { readonly tools?: readonly { readonly name?: unknown }[] };
+  readonly error?: { readonly message?: unknown };
+}
+
+/** The JSON-RPC answer, sent as JSON or as one SSE `message` event. */
+function readAnswer(body: string): ToolsListAnswer {
+  const data = body.startsWith("event:") ? (body.split("\n").find((line) => line.startsWith("data: "))?.slice("data: ".length) ?? "null") : body;
+  return (JSON.parse(data) ?? {}) as ToolsListAnswer;
+}

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+// `@softure-ai/mcp-access/testing`: checks for an app's own tests.
+export { expectToolCatalogMatchesServer, getToolCatalogDifferences, type ToolCatalogDifferences } from "./catalog.js";