chore(mcp): address review nits (snapshot test, ToolDef, examples)

- Add tools/list + initialize snapshot tests so any future drift between
  TOOLS, OOXML_TOOL_DEFS, and the docs fails CI. Asserts the 9 expected
  ooxml_* names in documented order and serverInfo.name === 'ooxml'.
- Extract ToolDef interface and annotate both TOOLS and OOXML_TOOL_DEFS
  so a future field on either array (annotations, outputSchema) widens
  both consistently.
- Restore one prose example query so the /mcp page reads as 1 newcomer
  prose + 1 implementer prose + 2 schema, not jargon-heavy across the
  board.
- Bump root README MCP server badge from v0.0.1 to v0.14.0.

Worker auto-deploy concern (route still pointing at the old name) is
acknowledged as a manual route swap on merge per author's call.

Author: caiopizzol

README.md

@@ -1,7 +1,7 @@
 <img width="300" alt="logo" src="https://github.com/user-attachments/assets/df6311a6-c050-4592-bbf1-4a2228655bc3" />
 
 [![Web](https://img.shields.io/badge/Web-v0.1.3-blue)](https://ooxml.dev)
-[![MCP Server](https://img.shields.io/badge/MCP_Server-v0.0.1-blue)](https://api.ooxml.dev/mcp)
+[![MCP Server](https://img.shields.io/badge/MCP_Server-v0.14.0-blue)](https://api.ooxml.dev/mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 The OOXML spec, explained by people who actually implemented it.

apps/mcp-server/src/mcp.ts

@@ -37,8 +37,20 @@ const PART_DESCRIPTIONS: Record<number, string> = {
 	4: "Transitional Migration Features",
 };
 
+/** Shape of an MCP tool definition. Shared with OOXML_TOOL_DEFS so a future
+ * field added to one (annotations, outputSchema, etc.) widens both arrays. */
+export interface ToolDef {
+	name: string;
+	description: string;
+	inputSchema: {
+		type: "object";
+		properties: Record<string, unknown>;
+		required?: string[];
+	};
+}
+
 // Tool definitions
-export const TOOLS = [
+export const TOOLS: ToolDef[] = [
 	{
 		name: "ooxml_search",
 		description:

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

@@ -10,6 +10,7 @@
  */
 
 import { neon } from "@neondatabase/serverless";
+import type { ToolDef } from "./mcp";
 import {
 	type AttrEntry,
 	type ChildEdge,
@@ -33,7 +34,7 @@ export interface OoxmlEnv {
 	DATABASE_URL: string;
 }
 
-export const OOXML_TOOL_DEFS = [
+export const OOXML_TOOL_DEFS: ToolDef[] = [
 	{
 		name: "ooxml_element",
 		description:

apps/web/src/pages/Mcp.tsx

@@ -59,7 +59,7 @@ const SCHEMA_TOOLS = [
 
 const EXAMPLE_QUERIES = [
 	"How do I add borders to a table cell?",
-	"What's the difference between w:pPr and w:rPr?",
+	"How does numbering work in WordprocessingML?",
 	"What are the legal children of w:CT_Tbl?",
 	"List all attributes of w:CT_R, including inherited ones.",
 ];

tests/mcp-server/tools-list.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Snapshot the public MCP surface so a future rename or accidental drop
+ * (between TOOLS, OOXML_TOOL_DEFS, and the docs) fails CI.
+ *
+ * No DB access; we exercise tools/list and the initialize handler. tools/call
+ * is covered by the per-tool tests in ooxml-queries.test.ts.
+ */
+
+import { expect, test } from "bun:test";
+import { handleMcpRequest } from "../../apps/mcp-server/src/mcp.ts";
+
+const EXPECTED_TOOL_NAMES = [
+	// Prose search (over the spec PDFs)
+	"ooxml_search",
+	"ooxml_section",
+	"ooxml_parts",
+	// Schema lookup (over the parsed XSDs)
+	"ooxml_element",
+	"ooxml_type",
+	"ooxml_children",
+	"ooxml_attributes",
+	"ooxml_enum",
+	"ooxml_namespace",
+] as const;
+
+interface JsonRpcResponse {
+	jsonrpc: string;
+	id: number | string | null;
+	result?: { tools?: Array<{ name: string }>; serverInfo?: { name: string } };
+	error?: { code: number; message: string };
+}
+
+async function rpc(method: string, params?: unknown): Promise<JsonRpcResponse> {
+	const req = new Request("https://example.invalid/mcp", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+	});
+	// Env is unused for tools/list and initialize.
+	const env = { DATABASE_URL: "", VOYAGE_API_KEY: "" } as never;
+	const res = await handleMcpRequest(req, env);
+	return (await res.json()) as JsonRpcResponse;
+}
+
+test("tools/list returns the full ooxml_* tool set in the documented order", async () => {
+	const r = await rpc("tools/list");
+	const names = r.result?.tools?.map((t) => t.name) ?? [];
+	expect(names).toEqual([...EXPECTED_TOOL_NAMES]);
+});
+
+test("initialize advertises serverInfo.name as 'ooxml'", async () => {
+	const r = await rpc("initialize");
+	expect(r.result?.serverInfo?.name).toBe("ooxml");
+});