@withpica/mcp-server 2.39.0 → 2.40.0

package/scripts/build-required-schemas.ts

@@ -0,0 +1,233 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * ADR-214 — generator for `required-schemas.generated.ts`.
+ *
+ * Reads three inputs:
+ *   1. ToolRegistry (instantiated from src) → tool inputSchemas
+ *   2. mcp-server/src/resources/required-schemas.source.ts → narrative + companion_calls
+ *   3. mcp-server/src/resources/schema-mirror.json → CHECK constraint enums
+ *
+ * Joins them and emits `mcp-server/src/resources/required-schemas.generated.ts`,
+ * a TypeScript module exporting `REQUIRED_SCHEMAS` consumed by ResourceRegistry.
+ *
+ * Determinism: object keys sorted alphabetically, arrays preserved in source
+ * order. Re-running with no source changes produces a byte-identical file.
+ *
+ * Wired into mcp-server/package.json as part of `prebuild` (after
+ * bundle-apps.ts). Runs via tsx; no build step required.
+ *
+ * Failure modes:
+ *   - source.ts references a tool not in ToolRegistry → exit 1, name file to fix
+ *   - companion_calls[].tool not in ToolRegistry → exit 1
+ *   - enum_tables references missing table/column in mirror → exit 1
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  REQUIRED_SCHEMAS_SOURCE,
+  type RequiredSchemaSource,
+} from "../src/resources/required-schemas.source.js";
+import { ToolRegistry, type ToolDefinition } from "../src/tools/index.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const MCP_SERVER_ROOT = join(__dirname, "..");
+const MIRROR_PATH = join(
+  MCP_SERVER_ROOT,
+  "src/resources/schema-mirror.json",
+);
+const OUTPUT_PATH = join(
+  MCP_SERVER_ROOT,
+  "src/resources/required-schemas.generated.ts",
+);
+
+interface SchemaMirror {
+  [table: string]: string[] | Record<string, string[]> | string | undefined;
+}
+
+function loadMirror(): SchemaMirror {
+  const raw = readFileSync(MIRROR_PATH, "utf-8");
+  return JSON.parse(raw) as SchemaMirror;
+}
+
+function loadRegistry(): Map<string, ToolDefinition> {
+  const stubPica = {} as never;
+  const stubConfig = {
+    picaApiKey: "stub",
+    picaApiUrl: "https://stub.example.com/api",
+    serverName: "schema-generator",
+    version: "0.0.0",
+    debug: false,
+    lobbyMode: false,
+    credentialsPath: "",
+    discoveryMode: false,
+  } as never;
+
+  const registry = new ToolRegistry(
+    stubPica,
+    stubConfig,
+    () => {},
+    { callerIdentity: "schema-generator", transport: "stdio" } as never,
+    () => {},
+  );
+
+  const map = new Map<string, ToolDefinition>();
+  // ToolRegistry.tools is private but read-accessible from sibling code in
+  // the same workspace (matches existing pattern in scripts/lint-mcp-tools.ts).
+  const tools = (registry as unknown as {
+    tools: Map<string, { definition: ToolDefinition }>;
+  }).tools;
+  for (const [name, entry] of tools) {
+    map.set(name, entry.definition);
+  }
+  return map;
+}
+
+function fail(msg: string): never {
+  console.error(`[build-required-schemas] ERROR: ${msg}`);
+  process.exit(1);
+}
+
+function getRequiredAndProperties(
+  tools: Map<string, ToolDefinition>,
+  toolName: string,
+  source: string,
+): { required: string[]; properties: string[] } {
+  const def = tools.get(toolName);
+  if (!def) {
+    fail(
+      `${source} references tool '${toolName}' which is not in ToolRegistry. ` +
+        `Edit mcp-server/src/resources/required-schemas.source.ts and remove or rename the reference.`,
+    );
+  }
+  const schema = def.inputSchema;
+  const required = Array.isArray(schema.required) ? [...schema.required] : [];
+  const properties = Object.keys(schema.properties ?? {});
+  return { required, properties };
+}
+
+function buildEnums(
+  mirror: SchemaMirror,
+  tables: RequiredSchemaSource["enum_tables"],
+  workflow: string,
+): Record<string, string[]> {
+  if (!tables || tables.length === 0) return {};
+  const out: Record<string, string[]> = {};
+  for (const { table, columns } of tables) {
+    const tableEntry = mirror[table];
+    if (!tableEntry || typeof tableEntry !== "object" || Array.isArray(tableEntry)) {
+      fail(
+        `Workflow '${workflow}' references table '${table}' missing from schema-mirror.json. ` +
+          `Run \`tsx mcp-server/scripts/refresh-schema-mirror.ts\` against staging to regenerate.`,
+      );
+    }
+    const tableMap = tableEntry as Record<string, string[]>;
+    for (const col of columns) {
+      const values = tableMap[col];
+      if (!Array.isArray(values)) {
+        fail(
+          `Workflow '${workflow}' references ${table}.${col} missing from schema-mirror.json.`,
+        );
+      }
+      out[col] = [...values].sort();
+    }
+  }
+  return out;
+}
+
+function buildCompanion(
+  tools: Map<string, ToolDefinition>,
+  companion: RequiredSchemaSource["companion_calls"][number],
+  workflow: string,
+): Record<string, unknown> {
+  // Verify the tool exists; we don't pull required[] from its inputSchema
+  // since companion_calls already declare what the call requires (often a
+  // wrapper/batch shape rather than the raw entity required-fields).
+  if (!tools.has(companion.tool)) {
+    fail(
+      `Workflow '${workflow}' companion '${companion.tool}' not in ToolRegistry. ` +
+        `Edit required-schemas.source.ts.`,
+    );
+  }
+  const out: Record<string, unknown> = {
+    tool: companion.tool,
+    when: companion.when,
+    required: companion.required,
+  };
+  if (companion.per_row_required) {
+    out.per_row_required = companion.per_row_required;
+  }
+  if (companion.constraint) {
+    out.constraint = companion.constraint;
+  }
+  return out;
+}
+
+function buildResource(
+  tools: Map<string, ToolDefinition>,
+  mirror: SchemaMirror,
+  source: RequiredSchemaSource,
+): Record<string, unknown> {
+  const { required, properties } = getRequiredAndProperties(
+    tools,
+    source.primary_tool,
+    `Workflow '${source.workflow}' primary_tool`,
+  );
+  const recommended = properties.filter((p) => !required.includes(p));
+  const enums = buildEnums(mirror, source.enum_tables, source.workflow);
+  const companions = source.companion_calls.map((c) =>
+    buildCompanion(tools, c, source.workflow),
+  );
+
+  return {
+    workflow: source.workflow,
+    summary: source.summary,
+    primary_tool: source.primary_tool,
+    primary_required: required,
+    primary_recommended: recommended,
+    enums,
+    companion_calls: companions,
+    example: source.example,
+  };
+}
+
+function emit(resources: Record<string, Record<string, unknown>>): string {
+  // Sort keys deterministically so re-runs produce byte-identical output.
+  const sortedKeys = Object.keys(resources).sort();
+  const sortedResources: Record<string, Record<string, unknown>> = {};
+  for (const k of sortedKeys) sortedResources[k] = resources[k];
+
+  const json = JSON.stringify(sortedResources, null, 2);
+  return [
+    "// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.",
+    "//",
+    "// AUTO-GENERATED by mcp-server/scripts/build-required-schemas.ts.",
+    "// Do not edit by hand. Re-run via `cd mcp-server && npm run prebuild`.",
+    "// Source: required-schemas.source.ts + schema-mirror.json + ToolRegistry inputSchemas.",
+    "// ADR-214 — required-fields contracts per workflow.",
+    "",
+    "export const REQUIRED_SCHEMAS = " + json + " as const;",
+    "",
+    "export type RequiredSchemaKey = keyof typeof REQUIRED_SCHEMAS;",
+    "",
+  ].join("\n");
+}
+
+function main(): void {
+  const tools = loadRegistry();
+  const mirror = loadMirror();
+  const out: Record<string, Record<string, unknown>> = {};
+  for (const [key, source] of Object.entries(REQUIRED_SCHEMAS_SOURCE)) {
+    out[key] = buildResource(tools, mirror, source);
+  }
+  const text = emit(out);
+  writeFileSync(OUTPUT_PATH, text, "utf-8");
+  console.log(
+    `[build-required-schemas] wrote ${Object.keys(out).length} schemas to ${OUTPUT_PATH}`,
+  );
+}
+
+main();

package/scripts/refresh-schema-mirror.ts

@@ -0,0 +1,182 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * ADR-214 — refresh schema-mirror.json against staging or prod.
+ *
+ * Connects to the configured Postgres URL (env var SUPABASE_DB_URL or
+ * DATABASE_URL) and queries pg_constraint for CHECK constraints on the
+ * tables backing Phase 1 schema resources. Parses the constraint
+ * definitions, extracts enum values, writes a deterministic JSON file at
+ * mcp-server/src/resources/schema-mirror.json.
+ *
+ * NOT run by CI — humans run this when they suspect or know that a CHECK
+ * constraint changed in production. The mirror is committed to git so PR
+ * diffs surface drift.
+ *
+ * Usage:
+ *   SUPABASE_DB_URL=postgres://... npx tsx mcp-server/scripts/refresh-schema-mirror.ts
+ *
+ * Optional dep: `pg` (added as devDependency on mcp-server).
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const MIRROR_PATH = join(
+  __dirname,
+  "..",
+  "src/resources/schema-mirror.json",
+);
+
+interface MirrorContent {
+  _generated_at: string;
+  _source: string;
+  _note: string;
+  [table: string]:
+    | string
+    | Record<string, string[]>;
+}
+
+const TABLES_TO_MIRROR: Array<{ table: string; columns: string[] }> = [
+  { table: "audio_files", columns: ["classification", "file_type"] },
+  { table: "recording_credits", columns: ["role"] },
+  { table: "recordings", columns: ["version_type"] },
+  {
+    table: "work_credits",
+    columns: ["attestation_status", "credit_type", "rights_type"],
+  },
+  { table: "works", columns: ["work_status", "work_type"] },
+];
+
+function fail(msg: string): never {
+  console.error(`[refresh-schema-mirror] ERROR: ${msg}`);
+  process.exit(1);
+}
+
+/**
+ * Parse a CHECK constraint definition string for ANY-of-array shapes.
+ * Postgres formats vary; common shapes:
+ *   CHECK ((work_type = ANY (ARRAY['song'::text, 'instrumental'::text, ...])))
+ *   CHECK ((work_type::text = ANY (ARRAY['song'::text, ...])))
+ *   CHECK (work_type IN ('song', 'instrumental', ...))
+ * Returns the literal values in source order; caller sorts for determinism.
+ */
+function parseEnumFromCheckDef(def: string): string[] | null {
+  // Match ARRAY[...] form
+  const arrayMatch = def.match(/ARRAY\[([^\]]+)\]/);
+  if (arrayMatch) {
+    const inside = arrayMatch[1];
+    const literals = [...inside.matchAll(/'([^']+)'/g)].map((m) => m[1]);
+    return literals.length > 0 ? literals : null;
+  }
+  // Match IN (...) form
+  const inMatch = def.match(/IN\s*\(([^)]+)\)/i);
+  if (inMatch) {
+    const inside = inMatch[1];
+    const literals = [...inside.matchAll(/'([^']+)'/g)].map((m) => m[1]);
+    return literals.length > 0 ? literals : null;
+  }
+  return null;
+}
+
+async function main(): Promise<void> {
+  const dbUrl = process.env.SUPABASE_DB_URL ?? process.env.DATABASE_URL;
+  if (!dbUrl) {
+    fail(
+      "SUPABASE_DB_URL (or DATABASE_URL) env var not set. Provide a Postgres connection string for staging or prod.",
+    );
+  }
+
+  // Lazy-import pg so the file type-checks even if pg isn't installed.
+  // Generator is the hot path; refresh is operator-only.
+  let Client: typeof import("pg").Client;
+  try {
+    ({ Client } = await import("pg"));
+  } catch {
+    fail(
+      "pg npm package not installed. Run: cd mcp-server && npm install --save-dev pg @types/pg",
+    );
+  }
+
+  const client = new Client({ connectionString: dbUrl });
+  await client.connect();
+
+  const out: Record<string, Record<string, string[]>> = {};
+
+  for (const { table, columns } of TABLES_TO_MIRROR) {
+    out[table] = {};
+    for (const col of columns) {
+      // Find a CHECK constraint on this column. Look for any constraint
+      // whose pg_get_constraintdef text references the column name and
+      // contains an ANY/IN enum list.
+      const result = await client.query<{ def: string }>(
+        `
+        SELECT pg_get_constraintdef(oid) AS def
+        FROM pg_constraint
+        WHERE conrelid = $1::regclass
+          AND contype = 'c'
+          AND pg_get_constraintdef(oid) ILIKE $2
+        `,
+        [`public.${table}`, `%${col}%`],
+      );
+
+      let values: string[] | null = null;
+      for (const row of result.rows) {
+        const parsed = parseEnumFromCheckDef(row.def);
+        if (parsed && parsed.length > 0) {
+          values = parsed;
+          break;
+        }
+      }
+      if (!values) {
+        console.warn(
+          `[refresh-schema-mirror] warn: no enum CHECK found for ${table}.${col}; leaving empty array`,
+        );
+        values = [];
+      }
+      out[table][col] = [...values].sort();
+    }
+  }
+
+  await client.end();
+
+  // Preserve metadata from existing mirror if present.
+  let existingNote =
+    "CHECK constraint enums for tables backing ADR-214 Phase 1 schemas. Refresh via `npx tsx mcp-server/scripts/refresh-schema-mirror.ts` against staging. Committed so PR diffs surface schema drift. See ADR-214 Decision section, Drift Prevention #3.";
+  try {
+    const prev = JSON.parse(
+      readFileSync(MIRROR_PATH, "utf-8"),
+    ) as MirrorContent;
+    if (typeof prev._note === "string") existingNote = prev._note;
+  } catch {
+    // first run — fine
+  }
+
+  const sortedTables = Object.keys(out).sort();
+  const sortedOut: Record<string, Record<string, string[]>> = {};
+  for (const t of sortedTables) {
+    const cols = Object.keys(out[t]).sort();
+    sortedOut[t] = {};
+    for (const c of cols) sortedOut[t][c] = out[t][c];
+  }
+
+  const final: MirrorContent = {
+    _generated_at: new Date().toISOString(),
+    _source: dbUrl.replace(/:[^:@]+@/, ":***@"),
+    _note: existingNote,
+    ...sortedOut,
+  };
+
+  writeFileSync(MIRROR_PATH, JSON.stringify(final, null, 2) + "\n", "utf-8");
+  console.log(
+    `[refresh-schema-mirror] wrote ${sortedTables.length} tables to ${MIRROR_PATH}`,
+  );
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/withpica/pica",
     "source": "github"
   },
-  "version": "2.39.0",
+  "version": "2.40.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@withpica/mcp-server",
-      "version": "2.39.0",
+      "version": "2.40.0",
       "transport": {
         "type": "stdio"
       }