chore(mcp): split ooxml dispatch + add local e2e harness

The deployed Worker uses @neondatabase/serverless (HTTP-only) which
can't talk to local Postgres, so callOoxmlTool is now a thin
Neon-creating wrapper around runOoxmlTool, which takes any
tagged-template sql function. Tests and the new CLI use postgres.js
against local Docker; the Worker keeps Neon.

scripts/ooxml-call.ts dispatches the same code path the Worker uses.
Five PLAN.md acceptance queries verified against the real WML closure:

  ooxml_children("w:tbl")
    -> EG_RangeMarkupElements (group, 0..unbounded), tblPr (1..1),
       tblGrid (1..1), EG_ContentRowContent (group, 0..unbounded)

  ooxml_lookup_element("w:tblGrid")
    -> type_ref={...wml-main}CT_TblGridBase; in CT_Tbl context min/max=1
       (required, per Q1)

  ooxml_attributes("w:jc")
    -> single attr 'val' (required), type_ref to ST_Jc

  ooxml_enum("w:ST_Jc")
    -> 12 values incl. start/end (Strict) and left/right (Transitional)

  ooxml_lookup_element("w:notARealElement")
    -> 'Not found' card with profile and recovery hints

Author: caiopizzol

apps/mcp-server/src/ooxml-tools.ts

@@ -16,16 +16,16 @@ import {
 	type AttrEntry,
 	type ChildEdge,
 	type EnumEntry,
-	type NamespaceInfo,
-	type SymbolHit,
 	getAttributes,
 	getChildren,
 	getEnums,
 	getNamespaceInfo,
 	lookupElement,
 	lookupSymbolByTypeRef,
 	lookupType,
+	type NamespaceInfo,
 	parseQName,
+	type SymbolHit,
 } from "./ooxml-queries";
 
 export const DEFAULT_PROFILE = "transitional";
@@ -79,7 +79,8 @@ export const OOXML_TOOL_DEFS = [
 			properties: {
 				qname: {
 					type: "string",
-					description: "Element, complexType, or group qname (e.g. 'w:tbl', 'CT_Tbl', 'EG_PContent').",
+					description:
+						"Element, complexType, or group qname (e.g. 'w:tbl', 'CT_Tbl', 'EG_PContent').",
 				},
 				profile: { type: "string", description: "Profile name (default: 'transitional')." },
 			},
@@ -143,12 +144,30 @@ export function isOoxmlTool(name: string): name is OoxmlToolName {
 // biome-ignore lint/suspicious/noExplicitAny: neon's tagged template is loosely typed.
 type Sql = any;
 
+/**
+ * Worker-side entry point: constructs a Neon HTTP client from env and dispatches.
+ * Local CLIs and tests should call `runOoxmlTool` directly with their own sql
+ * (e.g. postgres.js against a local Postgres) to avoid the Neon HTTP path.
+ */
 export async function callOoxmlTool(
 	name: OoxmlToolName,
 	args: Record<string, unknown>,
 	env: OoxmlEnv,
 ): Promise<string> {
-	const sql: Sql = neon(env.DATABASE_URL);
+	const sql = neon(env.DATABASE_URL);
+	return runOoxmlTool(name, args, sql);
+}
+
+/**
+ * Driver-agnostic dispatch. `sql` is any tagged-template SQL function whose
+ * shape matches `(strings, ...values) => Promise<row[]>` (Neon and postgres.js
+ * both qualify).
+ */
+export async function runOoxmlTool(
+	name: OoxmlToolName,
+	args: Record<string, unknown>,
+	sql: Sql,
+): Promise<string> {
 	const profile = (args.profile as string | undefined) ?? DEFAULT_PROFILE;
 
 	switch (name) {
@@ -175,7 +194,11 @@ export async function callOoxmlTool(
 					profile,
 				);
 			}
-			return formatSymbolReport(hit.kind === "simpleType" ? "SimpleType" : "ComplexType", hit, profile);
+			return formatSymbolReport(
+				hit.kind === "simpleType" ? "SimpleType" : "ComplexType",
+				hit,
+				profile,
+			);
 		}
 
 		case "ooxml_children": {
@@ -286,7 +309,9 @@ function formatSymbolReport(label: string, hit: SymbolHit, profile: string): str
 	lines.push(`## ${label}: ${hit.localName}`);
 	lines.push("");
 	lines.push(`- profile: ${profile}`);
-	lines.push(`- canonical: (vocabulary=${hit.vocabularyId}, kind=${hit.kind}, name=${hit.localName})`);
+	lines.push(
+		`- canonical: (vocabulary=${hit.vocabularyId}, kind=${hit.kind}, name=${hit.localName})`,
+	);
 	lines.push(`- namespace: ${hit.namespaceUri}`);
 	if (hit.typeRef) lines.push(`- type_ref: ${hit.typeRef}`);
 	if (hit.sourceName) lines.push(`- source: ${hit.sourceName}`);

package.json

@@ -24,6 +24,7 @@
     "xsd:fetch": "bun scripts/fetch-xsd.ts",
     "xsd:smoke": "bun scripts/ingest-xsd/smoke.ts",
     "xsd:ingest": "bun scripts/ingest-xsd/ingest.ts",
+    "ooxml:call": "bun scripts/ooxml-call.ts",
     "test": "bun test tests/",
     "ingest": "bun scripts/ingest/pipeline.ts",
     "ingest:chunk": "bun scripts/ingest/chunk.ts",

scripts/ooxml-call.ts

@@ -0,0 +1,56 @@
+/**
+ * Local end-to-end harness for the Phase 4 OOXML tools.
+ *
+ * The deployed Worker uses @neondatabase/serverless (HTTP-only), which can't
+ * talk to local Postgres. This CLI bypasses the Worker and dispatches through
+ * `runOoxmlTool` directly with a postgres.js-backed sql function, so the same
+ * code path that the Worker exercises runs end-to-end against the dev DB.
+ *
+ * Usage:
+ *   bun scripts/ooxml-call.ts <tool> <jsonArgs>
+ *   bun scripts/ooxml-call.ts ooxml_children '{"qname":"w:tbl"}'
+ *   bun scripts/ooxml-call.ts ooxml_attributes '{"qname":"w:pBdr"}'
+ *   bun scripts/ooxml-call.ts ooxml_enum '{"qname":"w:ST_Jc"}'
+ *
+ * Environment:
+ *   DATABASE_URL - postgres connection string (defaults to local docker)
+ */
+
+import { createDbClient } from "../packages/shared/src/db/index.ts";
+import {
+	type OoxmlToolName,
+	isOoxmlTool,
+	runOoxmlTool,
+} from "../apps/mcp-server/src/ooxml-tools.ts";
+
+async function main() {
+	const [, , toolArg, argsArg] = process.argv;
+	if (!toolArg) {
+		console.error("Usage: bun scripts/ooxml-call.ts <tool> [jsonArgs]");
+		console.error("Tools: ooxml_lookup_element, ooxml_lookup_type, ooxml_children,");
+		console.error("       ooxml_attributes, ooxml_enum, ooxml_namespace_info");
+		process.exit(1);
+	}
+	if (!isOoxmlTool(toolArg)) {
+		console.error(`Unknown tool: ${toolArg}`);
+		process.exit(1);
+	}
+
+	const args: Record<string, unknown> = argsArg ? JSON.parse(argsArg) : {};
+
+	const databaseUrl =
+		process.env.DATABASE_URL ?? "postgresql://postgres:postgres@localhost:5432/ecma_spec";
+	const db = createDbClient(databaseUrl);
+
+	try {
+		const text = await runOoxmlTool(toolArg as OoxmlToolName, args, db.sql);
+		console.log(text);
+	} finally {
+		await db.close();
+	}
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});