feat(mcp): add read-only OOXML structural tools (Phase 4)

Six new MCP tools, gated by the ENABLE_OOXML_TOOLS env var. tools/list
filters them out and tools/call returns method-not-found until the flag
is set, so api.ooxml.dev/mcp's existing surface (search_ecma_spec /
get_section / list_parts) is unaffected.

Tools:
  ooxml_lookup_element  qname (w:tbl, {ns}local, or bare) -> symbol info
  ooxml_lookup_type     qname -> complexType or simpleType symbol
  ooxml_children        element/type/group qname -> ordered child + group ref list
  ooxml_attributes      element/type qname -> attrs unfolded through inheritance
                        and attributeGroup refs
  ooxml_enum            simpleType qname -> enumeration values in declared order
  ooxml_namespace_info  uri -> profiles + symbol counts per profile

Query layer (apps/mcp-server/src/ooxml-queries.ts):
  - parseQName accepts known OOXML prefixes (w/r/s/m/a/wp/pic/c/dgm/xsd),
    Clark form, or bare local names (defaults to wml-main).
  - lookupElement / lookupType / lookupSymbolByTypeRef walk
    xsd_symbol_profiles for profile-scoped hits.
  - getChildren walks the xsd_inheritance_edges chain via a recursive CTE
    and unions self + base xsd_child_edges and xsd_group_edges (group refs)
    in document order. Each entry carries its compositor kind and the type
    that contributed it.
  - getAttributes does the same and additionally recurses through
    attributeGroup refs; each entry carries 'self' / 'inherited' /
    'attributeGroup' provenance with the owning name.
  - getEnums and getNamespaceInfo are direct profile-scoped lookups.

Tool dispatch (apps/mcp-server/src/ooxml-tools.ts):
  - For element qnames passed to ooxml_children / ooxml_attributes the
    handler looks up the element, follows type_ref to its complexType,
    then reads from there (per the Phase 4 caveat in PLAN.md).
  - ooxml_children also falls back to looking up groups by name so users
    can call it on EG_PContent etc.
  - Unknown qnames produce a 'Not found' card listing alternative formats
    and the searched profile.
  - Default profile is literal 'transitional' until Phase 6.

Response shape per PLAN.md: canonical symbol, namespace, type_ref where
relevant, source, and a behavior-notes placeholder hooked up to nothing
yet (Phase 5 fills it).

Tests: 15 query-layer tests against a fresh ingest of the existing
fixtures; passes alongside 21 ingest tests for a 36 / 0 total.

Worker bundle dry-runs at 263 KiB (67 KiB gzip).

Author: caiopizzol

apps/mcp-server/src/index.ts

@@ -16,6 +16,12 @@ import { handleMcpRequest } from "./mcp";
 export interface Env {
 	DATABASE_URL: string;
 	VOYAGE_API_KEY: string;
+	/**
+	 * Phase 4 feature flag. Set to "true" to expose ooxml_lookup_element /
+	 * ooxml_lookup_type / ooxml_children / ooxml_attributes / ooxml_enum /
+	 * ooxml_namespace_info via tools/list and tools/call. Default off.
+	 */
+	ENABLE_OOXML_TOOLS?: string;
 }
 
 // Part descriptions

apps/mcp-server/src/mcp.ts

@@ -7,6 +7,12 @@
 import { createDb } from "./db";
 import { embedQuery } from "./embeddings";
 import type { Env } from "./index";
+import {
+	OOXML_TOOL_DEFS,
+	callOoxmlTool,
+	isOoxmlTool,
+	ooxmlToolsEnabled,
+} from "./ooxml-tools";
 
 // JSON-RPC types
 interface JsonRpcRequest {
@@ -132,13 +138,12 @@ function handleInitialize(id: number | string | null): JsonRpcResponse {
 	};
 }
 
-function handleToolsList(id: number | string | null): JsonRpcResponse {
+function handleToolsList(id: number | string | null, env: Env): JsonRpcResponse {
+	const tools = ooxmlToolsEnabled(env) ? [...TOOLS, ...OOXML_TOOL_DEFS] : TOOLS;
 	return {
 		jsonrpc: "2.0",
 		id,
-		result: {
-			tools: TOOLS,
-		},
+		result: { tools },
 	};
 }
 
@@ -162,6 +167,25 @@ async function handleToolsCall(
 	try {
 		let resultText: string;
 
+		// Phase 4 OOXML tools, feature-flagged. tools/list also gates on the same flag,
+		// so callers should not see these tool names unless the flag is on. Defensive
+		// check here in case a caller hand-crafts a request.
+		if (isOoxmlTool(name)) {
+			if (!ooxmlToolsEnabled(env)) {
+				return {
+					jsonrpc: "2.0",
+					id,
+					error: { code: METHOD_NOT_FOUND, message: `Unknown tool: ${name}` },
+				};
+			}
+			resultText = await callOoxmlTool(name, args ?? {}, env);
+			return {
+				jsonrpc: "2.0",
+				id,
+				result: { content: [{ type: "text", text: resultText }] },
+			};
+		}
+
 		switch (name) {
 			case "search_ecma_spec": {
 				const query = args?.query as string;
@@ -374,7 +398,7 @@ export async function handleMcpRequest(request: Request, env: Env): Promise<Resp
 			return new Response(null, { status: 202 });
 
 		case "tools/list":
-			return jsonResponse(handleToolsList(id));
+			return jsonResponse(handleToolsList(id, env));
 
 		case "tools/call":
 			return jsonResponse(await handleToolsCall(id, body.params, env));