@twobirds/microcomponents 0.4.0 → 0.5.0

package/dist/mcp/index.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+MCP (Model Context Protocol) Server for the Micro Components library.
+
+Gives AI assistants tools to explore and work with @twobirds/microcomponents.
+
+Documentation is derived, never hand-copied. In a published package the server runs
+from dist/mcp and reads the prebuilt api.json and the copied concepts/ that the build
+step emits next to it. 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 server is Node-only and is emitted by tsconfig.mcp.json; package.json "bin" points
+at the compiled dist/mcp/index.js.
+
+@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
+*/
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MAX_SOURCE_BYTES = 200_000;
+const FENCE = '`'.repeat(3);
+// Development: tsx runs src/mcp/index.ts, where the source file is present, so the
+// index is generated live from src/ and concepts are read straight from docs/concepts.
+// Production: the compiled server sits in dist/mcp, where no .ts source exists, so it
+// reads the prebuilt api.json and the copied concepts/ that the build step emits next to it.
+const IS_DEV = existsSync(join(__dirname, 'index.ts'));
+let index;
+let undocumented;
+if (IS_DEV) {
+    // variable specifier keeps tsc from resolving the .ts path; tsx resolves it at runtime
+    const generator = '../../mcp-docs-generate.ts';
+    const live = await import(generator);
+    index = live.index;
+    undocumented = live.undocumented;
+}
+else {
+    const data = JSON.parse(readFileSync(join(__dirname, 'api.json'), 'utf8'));
+    index = data;
+    undocumented = data.undocumented;
+}
+const API = index.entries;
+/** Concept essays live one per file: copied into dist/mcp/concepts in production, read from docs/concepts in development. */
+const 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;
+}
+const CONCEPTS = readConcepts();
+const CONCEPT_NAMES = Object.keys(CONCEPTS);
+// get-source-file is confined to the package root: the installed package in production, the repo root in development.
+const SOURCE_ROOT = join(__dirname, '..', '..');
+/** First paragraph or sentence of a description, truncated honestly. */
+function summarize(text, limit = 160) {
+    const first = text.split(/\n\s*\n|(?<=[.!?])\s+/)[0] ?? text;
+    const flat = first.replace(/\s+/g, ' ').trim();
+    if (flat.length <= limit)
+        return flat;
+    return `${flat.slice(0, limit).replace(/[\s,\-]+$/, '')}...`;
+}
+// ---------------------------------------------------------------------------
+// MCP Server Setup
+// ---------------------------------------------------------------------------
+const 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);
+    // confine reads to the shipped sources so a caller cannot traverse outside them.
+    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.`,
+        },
+    ],
+}));
+// ============================================================================
+// Start Server
+// ============================================================================
+const 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)`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twobirds/microcomponents",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Micro Components",
 	"keywords": [
 		"PWA",
@@ -33,7 +33,8 @@
 		"url": "git+https://gitlab.com/twoBirds/microcomponents.git"
 	},
 	"bin": {
-		"mc": "./dist/cli/index.js"
+		"mc": "./dist/cli/index.js",
+		"microcomponents-mcp": "./dist/mcp/index.js"
 	},
 	"files": [
 		"dist"
@@ -67,13 +68,17 @@
 			"types": "./dist/state/formValues.d.ts",
 			"import": "./dist/state/formValues.js"
 		},
+		"./mcp": {
+			"types": "./dist/mcp/index.d.ts",
+			"import": "./dist/mcp/index.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"scripts": {
 		"format": "oxfmt .",
 		"lint": "oxlint \"src\"",
 		"fix": "oxfmt . && oxlint \"src\" --fix",
-		"check": "tsc --noEmit -p tsconfig.lib.json && tsc --noEmit -p tsconfig.cli.json && tsc -p tsconfig.test.json && tsc -p demo/web-test/tsconfig.demo.json && tsc --noEmit -p demo/shop/tsconfig.demo.json && tsc --noEmit -p demo/todo_mvc/tsconfig.demo.json && tsc -p tsconfig.node.json",
+		"check": "tsc --noEmit -p tsconfig.lib.json && tsc --noEmit -p tsconfig.cli.json && tsc --noEmit -p tsconfig.mcp.json && tsc -p tsconfig.test.json && tsc -p demo/web-test/tsconfig.demo.json && tsc --noEmit -p demo/shop/tsconfig.demo.json && tsc --noEmit -p demo/todo_mvc/tsconfig.demo.json && tsc -p tsconfig.node.json",
 		"check:pack": "publint && attw --pack . --profile esm-only",
 		"test": "vitest",
 		"test:run": "vitest run --reporter=verbose",
@@ -88,20 +93,24 @@
 		"typedoc": "typedoc --displayBasePath ./typedoc/",
 		"bundle": "tsx vite.build.ts",
 		"clean": "rm -rf dist public build coverage",
-		"build": "pnpm run clean && tsc -p tsconfig.lib.json && tsc -p tsconfig.cli.json && chmod +x dist/cli/index.js && pnpm run test:coverage && pnpm run bundle && pnpm run check:pack && pnpm run typedoc && pnpm run demo:build && pnpm run demo:shop:build && pnpm run demo:todo:build && find src -name '*.js' -delete",
+		"build": "pnpm run clean && tsc -p tsconfig.lib.json && tsc -p tsconfig.cli.json && chmod +x dist/cli/index.js && pnpm run mcp:build && pnpm run test:coverage && pnpm run bundle && pnpm run check:pack && pnpm run typedoc && pnpm run demo:build && pnpm run demo:shop:build && pnpm run demo:todo:build && find src -name '*.js' -delete",
+		"mcp:build": "tsc -p tsconfig.mcp.json && node mcp-docs-generate.ts && cp -r docs/concepts dist/mcp/concepts && chmod +x dist/mcp/index.js",
 		"demo:build": "tsx demo/web-test/vite.demo.ts",
 		"dev": "vite preview --outDir build/web-test --port 10000 --host",
 		"doc": "vite preview --outDir public/typedoc --port 11000 --host",
 		"watch": "tsx watch.ts",
 		"cli": "tsx src/cli/index.ts",
-		"mcp:dev": "tsx watch microcomponents-mcp-server.ts",
+		"mcp:dev": "tsx watch src/mcp/index.ts",
 		"mcp:docs": "node mcp-docs-generate.ts",
-		"mcp:run": "tsx microcomponents-mcp-server.ts",
+		"mcp:run": "tsx src/mcp/index.ts",
 		"prepublishOnly": "pnpm run build && pnpm run check"
 	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.30.0",
+		"zod": "^4.6.5"
+	},
 	"devDependencies": {
 		"@arethetypeswrong/cli": "^0.18.5",
-		"@modelcontextprotocol/sdk": "^1.30.0",
 		"@types/node": "^22.20.1",
 		"@vitest/coverage-v8": "^4.1.10",
 		"jsdom": "^29.1.1",
@@ -112,8 +121,7 @@
 		"typedoc": "^0.28.20",
 		"typescript": "^6.0.3",
 		"vite": "^8.1.5",
-		"vitest": "^4.1.10",
-		"zod": "^4.6.5"
+		"vitest": "^4.1.10"
 	},
 	"engines": {
 		"node": ">=22.18"