@urbicon-ui/mcp-server 6.22.0 → 6.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/mcp-server",
-  "version": "6.22.0",
+  "version": "6.23.0",
   "description": "Model Context Protocol server exposing the Urbicon UI component catalog, recipes and design intelligence to LLM agents",
   "license": "MIT",
   "repository": {
@@ -32,8 +32,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@urbicon-ui/design-content": "6.22.0",
-    "@urbicon-ui/design-engine": "6.22.0",
+    "@urbicon-ui/design-content": "6.23.0",
+    "@urbicon-ui/design-engine": "6.23.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/src/data/catalog-loader.ts

@@ -31,6 +31,13 @@ function initWatcher(): void {
   }
 }
 
+/**
+ * Load and cache the assembled component catalog (the single source of truth,
+ * auth components included). Unlike the read-tolerant loaders, this **throws**
+ * on a missing or corrupt catalog by design — the server never serves a
+ * silently empty or stale catalog. A file watcher invalidates the cache when
+ * the catalog changes on disk (dev regeneration).
+ */
 export async function loadCatalog(): Promise<ComponentCatalog> {
   if (cachedCatalog) return cachedCatalog;
 
@@ -48,6 +55,7 @@ export async function loadCatalog(): Promise<ComponentCatalog> {
   return cachedCatalog;
 }
 
+/** The in-memory catalog if {@link loadCatalog} has run, else `null`. No I/O. */
 export function getCachedCatalog(): ComponentCatalog | null {
   return cachedCatalog;
 }

package/src/data/component-loader.ts

@@ -9,6 +9,16 @@ const SEARCH_GROUPS = [
   'auth/components'
 ];
 
+/**
+ * Read a component's `llm.txt` by slug, probing each search group in order
+ * (blocks primitives/components, docs, table, auth). Returns `null` only when
+ * the file is absent (ENOENT) in *every* group — a genuine "unknown component".
+ * Any other I/O error (permissions, corrupt mount) is rethrown rather than
+ * masked as not-found.
+ *
+ * @param slug - Kebab-case component slug (e.g. `date-picker`).
+ * @returns The raw llm.txt, or `null` if no group has it.
+ */
 export async function loadComponentLlmTxt(slug: string): Promise<string | null> {
   for (const group of SEARCH_GROUPS) {
     const path = getComponentLlmPath(group, slug);

package/src/data/design-system-loader.ts

@@ -16,6 +16,11 @@ export {
 let cachedPrinciples: string | null = null;
 let cachedPatterns: PatternEntry[] | null = null;
 
+/**
+ * Load and cache `principles.md` from the design-system dir. Read-tolerant:
+ * yields `''` when the file is absent, so `get_design_principles` can degrade to
+ * a hint instead of crashing.
+ */
 export async function loadPrinciples(): Promise<string> {
   if (cachedPrinciples !== null) return cachedPrinciples;
 
@@ -28,6 +33,11 @@ export async function loadPrinciples(): Promise<string> {
   return cachedPrinciples;
 }
 
+/**
+ * Load, parse and cache every `patterns/*.md` file, sorted by name. Read-
+ * tolerant: a missing dir or an unreadable file yields `[]` / is skipped rather
+ * than throwing.
+ */
 export async function loadPatterns(): Promise<PatternEntry[]> {
   if (cachedPatterns) return cachedPatterns;
 
@@ -61,6 +71,7 @@ export async function loadPatterns(): Promise<PatternEntry[]> {
   return entries;
 }
 
+/** One pattern by exact name from the cached set, or `null` if none matches. */
 export async function getPatternByName(name: string): Promise<PatternEntry | null> {
   const patterns = await loadPatterns();
   return patterns.find((p) => p.name === name) ?? null;

package/src/data/template-loader.ts

@@ -1,6 +1,11 @@
 import { readFile } from 'node:fs/promises';
 import { getTemplatePath } from '@urbicon-ui/design-content';
 
+/**
+ * The seven guide sections carved out of the single template document, keyed by
+ * guide id. Each value is the raw markdown of one `## …` section; the keys are
+ * the ids the guide resources ({@link registerGuideResources}) expose.
+ */
 export interface TemplateSections {
   'api-grammar': string;
   'component-families': string;
@@ -28,6 +33,11 @@ function extractSection(lines: string[], startHeading: string, endMarker: string
   return lines.slice(startIdx, endIdx).join('\n').trim();
 }
 
+/**
+ * Load the template document once and slice it into the seven
+ * {@link TemplateSections} by `## …` heading (each running up to the next `---`
+ * rule; auth-setup, the last section, runs to EOF). Cached per process.
+ */
 export async function loadTemplateSections(): Promise<TemplateSections> {
   if (cachedSections) return cachedSections;
 
@@ -50,6 +60,7 @@ export async function loadTemplateSections(): Promise<TemplateSections> {
   return cachedSections;
 }
 
+/** The cached sections if {@link loadTemplateSections} has run, else `null`. No I/O. */
 export function getCachedSections(): TemplateSections | null {
   return cachedSections;
 }

package/src/prompts/design-prompts.ts

@@ -141,6 +141,11 @@ function schemaFor(args: VerbArg[]): Record<string, z.ZodString | z.ZodOptional<
   return shape;
 }
 
+/**
+ * Register one MCP prompt per {@link VERBS} entry. Each prompt exposes only the
+ * args that verb uses, loads its recipe body lazily on invocation (via
+ * `loadVerb`), and wraps it with the per-call header from {@link buildVerbPrompt}.
+ */
 export function registerDesignPrompts(server: McpServer): void {
   for (const verb of VERBS) {
     server.prompt(verb.name, verb.summary, schemaFor(verb.args), async (args: VerbArgs) => {

package/src/resources/catalog.ts

@@ -2,6 +2,12 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { loadCatalog } from '../data/catalog-loader.js';
 import { formatCompactCatalog } from '../utils/format-catalog.js';
 
+/**
+ * Register the `urbicon://catalog` resource: the whole component catalog as
+ * compact markdown (the same `formatCompactCatalog` render as `find_components`
+ * with no query). Lets a client pin the catalog as context instead of calling
+ * the tool.
+ */
 export function registerCatalogResource(server: McpServer): void {
   server.resource('catalog', 'urbicon://catalog', async (uri) => {
     const catalog = await loadCatalog();

package/src/resources/guides.ts

@@ -2,6 +2,11 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { TemplateSections } from '../data/template-loader.js';
 import { loadTemplateSections } from '../data/template-loader.js';
 
+/**
+ * The seven guide surfaces, each mapping a stable resource id to a section of
+ * the template bundle ({@link TemplateSections}). Edit here to add/rename a
+ * guide; the `key` must exist in `TemplateSections`.
+ */
 const GUIDE_RESOURCES: { id: string; name: string; key: keyof TemplateSections }[] = [
   {
     id: 'api-grammar',
@@ -40,6 +45,11 @@ const GUIDE_RESOURCES: { id: string; name: string; key: keyof TemplateSections }
   }
 ];
 
+/**
+ * Register one `urbicon://guide/<id>` resource per {@link GUIDE_RESOURCES} entry.
+ * Each read slices its section out of the cached template bundle and degrades to
+ * a "not found" note if the section is missing.
+ */
 export function registerGuideResources(server: McpServer): void {
   for (const guide of GUIDE_RESOURCES) {
     server.resource(`guide-${guide.id}`, `urbicon://guide/${guide.id}`, async (uri) => {

package/src/server.ts

@@ -13,6 +13,16 @@ import { registerGetRecipeTool } from './tools/get-recipe.js';
 import { registerSuggestImplementationTool } from './tools/suggest-implementation.js';
 import { registerValidateDesignTool } from './tools/validate-design.js';
 
+/**
+ * Assemble a fully-wired `urbicon-ui` MCP server: the two resources, the ten
+ * read-only tools, and the design-verb prompts. Deliberately stateless — it
+ * never reads or writes a consumer's design manifest (that lives in the
+ * consumer repo, via the `urbicon` CLI or the agent's own file tools), so a
+ * fresh instance can be created per HTTP session. Called by both transports.
+ *
+ * @returns A ready-to-connect `McpServer`; the caller attaches a transport
+ *   (`startStdioTransport` / `startHttpTransport`).
+ */
 export function createServer(): McpServer {
   const server = new McpServer({
     name: 'urbicon-ui',

package/src/tools/find-components.ts

@@ -4,6 +4,13 @@ import { z } from 'zod';
 import { loadCatalog } from '../data/catalog-loader.js';
 import { formatCompactCatalog, formatComponentLine } from '../utils/format-catalog.js';
 
+/**
+ * Register the `find_components` tool: the catalog entry point. With no query it
+ * renders the full catalog grouped by category (via `formatCompactCatalog`);
+ * with a query it fuzzy-matches names/descriptions/tags through the engine's
+ * `matchComponents` (top 10). Every line keeps the origin-package tag so a
+ * non-blocks match (e.g. `Table`) is never mistaken for a blocks export.
+ */
 export function registerFindComponentsTool(server: McpServer): void {
   server.tool(
     'find_components',

package/src/tools/find-icons.ts

@@ -2,6 +2,12 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ICON_CATEGORY_ORDER } from '@urbicon-ui/design-engine/search';
 import { loadIcons } from '../data/icon-loader.js';
 
+/**
+ * Register the `find_icons` tool (no arguments): render the full icon reference
+ * — usage snippets plus every icon grouped by `ICON_CATEGORY_ORDER`, each listed
+ * as component name + dynamic `name`. Degrades to a hint when the icon bundle is
+ * unavailable (see {@link loadIcons}).
+ */
 export function registerFindIconsTool(server: McpServer): void {
   server.tool(
     'find_icons',

package/src/tools/get-checklist.ts

@@ -2,6 +2,13 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { loadCatalog } from '../data/catalog-loader.js';
 
+/**
+ * Register the `get_implementation_checklist` tool: emit the static best-practice
+ * checklist (setup, tokens, styling, a11y, i18n, design quality). When
+ * `components` are supplied, append a per-component notes section (variants,
+ * slots, related) resolved from the catalog. Overlaps the rules that
+ * `suggest_implementation` inlines — this is the standalone entry point.
+ */
 export function registerGetChecklistTool(server: McpServer): void {
   server.tool(
     'get_implementation_checklist',

package/src/tools/get-component.ts

@@ -127,6 +127,13 @@ function generateCompactView(entry: ComponentCatalogEntry, llmContent: string):
   return md;
 }
 
+/**
+ * Register the `get_component` tool: per-component API docs at three depths —
+ * a compact catalog+llm.txt summary (default), one named `section`, or the full
+ * llm.txt (`section="full"`). Unknown slugs return a find_components hint; a
+ * slug present in llm.txt but absent from the catalog falls back to full content
+ * rather than failing.
+ */
 export function registerGetComponentTool(server: McpServer): void {
   server.tool(
     'get_component',

package/src/tools/get-css-reference.ts

@@ -9,6 +9,12 @@ import { z } from 'zod';
 // `urbicon css-reference` CLI command so local and remote answers agree; this tool is
 // only the MCP facade. Drift against the real blocks CSS is guarded by the engine's
 // `css-reference.test.ts`.
+/**
+ * Register the `get_css_reference` tool: a pure facade over the engine's
+ * `renderCssReference`. Returns the token overview (naming + dark-mode
+ * mechanism) or a single category section. All text lives in the engine, shared
+ * with `urbicon css-reference`, so this file holds no reference content itself.
+ */
 export function registerGetCssReferenceTool(server: McpServer): void {
   server.tool(
     'get_css_reference',

package/src/tools/get-design-principles.ts

@@ -7,6 +7,13 @@ import {
   PRINCIPLE_TOPICS
 } from '../data/design-system-loader.js';
 
+/**
+ * Register the `get_design_principles` tool with two output modes. `as="guide"`
+ * (default) returns the heuristics from `principles.md` — whole, or one `topic`
+ * section. `as="rubric"` instead renders the engine's scoring rubric (via
+ * `renderRubric`) and ignores `topic`. Missing principles content degrades to a
+ * hint rather than throwing.
+ */
 export function registerGetDesignPrinciplesTool(server: McpServer): void {
   server.tool(
     'get_design_principles',

package/src/tools/get-pattern.ts

@@ -2,6 +2,12 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { getPatternByName, loadPatterns } from '../data/design-system-loader.js';
 
+/**
+ * Register the `get_pattern` tool: one composition pattern's full content by
+ * `name`, or — when `name` is omitted — the list of available patterns. An
+ * unknown name echoes the valid names back. Patterns are loaded/cached by
+ * `design-system-loader`.
+ */
 export function registerGetPatternTool(server: McpServer): void {
   server.tool(
     'get_pattern',

package/src/tools/get-recipe.ts

@@ -2,6 +2,12 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { loadCatalog } from '../data/catalog-loader.js';
 
+/**
+ * Register the `get_recipe` tool: return a full, production-ready recipe (title,
+ * pattern link, components, features, code) by id. Recipes travel inside the
+ * catalog — no separate source read — so an unknown id lists every available id
+ * from the same catalog load.
+ */
 export function registerGetRecipeTool(server: McpServer): void {
   server.tool(
     'get_recipe',

package/src/tools/suggest-implementation.ts

@@ -86,6 +86,14 @@ const IMPLEMENTATION_RULES = `## Implementation Rules
 - **Don't copy recipe styling** — Recipes show ONE interpretation. Create YOUR visual identity with your own spacing rhythm, color distribution, and layout density.
 `;
 
+/**
+ * Register the `suggest_implementation` tool: assemble a Svelte 5 skeleton from
+ * either explicit component names (looked up in the catalog) or a free-text
+ * description (matched via the engine). Emits imports, a per-component prop/
+ * variant digest, a skeleton built from `SKELETON_HINTS`, the inlined
+ * `IMPLEMENTATION_RULES` (so no follow-up checklist call is needed), and any
+ * recipe whose id substring-matches or that shares ≥40% of the matched set.
+ */
 export function registerSuggestImplementationTool(server: McpServer): void {
   server.tool(
     'suggest_implementation',

package/src/tools/validate-design.ts

@@ -56,6 +56,13 @@ function renderReport(report: LintReport): string {
   return md;
 }
 
+/**
+ * Register the `validate_design` tool: a thin facade over the engine's
+ * `lintDesign`. It renders the {@link LintReport} into markdown (findings
+ * grouped by severity, with per-finding fixes and the two scores) but adds no
+ * rules of its own — the linter is shared verbatim with the `urbicon validate`
+ * CLI, so local and remote verdicts agree.
+ */
 export function registerValidateDesignTool(server: McpServer): void {
   server.tool(
     'validate_design',

package/src/transports/http.ts

@@ -2,6 +2,20 @@ import { createServer as createHttpServer } from 'node:http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { createServer as createMcpServer } from '../server.js';
 
+/**
+ * Serve the MCP over Streamable HTTP on `/mcp`, multiplexing clients by the
+ * `mcp-session-id` header. Each session gets its own server + transport pair:
+ * - `POST` **without** a session id opens one (fresh {@link createServer}, a
+ *   generated id) and remains registered until the transport closes;
+ * - `POST`/`GET`/`DELETE` **with** a known id are routed to that session;
+ * - a `POST` carrying an **unknown** id, or a session-less `GET`/`DELETE`, is a
+ *   `400` — the stateless server never resurrects a session it did not open.
+ *
+ * Any non-`/mcp` path returns a plain-text banner (a lightweight liveness ping).
+ * Runs until the process exits; there is no returned stop handle.
+ *
+ * @param port - TCP port to listen on (binds `http://localhost:<port>/mcp`).
+ */
 export async function startHttpTransport(port: number): Promise<void> {
   const sessions = new Map<string, StreamableHTTPServerTransport>();
 

package/src/transports/stdio.ts

@@ -1,6 +1,13 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
+/**
+ * Connect an assembled server over stdio — the transport for a local, single-
+ * client host (one server instance per process; the client speaks JSON-RPC on
+ * stdin/stdout). For a shared network endpoint use {@link startHttpTransport}.
+ *
+ * @param server - A server from {@link createServer}.
+ */
 export async function startStdioTransport(server: McpServer): Promise<void> {
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/src/utils/format-catalog.ts

@@ -23,12 +23,29 @@ const TAG_LABELS: Record<string, string> = {
   data: 'Data'
 };
 
+/**
+ * Drop the docs-site-only components (`ApiReference`, `CodeExample`, …) that
+ * ship in the assembled catalog but are not consumer-facing API, so they never
+ * surface in `find_components` / the catalog resource.
+ */
 export function filterInternalComponents(
   components: ComponentCatalogEntry[]
 ): ComponentCatalogEntry[] {
   return components.filter((c) => !INTERNAL_COMPONENTS.has(c.name));
 }
 
+/**
+ * Render the browse-view markdown: internal components filtered out, the rest
+ * bucketed by their primary tag in a fixed section order (`TAG_ORDER`, unknown
+ * tags → "Other"), preceded by the install/CSS/dark-mode setup block and
+ * followed by the recipe list. Shared by `find_components` (no query) and the
+ * catalog resource.
+ *
+ * @param components - Full catalog entries (internal ones are removed here).
+ * @param options - `tags` narrows to matching categories (case-insensitive);
+ *   `recipes` appends the recipe index.
+ * @returns Markdown document.
+ */
 export function formatCompactCatalog(
   components: ComponentCatalogEntry[],
   options?: { recipes?: RecipeEntry[]; tags?: string[] }
@@ -111,6 +128,12 @@ function isBooleanVariant(values: string[]): boolean {
   );
 }
 
+/**
+ * Format one catalog entry as a single markdown bullet: name, an origin-package
+ * tag for non-blocks components (so `Table` reads as `@urbicon-ui/table`), the
+ * description, its meaningful (non-boolean) variants, and related components.
+ * The one line shape shared by the browse and search views.
+ */
 export function formatComponentLine(comp: ComponentCatalogEntry): string {
   const variants = comp.variants
     .filter((v) => !isBooleanVariant(v.values))