@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.1

package/src/mcp/index.ts

@@ -0,0 +1,304 @@
+/**
+ * MCP contributions for the sql lexicon (chant #3210). Tools answer from the
+ * committed ClickHouse catalog and the tag parser, so an agent can look up an
+ * engine, a type or a setting, and check a statement, without a server.
+ *
+ * Tools register as `sql:<verb>` and resources as `chant://sql/<path>`.
+ */
+
+import type { McpResourceContribution, McpToolContribution } from "@intentius/chant/mcp/types";
+import { createCatalogResource, createDiffTool } from "@intentius/chant/lexicon-plugin-helpers";
+import { sqlSerializer } from "../serializer";
+import { catalogIndex } from "../lsp/catalog";
+import { database, table, view } from "../clickhouse/entities";
+import { SqlSyntaxError } from "../clickhouse/tokens";
+import { existsSync, readFileSync } from "fs";
+import { diffSchemas } from "../clickhouse/plan/diff";
+import { renderDiff } from "../clickhouse/plan/report";
+import { rebuildOpSuggestions } from "../clickhouse/plan/rebuild-handoff";
+import { CLASSIFIER_RULES } from "../clickhouse/plan/rules";
+import { schemaFromBuildFile, schemaFromBuildOutput } from "../clickhouse/plan/schema";
+import { asMajor, POSTGRES_KINDS, POSTGRES_TAGS, postgresLookup, postgresMcpResources, postgresParse, postgresSearch } from "./postgres";
+import { diffPgSchemas } from "../postgres/plan/diff";
+import { renderPgDiff } from "../postgres/plan/report";
+import { PG_CLASSIFIER_RULES } from "../postgres/plan/rules";
+import { pgSchemaFromBuildFile, pgSchemaFromBuildOutput } from "../postgres/plan/schema";
+import { migrationOpSuggestions } from "../postgres/migrate/handoff";
+import { CLICKHOUSE_IMAGE_DIGEST, CLICKHOUSE_VERSION, clickhouseImage } from "../spec/pin";
+
+const KINDS = ["engine", "database-engine", "type", "codec", "index-type", "setting", "function", "format"] as const;
+type Kind = (typeof KINDS)[number];
+
+const kindProp = {
+  type: "string",
+  enum: [...new Set([...KINDS, ...POSTGRES_KINDS])],
+  description: `Which part of the catalog. ClickHouse: ${KINDS.join(", ")}. Postgres: ${POSTGRES_KINDS.join(", ")}`,
+};
+const dialectProp = { type: "string", enum: ["clickhouse", "postgres"], description: "The dialect to answer for (default clickhouse)" };
+const majorProp = { type: "number", description: "Postgres only: answer for this major (14 to 18; for classify-change, the server's major); omitted, every major, with since/until on names not in all" };
+
+function asDialect(value: unknown): "clickhouse" | "postgres" {
+  if (value === undefined || value === "clickhouse") return "clickhouse";
+  if (value === "postgres") return "postgres";
+  throw new Error("dialect must be clickhouse or postgres");
+}
+
+type Row = { name: string; summary?: string };
+
+function rows(kind: Kind): Row[] {
+  const index = catalogIndex();
+  if (!index) throw new Error("the ClickHouse catalog snapshot could not be read");
+  const { catalog } = index;
+  switch (kind) {
+    case "engine":
+      return catalog.tableEngines;
+    case "database-engine":
+      return catalog.databaseEngines;
+    case "type":
+      return catalog.typeFamilies;
+    case "codec":
+      return catalog.codecs;
+    case "index-type":
+      return catalog.skipIndexTypes;
+    case "setting":
+      return [
+        ...catalog.mergeTreeSettings.map((s) => ({ ...s, scope: "merge-tree" })),
+        ...catalog.querySettings.map((s) => ({ ...s, scope: "query" })),
+      ];
+    case "function":
+      return catalog.functions;
+    case "format":
+      return catalog.formats;
+  }
+}
+
+function asKind(value: unknown): Kind {
+  if (!KINDS.includes(value as Kind)) throw new Error(`kind must be one of: ${KINDS.join(", ")}`);
+  return value as Kind;
+}
+
+const lookupTool: McpToolContribution = {
+  name: "lookup",
+  description:
+    "Look up a catalog entry by name. ClickHouse (default): engine, type family, codec, skip index type, setting, function or format, from the pinned server (" +
+    CLICKHOUSE_VERSION +
+    "). Postgres (dialect postgres): type or alias, index or table access method, storage parameter, setting, function, key word or extension, from the pinned servers of majors 14 to 18, with since/until. Returns every catalog row with that name, or the closest names when there is none.",
+  inputSchema: { type: "object", properties: { dialect: dialectProp, kind: kindProp, name: { type: "string" }, major: majorProp }, required: ["kind", "name"] },
+  async handler(params) {
+    if (asDialect(params.dialect) === "postgres") return postgresLookup(params);
+    const kind = asKind(params.kind);
+    const name = String(params.name ?? "");
+    const all = rows(kind);
+    const exact = all.filter((r) => r.name === name);
+    const found = exact.length ? exact : all.filter((r) => r.name.toLowerCase() === name.toLowerCase());
+    if (found.length) return { kind, version: CLICKHOUSE_VERSION, matches: found };
+    const near = all.filter((r) => r.name.toLowerCase().includes(name.toLowerCase())).slice(0, 10).map((r) => r.name);
+    return { kind, version: CLICKHOUSE_VERSION, matches: [], closest: near };
+  },
+};
+
+const searchTool: McpToolContribution = {
+  name: "search",
+  description: "Search one part of a dialect's catalog by a name substring. Returns names with the first line of their description.",
+  inputSchema: {
+    type: "object",
+    properties: { dialect: dialectProp, kind: kindProp, query: { type: "string" }, major: majorProp, limit: { type: "number", description: "At most this many results (default 25)" } },
+    required: ["kind", "query"],
+  },
+  async handler(params) {
+    if (asDialect(params.dialect) === "postgres") return postgresSearch(params);
+    const kind = asKind(params.kind);
+    const query = String(params.query ?? "").toLowerCase();
+    const limit = Math.max(1, Math.min(200, Number(params.limit ?? 25)));
+    const hits = rows(kind).filter((r) => r.name.toLowerCase().includes(query));
+    return {
+      kind,
+      total: hits.length,
+      results: hits.slice(0, limit).map((r) => ({ name: r.name, ...(typeof r.summary === "string" ? { summary: r.summary } : {}) })),
+    };
+  },
+};
+
+const parseTool: McpToolContribution = {
+  name: "parse-ddl",
+  description:
+    "Parse one CREATE statement the way its tag does (dialect clickhouse, the default: table, view, database; dialect postgres: schema, table, index, view, sequence, type, domain, extension), and return the entity it builds (columns, engine, keys, settings, and for a view its lineage). A statement that does not parse comes back as the error with its line and column, the same one SQLCH001 (ClickHouse) or SQLPG001 (Postgres) reports. The statement is plain DDL: there are no interpolations.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      dialect: dialectProp,
+      tag: { type: "string", enum: [...new Set(["table", "view", "database", ...POSTGRES_TAGS])], description: "The tag the statement belongs in (ClickHouse: table, view, database; Postgres: " + POSTGRES_TAGS.join(", ") + ")" },
+      ddl: { type: "string", description: "The CREATE statement" },
+    },
+    required: ["tag", "ddl"],
+  },
+  async handler(params) {
+    const ddl = String(params.ddl ?? "");
+    const tag = String(params.tag);
+    if (asDialect(params.dialect) === "postgres") return postgresParse(tag, ddl, position);
+    const build = tag === "table" ? table : tag === "view" ? view : tag === "database" ? database : undefined;
+    if (!build) throw new Error("tag must be table, view or database");
+    const strings = Object.assign([ddl], { raw: [ddl] }) as unknown as TemplateStringsArray;
+    try {
+      const entity = build(strings);
+      return { ok: true, entityType: entity.entityType, name: entity.sqlName, props: JSON.parse(JSON.stringify(entity.props)) };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const offset = (err as { offset?: number }).offset;
+      const where = typeof offset === "number" ? position(ddl, offset) : undefined;
+      const syntax = err instanceof SqlSyntaxError || (err as Error).name === "SqlTemplateError";
+      return { ok: false, rule: syntax ? "SQLCH001" : undefined, message, ...(where ?? {}) };
+    }
+  },
+};
+
+const classifyTool: McpToolContribution = {
+  name: "classify-change",
+  description:
+    "Classify the schema change between two revisions of a sql lexicon build, offline. Each side is a `chant build` output (a path to the file, or its JSON text); the dialect is the one the output names, or `dialect`. ClickHouse: every change with its class (create, drop, metadata, rewrite, rebuild), the SQLCH2xx rule and the ClickHouse restriction behind it with its documentation link, the rebuilds a plan must refuse in place with the ClickHouseRebuildOp declaration to run each one as, rename hints, and a rendered report. Postgres: every change with its class by the lock it takes (create, metadata, validate, concurrently, rewrite, expand, drop), the SQLPG2xx rule and its restriction with its Postgres documentation link, the `refused` changes that can only be made as expand and contract with the PostgresMigrationOp declaration to run each column rename or type change across kinds as (`migrationOps`), rename hints and a rendered report; `major` is the server's major (default the newest pinned).",
+  inputSchema: {
+    type: "object",
+    properties: {
+      before: { type: "string", description: "The earlier build output: a file path or the JSON text" },
+      after: { type: "string", description: "The later build output: a file path or the JSON text" },
+      dialect: dialectProp,
+      major: majorProp,
+    },
+    required: ["before", "after"],
+  },
+  async handler(params) {
+    if (buildDialect(params) === "postgres") return classifyPostgres(params);
+    const side = (v: unknown) => {
+      const text = String(v ?? "");
+      return !text.trimStart().startsWith("{") && existsSync(text) ? schemaFromBuildFile(text) : schemaFromBuildOutput(text);
+    };
+    const after = side(params.after);
+    const plain = diffSchemas(side(params.before), after);
+    const rebuildOps = rebuildOpSuggestions(plain, new Map(after.map((o) => [o.key, o.canonical])), "<env>");
+    const diff = rebuildOps.length > 0 ? { ...plain, rebuildOps } : plain;
+    const classes: Record<string, number> = {};
+    for (const c of diff.changes) classes[c.class] = (classes[c.class] ?? 0) + 1;
+    return {
+      summary: classes,
+      changes: diff.changes.map((c) => ({ ...c, restriction: CLASSIFIER_RULES[c.rule].restriction, cite: CLASSIFIER_RULES[c.rule].cite })),
+      rebuilds: diff.rebuilds,
+      rebuildOps,
+      hints: diff.hints,
+      report: renderDiff(diff),
+    };
+  },
+};
+
+/** The dialect a classify call is for: `dialect`, else the one either build output names, else ClickHouse. */
+function buildDialect(params: Record<string, unknown>): "clickhouse" | "postgres" {
+  if (params.dialect !== undefined) return asDialect(params.dialect);
+  for (const v of [params.after, params.before]) {
+    const text = String(v ?? "");
+    try {
+      const json = text.trimStart().startsWith("{") ? text : existsSync(text) ? readFileSync(text, "utf-8") : "";
+      const d = (JSON.parse(json) as { dialect?: string }).dialect;
+      if (d === "postgres") return "postgres";
+      if (d === "clickhouse") return "clickhouse";
+    } catch {
+      // Not JSON we can read: the schema reader reports it.
+    }
+  }
+  return "clickhouse";
+}
+
+function classifyPostgres(params: Record<string, unknown>): unknown {
+  const side = (v: unknown) => {
+    const text = String(v ?? "");
+    return !text.trimStart().startsWith("{") && existsSync(text) ? pgSchemaFromBuildFile(text) : pgSchemaFromBuildOutput(text);
+  };
+  const after = side(params.after);
+  const plain = diffPgSchemas(side(params.before), after, { major: asMajor(params.major) });
+  const migrationOps = migrationOpSuggestions(plain.refused, new Map(after.map((o) => [o.key, o.canonical])), "<env>");
+  const diff = migrationOps.length > 0 ? { ...plain, migrationOps } : plain;
+  const classes: Record<string, number> = {};
+  for (const c of diff.changes) classes[c.class] = (classes[c.class] ?? 0) + 1;
+  return {
+    dialect: "postgres",
+    summary: classes,
+    changes: diff.changes.map((c) => ({ ...c, restriction: PG_CLASSIFIER_RULES[c.rule].restriction, cite: PG_CLASSIFIER_RULES[c.rule].cite })),
+    refused: diff.refused.map((c) => ({
+      object: c.object,
+      field: c.field,
+      rule: c.rule,
+      advice: "No in-place change keeps old readers working: run it as expand and contract (add the new, write both, backfill, move readers, drop the old), as a migration Op.",
+    })),
+    migrationOps,
+    hints: diff.hints,
+    report: renderPgDiff(diff),
+  };
+}
+
+function position(text: string, offset: number): { line: number; column: number } {
+  const before = text.slice(0, offset).split("\n");
+  return { line: before.length, column: before[before.length - 1]!.length + 1 };
+}
+
+/** The tools the sql lexicon contributes. */
+export function sqlMcpTools(): McpToolContribution[] {
+  return [
+    lookupTool,
+    searchTool,
+    parseTool,
+    classifyTool,
+    createDiffTool(sqlSerializer, "Compare current sql build output against the previous build", "sql"),
+  ];
+}
+
+const json = (value: unknown) => JSON.stringify(value, null, 2);
+
+function catalogResource(uri: string, name: string, description: string, read: () => unknown): McpResourceContribution {
+  return {
+    uri,
+    name,
+    description,
+    mimeType: "application/json",
+    async handler() {
+      return json(read());
+    },
+  };
+}
+
+const need = () => {
+  const index = catalogIndex();
+  if (!index) throw new Error("the ClickHouse catalog snapshot could not be read");
+  return index.catalog;
+};
+
+/** The resources the sql lexicon contributes. */
+export function sqlMcpResources(): McpResourceContribution[] {
+  return [
+    // `generated/` sits beside plugin.ts, which is where the helper looks.
+    createCatalogResource(
+      new URL("../plugin.ts", import.meta.url).href,
+      "SQL Entity Catalog",
+      "The entity kinds the sql lexicon declares (database, table, view, materialized view)",
+      "lexicon-sql.json",
+      "sql",
+    ),
+    ...postgresMcpResources(),
+    catalogResource("clickhouse-pin", "ClickHouse Pin", "The pinned ClickHouse server the catalog was read from", () => ({
+      version: CLICKHOUSE_VERSION,
+      image: clickhouseImage(),
+      digest: CLICKHOUSE_IMAGE_DIGEST,
+    })),
+    catalogResource("clickhouse-engines", "ClickHouse Engines", "Table and database engines with their usage line, summary and capabilities", () => ({
+      tableEngines: need().tableEngines,
+      databaseEngines: need().databaseEngines,
+    })),
+    catalogResource("clickhouse-types", "ClickHouse Types", "Column type families, with aliases and case sensitivity", () => need().typeFamilies),
+    catalogResource("clickhouse-codecs", "ClickHouse Codecs", "Column codecs and skip index types", () => ({
+      codecs: need().codecs,
+      skipIndexTypes: need().skipIndexTypes,
+    })),
+    catalogResource("clickhouse-settings", "ClickHouse Settings", "MergeTree and query settings with type, default and tier", () => ({
+      mergeTreeSettings: need().mergeTreeSettings,
+      querySettings: need().querySettings,
+    })),
+    catalogResource("clickhouse-functions", "ClickHouse Functions", "Function names, with which are aggregate and which are aliases", () => need().functions),
+  ];
+}

package/src/mcp/mcp.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, test } from "vitest";
+import { sqlPlugin } from "../plugin";
+import { sqlMcpResources, sqlMcpTools } from "./index";
+
+const tool = (name: string) => sqlMcpTools().find((t) => t.name === name)!;
+
+describe("sql MCP tools", () => {
+  test("the plugin registers them", () => {
+    expect(sqlPlugin.mcpTools?.().map((t) => t.name).sort()).toEqual(["lookup", "parse-ddl", "search", "classify-change", "sql:diff"].sort());
+    expect(sqlPlugin.mcpResources?.().length).toBeGreaterThan(0);
+  });
+
+  test("lookup finds an engine and a setting", async () => {
+    const e = (await tool("lookup").handler({ kind: "engine", name: "ReplacingMergeTree" })) as { matches: Array<{ syntax: string }> };
+    expect(e.matches[0]!.syntax).toContain("ReplacingMergeTree");
+    const s = (await tool("lookup").handler({ kind: "setting", name: "index_granularity" })) as { matches: Array<{ scope: string }> };
+    expect(s.matches.map((m) => m.scope)).toContain("merge-tree");
+  });
+
+  test("lookup of an unknown name offers close ones", async () => {
+    const r = (await tool("lookup").handler({ kind: "engine", name: "Replacing" })) as { matches: unknown[]; closest: string[] };
+    expect(r.matches).toEqual([]);
+    expect(r.closest).toContain("ReplacingMergeTree");
+  });
+
+  test("lookup refuses an unknown kind", async () => {
+    await expect(tool("lookup").handler({ kind: "nope", name: "x" })).rejects.toThrow(/kind must be one of/);
+  });
+
+  test("search narrows by substring and limits", async () => {
+    const r = (await tool("search").handler({ kind: "codec", query: "zstd", limit: 1 })) as { total: number; results: unknown[] };
+    expect(r.total).toBeGreaterThan(0);
+    expect(r.results).toHaveLength(1);
+  });
+
+  test("parse-ddl returns the entity", async () => {
+    const r = (await tool("parse-ddl").handler({
+      tag: "table",
+      ddl: "CREATE TABLE events (user_id UUID, ts DateTime) ENGINE = MergeTree ORDER BY (user_id, ts)",
+    })) as { ok: boolean; name: string; props: { columns: unknown[]; engine: { name: string } } };
+    expect(r.ok).toBe(true);
+    expect(r.name).toBe("events");
+    expect(r.props.columns).toHaveLength(2);
+    expect(r.props.engine.name).toBe("MergeTree");
+  });
+
+  test("parse-ddl reports a syntax error at its line and column", async () => {
+    const r = (await tool("parse-ddl").handler({ tag: "table", ddl: "CREATE TABLE t (\n  a Strin g\n) ENGINE = Log" })) as {
+      ok: boolean;
+      rule: string;
+      line: number;
+      column: number;
+    };
+    expect(r).toMatchObject({ ok: false, rule: "SQLCH001", line: 2, column: 11 });
+  });
+});
+
+describe("sql classify-change", () => {
+  const build = (ddl: string) => JSON.stringify({ dialect: "clickhouse", objects: [{ export: "events", ddl }] });
+  const base = "CREATE TABLE events (id UInt64, kind String) ENGINE = MergeTree ORDER BY id";
+
+  test("classifies a changed engine as a rebuild with its restriction", async () => {
+    const r = (await tool("classify-change").handler({
+      before: build(base),
+      after: build(base.replace("MergeTree", "ReplacingMergeTree")),
+    })) as { summary: Record<string, number>; rebuilds: unknown[]; changes: Array<{ class: string; cite: string }> };
+    expect(r.summary.rebuild).toBeGreaterThan(0);
+    expect(r.rebuilds.length).toBeGreaterThan(0);
+    expect(r.changes[0]!.cite).toMatch(/^https:/);
+  });
+
+  test("identical builds have no changes", async () => {
+    const r = (await tool("classify-change").handler({ before: build(base), after: build(base) })) as { changes: unknown[] };
+    expect(r.changes).toEqual([]);
+  });
+});
+
+describe("sql classify-change for Postgres", () => {
+  const build = (...ddl: string[]) =>
+    JSON.stringify({ dialect: "postgres", objects: ddl.map((d, i) => ({ export: `t${i}`, type: "Postgres::Table", ddl: d })) });
+  const orders = "CREATE TABLE app.orders (id bigint PRIMARY KEY, amount numeric(12,2) NOT NULL, note varchar(20))";
+  type R = {
+    dialect: string;
+    summary: Record<string, number>;
+    changes: Array<{ field: string; rule: string; class: string; cite: string; restriction: string }>;
+    refused: Array<{ rule: string; advice: string }>;
+    report: string;
+  };
+
+  test("dispatches on the dialect the build names, with class, rule and citation", async () => {
+    const r = (await tool("classify-change").handler({
+      before: build(orders),
+      after: build(orders.replace("note varchar(20)", "note varchar(20), tag text")),
+    })) as R;
+    expect(r.dialect).toBe("postgres");
+    expect(r.changes).toHaveLength(1);
+    expect(r.changes[0]).toMatchObject({ field: "columns.tag", rule: "SQLPG201", class: "metadata" });
+    expect(r.changes[0]!.cite).toMatch(/^https:\/\/www\.postgresql\.org\/docs\/18\//);
+    expect(r.changes[0]!.restriction).toMatch(/ADD COLUMN/);
+    expect(r.refused).toEqual([]);
+  });
+
+  test("a change only expand and contract can make is refused", async () => {
+    const r = (await tool("classify-change").handler({
+      before: build(orders),
+      after: build(orders.replace("amount numeric(12,2)", "amount text")),
+    })) as R;
+    expect(r.summary.expand).toBeGreaterThan(0);
+    expect(r.refused.length).toBeGreaterThan(0);
+    expect(r.refused[0]!.advice).toMatch(/expand and contract/);
+    expect(r.report).toMatch(/Refused/);
+  });
+
+  test("the dialect argument and the major are honoured", async () => {
+    const stored = "CREATE TABLE t (a int, b int GENERATED ALWAYS AS (a * 2) STORED)";
+    const r = (changed: string, major?: number) =>
+      tool("classify-change").handler({ dialect: "postgres", major, before: build(stored), after: build(changed) }) as Promise<R>;
+    const changed = stored.replace("a * 2", "a * 3");
+    expect((await r(changed, 17)).changes[0]!.class).toBe("rewrite");
+    expect((await r(changed, 16)).changes[0]!.class).toBe("expand");
+  });
+
+  test("identical builds have no changes", async () => {
+    const r = (await tool("classify-change").handler({ before: build(orders), after: build(orders) })) as R;
+    expect(r.changes).toEqual([]);
+  });
+});
+
+describe("sql MCP resources", () => {
+  test("serve JSON from the catalog", async () => {
+    const byUri = (uri: string) => sqlMcpResources().find((r) => r.uri === uri)!;
+    expect(JSON.parse(await byUri("clickhouse-pin").handler()).version).toMatch(/^\d+\.\d+/);
+    expect(JSON.parse(await byUri("clickhouse-engines").handler()).tableEngines.length).toBeGreaterThan(50);
+    expect(JSON.parse(await byUri("clickhouse-types").handler()).length).toBeGreaterThan(50);
+  });
+});
+
+describe("sql MCP tools for Postgres", () => {
+  test("lookup finds a type, an access method and a storage parameter", async () => {
+    const t = (await tool("lookup").handler({ dialect: "postgres", kind: "type", name: "int4" })) as { matches: Array<{ aliasOf: string }> };
+    expect(t.matches[0]!.aliasOf).toBe("integer");
+    const m = (await tool("lookup").handler({ dialect: "postgres", kind: "index-method", name: "gin" })) as { matches: Array<{ properties: string[] }> };
+    expect(m.matches[0]!.properties.length).toBeGreaterThan(0);
+    const s = (await tool("lookup").handler({ dialect: "postgres", kind: "storage-parameter", name: "fillfactor" })) as { matches: Array<{ targets: string[] }> };
+    expect(s.matches[0]!.targets).toContain("table");
+  });
+
+  test("a function carries since, and major narrows", async () => {
+    const all = (await tool("lookup").handler({ dialect: "postgres", kind: "function", name: "array_sort" })) as { matches: Array<{ since?: number }> };
+    expect(all.matches[0]!.since).toBe(18);
+    const at15 = (await tool("lookup").handler({ dialect: "postgres", kind: "function", name: "array_sort", major: 15 })) as { matches: unknown[]; closest: string[] };
+    expect(at15.matches).toEqual([]);
+    await expect(tool("lookup").handler({ dialect: "postgres", kind: "function", name: "x", major: 13 })).rejects.toThrow(/major must be one of/);
+  });
+
+  test("lookup refuses a ClickHouse kind for Postgres", async () => {
+    await expect(tool("lookup").handler({ dialect: "postgres", kind: "engine", name: "x" })).rejects.toThrow(/kind must be one of/);
+  });
+
+  test("search", async () => {
+    const r = (await tool("search").handler({ dialect: "postgres", kind: "keyword", query: "defer", limit: 5 })) as { total: number };
+    expect(r.total).toBeGreaterThan(0);
+  });
+
+  test("parse-ddl returns the entity", async () => {
+    const r = (await tool("parse-ddl").handler({ dialect: "postgres", tag: "table", ddl: "CREATE TABLE app.t (id bigint PRIMARY KEY, n text NOT NULL)" })) as { ok: boolean; entityType: string; name: string; props: { columns: unknown[] } };
+    expect(r).toMatchObject({ ok: true, entityType: "Postgres::Table", name: "app.t" });
+    expect(r.props.columns).toHaveLength(2);
+  });
+
+  test("parse-ddl reports SQLPG001 at line and column", async () => {
+    const r = (await tool("parse-ddl").handler({ dialect: "postgres", tag: "table", ddl: "CREATE TABLE t (\n  a ARRAY[4]\n)" })) as { ok: boolean; rule: string; line: number };
+    expect(r).toMatchObject({ ok: false, rule: "SQLPG001", line: 2 });
+  });
+
+  test("the postgres resources are registered under the sql namespace", async () => {
+    const uris = sqlMcpResources().map((r) => r.uri);
+    expect(uris).toEqual(expect.arrayContaining(["postgres-pin", "postgres-types", "postgres-access-methods", "postgres-storage-parameters", "postgres-functions", "postgres-keywords", "postgres-settings", "clickhouse-engines"]));
+    const pin = JSON.parse(await sqlMcpResources().find((r) => r.uri === "postgres-pin")!.handler()) as { pins: unknown[] };
+    expect(pin.pins).toHaveLength(5);
+    const fns = JSON.parse(await sqlMcpResources().find((r) => r.uri === "postgres-functions")!.handler()) as Array<{ name: string; since?: number }>;
+    expect(fns.find((f) => f.name === "array_sort")?.since).toBe(18);
+  });
+});

package/src/mcp/postgres.ts

@@ -0,0 +1,125 @@
+/**
+ * The Postgres side of the sql MCP tools and resources (chant #3283). Rows
+ * come from the committed catalogs of the pinned servers, one per major; a
+ * name present in only some majors carries `since` and `until`, as the
+ * generated types' `@since` / `@until` do.
+ */
+
+import type { McpResourceContribution } from "@intentius/chant/mcp/types";
+import { POSTGRES_LATEST_MAJOR, POSTGRES_MAJORS, POSTGRES_PINS, postgresImage } from "../spec/postgres-pin";
+import { section, type Section } from "../lsp/postgres-catalog";
+import * as pg from "../postgres/entities";
+import { SqlSyntaxError } from "../postgres/tokens";
+
+export const POSTGRES_KINDS = ["type", "index-method", "table-method", "storage-parameter", "setting", "function", "keyword", "extension"] as const;
+export type PostgresKind = (typeof POSTGRES_KINDS)[number];
+
+type Row = { name: string; summary?: string; since?: number; until?: number };
+
+const SECTION: Record<PostgresKind, Section> = {
+  type: "types",
+  "index-method": "accessMethods",
+  "table-method": "accessMethods",
+  "storage-parameter": "storageParameters",
+  setting: "settings",
+  function: "functions",
+  keyword: "keywords",
+  extension: "extensions",
+};
+
+export function asPostgresKind(value: unknown): PostgresKind {
+  if (!POSTGRES_KINDS.includes(value as PostgresKind)) throw new Error(`kind must be one of: ${POSTGRES_KINDS.join(", ")}`);
+  return value as PostgresKind;
+}
+
+/** The major a tool call is about: `major` when given, else every major (undefined). */
+export function asMajor(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const n = Number(value);
+  if (!POSTGRES_MAJORS.includes(n)) throw new Error(`major must be one of: ${POSTGRES_MAJORS.join(", ")}`);
+  return n;
+}
+
+/** The rows of a kind, each with its range; only those at `major` when one is given. */
+export function postgresRows(kind: PostgresKind, major?: number): Row[] {
+  const s = section<Record<string, unknown> & { type?: string; description?: string }>(SECTION[kind]);
+  if (!s) throw new Error("the Postgres catalog snapshots could not be read");
+  const wantType = kind === "index-method" ? "index" : kind === "table-method" ? "table" : undefined;
+  const out: Row[] = [];
+  for (const e of s.values()) {
+    if (major !== undefined && !e.majors.includes(major)) continue;
+    if (wantType && e.row.type !== wantType) continue;
+    const summary = typeof e.row.description === "string" ? e.row.description : e.detail;
+    out.push({ ...(e.row as object), name: e.name, ...(summary ? { summary } : {}), ...e.range } as Row);
+  }
+  return out;
+}
+
+export function postgresLookup(params: Record<string, unknown>): unknown {
+  const kind = asPostgresKind(params.kind);
+  const major = asMajor(params.major);
+  const name = String(params.name ?? "");
+  const all = postgresRows(kind, major);
+  const exact = all.filter((r) => r.name === name);
+  const found = exact.length ? exact : all.filter((r) => r.name.toLowerCase() === name.toLowerCase());
+  const base = { dialect: "postgres", kind, majors: major !== undefined ? [major] : POSTGRES_MAJORS };
+  if (found.length) return { ...base, matches: found };
+  const near = all.filter((r) => r.name.toLowerCase().includes(name.toLowerCase())).slice(0, 10).map((r) => r.name);
+  return { ...base, matches: [], closest: near };
+}
+
+export function postgresSearch(params: Record<string, unknown>): unknown {
+  const kind = asPostgresKind(params.kind);
+  const query = String(params.query ?? "").toLowerCase();
+  const limit = Math.max(1, Math.min(200, Number(params.limit ?? 25)));
+  const hits = postgresRows(kind, asMajor(params.major)).filter((r) => r.name.toLowerCase().includes(query));
+  return {
+    dialect: "postgres",
+    kind,
+    total: hits.length,
+    results: hits.slice(0, limit).map((r) => ({ name: r.name, ...(r.summary ? { summary: r.summary } : {}), ...(r.since ? { since: r.since } : {}), ...(r.until ? { until: r.until } : {}) })),
+  };
+}
+
+const TAGS = { schema: pg.schema, table: pg.table, index: pg.index, view: pg.view, sequence: pg.sequence, type: pg.type, domain: pg.domain, extension: pg.extension } as const;
+export const POSTGRES_TAGS = Object.keys(TAGS);
+
+/** Parse one statement with the Postgres tag; an error comes back as SQLPG001 with its line and column. */
+export function postgresParse(tag: string, ddl: string, position: (text: string, offset: number) => { line: number; column: number }): unknown {
+  const build = (TAGS as Record<string, (s: TemplateStringsArray) => pg.PostgresObject>)[tag];
+  if (!build) throw new Error(`tag must be one of: ${POSTGRES_TAGS.join(", ")}`);
+  const strings = Object.assign([ddl], { raw: [ddl] }) as unknown as TemplateStringsArray;
+  try {
+    const entity = build(strings);
+    return { ok: true, dialect: "postgres", entityType: entity.entityType, name: entity.sqlName, props: JSON.parse(JSON.stringify((entity as unknown as { props: unknown }).props)) };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const offset = (err as { offset?: number }).offset;
+    const where = typeof offset === "number" ? position(ddl, offset) : undefined;
+    const syntax = err instanceof SqlSyntaxError || (err as Error).name === "SqlTemplateError";
+    return { ok: false, dialect: "postgres", rule: syntax ? "SQLPG001" : undefined, message, ...(where ?? {}) };
+  }
+}
+
+const json = (value: unknown) => JSON.stringify(value, null, 2);
+
+function resource(uri: string, name: string, description: string, read: () => unknown): McpResourceContribution {
+  return { uri, name, description, mimeType: "application/json", async handler() { return json(read()); } };
+}
+
+/** The Postgres resources: every supported major's names in one list, each with `since` / `until` when not in all. */
+export function postgresMcpResources(): McpResourceContribution[] {
+  const all = (...kinds: PostgresKind[]) => Object.fromEntries(kinds.map((k) => [k, postgresRows(k)]));
+  return [
+    resource("postgres-pin", "Postgres Pins", "The pinned server for each supported major the catalogs were read from", () => ({
+      latest: POSTGRES_LATEST_MAJOR,
+      pins: POSTGRES_PINS.map((p) => ({ ...p, image: postgresImage(p.major) })),
+    })),
+    resource("postgres-types", "Postgres Types", "Column types and their aliases, with since/until majors", () => postgresRows("type")),
+    resource("postgres-access-methods", "Postgres Access Methods", "Index access methods (btree, gin...) and table access methods", () => all("index-method", "table-method")),
+    resource("postgres-storage-parameters", "Postgres Storage Parameters", "WITH (...) parameters, the relation kinds that accept each, and their types", () => postgresRows("storage-parameter")),
+    resource("postgres-functions", "Postgres Functions", "Built-in function names with since/until majors", () => postgresRows("function")),
+    resource("postgres-keywords", "Postgres Keywords", "Key words and their categories", () => postgresRows("keyword")),
+    resource("postgres-settings", "Postgres Settings", "Server settings with type, default and range", () => postgresRows("setting")),
+  ];
+}