@twobirds/microcomponents 0.10.3 → 0.11.0

package/dist/mcp/index.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { z } from "zod";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __esmMin = (fn, res, err) => () => {
@@ -25,6 +25,301 @@ var __exportAll = (all, no_symbols) => {
 	return target;
 };
 //#endregion
+//#region src/mcp/docs.ts
+/**
+Documentation data for the MCP server — the single source of truth the tools read.
+
+The index is derived, never hand-copied. In a published package the server runs from
+dist/mcp and reads the prebuilt api.json; in development (tsx from src/mcp) the index
+is generated live from src/ at startup, so it cannot drift away from the library it
+documents. The dev/prod decision lives in server.ts; this module is the pure data layer.
+
+@module MCP/Docs
+*/
+/**
+Reads the prebuilt api.json from a server directory.
+
+@param dir - The directory the compiled server sits in; api.json is beside it.
+@returns The parsed index.
+*/
+function loadIndex(dir) {
+	return JSON.parse(readFileSync(join(dir, "api.json"), "utf8"));
+}
+/**
+Concept essays live one per file: copied into dist/mcp/concepts in production, read
+from docs/concepts in development.
+
+@param dir - The concepts folder.
+@returns A record of concept name (filename without `.md`) to essay text. An empty
+record when the folder is absent.
+*/
+function readConcepts(dir) {
+	if (!existsSync(dir)) return {};
+	const out = {};
+	for (const f of readdirSync(dir)) {
+		if (!f.endsWith(".md")) continue;
+		out[f.replace(/\.md$/, "")] = readFileSync(join(dir, f), "utf8").trim();
+	}
+	return out;
+}
+/**
+First paragraph or sentence of a description, truncated honestly.
+
+@param text - The description text.
+@param limit - Maximum characters before truncation.
+@returns The summary.
+*/
+function summarize(text, limit = 160) {
+	const flat = (text.split(/\n\s*\n|(?<=[.!?])\s+/)[0] ?? text).replace(/\s+/g, " ").trim();
+	if (flat.length <= limit) return flat;
+	return `${flat.slice(0, limit).replace(/[\s,\-]+$/, "")}...`;
+}
+var FENCE = "`".repeat(3);
+/**
+Scores one index entry against a lowercased query.
+
+@param e - The entry to score.
+@param q - The lowercased query.
+@returns The relevance score; 0 when the entry does not match.
+*/
+function scoreEntry(e, q) {
+	let score = 0;
+	if (e.name.toLowerCase() === q) score += 8;
+	if (e.name.toLowerCase().includes(q)) score += 4;
+	if ((e.group ?? "").toLowerCase().includes(q)) score += 2;
+	if ((e.description ?? "").toLowerCase().includes(q)) score += 3;
+	for (const ex of e.examples ?? []) if (ex.code.toLowerCase().includes(q) || ex.title.toLowerCase().includes(q)) score += 2;
+	return score;
+}
+/**
+Builds the six tools against a given context.
+
+@param ctx - The index, the concept essays, and the readable source root.
+@returns A record of tool name to definition, in registration order.
+*/
+function createTools(ctx) {
+	const API = ctx.index.entries;
+	const undocumented = ctx.index.undocumented;
+	const CONCEPT_NAMES = Object.keys(ctx.concepts);
+	return {
+		"list-components": {
+			description: "List all documented Micro Components classes, utilities and types with their group and a short summary",
+			schema: {},
+			handler: async () => {
+				const list = Object.values(API).map((e) => ({
+					name: e.name,
+					kind: e.kind,
+					group: e.group,
+					file: e.file,
+					summary: summarize(e.description ?? "", 120),
+					examples: (e.examples ?? []).length
+				}));
+				return { content: [{
+					type: "text",
+					text: JSON.stringify({
+						libraryVersion: ctx.index.libraryVersion,
+						exportedCount: ctx.index.exportedCount,
+						components: list
+					}, null, 2)
+				}] };
+			}
+		},
+		"get-component-docs": {
+			description: "Get comprehensive documentation and usage examples for a Micro Components class or utility",
+			schema: { componentName: z.string().describe("The name of the component (e.g., DC, defineCE, observe, injectCSS)") },
+			handler: async ({ componentName }) => {
+				const entry = API[componentName];
+				if (!entry) return {
+					content: [{
+						type: "text",
+						text: `No documentation for "${componentName}". ${Object.keys(API).length} entries exist; call list-components or search-components to discover names.`
+					}],
+					isError: true
+				};
+				const lines = [
+					`# ${entry.name}`,
+					"",
+					`**Kind:** ${entry.kind ?? "unknown"}`,
+					...entry.group ? [`**Group:** ${entry.group}`] : [],
+					...entry.file ? [`**Source:** ${entry.file}`] : [],
+					""
+				];
+				if (entry.description) lines.push("## Description", entry.description, "");
+				if (entry.signatures?.length) {
+					lines.push("## Signatures");
+					for (const sig of entry.signatures) lines.push(`${FENCE}ts`, sig, FENCE, "");
+				}
+				const examples = entry.examples ?? [];
+				if (examples.length) {
+					lines.push("## Examples");
+					for (const ex of examples) {
+						if (ex.title) lines.push(`### ${ex.title}`);
+						lines.push(`${FENCE}ts`, ex.code, FENCE, "");
+					}
+				}
+				return { content: [{
+					type: "text",
+					text: lines.join("\n")
+				}] };
+			}
+		},
+		"search-components": {
+			description: "Search Micro Components documentation by keyword. Searches names, groups, descriptions and code examples.",
+			schema: { query: z.string().describe("Search term to find relevant components (e.g., \"event\", \"observable\", \"css\")") },
+			handler: async ({ query }) => {
+				const q = query.toLowerCase();
+				const hits = Object.values(API).map((e) => ({
+					e,
+					s: scoreEntry(e, q)
+				})).filter((h) => h.s > 0).sort((a, b) => b.s - a.s || a.e.name.localeCompare(b.e.name)).slice(0, 12);
+				const conceptHits = CONCEPT_NAMES.filter((k) => ctx.concepts[k].toLowerCase().includes(q));
+				if (!hits.length && !conceptHits.length) return { content: [{
+					type: "text",
+					text: `No documentation matched "${query}". Use list-components to see every entry, or get-source-file for raw source.`
+				}] };
+				const results = hits.map((h) => ({
+					name: h.e.name,
+					kind: h.e.kind,
+					group: h.e.group,
+					relevance: h.s,
+					snippet: summarize(h.e.description ?? "", 150)
+				}));
+				return { content: [{
+					type: "text",
+					text: JSON.stringify({
+						query,
+						results,
+						conceptMatches: conceptHits
+					}, null, 2)
+				}] };
+			}
+		},
+		"get-core-concept": {
+			description: `Get a core Micro Components concept essay. Available: ${CONCEPT_NAMES.join(", ") || "none"}`,
+			schema: { concept: z.string().describe(`Concept name, one of: ${CONCEPT_NAMES.join(", ")}`) },
+			handler: async ({ concept }) => {
+				const content = ctx.concepts[concept];
+				if (!content) return {
+					content: [{
+						type: "text",
+						text: `Concept "${concept}" not found. Available: ${CONCEPT_NAMES.join(", ")}`
+					}],
+					isError: true
+				};
+				return { content: [{
+					type: "text",
+					text: content
+				}] };
+			}
+		},
+		"get-source-file": {
+			description: "Retrieve the actual source code from a Micro Components library file (package-root relative)",
+			schema: { filepath: z.string().describe("Path to source file, e.g. dist/core/MC.js, dist/core/MC.d.ts, dist/mcp/concepts/event-system.md") },
+			handler: async ({ filepath }) => {
+				const full = resolve(ctx.sourceRoot, filepath);
+				if (full !== ctx.sourceRoot && !full.startsWith(ctx.sourceRoot + "/")) return {
+					content: [{
+						type: "text",
+						text: `Refused: "${filepath}" is outside the package sources.`
+					}],
+					isError: true
+				};
+				if (!existsSync(full)) return {
+					content: [{
+						type: "text",
+						text: `File not found: ${filepath}`
+					}],
+					isError: true
+				};
+				try {
+					const source = readFileSync(full, "utf8");
+					if (source.length > 2e5) return {
+						content: [{
+							type: "text",
+							text: `File too large (${source.length} bytes). Request a specific symbol via get-component-docs instead.`
+						}],
+						isError: true
+					};
+					return { content: [{
+						type: "text",
+						text: source
+					}] };
+				} catch (error) {
+					return {
+						content: [{
+							type: "text",
+							text: `Error reading file: ${error}`
+						}],
+						isError: true
+					};
+				}
+			}
+		},
+		"list-undocumented": {
+			description: "Report public exports whose source lacks a doc block — the drift signal for src/ documentation",
+			schema: {},
+			handler: async () => ({ content: [{
+				type: "text",
+				text: undocumented.length ? `${undocumented.length} undocumented export(s):\n${undocumented.join("\n")}` : `All ${ctx.index.exportedCount} public exports carry a doc block.`
+			}] })
+		}
+	};
+}
+//#endregion
+//#region src/mcp/server.ts
+/**
+Wiring for the MCP server: read the documentation environment, and build the McpServer.
+
+The tool behaviour lives in tools.ts and the data layer in docs.ts, both transport-free and
+unit-tested. This module is the seam between them: loadEnv() makes the dev/prod decision and
+reads the index and the concept essays, createServer() registers the tools on a server without
+connecting a transport. Both are testable. Connecting stdio is the entry point's job
+(index.ts), excluded from coverage as the process entry — running it in a test would take over
+the test process's real stdio, which is not available in a worker thread.
+
+@module MCP/Server
+*/
+/**
+Reads the documentation environment for the directory the compiled server sits in.
+
+Production: the server runs from dist/mcp, so it reads the prebuilt api.json and the copied
+concepts/ that the build step emits next to it. Development: the server runs from src/mcp,
+where index.ts is present, so the index is generated live from src/ (it cannot drift away
+from the library it documents) and concepts are read straight from docs/concepts.
+
+@param dir - The directory the server module lives in.
+@param devLoader - Supplies the live-generated index in development. The entry point passes
+the real doc generator; tests pass a fixture, so the dev branch is pinned without running
+the generator as a side effect on dist/.
+@returns The index, the concept essays, and the folder get-source-file is confined to.
+*/
+async function loadEnv(dir, devLoader) {
+	const IS_DEV = existsSync(join(dir, "index.ts"));
+	const conceptsDir = IS_DEV ? join(dir, "..", "..", "docs", "concepts") : join(dir, "concepts");
+	return {
+		index: IS_DEV ? await devLoader() : loadIndex(dir),
+		concepts: readConcepts(conceptsDir),
+		sourceRoot: join(dir, "..", "..")
+	};
+}
+/**
+Registers every tool on a fresh McpServer, without connecting a transport.
+
+@param env - The index, the concept essays, and the readable source root.
+@returns The server, ready to connect.
+*/
+function createServer(env) {
+	const server = new McpServer({
+		name: "microcomponents-mcp",
+		version: env.index.libraryVersion
+	});
+	for (const [name, def] of Object.entries(createTools(env))) server.registerTool(name, {
+		description: def.description,
+		inputSchema: def.schema
+	}, (args) => def.handler(args));
+	return server;
+}
+//#endregion
 //#region mcp-docs-generate.ts
 /**
 Generates the documentation index for the MCP server directly from src/.
@@ -45,9 +340,9 @@ above the first overload supplies the prose.
 */
 var mcp_docs_generate_exports = /* @__PURE__ */ __exportAll({
 	extract: () => extract,
-	index: () => index$1,
+	index: () => index,
 	scanFile: () => scanFile,
-	undocumented: () => undocumented$1,
+	undocumented: () => undocumented,
 	walk: () => walk
 });
 /** Read a barrel file, returning each re-exported name with its group and hidden flag. */
@@ -209,7 +504,7 @@ function pickDoc(name) {
 	}
 	return best ?? { decl: candidates[0] };
 }
-var ROOT, SRC, OUTFILE, MAX_DOC_GAP_LINES, DECL_PATTERNS, publicEntries, scanned, byName, pkg, entries, undocumented$1, publicCount, index$1;
+var ROOT, SRC, OUTFILE, MAX_DOC_GAP_LINES, DECL_PATTERNS, publicEntries, scanned, byName, pkg, entries, undocumented, publicCount, index;
 var init_mcp_docs_generate = __esmMin((() => {
 	ROOT = dirname(fileURLToPath(import.meta.url));
 	SRC = join(ROOT, "src");
@@ -240,12 +535,12 @@ var init_mcp_docs_generate = __esmMin((() => {
 	for (const scan of Object.values(scanned)) for (const d of scan.decls) (byName[d.name] ??= []).push(d);
 	pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
 	entries = {};
-	undocumented$1 = [];
+	undocumented = [];
 	for (const pub of publicEntries) {
 		if (pub.hidden) continue;
 		const found = pickDoc(pub.name);
 		if (!found) {
-			undocumented$1.push(`${pub.kind} ${pub.name}`);
+			undocumented.push(`${pub.kind} ${pub.name}`);
 			continue;
 		}
 		const sigs = byName[pub.name].map((d) => d.sig).filter(Boolean);
@@ -262,20 +557,20 @@ var init_mcp_docs_generate = __esmMin((() => {
 			description: doc.description || void 0,
 			examples: doc.examples.length ? doc.examples : void 0
 		};
-		if (!doc.description) undocumented$1.push(`${pub.kind} ${pub.name}`);
+		if (!doc.description) undocumented.push(`${pub.kind} ${pub.name}`);
 	}
 	publicCount = publicEntries.filter((p) => !p.hidden).length;
-	index$1 = {
+	index = {
 		libraryVersion: pkg.version,
 		exportedCount: publicCount,
 		entries,
-		undocumented: undocumented$1
+		undocumented
 	};
 	if (Boolean(process.argv[1]) && import.meta.url === `file://${resolve(process.argv[1])}`) {
-		writeFileSync(OUTFILE, JSON.stringify(index$1, null, 2));
+		writeFileSync(OUTFILE, JSON.stringify(index, null, 2));
 		console.log(`${OUTFILE}: ${Object.keys(entries).length} of ${publicCount} public exports documented`);
-		if (undocumented$1.length) {
-			console.warn(`missing doc block (${undocumented$1.length}): ${undocumented$1.join(", ")}`);
+		if (undocumented.length) {
+			console.warn(`missing doc block (${undocumented.length}): ${undocumented.join(", ")}`);
 			process.exit(1);
 		}
 	}
@@ -293,199 +588,21 @@ step emits next to it. In development (tsx from src/mcp) the index is generated
 from src/ at startup, so it cannot drift away from the library it documents.
 
 The server is Node-only and is emitted by tsconfig.mcp.json; package.json "bin" points
-at the compiled dist/mcp/index.js.
+at the compiled dist/mcp/index.js. The tool layer (tools.ts), the data layer (docs.ts)
+and the wiring (server.ts) are transport-free and unit-tested; this file is the process
+entry that supplies the live generator, connects stdio, and reports readiness. It is
+excluded from coverage — running it in a test would take over the test process's real
+stdio, which a worker thread does not have.
 
 @example Run the published server: node dist/mcp/index.js
 @example Run from source during development: pnpm run mcp:dev
 @example Regenerate the shipped index only: pnpm run mcp:docs
 */
-var __dirname = dirname(fileURLToPath(import.meta.url));
-var MAX_SOURCE_BYTES = 2e5;
-var FENCE = "`".repeat(3);
-var IS_DEV = existsSync(join(__dirname, "index.ts"));
-var index;
-var undocumented;
-if (IS_DEV) {
-	const live = await Promise.resolve().then(() => (init_mcp_docs_generate(), mcp_docs_generate_exports));
-	index = live.index;
-	undocumented = live.undocumented;
-} else {
-	const data = JSON.parse(readFileSync(join(__dirname, "api.json"), "utf8"));
-	index = data;
-	undocumented = data.undocumented;
-}
-var API = index.entries;
-/** Concept essays live one per file: copied into dist/mcp/concepts in production, read from docs/concepts in development. */
-var CONCEPTS_DIR = IS_DEV ? join(__dirname, "..", "..", "docs", "concepts") : join(__dirname, "concepts");
-function readConcepts() {
-	if (!existsSync(CONCEPTS_DIR)) return {};
-	const out = {};
-	for (const f of readdirSync(CONCEPTS_DIR)) {
-		if (!f.endsWith(".md")) continue;
-		out[f.replace(/\.md$/, "")] = readFileSync(join(CONCEPTS_DIR, f), "utf8").trim();
-	}
-	return out;
+/** Development: tsx runs src/mcp/index.ts, so the index is generated live from src/. */
+async function generateIndex() {
+	return (await Promise.resolve().then(() => (init_mcp_docs_generate(), mcp_docs_generate_exports))).index;
 }
-var CONCEPTS = readConcepts();
-var CONCEPT_NAMES = Object.keys(CONCEPTS);
-var SOURCE_ROOT = join(__dirname, "..", "..");
-/** First paragraph or sentence of a description, truncated honestly. */
-function summarize(text, limit = 160) {
-	const flat = (text.split(/\n\s*\n|(?<=[.!?])\s+/)[0] ?? text).replace(/\s+/g, " ").trim();
-	if (flat.length <= limit) return flat;
-	return `${flat.slice(0, limit).replace(/[\s,\-]+$/, "")}...`;
-}
-var server = new McpServer({
-	name: "microcomponents-mcp",
-	version: index.libraryVersion
-});
-server.tool("list-components", "List all documented Micro Components classes, utilities and types with their group and a short summary", {}, async () => {
-	const list = Object.values(API).map((e) => ({
-		name: e.name,
-		kind: e.kind,
-		group: e.group,
-		file: e.file,
-		summary: summarize(e.description ?? "", 120),
-		examples: (e.examples ?? []).length
-	}));
-	return { content: [{
-		type: "text",
-		text: JSON.stringify({
-			libraryVersion: index.libraryVersion,
-			exportedCount: index.exportedCount,
-			components: list
-		}, null, 2)
-	}] };
-});
-server.tool("get-component-docs", "Get comprehensive documentation and usage examples for a Micro Components class or utility", { componentName: z.string().describe("The name of the component (e.g., DC, defineCE, observe, injectCSS)") }, async ({ componentName }) => {
-	const entry = API[componentName];
-	if (!entry) return {
-		content: [{
-			type: "text",
-			text: `No documentation for "${componentName}". ${Object.keys(API).length} entries exist; call list-components or search-components to discover names.`
-		}],
-		isError: true
-	};
-	const lines = [
-		`# ${entry.name}`,
-		"",
-		`**Kind:** ${entry.kind ?? "unknown"}`,
-		...entry.group ? [`**Group:** ${entry.group}`] : [],
-		...entry.file ? [`**Source:** ${entry.file}`] : [],
-		""
-	];
-	if (entry.description) lines.push("## Description", entry.description, "");
-	if (entry.signatures?.length) {
-		lines.push("## Signatures");
-		for (const sig of entry.signatures) lines.push(`${FENCE}ts`, sig, FENCE, "");
-	}
-	const examples = entry.examples ?? [];
-	if (examples.length) {
-		lines.push("## Examples");
-		for (const ex of examples) {
-			if (ex.title) lines.push(`### ${ex.title}`);
-			lines.push(`${FENCE}ts`, ex.code, FENCE, "");
-		}
-	}
-	return { content: [{
-		type: "text",
-		text: lines.join("\n")
-	}] };
-});
-server.tool("search-components", "Search Micro Components documentation by keyword. Searches names, groups, descriptions and code examples.", { query: z.string().describe("Search term to find relevant components (e.g., \"event\", \"observable\", \"css\")") }, async ({ query }) => {
-	const q = query.toLowerCase();
-	const scoreEntry = (e) => {
-		let score = 0;
-		if (e.name.toLowerCase() === q) score += 8;
-		if (e.name.toLowerCase().includes(q)) score += 4;
-		if ((e.group ?? "").toLowerCase().includes(q)) score += 2;
-		if ((e.description ?? "").toLowerCase().includes(q)) score += 3;
-		for (const ex of e.examples ?? []) if (ex.code.toLowerCase().includes(q) || ex.title.toLowerCase().includes(q)) score += 2;
-		return score;
-	};
-	const hits = Object.values(API).map((e) => ({
-		e,
-		s: scoreEntry(e)
-	})).filter((h) => h.s > 0).sort((a, b) => b.s - a.s || a.e.name.localeCompare(b.e.name)).slice(0, 12);
-	const conceptHits = CONCEPT_NAMES.filter((k) => CONCEPTS[k].toLowerCase().includes(q));
-	if (!hits.length && !conceptHits.length) return { content: [{
-		type: "text",
-		text: `No documentation matched "${query}". Use list-components to see every entry, or get-source-file for raw source.`
-	}] };
-	const results = hits.map((h) => ({
-		name: h.e.name,
-		kind: h.e.kind,
-		group: h.e.group,
-		relevance: h.s,
-		snippet: summarize(h.e.description ?? "", 150)
-	}));
-	return { content: [{
-		type: "text",
-		text: JSON.stringify({
-			query,
-			results,
-			conceptMatches: conceptHits
-		}, null, 2)
-	}] };
-});
-server.tool("get-core-concept", `Get a core Micro Components concept essay. Available: ${CONCEPT_NAMES.join(", ") || "none"}`, { concept: z.string().describe(`Concept name, one of: ${CONCEPT_NAMES.join(", ")}`) }, async ({ concept }) => {
-	const content = CONCEPTS[concept];
-	if (!content) return {
-		content: [{
-			type: "text",
-			text: `Concept "${concept}" not found. Available: ${CONCEPT_NAMES.join(", ")}`
-		}],
-		isError: true
-	};
-	return { content: [{
-		type: "text",
-		text: content
-	}] };
-});
-server.tool("get-source-file", "Retrieve the actual source code from a Micro Components library file (package-root relative)", { filepath: z.string().describe("Path to source file, e.g. dist/core/MC.js, dist/core/MC.d.ts, dist/mcp/concepts/event-system.md") }, async ({ filepath }) => {
-	const full = resolve(SOURCE_ROOT, filepath);
-	if (full !== SOURCE_ROOT && !full.startsWith(SOURCE_ROOT + "/")) return {
-		content: [{
-			type: "text",
-			text: `Refused: "${filepath}" is outside the package sources.`
-		}],
-		isError: true
-	};
-	if (!existsSync(full)) return {
-		content: [{
-			type: "text",
-			text: `File not found: ${filepath}`
-		}],
-		isError: true
-	};
-	try {
-		const source = readFileSync(full, "utf8");
-		if (source.length > MAX_SOURCE_BYTES) return {
-			content: [{
-				type: "text",
-				text: `File too large (${source.length} bytes). Request a specific symbol via get-component-docs instead.`
-			}],
-			isError: true
-		};
-		return { content: [{
-			type: "text",
-			text: source
-		}] };
-	} catch (error) {
-		return {
-			content: [{
-				type: "text",
-				text: `Error reading file: ${error}`
-			}],
-			isError: true
-		};
-	}
-});
-server.tool("list-undocumented", "Report public exports whose source lacks a doc block — the drift signal for src/ documentation", {}, async () => ({ content: [{
-	type: "text",
-	text: undocumented.length ? `${undocumented.length} undocumented export(s):\n${undocumented.join("\n")}` : `All ${index.exportedCount} public exports carry a doc block.`
-}] }));
-var transport = new StdioServerTransport();
-await server.connect(transport);
-console.error(`Micro Components MCP server running on stdio (library ${index.libraryVersion}, ${Object.keys(API).length} documented exports)`);
+var env = await loadEnv(dirname(fileURLToPath(import.meta.url)), generateIndex);
+await createServer(env).connect(new StdioServerTransport());
+console.error(`Micro Components MCP server running on stdio (library ${env.index.libraryVersion}, ${Object.keys(env.index.entries).length} documented exports)`);
 //#endregion

package/dist/mcp/server.d.ts

@@ -0,0 +1,43 @@
+/**
+Wiring for the MCP server: read the documentation environment, and build the McpServer.
+
+The tool behaviour lives in tools.ts and the data layer in docs.ts, both transport-free and
+unit-tested. This module is the seam between them: loadEnv() makes the dev/prod decision and
+reads the index and the concept essays, createServer() registers the tools on a server without
+connecting a transport. Both are testable. Connecting stdio is the entry point's job
+(index.ts), excluded from coverage as the process entry — running it in a test would take over
+the test process's real stdio, which is not available in a worker thread.
+
+@module MCP/Server
+*/
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type IndexFile } from './docs.js';
+/** Everything the tools read: the index, the concept essays, and the readable source root. */
+export interface ServerEnv {
+    index: IndexFile;
+    concepts: Record<string, string>;
+    sourceRoot: string;
+}
+/**
+Reads the documentation environment for the directory the compiled server sits in.
+
+Production: the server runs from dist/mcp, so it reads the prebuilt api.json and the copied
+concepts/ that the build step emits next to it. Development: the server runs from src/mcp,
+where index.ts is present, so the index is generated live from src/ (it cannot drift away
+from the library it documents) and concepts are read straight from docs/concepts.
+
+@param dir - The directory the server module lives in.
+@param devLoader - Supplies the live-generated index in development. The entry point passes
+the real doc generator; tests pass a fixture, so the dev branch is pinned without running
+the generator as a side effect on dist/.
+@returns The index, the concept essays, and the folder get-source-file is confined to.
+*/
+export declare function loadEnv(dir: string, devLoader: () => Promise<IndexFile>): Promise<ServerEnv>;
+/**
+Registers every tool on a fresh McpServer, without connecting a transport.
+
+@param env - The index, the concept essays, and the readable source root.
+@returns The server, ready to connect.
+*/
+export declare function createServer(env: ServerEnv): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;EAWE;AACF,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,EAA2B,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAGpE,8FAA8F;AAC9F,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;EAaE;AACF,wBAAsB,OAAO,CAC5B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GACjC,OAAO,CAAC,SAAS,CAAC,CAWpB;AAED;;;;;EAKE;AACF,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,CAatD"}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,54 @@
+/**
+The MCP tool layer — six tools over the derived documentation index.
+
+Every tool is a plain handler over the index, the concept essays and a source root, so
+the behaviour (including the path-traversal guard of get-source-file) is testable
+without a transport. server.ts wires these onto an McpServer; this module has no
+transport, no console side effects, and no module-level state.
+
+@module MCP/Tools
+*/
+import { z } from 'zod';
+import { type Entry, type IndexFile } from './docs.js';
+/** Files larger than this are refused by get-source-file. */
+export declare const MAX_SOURCE_BYTES = 200000;
+/**
+The text payload a tool returns. Shaped to satisfy the SDK's ToolCallback return type,
+which requires an index signature — a plain interface does not have one.
+*/
+export type ToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+    [key: string]: unknown;
+};
+/** One tool: what it says, what it accepts, and what it does. */
+export interface ToolDef {
+    description: string;
+    schema: Record<string, z.ZodTypeAny>;
+    handler: (args: Record<string, string>) => Promise<ToolResult>;
+}
+/** Everything the tools read: the index, the essays, and the readable source root. */
+export interface ToolContext {
+    index: IndexFile;
+    concepts: Record<string, string>;
+    sourceRoot: string;
+}
+/**
+Scores one index entry against a lowercased query.
+
+@param e - The entry to score.
+@param q - The lowercased query.
+@returns The relevance score; 0 when the entry does not match.
+*/
+export declare function scoreEntry(e: Entry, q: string): number;
+/**
+Builds the six tools against a given context.
+
+@param ctx - The index, the concept essays, and the readable source root.
+@returns A record of tool name to definition, in registration order.
+*/
+export declare function createTools(ctx: ToolContext): Record<string, ToolDef>;
+//# sourceMappingURL=tools.d.ts.map