wasm-mcp 0.1.0

package/dist/mcp/_args.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+/**
+ * Which WebAssembly specification to query. `core` (default) is the
+ * instruction set / validation / execution / formats; `js-api` and
+ * `web-api` are the JavaScript + Web embedding specs. Only the
+ * section/search tools are spec-aware — instruction and type tools are
+ * `core`-only.
+ */
+export declare const specArg: z.ZodDefault<z.ZodEnum<{
+    core: "core";
+    "js-api": "js-api";
+    "web-api": "web-api";
+}>>;
+/**
+ * The spec version selector. `latest` (default) resolves to the
+ * current served version; `main` is the working draft. More release
+ * labels (e.g. `3.0`) can be added without changing tool code.
+ */
+export declare const versionArg: z.ZodDefault<z.ZodEnum<{
+    main: "main";
+    latest: "latest";
+}>>;

package/dist/mcp/_args.js

@@ -0,0 +1,25 @@
+// Shared Zod argument fragments reused across tool input schemas, so
+// every tool describes the `version` selector identically.
+import { z } from "zod";
+import { VERSION_VALUES } from "../versions.js";
+import { SPEC_NAMES } from "../spec/catalog.js";
+/**
+ * Which WebAssembly specification to query. `core` (default) is the
+ * instruction set / validation / execution / formats; `js-api` and
+ * `web-api` are the JavaScript + Web embedding specs. Only the
+ * section/search tools are spec-aware — instruction and type tools are
+ * `core`-only.
+ */
+export const specArg = z
+    .enum(SPEC_NAMES)
+    .default("core")
+    .describe("Which WebAssembly spec to query: `core` (default; instructions, types, validation, execution, formats), `js-api` (JavaScript embedding), or `web-api` (Web platform integration).");
+/**
+ * The spec version selector. `latest` (default) resolves to the
+ * current served version; `main` is the working draft. More release
+ * labels (e.g. `3.0`) can be added without changing tool code.
+ */
+export const versionArg = z
+    .enum(VERSION_VALUES)
+    .default("latest")
+    .describe("WebAssembly spec version to query. `latest` (default) is the current served version; `main` is the upstream working draft.");

package/dist/mcp/instructions.d.ts

@@ -0,0 +1 @@
+export declare const SERVER_INSTRUCTIONS: string;

package/dist/mcp/instructions.js

@@ -0,0 +1,67 @@
+// Server-level instructions surfaced to MCP clients during the
+// initialize handshake. Clients that forward `instructions` into the
+// LLM's system prompt give the agent this guidance automatically.
+//
+// Keep it focused on workflows and invariants; per-tool detail lives
+// in each tool's `description`.
+import { HOSTED_TOOLS, STDIO_ONLY_TOOLS, TOTAL_TOOL_COUNT } from "../spec/tool_inventory.js";
+export const SERVER_INSTRUCTIONS = `
+wasm-mcp serves read-only structured data from the WebAssembly core
+specification (https://github.com/WebAssembly/spec). Every response
+is deterministic over data pinned to a specific upstream commit and
+baked into the package at build time.
+
+Unofficial, community-maintained — not affiliated with, endorsed by,
+or sponsored by the W3C WebAssembly Community Group or Working Group.
+
+Common workflow:
+  1. \`spec_version\` — call first when you need to cite the spec or
+     report what you're reading. Returns the pinned upstream commit.
+  2. \`instruction_search\` — find an instruction from a partial name
+     or symptom ("extend", "trunc", "0x6a") when you don't know the
+     exact mnemonic. Returns ranked lightweight hits.
+  3. \`instruction_get { mnemonic }\` or \`{ opcode }\` — the full
+     record for one instruction: opcode bytes, category, stack type
+     signature, and validation/execution prose anchors + URLs.
+  4. \`instruction_list { category? }\` — enumerate instructions,
+     filterable by category, introducing version, or mnemonic prefix.
+  5. \`type_get { name }\` — a value type or type form ('i32',
+     'funcref', 'functype', 'limits') with its defining clause prose.
+  6. \`spec_search { query }\` — full-text search across clause
+     anchors, titles, and prose when you don't know the anchor.
+  7. \`section_get { id, spec? }\` — one spec clause by anchor (e.g.
+     'syntax-numtype', 'valid-unreachable'): prose, cross-refs,
+     SpecTec formal-rule references, and the rendered URL.
+  8. \`section_list { spec?, path? }\` — navigate the clause tree,
+     scoped to an area ('syntax', 'valid', 'exec', 'binary', 'text',
+     'appendix').
+
+The section tools (section_get / section_list / spec_search) cover
+three specs via a 'spec' argument: 'core' (default — the instruction
+set, validation, execution, binary + text formats), 'js-api' (the
+JavaScript embedding API), and 'web-api' (Web-platform integration).
+The instruction and type tools are 'core'-only.
+  9. \`proposal_list { status? }\` — WebAssembly proposals and their
+     phases, from the pinned WebAssembly/proposals repo.
+
+Note on formal notation. Since 2025 the spec is authored in SpecTec;
+validation / execution clauses are generated from formal rules. This
+server keeps the hand-written prose and records each clause's SpecTec
+rule names in 'formal_refs', with 'url' linking the rendered
+notation. It does not itself render the formal grammar / reduction
+rules — follow the URL for those.
+
+The tool surface is intentionally narrow:
+  - Read-only. No tool mutates state or writes to disk / the network.
+  - Deterministic. Same input → same output, over the pinned commit.
+  - No execution. Tools never compile, validate-by-running,
+    instantiate, or run any WebAssembly or arbitrary code. Validation
+    and reduction rules are returned as data (the prose / typing
+    judgement), not by applying them.
+
+Transport differences:
+  - The stdio server (npx wasm-mcp) exposes all ${TOTAL_TOOL_COUNT} tools.
+  - The hosted Cloudflare Worker exposes ${HOSTED_TOOLS.length} of them.
+  - Tools that need a subprocess or filesystem (${STDIO_ONLY_TOOLS.length} today)
+    are stdio-only.
+`.trim();

package/dist/mcp/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// wasm-mcp — Model Context Protocol server for the WebAssembly core
+// specification.
+//
+// Read-only, SHA-pinned, structured lookup. Runs as a stdio MCP
+// server (for local Claude Code use). A hosted Cloudflare Worker
+// deployment will reuse the same tool implementations behind a
+// streamable-HTTP transport (see `worker/`).
+//
+// Every tool is registered from the shared TOOLS registry in
+// ./tool_meta.ts — the same array the docs generator reads, so the
+// server and its documentation can't drift.
+//
+// Wire into Claude Code by adding to your project's `.mcp.json`:
+//
+//   {
+//     "mcpServers": {
+//       "wasm": {
+//         "type": "stdio",
+//         "command": "npx",
+//         "args": ["wasm-mcp"]
+//       }
+//     }
+//   }
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SERVER_INSTRUCTIONS } from "./instructions.js";
+import { TOOLS, setPackageInfo } from "./tool_meta.js";
+function readPackageInfo() {
+    try {
+        const req = createRequire(import.meta.url);
+        const path = req.resolve("../../package.json");
+        const pkg = JSON.parse(readFileSync(path, "utf8"));
+        return { name: pkg.name ?? "wasm-mcp", version: pkg.version ?? "unknown" };
+    }
+    catch {
+        return { name: "wasm-mcp", version: "unknown" };
+    }
+}
+const PACKAGE = readPackageInfo();
+setPackageInfo(PACKAGE);
+const server = new McpServer({ name: PACKAGE.name, version: PACKAGE.version }, { instructions: SERVER_INSTRUCTIONS });
+for (const tool of TOOLS) {
+    server.registerTool(tool.name, {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: { readOnlyHint: true },
+    }, async (args) => {
+        const result = tool.handler(args ?? {});
+        if (result === null || result === undefined) {
+            return {
+                content: [{ type: "text", text: `No result for ${tool.name}. Try a search tool.` }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/mcp/tool_meta.d.ts

@@ -0,0 +1,32 @@
+import type { ZodRawShape } from "zod";
+/** One usage example shown in the docs tool reference. */
+export interface ToolExample {
+    /** Plain-language question this call answers. */
+    q: string;
+    /** The `arguments` object passed to the tool. */
+    input: Record<string, unknown>;
+    /** Optional note on what the result looks like / why. */
+    note?: string;
+}
+/**
+ * A tool's complete public definition. `handler` returns either the
+ * result payload (serialised as JSON text) or null. Returning null
+ * is rendered as an isError response by the server.
+ */
+export interface ToolMeta {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: ZodRawShape;
+    examples: ToolExample[];
+    handler: (args: Record<string, unknown>) => unknown;
+}
+export declare const TOOLS: ToolMeta[];
+export declare let PACKAGE_INFO: {
+    name: string;
+    version: string;
+};
+export declare function setPackageInfo(info: {
+    name: string;
+    version: string;
+}): void;

package/dist/mcp/tool_meta.js

@@ -0,0 +1,100 @@
+// Single source of truth for the tool surface: name, title,
+// description, Zod input schema, handler, and usage examples for
+// every tool. Both the stdio server (src/mcp/server.ts) and the docs
+// generator (src/docs/build_docs.ts) consume this array, so a tool's
+// description and examples live in exactly one place and can't drift
+// between the running server and its documentation.
+import { specVersion, specVersionSchema } from "./tools/spec_version.js";
+import { instructionGet, instructionGetSchema, instructionGetExamples, } from "./tools/instruction_get.js";
+import { instructionList, instructionListSchema, instructionListExamples, } from "./tools/instruction_list.js";
+import { instructionSearch, instructionSearchSchema, instructionSearchExamples, } from "./tools/instruction_search.js";
+import { typeGet, typeGetSchema, typeGetExamples } from "./tools/type_get.js";
+import { sectionGet, sectionGetSchema, sectionGetExamples } from "./tools/section_get.js";
+import { sectionList, sectionListSchema, sectionListExamples } from "./tools/section_list.js";
+import { specSearch, specSearchSchema, specSearchExamples } from "./tools/spec_search.js";
+import { proposalList, proposalListSchema, proposalListExamples } from "./tools/proposal_list.js";
+export const TOOLS = [
+    {
+        name: "spec_version",
+        title: "Pinned spec version",
+        description: "Return self-description of this MCP server: package name + version, plus the pinned upstream commit SHA for every spec snapshot baked into the package. Use this first when citing the spec, or to verify the server's freshness and reproducibility.",
+        inputSchema: specVersionSchema,
+        examples: [],
+        handler: () => specVersion(PACKAGE_INFO),
+    },
+    {
+        name: "instruction_get",
+        title: "Get instruction",
+        description: "Fetch one WebAssembly instruction by mnemonic (`i32.add`, `br_if`) or binary opcode (`0x6a`, `0xfd 0x89 0x02`) as structured JSON: opcode bytes, category, introducing version, stack type signature, and validation/execution prose anchors + spec URLs. Provide `mnemonic` or `opcode` (mnemonic wins if both match).",
+        inputSchema: instructionGetSchema,
+        examples: instructionGetExamples,
+        handler: (a) => instructionGet(a),
+    },
+    {
+        name: "instruction_list",
+        title: "List instructions",
+        description: "Enumerate WebAssembly instructions with optional filters: `category` (control, numeric, parametric, variable, table, memory, ref, i31, struct, array, extern, vec), `introduced_in` (1.0 | 2.0 | 3.0), and `prefix` (mnemonic prefix like `i32.`). Returns lightweight rows sorted by opcode; follow up with instruction_get for full detail.",
+        inputSchema: instructionListSchema,
+        examples: instructionListExamples,
+        handler: (a) => instructionList(a),
+    },
+    {
+        name: "instruction_search",
+        title: "Search instructions",
+        description: "Search WebAssembly instructions by free-text query, matched against mnemonic (exact > substring), category name, and opcode hex. The entry point when you don't know the exact mnemonic. Returns ranked lightweight hits with a `matched_on` field; follow up with instruction_get.",
+        inputSchema: instructionSearchSchema,
+        examples: instructionSearchExamples,
+        handler: (a) => instructionSearch(a),
+    },
+    {
+        name: "type_get",
+        title: "Get type",
+        description: "Look up a WebAssembly type or type form by name: concrete value types (`i32`, `i64`, `f32`, `f64`, `v128`, `funcref`, `externref`, …) or type forms (`functype`, `limits`, `memtype`, `tabletype`, `globaltype`, `reftype`, `valtype`, `rectype`, `heaptype`, …). Returns its classification, sibling members for category types, defining clause prose, SpecTec formal-rule references, and the rendered spec URL.",
+        inputSchema: typeGetSchema,
+        examples: typeGetExamples,
+        handler: (a) => typeGet(a),
+    },
+    {
+        name: "section_get",
+        title: "Get spec section",
+        description: "Fetch one spec clause by id or anchor, across `core` / `js-api` / `web-api` (set `spec`). For core: `syntax-numtype`, `valid-unreachable`, `binary-instr`, … For the embedding specs: `modules`, `memories`, `streaming-modules`, … Matches the rendered spec's stable fragment ids. Returns the clause title, cleaned prose, cross-references, the SpecTec `formal_refs` it cites (core), and the rendered URL. Core validation/execution clauses are SpecTec-generated: prose may be terse, but formal_refs + url point to the formal rule.",
+        inputSchema: sectionGetSchema,
+        examples: sectionGetExamples,
+        handler: (a) => sectionGet(a),
+    },
+    {
+        name: "section_list",
+        title: "List spec sections",
+        description: "Enumerate spec clauses for navigation, across `core` / `js-api` / `web-api` (set `spec`). Filter by source `path` (core: `intro`, `syntax`, `valid`, `exec`, `binary`, `text`, `appendix`, or sub-paths like `syntax/types`), `anchor_prefix`, `titled_only`, and `max_level`. Returns lightweight rows {id, anchors, title, level, path, url}; follow up with section_get.",
+        inputSchema: sectionListSchema,
+        examples: sectionListExamples,
+        handler: (a) => sectionList(a),
+    },
+    {
+        name: "spec_search",
+        title: "Search spec",
+        description: "Full-text search across the section index of a spec (`core` / `js-api` / `web-api`, set `spec`) — clause anchors/ids, titles, and prose. The entry point when you don't know the exact anchor. Returns ranked hits with a `matched_on` field (anchor-exact > title > anchor > prose) and a prose snippet for body matches; follow up with section_get.",
+        inputSchema: specSearchSchema,
+        examples: specSearchExamples,
+        handler: (a) => specSearch(a),
+    },
+    {
+        name: "proposal_list",
+        title: "List WebAssembly proposals",
+        description: "List WebAssembly proposals and their phases from the pinned WebAssembly/proposals repository. Filter by `status` (phase-0…phase-5, finished, inactive), `phase` (0–5), `champion` substring, `affects` (finished proposals touching core / js-api / web-api), or `contains` (name/champion substring). Each row carries name, status, phase, champion, affected_specs, spec_version, and the proposal URL.",
+        inputSchema: proposalListSchema,
+        examples: proposalListExamples,
+        handler: (a) => proposalList(a),
+    },
+];
+// The server injects the real package info before registering tools;
+// the docs generator never calls the spec_version handler, so a
+// placeholder is fine there. Kept module-scoped so the TOOLS array
+// stays a plain literal.
+export let PACKAGE_INFO = {
+    name: "wasm-mcp",
+    version: "0.0.0",
+};
+export function setPackageInfo(info) {
+    PACKAGE_INFO = info;
+}

package/dist/mcp/tools/instruction_get.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import type { InstructionRecord } from "../../parser/instructions.js";
+import type { VersionValue } from "../../versions.js";
+export declare const instructionGetSchema: {
+    mnemonic: z.ZodOptional<z.ZodString>;
+    opcode: z.ZodOptional<z.ZodString>;
+    version: z.ZodDefault<z.ZodEnum<{
+        main: "main";
+        latest: "latest";
+    }>>;
+};
+export type InstructionGetArgs = {
+    mnemonic?: string;
+    opcode?: string;
+    version?: VersionValue;
+};
+export declare const instructionGetExamples: ({
+    q: string;
+    input: {
+        mnemonic: string;
+        opcode?: undefined;
+    };
+    note: string;
+} | {
+    q: string;
+    input: {
+        opcode: string;
+        mnemonic?: undefined;
+    };
+    note: string;
+})[];
+export declare function instructionGet(args: InstructionGetArgs): InstructionRecord | null;

package/dist/mcp/tools/instruction_get.js

@@ -0,0 +1,39 @@
+// MCP tool: instruction_get — fetch one WebAssembly instruction by
+// mnemonic (`i32.add`) or binary opcode (`0x6a`). Returns the full
+// structured record: opcode bytes, category, version, stack type
+// signature, and validation/execution prose anchors + URLs.
+import { z } from "zod";
+import { versionArg } from "../_args.js";
+import { loadInstructions } from "../../spec/spec_data.js";
+import { getInstruction } from "../../spec/instructions_query.js";
+export const instructionGetSchema = {
+    mnemonic: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Instruction mnemonic, e.g. `i32.add`, `br_if`, `local.get`. Case-insensitive. Exact match."),
+    opcode: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Binary opcode as hex bytes, e.g. `0x6a`, `6a`, or multi-byte `0xfd 0x89 0x02`. Exact match. Used when `mnemonic` is absent or doesn't match."),
+    version: versionArg,
+};
+export const instructionGetExamples = [
+    {
+        q: "Get the i32.add instruction",
+        input: { mnemonic: "i32.add" },
+        note: "Returns opcode 0x6a, the [i32 i32] → [i32] signature, and validation/execution anchors.",
+    },
+    {
+        q: "What instruction is opcode 0x0d?",
+        input: { opcode: "0x0d" },
+        note: "Reverse lookup by binary opcode — resolves to br_if.",
+    },
+];
+export function instructionGet(args) {
+    if (args.mnemonic === undefined && args.opcode === undefined)
+        return null;
+    const records = loadInstructions(args.version);
+    return getInstruction(records, { mnemonic: args.mnemonic, opcode: args.opcode });
+}

package/dist/mcp/tools/instruction_list.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { type InstructionSummary } from "../../spec/instructions_query.js";
+import type { InstructionCategory } from "../../parser/instructions.js";
+import { WASM_VERSIONS } from "../../parser/instructions.js";
+import type { VersionValue } from "../../versions.js";
+export declare const instructionListSchema: {
+    category: z.ZodOptional<z.ZodEnum<{
+        control: "control";
+        numeric: "numeric";
+        parametric: "parametric";
+        variable: "variable";
+        table: "table";
+        memory: "memory";
+        ref: "ref";
+        i31: "i31";
+        struct: "struct";
+        array: "array";
+        extern: "extern";
+        vec: "vec";
+    }>>;
+    introduced_in: z.ZodOptional<z.ZodEnum<{
+        "1.0": "1.0";
+        "2.0": "2.0";
+        "3.0": "3.0";
+    }>>;
+    prefix: z.ZodOptional<z.ZodString>;
+    version: z.ZodDefault<z.ZodEnum<{
+        main: "main";
+        latest: "latest";
+    }>>;
+};
+export type InstructionListArgs = {
+    category?: InstructionCategory;
+    introduced_in?: (typeof WASM_VERSIONS)[number];
+    prefix?: string;
+    version?: VersionValue;
+};
+export declare const instructionListExamples: ({
+    q: string;
+    input: {
+        category: string;
+        introduced_in?: undefined;
+        prefix?: undefined;
+    };
+    note: string;
+} | {
+    q: string;
+    input: {
+        category: string;
+        introduced_in: string;
+        prefix?: undefined;
+    };
+    note: string;
+} | {
+    q: string;
+    input: {
+        prefix: string;
+        category?: undefined;
+        introduced_in?: undefined;
+    };
+    note: string;
+})[];
+export interface InstructionListResult {
+    count: number;
+    instructions: InstructionSummary[];
+}
+export declare function instructionList(args: InstructionListArgs): InstructionListResult;

package/dist/mcp/tools/instruction_list.js

@@ -0,0 +1,52 @@
+// MCP tool: instruction_list — enumerate WebAssembly instructions,
+// optionally filtered by category, version, or mnemonic prefix.
+// Returns lightweight rows (mnemonic, opcode bytes, category,
+// version); follow up with instruction_get for the full record.
+import { z } from "zod";
+import { versionArg } from "../_args.js";
+import { loadInstructions } from "../../spec/spec_data.js";
+import { listInstructions } from "../../spec/instructions_query.js";
+import { INSTRUCTION_CATEGORIES } from "../../parser/instructions.js";
+import { WASM_VERSIONS } from "../../parser/instructions.js";
+export const instructionListSchema = {
+    category: z
+        .enum(INSTRUCTION_CATEGORIES)
+        .optional()
+        .describe("Filter by instruction category: control, numeric, parametric, variable, table, memory, ref, i31, struct, array, extern, vec (vector/SIMD)."),
+    introduced_in: z
+        .enum(WASM_VERSIONS)
+        .optional()
+        .describe("Filter to instructions introduced in this WebAssembly version: `1.0`, `2.0`, or `3.0`."),
+    prefix: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Filter to mnemonics starting with this prefix, e.g. `i32.` or `v128.`. Case-insensitive."),
+    version: versionArg,
+};
+export const instructionListExamples = [
+    {
+        q: "List all control-flow instructions",
+        input: { category: "control" },
+        note: "Filters to the control category; rows are sorted by opcode.",
+    },
+    {
+        q: "What memory instructions did Wasm 3.0 add?",
+        input: { category: "memory", introduced_in: "3.0" },
+        note: "Combine category + introduced_in to see what a release contributed.",
+    },
+    {
+        q: "List the i32 numeric instructions",
+        input: { prefix: "i32." },
+        note: "Prefix filter is the quickest way to scope to one type family.",
+    },
+];
+export function instructionList(args) {
+    const records = loadInstructions(args.version);
+    const instructions = listInstructions(records, {
+        category: args.category,
+        version: args.introduced_in,
+        prefix: args.prefix,
+    });
+    return { count: instructions.length, instructions };
+}

package/dist/mcp/tools/instruction_search.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { type InstructionSearchHit } from "../../spec/instructions_query.js";
+import type { VersionValue } from "../../versions.js";
+export declare const instructionSearchSchema: {
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+    version: z.ZodDefault<z.ZodEnum<{
+        main: "main";
+        latest: "latest";
+    }>>;
+};
+export type InstructionSearchArgs = {
+    query: string;
+    limit?: number;
+    version?: VersionValue;
+};
+export declare const instructionSearchExamples: {
+    q: string;
+    input: {
+        query: string;
+    };
+    note: string;
+}[];
+export interface InstructionSearchResult {
+    count: number;
+    hits: InstructionSearchHit[];
+}
+export declare function instructionSearch(args: InstructionSearchArgs): InstructionSearchResult;

package/dist/mcp/tools/instruction_search.js

@@ -0,0 +1,33 @@
+// MCP tool: instruction_search — free-text search across instruction
+// mnemonics, categories, and opcodes. The entry point when you don't
+// know the exact mnemonic. Returns ranked lightweight hits; follow
+// up with instruction_get for the full record.
+import { z } from "zod";
+import { versionArg } from "../_args.js";
+import { loadInstructions } from "../../spec/spec_data.js";
+import { searchInstructions } from "../../spec/instructions_query.js";
+export const instructionSearchSchema = {
+    query: z
+        .string()
+        .min(1)
+        .describe("Search text. Matched against mnemonic (exact > substring), category name, and opcode hex. E.g. `extend`, `trunc`, `vec`, `0x6a`."),
+    limit: z.number().int().min(1).max(100).default(20).describe("Max ranked hits returned."),
+    version: versionArg,
+};
+export const instructionSearchExamples = [
+    {
+        q: "Find all the extend instructions",
+        input: { query: "extend" },
+        note: "Substring match across mnemonics surfaces i32.extend8_s, i64.extend_i32_u, etc.",
+    },
+    {
+        q: "Which instruction has opcode 0x6a?",
+        input: { query: "0x6a" },
+        note: "A hex query also matches by opcode — resolves i32.add at the top.",
+    },
+];
+export function instructionSearch(args) {
+    const records = loadInstructions(args.version);
+    const hits = searchInstructions(records, args.query, args.limit ?? 20);
+    return { count: hits.length, hits };
+}

package/dist/mcp/tools/proposal_list.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { PROPOSAL_STATUSES, type Proposal } from "../../parser/proposals.js";
+export declare const proposalListSchema: {
+    status: z.ZodOptional<z.ZodEnum<{
+        "phase-0": "phase-0";
+        "phase-1": "phase-1";
+        "phase-2": "phase-2";
+        "phase-3": "phase-3";
+        "phase-4": "phase-4";
+        "phase-5": "phase-5";
+        finished: "finished";
+        inactive: "inactive";
+    }>>;
+    phase: z.ZodOptional<z.ZodNumber>;
+    champion: z.ZodOptional<z.ZodString>;
+    affects: z.ZodOptional<z.ZodString>;
+    contains: z.ZodOptional<z.ZodString>;
+};
+export type ProposalListArgs = {
+    status?: (typeof PROPOSAL_STATUSES)[number];
+    phase?: number;
+    champion?: string;
+    affects?: string;
+    contains?: string;
+};
+export declare const proposalListExamples: ({
+    q: string;
+    input: {
+        status: string;
+        affects: string;
+        phase?: undefined;
+    };
+    note: string;
+} | {
+    q: string;
+    input: {
+        phase: number;
+        status?: undefined;
+        affects?: undefined;
+    };
+    note: string;
+})[];
+export interface ProposalListResult {
+    /** Pinned WebAssembly/proposals commit the list was indexed from. */
+    pin: {
+        sha: string;
+    };
+    count: number;
+    proposals: Proposal[];
+}
+export declare function proposalList(args: ProposalListArgs): ProposalListResult;