@kumikijs/mcp 0.1.0

package/README.ja.md

@@ -0,0 +1,41 @@
+# @kumikijs/mcp
+
+[English](./README.md) · 日本語
+
+Kumiki コンパイラと AI 編集ツールチェインを **MCP（Model Context Protocol）サーバー**として公開する。エディタや AI エージェントから、Kumiki プログラムの検査・ビルド・ナビゲーション・編集・仕様参照を行える。
+
+## ツール
+
+| ツール | 用途 |
+|---|---|
+| `kumiki_check` | `source` または `path` をパース + 型検査し、診断を返す |
+| `kumiki_build` | 自己完結 JS モジュールへコンパイル（runtime インライン） |
+| `kumiki_smoke` | headless DOM に mount して UI を操作し、ランタイム例外・空描画・未処理 rejection を検出（check/build では捕まらない層） |
+| `kumiki_run_scenario` | シナリオ（操作列 + 状態アサーション）でアプリを駆動し、毎ステップの slot 状態・DOM・エラー・emit を trace として返す。人を介さない生成→実行→観測→修正ループの土台 |
+| `kumiki_list` | ファイル内の定義一覧（layer で絞り込み可） |
+| `kumiki_view` | 定義 1 件の表示（`withDeps` で依存も） |
+| `kumiki_refs` | 定義への参照箇所を検索 |
+| `kumiki_add` / `kumiki_replace` / `kumiki_remove` / `kumiki_rename` | 定義の編集 |
+| `kumiki_fix` | 修復可能な診断の自動パッチ案を提示 |
+| `kumiki_spec_search` / `kumiki_spec_list` / `kumiki_spec_get` | 正規仕様（spec/）の検索・一覧・取得 |
+
+## 起動
+
+```sh
+pnpm --filter @kumikijs/mcp start
+```
+
+MCP クライアント（例: Claude Code）の設定例:
+
+```json
+{
+  "mcpServers": {
+    "kumiki": {
+      "command": "node",
+      "args": ["--import", "tsx", "packages/mcp/src/server.ts"]
+    }
+  }
+}
+```
+
+`spec/` の場所は通常リポジトリ構成から自動解決される。別配置の場合は環境変数 `KUMIKI_SPEC_DIR` で上書きする。

package/README.md

@@ -0,0 +1,41 @@
+# @kumikijs/mcp
+
+English · [日本語](./README.ja.md)
+
+Exposes the Kumiki compiler and the AI editing toolchain as an **MCP (Model Context Protocol) server**. From editors or AI agents, you can check, build, navigate, edit, and look up the spec for Kumiki programs.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `kumiki_check` | Parse + type-check `source` or `path` and return diagnostics |
+| `kumiki_build` | Compile to a self-contained JS module (runtime inlined) |
+| `kumiki_smoke` | Mount to a headless DOM and operate the UI to detect runtime exceptions, empty rendering, and unhandled rejections (the layer check/build don't catch) |
+| `kumiki_run_scenario` | Drive the app with a scenario (operation sequence + state assertions), returning per-step slot state, DOM, errors, and emits as a trace. The substrate for the human-free generate → run → observe → fix loop |
+| `kumiki_list` | List definitions in a file (filterable by layer) |
+| `kumiki_view` | Show a single definition (with dependencies via `withDeps`) |
+| `kumiki_refs` | Search for references to a definition |
+| `kumiki_add` / `kumiki_replace` / `kumiki_remove` / `kumiki_rename` | Edit definitions |
+| `kumiki_fix` | Propose auto-patches for fixable diagnostics |
+| `kumiki_spec_search` / `kumiki_spec_list` / `kumiki_spec_get` | Search, list, and retrieve the normative spec (spec/) |
+
+## Startup
+
+```sh
+pnpm --filter @kumikijs/mcp start
+```
+
+Example configuration for an MCP client (e.g. Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "kumiki": {
+      "command": "node",
+      "args": ["--import", "tsx", "packages/mcp/src/server.ts"]
+    }
+  }
+}
+```
+
+The location of `spec/` is auto-resolved from the usual repository layout. For a different location, override it with the `KUMIKI_SPEC_DIR` environment variable.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/index.d.ts
+declare function createServer(): McpServer;
+//#endregion
+export { createServer };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { t as createServer } from "./src-CUWuO58x.js";
+export { createServer };

package/dist/server.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/server.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { t as createServer } from "./src-CUWuO58x.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+//#region src/server.ts
+async function main() {
+	const server = createServer();
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	console.error("Kumiki MCP server running on stdio");
+}
+main().catch((err) => {
+	console.error("Fatal error starting Kumiki MCP server:", err);
+	process.exit(1);
+});
+//#endregion
+export {};

package/dist/src-CUWuO58x.js

@@ -0,0 +1,294 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { addDef, findReferences, listDefs, load, planFixes, removeDef, renameDef, replaceDef, runScenarioSource, smokeSource, viewDef, viewWithDeps } from "@kumikijs/cli";
+import { check, compile, lex, parse } from "@kumikijs/compiler";
+import { nodeRuntimeBundleReader } from "@kumikijs/compiler/node";
+import { z } from "zod";
+import { fileURLToPath } from "node:url";
+//#region src/spec.ts
+/** Resolve the repo's spec/ directory. Override with KUMIKI_SPEC_DIR. */
+function specDir() {
+	const env = process.env.KUMIKI_SPEC_DIR;
+	if (env) return env;
+	return join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "spec");
+}
+function listSpecDocs() {
+	const dir = specDir();
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
+}
+function getSpecDoc(name) {
+	const path = join(specDir(), name.endsWith(".md") ? name : `${name}.md`);
+	if (!existsSync(path)) return null;
+	return readFileSync(path, "utf8");
+}
+function searchSpec(query, maxHits = 40) {
+	const dir = specDir();
+	const needle = query.toLowerCase();
+	const hits = [];
+	for (const doc of listSpecDocs()) {
+		const lines = readFileSync(join(dir, doc), "utf8").split(/\r?\n/);
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i] ?? "";
+			if (line.toLowerCase().includes(needle)) {
+				hits.push({
+					doc,
+					line: i + 1,
+					text: line.trim()
+				});
+				if (hits.length >= maxHits) return hits;
+			}
+		}
+	}
+	return hits;
+}
+//#endregion
+//#region src/index.ts
+function text(s) {
+	return { content: [{
+		type: "text",
+		text: s
+	}] };
+}
+function readSource(input) {
+	if (typeof input.source === "string") return input.source;
+	if (input.path) return readFileSync(resolve(process.cwd(), input.path), "utf8");
+	throw new Error("provide either `source` or `path`");
+}
+function toDiagnostics(errors) {
+	return errors.map((e) => ({
+		code: e.code,
+		kind: e.kind,
+		message: e.message,
+		line: e.pos.line,
+		col: e.pos.col
+	}));
+}
+/** Parse + typecheck, normalizing parse exceptions into a single diagnostic. */
+function validate(source) {
+	try {
+		const errors = check(parse(lex(source)));
+		return {
+			ok: errors.length === 0,
+			diagnostics: toDiagnostics(errors)
+		};
+	} catch (e) {
+		const pe = e;
+		return {
+			ok: false,
+			diagnostics: [{
+				code: "E0000",
+				kind: "parse-error",
+				message: pe.message ?? String(e),
+				line: pe.pos?.line ?? 0,
+				col: pe.pos?.col ?? 0
+			}]
+		};
+	}
+}
+function createServer() {
+	const server = new McpServer({
+		name: "kumiki",
+		version: "0.1.0"
+	});
+	server.registerTool("kumiki_check", {
+		title: "Check Kumiki source",
+		description: "Parse and typecheck a Kumiki program. Pass `source` (text) or `path` (file). Returns ok or a list of diagnostics with codes (see spec/errors.md).",
+		inputSchema: {
+			source: z.string().optional().describe("Full Kumiki source text"),
+			path: z.string().optional().describe("Path to a .kumiki file (relative to cwd)")
+		}
+	}, async (input) => {
+		const result = validate(readSource(input));
+		if (result.ok) return text("ok — no diagnostics");
+		return text(JSON.stringify(result.diagnostics, null, 2));
+	});
+	server.registerTool("kumiki_build", {
+		title: "Build Kumiki source",
+		description: "Compile a Kumiki program to a self-contained JS module (runtime inlined). Pass `source` or `path`. Returns the generated JS, or diagnostics on failure.",
+		inputSchema: {
+			source: z.string().optional(),
+			path: z.string().optional(),
+			includeJs: z.boolean().optional().describe("Return full JS (default: only a summary)")
+		}
+	}, async (input) => {
+		const result = compile(readSource(input), {
+			runtimeSpecifier: "./runtime.js",
+			bundle: true,
+			readRuntimeBundle: nodeRuntimeBundleReader
+		});
+		if (result.kind === "fail") return text(`build failed:\n${JSON.stringify(toDiagnostics(result.errors), null, 2)}`);
+		if (input.includeJs) return text(result.js);
+		return text(`build ok — ${result.js.length} bytes of JS (pass includeJs=true for the source)`);
+	});
+	server.registerTool("kumiki_smoke", {
+		title: "Runtime smoke test",
+		description: "Mount a Kumiki program in a headless DOM, exercise its UI, and report runtime failures that check/build cannot catch (throws, empty render, unhandled rejections). Pass `source` or `path`. Run this after check/build — a program can compile yet error or render nothing when actually used.",
+		inputSchema: {
+			source: z.string().optional(),
+			path: z.string().optional()
+		}
+	}, async (input) => {
+		const report = await smokeSource(readSource(input));
+		if (report.ok) return text(`ok — mounted, rendered, ${report.interactions} interaction(s), no runtime errors`);
+		const lines = report.issues.map((i) => `[${i.phase}] ${i.message}${i.trigger ? ` (on ${i.trigger})` : ""}`);
+		return text(`runtime smoke failed (mounted=${report.mounted}, rendered=${report.rendered}):\n${lines.join("\n")}`);
+	});
+	server.registerTool("kumiki_run_scenario", {
+		title: "Run a scenario",
+		description: "Drive a Kumiki app through a scenario and return a per-step trace (slot state, DOM text, errors, emitted effects) plus assertion results. This is the substrate for an autonomous generate→run→observe→fix loop: write the user's requirements as scenario steps with `expect` assertions on state, run, read the trace, and patch without a human operating the app.\n\nScenario shape: { steps: [{ label?, do?, expect? }], effects?: { <name>: [{outcome, value}] } }. An action `do` is one of: {dispatch, payload?}, {clickText}, {click}, {fill, value}, {choose, value}, {navigate}. An `expect` is { noErrors?, state?: {slot: value}, domIncludes?: [..], domExcludes?: [..] } (state uses partial match; keys may be dotted paths).",
+		inputSchema: {
+			source: z.string().optional(),
+			path: z.string().optional(),
+			scenario: z.object({
+				steps: z.array(z.record(z.string(), z.unknown())),
+				effects: z.record(z.string(), z.array(z.record(z.string(), z.unknown()))).optional(),
+				defaultEffect: z.record(z.string(), z.unknown()).optional()
+			}).describe("The scenario to run")
+		}
+	}, async (input) => {
+		const report = await runScenarioSource(readSource(input), input.scenario);
+		const lines = report.steps.map((s, i) => {
+			const status = s.errors.length === 0 && s.failures.length === 0 ? "ok" : "FAIL";
+			const head = `step ${i}${s.label ? ` (${s.label})` : ""}${s.action ? `: ${s.action}` : ""}`;
+			const sub = [...s.errors.map((e) => `    error: ${e}`), ...s.failures.map((f) => `    assert: ${f}`)];
+			const emits = s.emits.length ? `    emits: ${s.emits.map((e) => e.effect).join(", ")}` : "";
+			return [
+				`[${status}] ${head}`,
+				...sub,
+				emits
+			].filter(Boolean).join("\n");
+		});
+		const tail = report.ok ? "scenario passed" : "scenario FAILED";
+		const finalState = report.steps.at(-1)?.state ?? {};
+		return text(`${lines.join("\n")}\n\n${tail}\nfinal state: ${JSON.stringify(finalState)}`);
+	});
+	server.registerTool("kumiki_list", {
+		title: "List definitions",
+		description: "List the definitions in a .kumiki file, optionally filtered by layer.",
+		inputSchema: {
+			path: z.string().describe("Path to a .kumiki file"),
+			layer: z.enum([
+				"type",
+				"slot",
+				"effect",
+				"reducer",
+				"tile",
+				"fn",
+				"app",
+				"theme"
+			]).optional()
+		}
+	}, async ({ path, layer }) => {
+		return text(listDefs(load(resolve(process.cwd(), path)), layer).map((e) => `${e.layer}.${e.name}  (lines ${e.range.startLine}-${e.range.endLine})`).join("\n") || "(no definitions)");
+	});
+	server.registerTool("kumiki_view", {
+		title: "View a definition",
+		description: "Show the source of one definition (`<layer>.<name>`), optionally with its dependencies.",
+		inputSchema: {
+			path: z.string(),
+			name: z.string().describe("Qualified name, e.g. tile.App or reducer.addTodo"),
+			withDeps: z.boolean().optional()
+		}
+	}, async ({ path, name, withDeps }) => {
+		const store = load(resolve(process.cwd(), path));
+		return text((withDeps ? viewWithDeps(store, name) : viewDef(store, name)) ?? `not found: ${name}`);
+	});
+	server.registerTool("kumiki_refs", {
+		title: "Find references",
+		description: "Find all sites that reference a definition.",
+		inputSchema: {
+			path: z.string(),
+			name: z.string()
+		}
+	}, async ({ path, name }) => {
+		return text(findReferences(load(resolve(process.cwd(), path)), name).map((r) => `${r.qname} @ line ${r.line}`).join("\n") || "(no references)");
+	});
+	server.registerTool("kumiki_add", {
+		title: "Add a definition",
+		description: "Append a new definition to a .kumiki file.",
+		inputSchema: {
+			path: z.string(),
+			layer: z.enum([
+				"type",
+				"slot",
+				"effect",
+				"reducer",
+				"tile",
+				"fn",
+				"app",
+				"theme"
+			]),
+			name: z.string(),
+			body: z.string().describe("The definition body (without the `<layer> <name>` prefix)")
+		}
+	}, async ({ path, layer, name, body }) => {
+		addDef(resolve(process.cwd(), path), layer, name, body);
+		return text(`added ${layer}.${name}`);
+	});
+	server.registerTool("kumiki_replace", {
+		title: "Replace a definition",
+		description: "Replace the body of an existing definition.",
+		inputSchema: {
+			path: z.string(),
+			name: z.string(),
+			body: z.string()
+		}
+	}, async ({ path, name, body }) => {
+		replaceDef(resolve(process.cwd(), path), name, body);
+		return text(`replaced ${name}`);
+	});
+	server.registerTool("kumiki_remove", {
+		title: "Remove a definition",
+		description: "Remove a definition. Set cascade=true to also remove definitions that only it referenced.",
+		inputSchema: {
+			path: z.string(),
+			name: z.string(),
+			cascade: z.boolean().optional()
+		}
+	}, async ({ path, name, cascade }) => {
+		removeDef(resolve(process.cwd(), path), name, cascade ?? false);
+		return text(`removed ${name}`);
+	});
+	server.registerTool("kumiki_rename", {
+		title: "Rename a definition",
+		description: "Rename a definition and update all references.",
+		inputSchema: {
+			path: z.string(),
+			name: z.string(),
+			newName: z.string()
+		}
+	}, async ({ path, name, newName }) => {
+		renameDef(resolve(process.cwd(), path), name, newName);
+		return text(`renamed ${name} -> ${newName}`);
+	});
+	server.registerTool("kumiki_fix", {
+		title: "Plan auto-fixes",
+		description: "Typecheck a file and propose auto-patches for repairable errors (e.g. misspelled names). Returns the planned fixes; this tool does not write to disk.",
+		inputSchema: { path: z.string() }
+	}, async ({ path }) => {
+		const store = load(resolve(process.cwd(), path));
+		return text(planFixes(store, check(store.program)).map((p) => `${p.code}: ${p.description}`).join("\n") || "(no auto-fixable diagnostics)");
+	});
+	server.registerTool("kumiki_spec_search", {
+		title: "Search the spec",
+		description: "Keyword search across the normative spec/ documents. Returns doc:line matches.",
+		inputSchema: { query: z.string() }
+	}, async ({ query }) => {
+		return text(searchSpec(query).map((h) => `${h.doc}:${h.line}  ${h.text}`).join("\n") || `(no matches for "${query}")`);
+	});
+	server.registerTool("kumiki_spec_list", {
+		title: "List spec documents",
+		description: "List the available normative spec/ documents.",
+		inputSchema: {}
+	}, async () => text(listSpecDocs().join("\n") || "(spec/ not found)"));
+	server.registerTool("kumiki_spec_get", {
+		title: "Get a spec document",
+		description: "Fetch the full text of one spec document (e.g. 'language' or 'errors.md').",
+		inputSchema: { doc: z.string() }
+	}, async ({ doc }) => text(getSpecDoc(doc) ?? `not found: ${doc}`));
+	return server;
+}
+//#endregion
+export { createServer as t };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@kumikijs/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Kumiki MCP server — exposes the compiler (check/build/list/view/add/replace/remove/fix) and spec search as MCP tools.",
+  "license": "Apache-2.0",
+  "author": "kage1020",
+  "homepage": "https://github.com/kage1020/Kumiki/tree/main/packages/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kage1020/Kumiki.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": "https://github.com/kage1020/Kumiki/issues",
+  "keywords": [
+    "kumiki",
+    "ai-first",
+    "mcp",
+    "model-context-protocol",
+    "compiler"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "kumiki-mcp": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check src",
+    "start": "tsx src/server.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@kumikijs/cli": "workspace:*",
+    "@kumikijs/compiler": "workspace:*",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "tsx": "catalog:",
+    "typescript": "catalog:"
+  }
+}