wasm-mcp 0.1.0

package/dist/mcp/tools/proposal_list.js

@@ -0,0 +1,44 @@
+// MCP tool: proposal_list — list WebAssembly proposals and their
+// phases from the pinned WebAssembly/proposals repository. Filterable
+// by status / phase / champion / affected spec / free-text.
+import { z } from "zod";
+import { loadProposals } from "../../spec/spec_data.js";
+import { listProposals } from "../../spec/proposals_query.js";
+import { PROPOSAL_STATUSES } from "../../parser/proposals.js";
+export const proposalListSchema = {
+    status: z
+        .enum(PROPOSAL_STATUSES)
+        .optional()
+        .describe("Filter by lifecycle status: `phase-0`…`phase-5`, `finished` (merged into the spec), or `inactive`."),
+    phase: z
+        .number()
+        .int()
+        .min(0)
+        .max(5)
+        .optional()
+        .describe("Filter by numeric phase 0–5 (active + finished proposals carry a phase)."),
+    champion: z.string().min(1).optional().describe("Champion substring, case-insensitive."),
+    affects: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Filter to finished proposals affecting a given spec: `core`, `js-api`, or `web-api`."),
+    contains: z.string().min(1).optional().describe("Name or champion substring, case-insensitive."),
+};
+export const proposalListExamples = [
+    {
+        q: "What proposals are finished and in Wasm 3.0?",
+        input: { status: "finished", affects: "core" },
+        note: "Finished proposals carry affected_specs + spec_version; filter by the spec they touched.",
+    },
+    {
+        q: "What's in phase 3?",
+        input: { phase: 3 },
+        note: "Phase filter scopes to one stage of the proposal process.",
+    },
+];
+export function proposalList(args) {
+    const { pin, proposals } = loadProposals();
+    const filtered = listProposals(proposals, args);
+    return { pin: { sha: pin.sha }, count: filtered.length, proposals: filtered };
+}

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

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { SpecClause } from "../../parser/sections.js";
+import type { SpecName } from "../../spec/catalog.js";
+import type { VersionValue } from "../../versions.js";
+export declare const sectionGetSchema: {
+    id: z.ZodString;
+    spec: z.ZodDefault<z.ZodEnum<{
+        core: "core";
+        "js-api": "js-api";
+        "web-api": "web-api";
+    }>>;
+    version: z.ZodDefault<z.ZodEnum<{
+        main: "main";
+        latest: "latest";
+    }>>;
+};
+export type SectionGetArgs = {
+    id: string;
+    spec?: SpecName;
+    version?: VersionValue;
+};
+export declare const sectionGetExamples: {
+    q: string;
+    input: {
+        id: string;
+    };
+    note: string;
+}[];
+export declare function sectionGet(args: SectionGetArgs): SpecClause | null;

package/dist/mcp/tools/section_get.js

@@ -0,0 +1,32 @@
+// MCP tool: section_get — fetch one spec clause by id or anchor
+// (e.g. `syntax-numtype`, `valid-unreachable`, `binary-instr`).
+// Returns the clause's title, cleaned prose, cross-references, the
+// SpecTec formal-rule names it references, and the rendered URL.
+import { z } from "zod";
+import { versionArg, specArg } from "../_args.js";
+import { loadSections } from "../../spec/spec_data.js";
+import { getClause } from "../../spec/sections_query.js";
+export const sectionGetSchema = {
+    id: z
+        .string()
+        .min(1)
+        .describe("Clause id or anchor. For `core`: `syntax-numtype`, `valid-unreachable`, `binary-instr`, … For `js-api` / `web-api`: `modules`, `memories`, `streaming-modules`, … These match the stable fragment ids in the rendered spec."),
+    spec: specArg,
+    version: versionArg,
+};
+export const sectionGetExamples = [
+    {
+        q: "Get the number types section",
+        input: { id: "syntax-numtype" },
+        note: "Returns the Number Types clause: prose, the i32/i64/f32/f64 formal refs, and the spec URL.",
+    },
+    {
+        q: "Read the validation rule anchor for unreachable",
+        input: { id: "valid-unreachable" },
+        note: "Validation/execution clauses are SpecTec-spliced; prose may be terse but `formal_refs` names the rule and `url` links the rendered notation.",
+    },
+];
+export function sectionGet(args) {
+    const sections = loadSections(args.spec ?? "core", args.version);
+    return getClause(sections, args.id);
+}

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

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { type SectionSummary } from "../../spec/sections_query.js";
+import type { SpecName } from "../../spec/catalog.js";
+import type { VersionValue } from "../../versions.js";
+export declare const sectionListSchema: {
+    spec: z.ZodDefault<z.ZodEnum<{
+        core: "core";
+        "js-api": "js-api";
+        "web-api": "web-api";
+    }>>;
+    path: z.ZodOptional<z.ZodString>;
+    anchor_prefix: z.ZodOptional<z.ZodString>;
+    titled_only: z.ZodDefault<z.ZodBoolean>;
+    max_level: z.ZodOptional<z.ZodNumber>;
+    version: z.ZodDefault<z.ZodEnum<{
+        main: "main";
+        latest: "latest";
+    }>>;
+};
+export type SectionListArgs = {
+    spec?: SpecName;
+    path?: string;
+    anchor_prefix?: string;
+    titled_only?: boolean;
+    max_level?: number;
+    version?: VersionValue;
+};
+export declare const sectionListExamples: ({
+    q: string;
+    input: {
+        path: string;
+        titled_only: boolean;
+        anchor_prefix?: undefined;
+    };
+    note: string;
+} | {
+    q: string;
+    input: {
+        anchor_prefix: string;
+        path?: undefined;
+        titled_only?: undefined;
+    };
+    note: string;
+})[];
+export interface SectionListResult {
+    count: number;
+    sections: SectionSummary[];
+}
+export declare function sectionList(args: SectionListArgs): SectionListResult;

package/dist/mcp/tools/section_list.js

@@ -0,0 +1,56 @@
+// MCP tool: section_list — enumerate spec clauses for navigation,
+// optionally filtered by source path (structure / validation /
+// execution / binary / text live under distinct paths), anchor
+// prefix, heading presence, or depth. Returns lightweight rows;
+// follow up with section_get.
+import { z } from "zod";
+import { versionArg, specArg } from "../_args.js";
+import { loadSections } from "../../spec/spec_data.js";
+import { listSections } from "../../spec/sections_query.js";
+export const sectionListSchema = {
+    spec: specArg,
+    path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Filter to a source path / prefix. Top-level areas: `intro`, `syntax` (structure), `valid` (validation), `exec` (execution), `binary`, `text`, `appendix`. Sub-paths like `syntax/types` also work."),
+    anchor_prefix: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Filter to clauses whose id/anchor starts with this prefix, e.g. `syntax-`, `valid-`, `exec-`."),
+    titled_only: z
+        .boolean()
+        .default(false)
+        .describe("Drop anchor-only content blocks (keep only clauses with a heading)."),
+    max_level: z
+        .number()
+        .int()
+        .min(1)
+        .max(6)
+        .optional()
+        .describe("Cap heading depth (1 = page titles only). Anchor-only blocks are unaffected."),
+    version: versionArg,
+};
+export const sectionListExamples = [
+    {
+        q: "Outline the binary format sections",
+        input: { path: "binary", titled_only: true },
+        note: "Path filter scopes to one area; titled_only yields a clean outline.",
+    },
+    {
+        q: "List every validation clause",
+        input: { anchor_prefix: "valid-" },
+        note: "Anchor-prefix filter gathers all clauses in one rule family.",
+    },
+];
+export function sectionList(args) {
+    const sections = loadSections(args.spec ?? "core", args.version);
+    const out = listSections(sections, {
+        path: args.path,
+        anchor_prefix: args.anchor_prefix,
+        titled_only: args.titled_only,
+        max_level: args.max_level,
+    });
+    return { count: out.length, sections: out };
+}

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

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { type SpecSearchHit } from "../../spec/sections_query.js";
+import type { SpecName } from "../../spec/catalog.js";
+import type { VersionValue } from "../../versions.js";
+export declare const specSearchSchema: {
+    query: z.ZodString;
+    spec: z.ZodDefault<z.ZodEnum<{
+        core: "core";
+        "js-api": "js-api";
+        "web-api": "web-api";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    version: z.ZodDefault<z.ZodEnum<{
+        main: "main";
+        latest: "latest";
+    }>>;
+};
+export type SpecSearchArgs = {
+    query: string;
+    spec?: SpecName;
+    limit?: number;
+    version?: VersionValue;
+};
+export declare const specSearchExamples: {
+    q: string;
+    input: {
+        query: string;
+    };
+    note: string;
+}[];
+export interface SpecSearchResult {
+    count: number;
+    hits: SpecSearchHit[];
+}
+export declare function specSearch(args: SpecSearchArgs): SpecSearchResult;

package/dist/mcp/tools/spec_search.js

@@ -0,0 +1,34 @@
+// MCP tool: spec_search — full-text-ish search across the spec
+// section index (anchors, titles, and prose). The entry point when
+// you don't know the exact anchor. Returns ranked lightweight hits
+// with a matched_on field and a prose snippet for body matches.
+import { z } from "zod";
+import { versionArg, specArg } from "../_args.js";
+import { loadSections } from "../../spec/spec_data.js";
+import { searchSpec } from "../../spec/sections_query.js";
+export const specSearchSchema = {
+    query: z
+        .string()
+        .min(1)
+        .describe("Search text. Matched against clause anchors/ids, titles, and prose. E.g. `block type`, `trap`, `funcref`, `streaming compilation`."),
+    spec: specArg,
+    limit: z.number().int().min(1).max(100).default(20).describe("Max ranked hits returned."),
+    version: versionArg,
+};
+export const specSearchExamples = [
+    {
+        q: "Where does the spec define traps?",
+        input: { query: "trap" },
+        note: "Ranks title matches above prose matches; prose hits include a snippet around the match.",
+    },
+    {
+        q: "Find the block type section",
+        input: { query: "block type" },
+        note: "Title substring search surfaces syntax-blocktype near the top.",
+    },
+];
+export function specSearch(args) {
+    const sections = loadSections(args.spec ?? "core", args.version);
+    const hits = searchSpec(sections, args.query, args.limit ?? 20);
+    return { count: hits.length, hits };
+}

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

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export declare const specVersionSchema: {};
+export interface SpecVersionPin {
+    /** Pin key, e.g. `spec/main` or `proposals/main`. */
+    key: string;
+    /** Full upstream commit SHA pinned for this snapshot. */
+    sha: string;
+}
+export interface SpecVersionResult {
+    /** Package name as published to npm. */
+    name: string;
+    /** Package version read from package.json at runtime. */
+    version: string;
+    /** Pins baked into the package (core spec + proposals). */
+    pins: SpecVersionPin[];
+}
+export declare const SpecVersionResultSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    pins: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        sha: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function specVersion(packageInfo: {
+    name: string;
+    version: string;
+}): SpecVersionResult;

package/dist/mcp/tools/spec_version.js

@@ -0,0 +1,30 @@
+// `spec_version` — return the pinned upstream commits + package
+// version. Reads the pin from the baked artifacts (which ship in the
+// package), NOT from vendor/PINNED.txt (which is a build-time-only
+// input and is absent from the published package). The simplest
+// read-only tool; serves as a freshness probe and a smoke test that
+// the data pipeline ran.
+import { z } from "zod";
+import { loadSnapshot, loadProposals } from "../../spec/spec_data.js";
+export const specVersionSchema = {};
+const PinSchema = z.object({ key: z.string(), sha: z.string() });
+export const SpecVersionResultSchema = z.object({
+    name: z.string(),
+    version: z.string(),
+    pins: z.array(PinSchema),
+});
+export function specVersion(packageInfo) {
+    const pins = [];
+    const spec = loadSnapshot();
+    pins.push({ key: spec.pin.key, sha: spec.pin.sha });
+    // Proposals are a separate, optional artifact (separate upstream
+    // repo + pin). Tolerate its absence so the core tool still works.
+    try {
+        const proposals = loadProposals();
+        pins.push({ key: proposals.pin.key, sha: proposals.pin.sha });
+    }
+    catch {
+        // proposals index not built — omit it from the pin list.
+    }
+    return { name: packageInfo.name, version: packageInfo.version, pins };
+}

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

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { type TypeEntry } from "../../parser/types.js";
+import type { VersionValue } from "../../versions.js";
+export declare const typeGetSchema: {
+    name: z.ZodString;
+    version: z.ZodDefault<z.ZodEnum<{
+        main: "main";
+        latest: "latest";
+    }>>;
+};
+export type TypeGetArgs = {
+    name: string;
+    version?: VersionValue;
+};
+export declare const typeGetExamples: {
+    q: string;
+    input: {
+        name: string;
+    };
+    note: string;
+}[];
+export declare function typeGet(args: TypeGetArgs): TypeEntry | null;

package/dist/mcp/tools/type_get.js

@@ -0,0 +1,31 @@
+// MCP tool: type_get — look up a WebAssembly type or type form by
+// name (`i32`, `funcref`, `v128`, `functype`, `limits`, …). Returns
+// its classification, sibling members for category types, defining
+// clause prose, formal-rule references, and the rendered spec URL.
+import { z } from "zod";
+import { versionArg } from "../_args.js";
+import { loadTypes } from "../../spec/spec_data.js";
+import { getType } from "../../parser/types.js";
+export const typeGetSchema = {
+    name: z
+        .string()
+        .min(1)
+        .describe("Type or type-form name. Concrete value types: `i32`, `i64`, `f32`, `f64`, `v128`, `funcref`, `externref`, … Type forms: `functype`, `limits`, `memtype`, `tabletype`, `globaltype`, `reftype`, `valtype`, `rectype`, `heaptype`, … Case-insensitive, exact match."),
+    version: versionArg,
+};
+export const typeGetExamples = [
+    {
+        q: "What is the i32 type?",
+        input: { name: "i32" },
+        note: "Returns kind=number, the sibling number types (i64/f32/f64), and the Number Types clause prose + URL.",
+    },
+    {
+        q: "Describe a function type",
+        input: { name: "functype" },
+        note: "Type forms like functype/limits/memtype resolve to their defining clause in the types section.",
+    },
+];
+export function typeGet(args) {
+    const catalog = loadTypes(args.version);
+    return getType(catalog, args.name);
+}

package/dist/parser/bikeshed.d.ts

@@ -0,0 +1,8 @@
+import type { SpecClause } from "./sections.js";
+/** Map a Bikeshed spec path + anchor to the rendered spec URL. */
+export declare function bikeshedUrl(path: string, anchor: string | null): string;
+/**
+ * Parse a Bikeshed document into clauses. `path` is the spec slug
+ * (`js-api` or `web-api`).
+ */
+export declare function parseBikeshed(source: string, path: string): SpecClause[];

package/dist/parser/bikeshed.js

@@ -0,0 +1,106 @@
+// Parse the Bikeshed (.bs) sources for the JS-API and Web-API specs
+// into the same anchor-addressable `SpecClause` shape the RST parser
+// produces, so the section query functions work unchanged across all
+// three specs.
+//
+// Unlike the core spec (reStructuredText + SpecTec), the js-api and
+// web-api specs are authored in Bikeshed and use plain HTML headings
+// with stable ids — `<h2 id="modules">Modules</h2>` — which map
+// directly to the fragment ids in the rendered spec. Bodies mix HTML,
+// Web IDL blocks, and Bikeshed autolink shorthands; we strip those to
+// readable prose and record the cross-reference targets.
+const SPEC_BASE = "https://webassembly.github.io/spec";
+/** Map a Bikeshed spec path + anchor to the rendered spec URL. */
+export function bikeshedUrl(path, anchor) {
+    const page = `${SPEC_BASE}/${path}/`;
+    return anchor ? `${page}#${anchor}` : page;
+}
+/** Strip inline HTML tags and decode the few entities we encounter. */
+function stripTags(s) {
+    return s
+        .replace(/<[^>]+>/g, "")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&")
+        .replace(/&quot;/g, '"')
+        .trim();
+}
+/**
+ * Clean a Bikeshed body block into readable prose, collecting
+ * cross-reference targets as a side effect. Removes fenced/`<pre>`
+ * code + IDL blocks, resolves Bikeshed autolink shorthands, and
+ * strips remaining HTML.
+ */
+function cleanBody(raw, crossrefs) {
+    let text = raw;
+    // Drop fenced code blocks (```...```), <pre>/<xmp> blocks (IDL,
+    // algorithms, examples) — they aren't prose.
+    text = text.replace(/```[\s\S]*?```/g, " ");
+    text = text.replace(/<(pre|xmp)\b[^>]*>[\s\S]*?<\/\1>/gi, " ");
+    // Bikeshed autolinks:
+    //   [=term=]            definition autolink
+    //   [=term|display=]    definition with custom text
+    //   {{IdlThing}}        IDL autolink
+    //   [[#anchor]]         local section ref
+    //   [[BIBLIO]]          bibliography ref
+    text = text.replace(/\[=([^=\]|]+)(?:\|([^=\]]+))?=\]/g, (_m, term, disp) => {
+        crossrefs.add(term.trim());
+        return (disp ?? term).trim();
+    });
+    text = text.replace(/\{\{([^}]+)\}\}/g, (_m, idl) => {
+        const name = idl.split("/")[0].trim();
+        crossrefs.add(name);
+        return name;
+    });
+    text = text.replace(/\[\[#([^\]]+)\]\]/g, (_m, anchor) => {
+        crossrefs.add(anchor.trim());
+        return anchor.trim();
+    });
+    text = text.replace(/\[\[!?([A-Z0-9-]+)\]\]/g, "$1");
+    // Bikeshed algorithm-variable markers: |source| → source.
+    text = text.replace(/\|([A-Za-z][A-Za-z0-9 _]*)\|/g, "$1");
+    // Markdown emphasis / inline code → plain text.
+    text = text.replace(/\*\*([^*]+)\*\*/g, "$1").replace(/\*([^*]+)\*/g, "$1");
+    text = text.replace(/`([^`]+)`/g, "$1");
+    // Remaining HTML tags + entities.
+    text = stripTags(text);
+    return text.replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim();
+}
+const HEADING_RE = /<h([1-6])\s+id="([^"]+)"[^>]*>([\s\S]*?)<\/h\1>/gi;
+/**
+ * Parse a Bikeshed document into clauses. `path` is the spec slug
+ * (`js-api` or `web-api`).
+ */
+export function parseBikeshed(source, path) {
+    // Locate every heading with its byte offset so we can slice the
+    // body that follows each one (up to the next heading).
+    const heads = [];
+    for (const m of source.matchAll(HEADING_RE)) {
+        heads.push({
+            level: Number(m[1]),
+            anchor: m[2],
+            title: stripTags(m[3]),
+            start: m.index,
+            end: m.index + m[0].length,
+        });
+    }
+    const clauses = [];
+    for (let i = 0; i < heads.length; i++) {
+        const h = heads[i];
+        const bodyEnd = i + 1 < heads.length ? heads[i + 1].start : source.length;
+        const crossrefs = new Set();
+        const prose = cleanBody(source.slice(h.end, bodyEnd), crossrefs);
+        clauses.push({
+            id: h.anchor,
+            anchors: [h.anchor],
+            title: h.title || null,
+            level: h.level,
+            path,
+            prose,
+            crossrefs: [...crossrefs],
+            formal_refs: [],
+            url: bikeshedUrl(path, h.anchor),
+        });
+    }
+    return clauses;
+}