bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/bin/bitboss-ui-mcp.mjs

@@ -0,0 +1,662 @@
+#!/usr/bin/env node
+/**
+ * bitboss-ui MCP server — exposes the installed package's `dist/ai`
+ * knowledge base (component manifest, recipes, validator) to MCP-capable
+ * agent harnesses (Cursor, Claude Code, …) so they can query instead of
+ * reading files blind.
+ *
+ * Built on `@modelcontextprotocol/sdk` (McpServer over the stdio transport);
+ * the SDK owns JSON-RPC framing, capability handshake, and protocol-version
+ * negotiation. Tool input schemas are declared as zod shapes (zod ships with
+ * the SDK); the SDK renders them to the JSON Schema advertised by tools/list.
+ *
+ * Run standalone: `npx bitboss-ui mcp` (delegated from bin/bitboss-ui.mjs).
+ * Register with an MCP-capable harness via `npx bitboss-ui ai-init --mcp`.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import {
+	loadManifest,
+	validateVueSnippet,
+} from '../scripts/lib/validate-bb-markup.mjs';
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const AI_ROOT = join(PACKAGE_ROOT, 'dist', 'ai');
+const MANIFEST_PATH = join(AI_ROOT, 'components.json');
+const RECIPE_PLATFORMS = ['vue', 'nuxt', 'inertia'];
+
+function packageVersion() {
+	try {
+		const pkg = JSON.parse(
+			readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf-8')
+		);
+		return pkg.version ?? 'unknown';
+	} catch {
+		return 'unknown';
+	}
+}
+
+function loadComponentsManifest() {
+	if (!existsSync(MANIFEST_PATH)) {
+		throw new Error(
+			`components.json not found at ${MANIFEST_PATH} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`
+		);
+	}
+	return JSON.parse(readFileSync(MANIFEST_PATH, 'utf-8'));
+}
+
+let cachedManifestMap = null;
+function getManifestMap() {
+	cachedManifestMap ??= loadManifest(MANIFEST_PATH);
+	return cachedManifestMap;
+}
+
+/** `search_components({ query })` — substring match over name/description. */
+const SEARCH_DEFAULT_LIMIT = 20;
+
+/**
+ * Relevance score for one component against a lowercased needle. Higher wins;
+ * 0 means "no match". Name hits always outrank description hits so
+ * `search_components({ query: 'table' })` leads with BbTable, not with every
+ * component whose prose mentions a table.
+ */
+function scoreComponent(component, needle) {
+	const name = component.name.toLowerCase();
+	const description = (component.description ?? '').toLowerCase();
+	if (name === needle) return 100;
+	if (name === `bb${needle}`) return 95; // 'button' → BbButton
+	if (name.startsWith(needle) || name.startsWith(`bb${needle}`)) return 80;
+	if (name.includes(needle)) return 60;
+	if (description.includes(needle)) return 30;
+	return 0;
+}
+
+function searchComponents({ query, limit, includeReferenceOnly } = {}) {
+	const manifest = loadComponentsManifest();
+	const needle = String(query ?? '')
+		.toLowerCase()
+		.trim();
+	const max =
+		Number.isFinite(limit) && limit > 0 ? limit : SEARCH_DEFAULT_LIMIT;
+
+	// Consumer-first: reference-only internals are excluded unless explicitly
+	// requested — recommending them is an agent-contract violation.
+	const pool = includeReferenceOnly
+		? manifest.components
+		: manifest.components.filter((c) => !c.referenceOnly);
+
+	const scored = pool
+		.map((c) => ({ c, score: scoreComponent(c, needle) }))
+		.filter(({ score }) => score > 0)
+		// Ties break alphabetically so results are stable between calls.
+		.sort((a, b) => b.score - a.score || a.c.name.localeCompare(b.c.name));
+
+	const shown = scored.slice(0, max);
+	return {
+		query: query ?? '',
+		count: shown.length,
+		totalMatches: scored.length,
+		...(scored.length > shown.length
+			? {
+					truncated: true,
+					hint: `Showing the ${shown.length} most relevant of ${scored.length} matches — refine the query or raise \`limit\`.`,
+				}
+			: {}),
+		components: shown.map(({ c }) => ({
+			name: c.name,
+			group: c.group,
+			description: c.description,
+			referenceOnly: Boolean(c.referenceOnly),
+			contract: c.contract,
+		})),
+	};
+}
+
+/** `get_component({ name })` — manifest slice + resolved contract content. */
+/**
+ * Default cap for markdown payloads. A full contract can exceed 110 KB
+ * (BbTable), which swamps an agent's context in one call.
+ *
+ * IMPORTANT: only ever applied to *prose/markdown*. The structured manifest
+ * entry (props/events/slots/models) is never truncated — a partial prop list
+ * is what makes an agent invent API, which is precisely what this server
+ * exists to prevent.
+ */
+const MARKDOWN_DEFAULT_MAX_CHARS = 40000;
+
+/**
+ * Cut `text` to `maxChars` on a line boundary, reporting what was dropped.
+ * `maxChars: 0` disables truncation (full payload).
+ */
+function truncateMarkdown(text, maxChars, readHint) {
+	const limit = Number.isFinite(maxChars)
+		? maxChars
+		: MARKDOWN_DEFAULT_MAX_CHARS;
+	if (!text || limit <= 0 || text.length <= limit) {
+		return { content: text, truncated: false };
+	}
+	const cut = text.slice(0, limit);
+	// Prefer a clean line break so a table row or code line isn't split.
+	const lastBreak = cut.lastIndexOf('\n');
+	let content = lastBreak > limit * 0.5 ? cut.slice(0, lastBreak) : cut;
+
+	// A cut landing inside a ``` block leaves the fence unbalanced, so the
+	// reader can't tell where code ends. Close it and say so explicitly.
+	const fence = '`'.repeat(3);
+	const fenceCount = (content.match(/^\s*```/gm) ?? []).length;
+	const inFence = fenceCount % 2 !== 0;
+	if (inFence) content += `\n${fence}`;
+	content += `\n\n<!-- TRUNCATED${inFence ? ' mid-example' : ''}: see \`hint\` -->`;
+
+	return {
+		content,
+		truncated: true,
+		originalChars: text.length,
+		returnedChars: content.length,
+		hint: `Truncated to ${content.length} of ${text.length} chars.${inFence ? ' The cut landed inside a code example — the last block is INCOMPLETE, do not copy it as-is.' : ''} ${readHint} Pass \`maxChars: 0\` for the full text, or a larger \`maxChars\`.`,
+	};
+}
+
+function getComponent({ name, maxChars } = {}) {
+	const manifest = loadComponentsManifest();
+	const entry = manifest.components.find((c) => c.name === name);
+	if (!entry) {
+		return {
+			found: false,
+			name,
+			hint: 'Unknown component name — try search_components first.',
+		};
+	}
+	const contractPath = entry.contract ?? null;
+	const contractAbsPath = contractPath
+		? join(PACKAGE_ROOT, 'dist', contractPath)
+		: null;
+	const raw =
+		contractAbsPath && existsSync(contractAbsPath)
+			? readFileSync(contractAbsPath, 'utf-8')
+			: null;
+	const { content, ...meta } = truncateMarkdown(
+		raw,
+		maxChars,
+		`The structured \`component\` field above is COMPLETE (all props/events/slots) — the cut text is guidance prose only.`
+	);
+	return {
+		found: true,
+		// Never truncated: the precision-critical surface.
+		component: entry,
+		contractPath,
+		contractContent: content,
+		...meta,
+	};
+}
+
+/** `list_recipes({ platform? })` — recipe names under dist/ai/recipes/<platform>/. */
+/** Shipped stylesheet that carries every resolved `--bb-*` theme token. */
+const STYLES_CSS = join(PACKAGE_ROOT, 'dist', 'styles.css');
+
+/**
+ * Selectors that carry a THEME value rather than a component-local rebind:
+ * the root scopes a consumer themes on. A selector list qualifies only when
+ * every comma-part is built solely from these — `:root`, `.light`, `:root.dark`
+ * and `html.dark` are theme roots; `.bb-tooltip .bb-common-popover__bubble` is
+ * not, however many `--bb-*` it redeclares.
+ */
+const THEME_ROOT_PART = /^(?::root|html|body|\.light|\.dark)+$/;
+function isThemeSelector(selector) {
+	return selector
+		.split(',')
+		.every((part) =>
+			THEME_ROOT_PART.test(part.replace(/[\s>+~]+/g, '').trim())
+		);
+}
+
+/**
+ * Walk a stylesheet and yield every `--bb-*` declaration WITH the selector that
+ * owns it. A flat regex cannot do this: it sees a declaration but not its
+ * scope, so a component that locally rebinds a theme token is indistinguishable
+ * from the dark theme redefining it. Brace-depth scanning (quote-aware, and
+ * tolerant of the missing final semicolon that minified CSS emits) is the
+ * cheapest way to keep the scope — and this file ships in the package, so it
+ * may not reach for postcss the way the dev-only `check:tokens` script does.
+ */
+function* eachTokenDeclaration(css) {
+	const stack = [];
+	let buffer = '';
+	let quote = null;
+	const declaration = () => {
+		const m = buffer.match(/(--bb-[a-z0-9-]+)\s*:\s*([\s\S]+)/);
+		buffer = '';
+		return m ? { name: m[1], value: m[2].trim() } : null;
+	};
+	for (const char of css) {
+		if (quote) {
+			buffer += char;
+			if (char === quote) quote = null;
+			continue;
+		}
+		if (char === '"' || char === "'") {
+			quote = char;
+			buffer += char;
+		} else if (char === '{') {
+			stack.push(buffer.trim());
+			buffer = '';
+		} else if (char === '}' || char === ';') {
+			const decl = declaration();
+			if (decl) yield { ...decl, selector: stack[stack.length - 1] ?? '' };
+			if (char === '}') stack.pop();
+		} else {
+			buffer += char;
+		}
+	}
+}
+
+/**
+ * `list_tokens({ filter })` — the `--bb-*` design tokens with their values,
+ * read from the shipped stylesheet (the same 89 `check:tokens` counts).
+ *
+ * WHY ONLY `--bb-*` — and why there is no opt-in for the unprefixed ones, even
+ * though `search_components` has `includeReferenceOnly`. The two tiers are not
+ * the same kind of thing. `--bb-*` is a flat, global, consumer-settable
+ * contract. Unprefixed component tokens are *sealed to the file that consumes
+ * them* (`check:tokens` rule 3), so the same name means different things in
+ * different components and is only meaningful inside that component's scope.
+ * Serving them as one flat list would invite exactly the wrong move — an agent
+ * writing `:root { --gap: … }` and wondering why nothing changed. They are
+ * documented per component, which `get_component` already serves.
+ *
+ * WHY `dist/styles.css` AND NOT `src/assets/css/variables.css`: `src/` is not
+ * in the published package, so the source file does not exist for the consumer
+ * this server runs inside. The shipped sheet also carries *resolved* values.
+ *
+ * There is no `limit`/`maxChars` here by design: the whole set is ~9 KB, and a
+ * half-list of tokens is the same failure as a half-list of props — it makes an
+ * agent invent the missing ones.
+ */
+function listTokens({ filter } = {}) {
+	if (!existsSync(STYLES_CSS)) {
+		return {
+			tokens: [],
+			error:
+				'dist/styles.css not found — the package looks unbuilt (run `npm run build`).',
+		};
+	}
+	const css = readFileSync(STYLES_CSS, 'utf-8');
+	const byName = new Map();
+	for (const { name, value, selector } of eachTokenDeclaration(css)) {
+		const entry = byName.get(name) ?? { theme: [], local: [] };
+		if (isThemeSelector(selector)) {
+			// Light first, dark after: report both rather than let one win.
+			if (!entry.theme.includes(value)) entry.theme.push(value);
+		} else if (!entry.local.some((r) => r.selector === selector)) {
+			// A component rebinding a theme token for its own subtree. Reporting
+			// this as a `themeOverride` is a lie an agent acts on — it reads
+			// `--bb-arrow: 0` as "the dark theme hides arrows".
+			entry.local.push({ selector, value });
+		}
+		byName.set(name, entry);
+	}
+	const needle = String(filter ?? '')
+		.toLowerCase()
+		.trim();
+	const tokens = [...byName.entries()]
+		.filter(([name]) => !needle || name.toLowerCase().includes(needle))
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([name, { theme, local }]) => ({
+			name,
+			value: theme[0],
+			...(theme.length > 1 ? { themeOverrides: theme.slice(1) } : {}),
+			...(local.length > 0 ? { localRebinds: local } : {}),
+		}));
+	return {
+		count: tokens.length,
+		...(needle ? { filter: needle } : { total: byName.size }),
+		tokens,
+		hint:
+			needle && tokens.length === 0
+				? `No token name contains '${needle}'. Call list_tokens with no filter for all ${byName.size} — the names are semantic (primary/danger/panel/text/border/radius/…), not literal colours.`
+				: 'Theme tokens are set by the consumer app (e.g. on :root / .dark); `themeOverrides` is the dark-theme value. `localRebinds` is a component rebinding the token inside its own subtree — not something to copy. Component-level unprefixed tokens are documented per component; see the design-tokens guide via get_guide.',
+	};
+}
+
+/** Every guide markdown path under dist/ai/guides, relative to that dir. */
+function collectGuidePaths(dir, prefix = '') {
+	const out = [];
+	if (!existsSync(dir)) return out;
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+		if (entry.isDirectory())
+			out.push(...collectGuidePaths(join(dir, entry.name), rel));
+		else if (entry.name.endsWith('.md')) out.push(rel);
+	}
+	return out;
+}
+
+/** `list_guides()` — the shipped prose guides an agent can read. */
+function listGuides() {
+	const guides = collectGuidePaths(join(AI_ROOT, 'guides')).sort();
+	return {
+		count: guides.length,
+		guides,
+		hint: 'Read one with get_guide({ name }). Start at `ai-router.md`, then `agent-contract.md` — do not read them all.',
+	};
+}
+
+/** `get_guide({ name, maxChars })` — read one guide by relative path. */
+function getGuide({ name, maxChars } = {}) {
+	const rel = String(name ?? '').replace(/^\/+/, '');
+	// Contain reads to the guides dir — no traversal out of the knowledge base.
+	if (!rel || rel.includes('..')) {
+		return {
+			found: false,
+			error: `Invalid guide name '${name}'.`,
+			hint: 'Call list_guides for the available names.',
+		};
+	}
+	const fileName = rel.endsWith('.md') ? rel : `${rel}.md`;
+	const guidesDir = join(AI_ROOT, 'guides');
+	const filePath = join(guidesDir, fileName);
+	if (!filePath.startsWith(guidesDir) || !existsSync(filePath)) {
+		return {
+			found: false,
+			error: `Guide not found: ${fileName}`,
+			hint: 'Call list_guides for the available names.',
+		};
+	}
+	const { content, ...meta } = truncateMarkdown(
+		readFileSync(filePath, 'utf-8'),
+		maxChars,
+		`Guides are ordered narrative — the cut tail is later sections.`
+	);
+	return { found: true, name: fileName, content, ...meta };
+}
+
+function listRecipes({ platform } = {}) {
+	const platforms = platform ? [platform] : RECIPE_PLATFORMS;
+	const invalid = platforms.filter((p) => !RECIPE_PLATFORMS.includes(p));
+	if (invalid.length > 0) {
+		return {
+			recipes: [],
+			error: `Unknown platform(s): ${invalid.join(', ')} — expected one of ${RECIPE_PLATFORMS.join(', ')}`,
+		};
+	}
+	const recipes = [];
+	for (const p of platforms) {
+		const dir = join(AI_ROOT, 'recipes', p);
+		if (!existsSync(dir)) continue;
+		for (const file of readdirSync(dir)) {
+			if (file.endsWith('.md')) {
+				recipes.push({ platform: p, name: file.slice(0, -3) });
+			}
+		}
+	}
+	return { recipes };
+}
+
+/** `get_recipe({ platform, name })` — read one recipe's markdown content. */
+function getRecipe({ platform, name, maxChars } = {}) {
+	if (!RECIPE_PLATFORMS.includes(platform)) {
+		return {
+			found: false,
+			error: `Unknown platform '${platform}' — expected one of ${RECIPE_PLATFORMS.join(', ')}`,
+		};
+	}
+	const fileName = String(name ?? '').endsWith('.md')
+		? String(name)
+		: `${name}.md`;
+	const filePath = join(AI_ROOT, 'recipes', platform, fileName);
+	if (!existsSync(filePath)) {
+		return { found: false, error: `Recipe not found: ${platform}/${fileName}` };
+	}
+	const { content, ...meta } = truncateMarkdown(
+		readFileSync(filePath, 'utf-8'),
+		maxChars,
+		`Recipes are ordered narrative — the cut tail is later sections.`
+	);
+	return {
+		found: true,
+		platform,
+		name: fileName.slice(0, -3),
+		content,
+		...meta,
+	};
+}
+
+/** `validate({ code })` — Phase 2 validator core over a Vue snippet. */
+function validateCode({ code } = {}) {
+	const manifest = getManifestMap();
+	const { findings } = validateVueSnippet(String(code ?? ''), manifest);
+	return { ok: findings.length === 0, findings };
+}
+
+/**
+ * Wrap a pure knowledge-base function as an SDK tool callback: its return
+ * value is pretty-printed into a single text content block; a thrown error
+ * becomes an `isError` result carrying `Error: <message>` — preserving the
+ * exact result shape of the previous hand-rolled dispatch.
+ */
+function toolCallback(fn) {
+	return (args) => {
+		try {
+			const result = fn(args ?? {});
+			return {
+				content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+				isError: false,
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: 'text', text: `Error: ${message}` }],
+				isError: true,
+			};
+		}
+	};
+}
+
+const platformSchema = z.enum(RECIPE_PLATFORMS);
+
+/** Register the knowledge-base tools on a fresh McpServer instance. */
+function buildServer() {
+	const server = new McpServer(
+		{ name: 'bitboss-ui', version: packageVersion() },
+		{ capabilities: { tools: {} } }
+	);
+
+	server.registerTool(
+		'search_components',
+		{
+			description:
+				'Search the bitboss-ui component manifest by name and description, ranked by relevance (exact/prefix name matches first, description matches last). Returns consumer-API components only by default. Use this to find the right Bb* component before writing usage code.',
+			inputSchema: {
+				query: z
+					.string()
+					.describe('Text to match against component name/description.'),
+				limit: z
+					.number()
+					.int()
+					.positive()
+					.optional()
+					.describe(
+						`Max results to return (default ${SEARCH_DEFAULT_LIMIT}). Response reports \`totalMatches\` when truncated.`
+					),
+				includeReferenceOnly: z
+					.boolean()
+					.optional()
+					.describe(
+						'Include reference-only internal components (BbBase*, Common*). Default false — these are not consumer API and should not be recommended.'
+					),
+			},
+		},
+		toolCallback(searchComponents)
+	);
+
+	server.registerTool(
+		'get_component',
+		{
+			description:
+				'Get the full manifest entry (props/events/slots/models, removed/renamed history) for one bitboss-ui component by exact name, plus the rendered contract markdown content.',
+			inputSchema: {
+				name: z.string().describe("Exact component name, e.g. 'BbButton'."),
+				maxChars: z
+					.number()
+					.int()
+					.min(0)
+					.optional()
+					.describe(
+						`Cap on the returned contract markdown (default ${MARKDOWN_DEFAULT_MAX_CHARS}; 0 = no cap). The structured props/events/slots are never truncated.`
+					),
+			},
+		},
+		toolCallback(getComponent)
+	);
+
+	server.registerTool(
+		'list_tokens',
+		{
+			description:
+				'List the bitboss-ui `--bb-*` design tokens with their shipped values (optionally filtered by substring). Use this before writing custom CSS so you theme with real tokens instead of hardcoded colors or sizes.',
+			inputSchema: {
+				filter: z
+					.string()
+					.optional()
+					.describe(
+						"Optional substring to narrow the token names, e.g. 'radius' or 'danger'."
+					),
+			},
+		},
+		toolCallback(listTokens)
+	);
+
+	server.registerTool(
+		'list_guides',
+		{
+			description:
+				'List the available bitboss-ui prose guides (router, agent contract, design language/tokens, platform and migration guides). Read one with get_guide.',
+			inputSchema: {},
+		},
+		toolCallback(listGuides)
+	);
+
+	server.registerTool(
+		'get_guide',
+		{
+			description:
+				"Read one bitboss-ui guide by name (as listed by list_guides, e.g. 'ai-router.md' or 'migration/v2-to-v3.md').",
+			inputSchema: {
+				name: z
+					.string()
+					.describe(
+						"Guide path relative to the guides dir, e.g. 'design-tokens.md'. The '.md' suffix is optional."
+					),
+				maxChars: z
+					.number()
+					.int()
+					.min(0)
+					.optional()
+					.describe(
+						`Cap on the returned markdown (default ${MARKDOWN_DEFAULT_MAX_CHARS}; 0 = no cap).`
+					),
+			},
+		},
+		toolCallback(getGuide)
+	);
+
+	server.registerTool(
+		'list_recipes',
+		{
+			description:
+				'List available page-level recipes (whole-page compositions), optionally filtered by platform.',
+			inputSchema: {
+				platform: platformSchema
+					.optional()
+					.describe('Optional platform filter.'),
+			},
+		},
+		toolCallback(listRecipes)
+	);
+
+	server.registerTool(
+		'get_recipe',
+		{
+			description:
+				'Read the full markdown content of one recipe by platform and name.',
+			inputSchema: {
+				platform: platformSchema.describe(
+					'Which platform variant of the recipe to read.'
+				),
+				name: z
+					.string()
+					.describe("Recipe name without extension, e.g. 'onboarding'."),
+				maxChars: z
+					.number()
+					.int()
+					.min(0)
+					.optional()
+					.describe(
+						`Cap on the returned markdown (default ${MARKDOWN_DEFAULT_MAX_CHARS}; 0 = no cap).`
+					),
+			},
+		},
+		toolCallback(getRecipe)
+	);
+
+	server.registerTool(
+		'validate',
+		{
+			description:
+				'Validate a Vue template/SFC snippet against the installed components.json manifest: reports unknown Bb* props, unknown v-models, and removed/renamed props. Run this after writing bitboss-ui markup.',
+			inputSchema: {
+				code: z
+					.string()
+					.describe('Vue template or SFC source containing Bb* usage.'),
+			},
+		},
+		toolCallback(validateCode)
+	);
+
+	return server;
+}
+
+/**
+ * Start the stdio MCP server and resolve once the transport closes (stdin
+ * ends). The SDK owns message framing and the protocol handshake.
+ */
+export async function main() {
+	const server = buildServer();
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	return new Promise((resolve) => {
+		transport.onclose = () => resolve();
+	});
+}
+
+export const start = main;
+
+/**
+ * The knowledge-base half, exported for in-process callers that want the same
+ * answers an MCP client gets without paying for a subprocess and a handshake —
+ * today, `scripts/run-eval-agent.mjs`, which hands these to a model as tools so
+ * the benchmark measures the knowledge base this server actually serves. Pure
+ * functions of the installed `dist/`: no transport, no state, safe to call
+ * concurrently. Importing this module does not start a server.
+ */
+export {
+	searchComponents,
+	getComponent,
+	listTokens,
+	listGuides,
+	getGuide,
+	listRecipes,
+	getRecipe,
+	validateCode,
+};
+
+const isDirectRun =
+	process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+if (isDirectRun) {
+	main();
+}