@aphrody/m3-mcp 0.0.0-stage → 3.3.4

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @aphrody/m3-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The design/UI MCP server of aphrody-m3 (stdio): packages, M3 tokens, docs, research links,
+templates, Material Symbols and desktop icons, served from this repository's files.
+
+```sh
+bun run start          # bun src/server.ts (stdio transport)
+```
+
+| Tool | Does |
+| --- | --- |
+| `m3_list_packages` | workspace packages with versions |
+| `m3_token_lookup`, `m3_token_validate` | look up and validate M3 tokens |
+| `m3_os_themes_list`, `m3_os_themes_generate` | OS theme targets of `@aphrody/m3-os-themes` (dry run) |
+| `m3_docs_search`, `m3_research_links` | search `docs/`, list research links |
+| `m3_list_templates` | `templates/` |
+| `m3_symbol_svg`, `m3_symbol_search` | Material Symbols SVG and catalogue search (`@aphrody/material-design-icons`) |
+| `m3_svg_to_ico` | SVG to Tauri desktop icons |
+
+Sources: `src/server.ts` (tool registration), `src/catalog.ts` (file-backed lookups). Tests:
+`bun test`; typecheck: `bun run typecheck`. Registered in the aphrody-labs plugins marketplace as
+the `aphrody-m3` plugin.

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@aphrody/m3-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.3.4",
+  "description": "Single design/UI MCP server of aphrody-m3: packages, M3 tokens (lookup, validate), docs search, research links, templates, Material Symbols SVG, SVG to Tauri icons.",
+  "type": "module",
+  "exports": {
+    ".": "./src/server.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "bun src/server.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@aphrody/m3-os-themes": "3.3.4",
+    "@aphrody/material-design-icons": "1.0.0",
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "zod": "^4.6.5"
+  },
+  "engines": {
+    "bun": ">=1.4.2"
+  }
+}

package/src/catalog.test.ts

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: Apache-2.0
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { loadTokens, lookupTokens, validateTokens } from "./catalog.ts";
+
+const scratch = mkdtempSync(join(tmpdir(), "m3-token-catalog-"));
+let fixtures = 0;
+afterAll(() => rmSync(scratch, { recursive: true, force: true }));
+
+function fixture(exports: Record<string, unknown>, files: Record<string, string>): string {
+  const root = join(scratch, String(fixtures++));
+  const pkg = join(root, "packages/m3-tokens");
+  mkdirSync(pkg, { recursive: true });
+  writeFileSync(join(pkg, "package.json"), JSON.stringify({ exports }));
+  for (const [path, text] of Object.entries(files)) {
+    const file = join(pkg, path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, text);
+  }
+  return root;
+}
+
+describe("the repository token catalogue", () => {
+  test("Expressive typography, motion and directional shapes can be looked up and validated", () => {
+    const names = [
+      "--md-sys-typescale-display-large-emphasized-font",
+      "--md-sys-motion-spring-expressive-fast-spatial-damping",
+      "--md-sys-shape-corner-large-start",
+    ];
+    for (const name of names) {
+      const tokens = lookupTokens(name);
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]?.source).toBe("packages/m3-tokens/src/expressive.css");
+    }
+    expect(lookupTokens(names[1]!)[0]?.value).toBe("0.6");
+    const input = names.map((name) => `var(${name})`).join(" ");
+    expect(validateTokens(input)).toEqual({ checked: names, unknown: [] });
+    expect(
+      validateTokens(`${input} var(--md-sys-motion-spring-expressive-fast-spatial-dampng)`).unknown,
+    ).toEqual(["--md-sys-motion-spring-expressive-fast-spatial-dampng"]);
+  });
+
+  test("base tokens, breakpoints and dynamic colour roles remain available without duplicates", () => {
+    expect(lookupTokens("corner-full")[0]?.value).toBe("9999px");
+    expect(lookupTokens("--md-breakpoint-expanded")[0]?.value).toBe("840px");
+    expect(lookupTokens("--md-sys-color-on-primary-container")[0]?.source).toBe(
+      "packages/m3-tokens/src/dynamic-color.ts",
+    );
+    const tokens = loadTokens();
+    expect(new Set(tokens.map((token) => token.name)).size).toBe(tokens.length);
+  });
+});
+
+describe("exported token sources", () => {
+  test("reads exported CSS rather than unrelated files and retains the first declaration's source", () => {
+    const root = fixture(
+      {
+        "./base.css": { default: "./src/base.css" },
+        "./alias.css": "./src/base.css",
+        "./extended.css": ["./src/extended.css"],
+        "./helpers": "./src/helpers.ts",
+      },
+      {
+        "src/base.css": `/* --md-commented-out: nope; */
+        :root { --md-sys-shape-corner-large: 16px; --md-sys-color-primary: #6750a4; }
+        .dark { --md-sys-shape-corner-large: 20px; }`,
+        "src/extended.css":
+          ":root { --md-sys-shape-corner-large: 32px; --md-sys-shape-corner-large-start: 16px 0 0 16px; }",
+        "src/unexported.css": ":root { --md-unexported: hidden; }",
+        "src/helpers.ts": "// --md-not-css: hidden;",
+        "src/dynamic-color.ts": `export const ROLES = ["primary", 'surfaceBright', "primary", /* "hiddenRole" */];`,
+      },
+    );
+    const tokens = loadTokens(root);
+    expect(tokens).toHaveLength(4);
+    expect(lookupTokens("--md-sys-shape-corner-large", 1, root)).toEqual([
+      {
+        name: "--md-sys-shape-corner-large",
+        value: "16px",
+        source: "packages/m3-tokens/src/base.css",
+      },
+    ]);
+    expect(lookupTokens("--md-sys-color-primary", 50, root)).toEqual([
+      {
+        name: "--md-sys-color-primary",
+        value: "#6750a4",
+        source: "packages/m3-tokens/src/base.css",
+      },
+    ]);
+    expect(lookupTokens("surface-bright", 50, root)).toEqual([
+      {
+        name: "--md-sys-color-surface-bright",
+        value: "(dynamic colour role)",
+        source: "packages/m3-tokens/src/dynamic-color.ts",
+      },
+    ]);
+    expect(
+      validateTokens(
+        "var(--md-sys-shape-corner-large-start) var(--md-sys-color-surface-bright)",
+        root,
+      ).unknown,
+    ).toEqual([]);
+    expect(
+      validateTokens(
+        "--md-unexported --md-commented-out --md-not-css --md-sys-color-hidden-role",
+        root,
+      ).unknown,
+    ).toEqual([
+      "--md-unexported",
+      "--md-commented-out",
+      "--md-not-css",
+      "--md-sys-color-hidden-role",
+    ]);
+  });
+
+  test("missing exported sheets do not hide present sheets or dynamic roles", () => {
+    const root = fixture(
+      {
+        "./missing.css": "./src/missing.css",
+        "./present.css": "./src/present.css",
+        "./outside.css": "../outside.css",
+      },
+      {
+        "src/present.css": ":root { --md-present: 1px; }",
+        "src/dynamic-color.ts": 'export const ROLES = ["onPrimaryContainer"];',
+      },
+    );
+    expect(loadTokens(root).map((token) => token.name)).toEqual([
+      "--md-present",
+      "--md-sys-color-on-primary-container",
+    ]);
+    expect(
+      validateTokens("--md-present --md-sys-color-on-primary-container --md-missing", root),
+    ).toEqual({
+      checked: ["--md-present", "--md-sys-color-on-primary-container", "--md-missing"],
+      unknown: ["--md-missing"],
+    });
+  });
+
+  test("an absent token checkout gives an empty catalogue and reports unknown references", () => {
+    const root = join(scratch, "absent");
+    expect(loadTokens(root)).toEqual([]);
+    expect(lookupTokens("primary", 50, root)).toEqual([]);
+    expect(validateTokens("var(--md-sys-color-primary)", root)).toEqual({
+      checked: ["--md-sys-color-primary"],
+      unknown: ["--md-sys-color-primary"],
+    });
+  });
+});

package/src/catalog.ts

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+export const ROOT = join(import.meta.dir, "../../..");
+
+const read = (p: string) => (existsSync(p) ? readFileSync(p, "utf8") : "");
+
+export function listPackages(root = ROOT): string[] {
+  const dir = join(root, "packages");
+  return readdirSync(dir).flatMap((d) => {
+    const p = join(dir, d, "package.json");
+    if (!existsSync(p)) return [];
+    const j = JSON.parse(readFileSync(p, "utf8"));
+    return [`${j.name}@${j.version ?? "0.0.0"}  packages/${d}`];
+  });
+}
+
+export interface Token {
+  name: string;
+  value: string;
+  source: string;
+}
+
+const kebab = (s: string) => s.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+
+/** Local CSS targets of the token package's exports, including conditional exports and aliases. */
+function exportedSheets(exports: unknown): string[] {
+  if (typeof exports === "string")
+    return exports.startsWith("./") && exports.endsWith(".css") && !exports.includes("*")
+      ? [exports]
+      : [];
+  if (Array.isArray(exports)) return exports.flatMap(exportedSheets);
+  if (exports && typeof exports === "object") return Object.values(exports).flatMap(exportedSheets);
+  return [];
+}
+
+/** Every exported `--md-*` CSS property and dynamic colour role, once per name. */
+export function loadTokens(root = ROOT): Token[] {
+  const pkg = join(root, "packages/m3-tokens");
+  const manifest = read(join(pkg, "package.json"));
+  const exports: unknown = manifest
+    ? (JSON.parse(manifest) as { exports?: unknown }).exports
+    : undefined;
+  const out = new Map<string, Token>();
+  const add = (token: Token) => {
+    // The first declaration is representative; theme/direction variants do not create new names.
+    if (!out.has(token.name)) out.set(token.name, token);
+  };
+  for (const target of new Set(exportedSheets(exports))) {
+    const file = resolve(pkg, target);
+    const path = relative(pkg, file).replaceAll("\\", "/");
+    if (
+      isAbsolute(path) ||
+      path === ".." ||
+      path.startsWith("../") ||
+      path.split("/").includes("node_modules")
+    )
+      continue;
+    const css = read(file).replace(/\/\*[\s\S]*?\*\//g, "");
+    for (const m of css.matchAll(/(--md-[\w-]+)\s*:\s*([^;]+);/g)) {
+      add({ name: m[1]!, value: m[2]!.trim(), source: `packages/m3-tokens/${path}` });
+    }
+  }
+  const dyn = read(join(pkg, "src/dynamic-color.ts"));
+  const roles = (/export const ROLES = \[([\s\S]*?)\]/.exec(dyn)?.[1] ?? "").replace(
+    /\/\*[\s\S]*?\*\/|\/\/[^\n]*/g,
+    "",
+  );
+  for (const m of roles.matchAll(/["'](\w+)["']/g)) {
+    add({
+      name: `--md-sys-color-${kebab(m[1]!)}`,
+      value: "(dynamic colour role)",
+      source: "packages/m3-tokens/src/dynamic-color.ts",
+    });
+  }
+  return [...out.values()];
+}
+
+export function lookupTokens(query: string, limit = 50, root = ROOT): Token[] {
+  const q = query.toLowerCase();
+  return loadTokens(root)
+    .filter((t) => t.name.includes(q) || t.value.toLowerCase().includes(q))
+    .slice(0, limit);
+}
+
+/** Validate token names or every `var(--md-*)` / `--md-*` reference found in a CSS snippet. */
+export function validateTokens(
+  input: string,
+  root = ROOT,
+): { checked: string[]; unknown: string[] } {
+  const known = new Set(loadTokens(root).map((t) => t.name));
+  const checked = [...new Set([...input.matchAll(/--md-[\w-]+/g)].map((m) => m[0]))];
+  return { checked, unknown: checked.filter((n) => !known.has(n)) };
+}
+
+function* walk(dir: string): Generator<string> {
+  for (const e of readdirSync(dir)) {
+    if (e === "node_modules" || e.startsWith(".git")) continue;
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) yield* walk(p);
+    else if (/\.(md|mdx)$/.test(e)) yield p;
+  }
+}
+
+export function searchDocs(query: string, limit = 20, root = ROOT): string[] {
+  const q = query.toLowerCase();
+  const hits: string[] = [];
+  const docs = join(root, "docs");
+  if (!existsSync(docs)) return hits;
+  for (const f of walk(docs)) {
+    const lines = read(f).split("\n");
+    for (let i = 0; i < lines.length && hits.length < limit; i++) {
+      if (lines[i]!.toLowerCase().includes(q))
+        hits.push(`${relative(root, f)}:${i + 1}: ${lines[i]!.trim().slice(0, 200)}`);
+    }
+    if (hits.length >= limit) break;
+  }
+  return hits;
+}
+
+export function researchLinks(root = ROOT): { files: string[]; links: string[] } {
+  const dir = join(root, "docs/research");
+  const files = existsSync(dir) ? [...walk(dir)].map((f) => relative(root, f)) : [];
+  const links = [
+    ...read(join(dir, "GOOGLE-LINKS.md")).matchAll(/^\|\s*([^|]+?)\s*\|\s*(https?:\/\/\S+)\s*\|/gm),
+  ].map((m) => `${m[1]}  ${m[2]}`);
+  return { files, links };
+}
+
+export function listTemplates(root = ROOT): string[] {
+  const rows: string[] = [];
+  for (const base of ["templates", "examples", "examples/tauri"]) {
+    const dir = join(root, base);
+    if (!existsSync(dir)) continue;
+    for (const e of readdirSync(dir)) {
+      if (statSync(join(dir, e)).isDirectory() && !(base === "examples" && e === "tauri"))
+        rows.push(`${base}/${e}`);
+    }
+  }
+  return rows;
+}

package/src/server.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env bun
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import type { Target } from "@aphrody/m3-os-themes";
+import {
+  ROOT,
+  listPackages,
+  listTemplates,
+  lookupTokens,
+  researchLinks,
+  searchDocs,
+  validateTokens,
+} from "./catalog";
+
+// The theme generators (16 ms with m3-tokens) and the symbol catalogue are loaded by the tools that use them, not at
+// start-up: the handshake with the client no longer waits for them.
+const osThemes = () => import("@aphrody/m3-os-themes");
+const symbols = () => import("@aphrody/material-design-icons");
+
+const text = (t: string) => ({ content: [{ type: "text" as const, text: t || "(no result)" }] });
+
+/** Construct the design server without connecting or taking ownership of stdin. */
+export function createM3McpServer(): McpServer {
+  const server = new McpServer({ name: "aphrody-m3", version: "1.1.0" });
+
+  server.tool(
+    "m3_list_packages",
+    "List the aphrody-m3 workspace packages with versions.",
+    {},
+    async () => text(listPackages().join("\n")),
+  );
+
+  server.tool(
+    "m3_token_lookup",
+    "Look up Material 3 design tokens (--md-*) by name or value fragment in m3-tokens.",
+    { query: z.string(), limit: z.number().int().min(1).max(500).default(50) },
+    async ({ query, limit }) =>
+      text(
+        lookupTokens(query, limit)
+          .map((t) => `${t.name}: ${t.value}  [${t.source}]`)
+          .join("\n"),
+      ),
+  );
+
+  server.tool(
+    "m3_token_validate",
+    "Validate that every --md-* custom property in a CSS snippet or name list exists in m3-tokens.",
+    { css: z.string() },
+    async ({ css }) => {
+      const r = validateTokens(css);
+      return text(
+        `checked ${r.checked.length}, unknown ${r.unknown.length}${r.unknown.length ? `\n${r.unknown.join("\n")}` : ""}`,
+      );
+    },
+  );
+
+  const themeInput = {
+    seed: z.string().describe("Seed colour #rrggbb"),
+    target: z.enum(["windows", "gnome", "cosmic", "chromium", "all"]).default("all"),
+    name: z.string().default("Aphrody"),
+  };
+
+  server.tool(
+    "m3_os_themes_list",
+    "List the files m3-os-themes would generate for a seed colour and target (nothing is written).",
+    themeInput,
+    async ({ seed, target, name }) => {
+      const { TARGETS, generate } = await osThemes();
+      const targets: readonly Target[] = target === "all" ? TARGETS : [target];
+      return text(
+        generate({ name, seed, mode: "auto" }, targets)
+          .map((f) => f.path)
+          .join("\n"),
+      );
+    },
+  );
+
+  server.tool(
+    "m3_os_themes_generate",
+    "Return the text content of one generated OS theme file (path from m3_os_themes_list). Never writes to disk or the system.",
+    { ...themeInput, path: z.string() },
+    async ({ seed, target, name, path }) => {
+      const { TARGETS, generate } = await osThemes();
+      const targets: readonly Target[] = target === "all" ? TARGETS : [target];
+      const file = generate({ name, seed, mode: "auto" }, targets).find((f) => f.path === path);
+      if (!file) return text(`unknown path ${path}`);
+      return text(
+        typeof file.content === "string" ? file.content : `(binary, ${file.content.length} bytes)`,
+      );
+    },
+  );
+
+  server.tool(
+    "m3_docs_search",
+    "Case-insensitive line search over aphrody-m3 docs/ (md, mdx); returns path:line hits.",
+    { query: z.string(), limit: z.number().int().min(1).max(500).default(20) },
+    async ({ query, limit }) => text(searchDocs(query, limit).join("\n")),
+  );
+
+  server.tool(
+    "m3_research_links",
+    "List docs/research files and the curated dated Google design/research link index.",
+    {},
+    async () => {
+      const r = researchLinks();
+      return text(`${r.files.join("\n")}\n\n${r.links.join("\n")}`);
+    },
+  );
+
+  server.tool(
+    "m3_list_templates",
+    "List UI templates, examples and Tauri example apps.",
+    {},
+    async () => text(listTemplates().join("\n")),
+  );
+
+  server.tool(
+    "m3_symbol_svg",
+    "Return path and SVG source of a Material Symbol from the forked catalogue.",
+    {
+      name: z.string().regex(/^[a-z0-9_]+$/),
+      style: z.enum(["outlined", "rounded", "sharp"]).default("outlined"),
+      weight: z
+        .union([
+          z.literal(100),
+          z.literal(200),
+          z.literal(300),
+          z.literal(400),
+          z.literal(500),
+          z.literal(600),
+          z.literal(700),
+        ])
+        .default(400),
+      filled: z.boolean().default(false),
+    },
+    async ({ name, style, weight, filled }) => {
+      const { symbolSvgPath } = await symbols();
+      const p = symbolSvgPath(name, style, weight, filled);
+      return existsSync(p) ? text(`${p}\n${readFileSync(p, "utf8")}`) : text(`not found: ${p}`);
+    },
+  );
+
+  server.tool(
+    "m3_symbol_search",
+    "Search the full Material Symbols catalogue (4150 names) by substring; returns matching symbol names.",
+    { query: z.string(), limit: z.number().int().min(1).max(500).default(50) },
+    async ({ query, limit }) => {
+      const { searchSymbols, symbolNames } = await symbols();
+      const hits = searchSymbols(query, limit);
+      return text(
+        hits.length > 0 ? hits.join("\n") : `no match among ${symbolNames().length} symbols`,
+      );
+    },
+  );
+
+  server.tool(
+    "m3_svg_to_ico",
+    "Generate Tauri desktop icons (ico, icns, png) from a symbol name or SVG file.",
+    {
+      input: z.string(),
+      out: z.string().default("src-tauri/icons"),
+      style: z.enum(["outlined", "rounded", "sharp"]).default("outlined"),
+      fill: z.string().optional(),
+    },
+    async ({ input, out, style, fill }, { signal }) => {
+      const args = [
+        "bun",
+        join(ROOT, "packages/material-design-icons/scripts/svg-to-ico.ts"),
+        input,
+        "--out",
+        out,
+        "--style",
+        style,
+      ];
+      if (fill) args.push("--fill", fill);
+      const child = Bun.spawn({
+        cmd: args,
+        stdout: "pipe",
+        stderr: "pipe",
+        signal,
+        timeout: 30_000,
+        killSignal: "SIGKILL",
+        maxBuffer: 1024 * 1024,
+      });
+      const [code, stdout, stderr] = await Promise.all([
+        child.exited,
+        new Response(child.stdout).text(),
+        new Response(child.stderr).text(),
+      ]);
+      return { ...text(`${code}\n${stdout}${stderr}`), ...(code !== 0 ? { isError: true } : {}) };
+    },
+  );
+
+  return server;
+}
+
+if (import.meta.main) {
+  void createM3McpServer()
+    .connect(new StdioServerTransport())
+    .catch((error: unknown) => {
+      console.error(error);
+      process.exitCode = 1;
+    });
+}

package/test/catalog.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+import {
+  listPackages,
+  listTemplates,
+  lookupTokens,
+  researchLinks,
+  searchDocs,
+  validateTokens,
+} from "../src/catalog";
+
+test("packages include m3-mcp", () => {
+  const p = listPackages().join("\n");
+  expect(p).toContain("@aphrody/m3-mcp");
+});
+test("token lookup and validation", () => {
+  expect(lookupTokens("corner-full")[0]?.value).toBe("9999px");
+  expect(lookupTokens("on-primary-container").length).toBeGreaterThan(0);
+  expect(validateTokens("a{color:var(--md-sys-color-primary);b:var(--md-nope)}").unknown).toEqual([
+    "--md-nope",
+  ]);
+});
+test("docs, research and templates", () => {
+  expect(searchDocs("Material", 3).length).toBeGreaterThan(0);
+  expect(researchLinks().links.length).toBeGreaterThan(20);
+  expect(listTemplates()).toContain("templates/react");
+});

package/test/protocol.test.ts

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+import { expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { createM3McpServer } from "../src/server.ts";
+
+test("the design server supports imported composition and a real MCP tool round trip", async () => {
+  const server = createM3McpServer();
+  const client = new Client({ name: "m3-test", version: "1.0.0" });
+  const [serverTransport, clientTransport] = InMemoryTransport.createLinkedPair();
+  try {
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    const tools = await client.listTools();
+    expect(tools.tools.map((tool) => tool.name)).toContain("m3_token_lookup");
+    expect(tools.tools.map((tool) => tool.name)).toContain("m3_os_themes_generate");
+    const result = await client.callTool({
+      name: "m3_token_lookup",
+      arguments: { query: "corner-full", limit: 1 },
+    });
+    expect(result.isError).not.toBe(true);
+    expect(JSON.stringify(result.content)).toContain("9999px");
+    const invalid = await client.callTool({
+      name: "m3_symbol_svg",
+      arguments: { name: "../../private" },
+    });
+    expect(invalid.isError).toBe(true);
+    const oversized = await client.callTool({
+      name: "m3_docs_search",
+      arguments: { query: "Material", limit: 501 },
+    });
+    expect(oversized.isError).toBe(true);
+  } finally {
+    await client.close();
+    await server.close();
+  }
+});
+
+test("the executable entry completes stdio handshake, discovery and tool execution", async () => {
+  const client = new Client({ name: "m3-stdio-test", version: "1.0.0" });
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [new URL("../src/server.ts", import.meta.url).pathname],
+    stderr: "pipe",
+  });
+  try {
+    await client.connect(transport);
+    expect((await client.listTools()).tools.length).toBeGreaterThan(10);
+    const result = await client.callTool({ name: "m3_list_packages", arguments: {} });
+    expect(result.isError).not.toBe(true);
+    expect(JSON.stringify(result.content)).toContain("@aphrody/m3-mcp");
+  } finally {
+    await client.close();
+  }
+}, 10_000);

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["bun"],
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src/**/*", "test/**/*"]
+}