@urbicon-ui/mcp-server 6.44.0 → 6.45.0

package/README.md

@@ -86,7 +86,7 @@ All tools are read-only (`readOnlyHint: true`) — this server never touches the
 | `find_icons`                   | Browse the 315-icon catalog by keyword, category, or name.                                                                                                                                                                                                                                                                                                                                                                                         |
 | `get_design_principles`        | Design heuristics (Layer 5): visual hierarchy, interaction, component selection, layout, accessibility, theming (paradigms, change decision tree). Call first when generating UI. `as="rubric"` returns the 8-criterion 1–5 scoring rubric for judging a generated UI.                                                                                                                                                                             |
 | `get_pattern`                  | Composition patterns (Layer 4) for page archetypes — settings-page, dashboard, form-page, tab-navigation, onboarding-guide.                                                                                                                                                                                                                                                                                                                        |
-| `validate_design`              | Lint generated markup on two axes — **correctness** (raw colours, `dark:`/`focus:` misuse, hardcoded z-index, broken dynamic classes, hallucinated tokens, foreign-library component APIs, unlabelled icon buttons; the blocking gate) and the **slop-floor** (20 system-agnostic "looks generic" heuristics: generic fonts, animated dimensions, grey-on-colour, touch targets, …; advisory). Returns a correctness score + a slop-floor score and per-finding fixes for a generate → validate → fix loop. |
+| `validate_design`              | Lint generated markup on two axes — **correctness** (raw colours, `dark:`/`focus:` misuse, hardcoded z-index, broken dynamic classes, hallucinated tokens, foreign-library component APIs, unlabelled icon buttons; the blocking gate) and the **craft** axis (20 system-agnostic "looks generic" heuristics: generic fonts, animated dimensions, grey-on-colour, touch targets, …; advisory). Returns a correctness score + a craft score and per-finding fixes for a generate → validate → fix loop. |
 
 ## Resources
 
@@ -111,8 +111,8 @@ The full design-verb table (DESIGN-MCP-V2 §8) — client-agnostic workflows you
 | `adopt`    | `brief?`                       | Brownfield: infer the design language from code, measure drift, seed the manifest.         |
 | `compose`  | `brief?`, `variants?`          | New page via generate → validate → judge → synthesise (variants + rubric + linter gate).   |
 | `redesign` | `brief?`, `code?`, `variants?` | Diagnose with linter + rubric, fix exactly the flagged weaknesses, preserve behaviour.     |
-| `polish`   | `brief?`, `code?`              | Small token-level fixes that raise the slop-floor score without restructuring.             |
-| `critique` | `brief?`, `code?`              | Judge without changing: correctness + slop + rubric → a prioritised, verb-tagged fix-list. |
+| `polish`   | `brief?`, `code?`              | Small token-level fixes that raise the craft score without restructuring.             |
+| `critique` | `brief?`, `code?`              | Judge without changing: correctness + craft + rubric → a prioritised, verb-tagged fix-list. |
 | `fix`      | `brief?`, `code?`              | Repair correctness defects (raw colours, `dark:`/`focus:`, z-index, hallucinated tokens).  |
 | `retheme`  | `brief?`                       | Rebrand: change the token layer once, propagate across every affected file.                |
 | `audit`    | `brief?`                       | App-wide sweep: validate the tree, check pattern cohorts, report drift over time.          |

package/package.json

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

package/src/prompts/design-prompts.ts

@@ -66,13 +66,13 @@ const VERBS: VerbSpec[] = [
   {
     name: 'polish',
     summary:
-      'Tighten a near-final page: small token-level fixes that raise the slop-floor score without restructuring.',
+      'Tighten a near-final page: small token-level fixes that raise the craft score without restructuring.',
     args: ['brief', 'code']
   },
   {
     name: 'critique',
     summary:
-      'Judge a page without changing it: correctness + slop-floor + rubric → a prioritised fix-list, each item tagged with the verb that repairs it.',
+      'Judge a page without changing it: correctness + craft + rubric → a prioritised fix-list, each item tagged with the verb that repairs it.',
     args: ['brief', 'code']
   },
   {

package/src/server.ts

@@ -18,7 +18,8 @@ import { registerValidateDesignTool } from './tools/validate-design.js';
  * 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.
+ * fresh instance can be built per HTTP *request* (~0.2 ms; the catalog behind
+ * it is cached module-globally). Called by both transports.
  *
  * @returns A ready-to-connect `McpServer`; the caller attaches a transport
  *   (`startStdioTransport` / `startHttpTransport`).

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

@@ -24,7 +24,7 @@ export function registerGetCssReferenceTool(server: McpServer): void {
         .enum(CSS_REFERENCE_SECTION_NAMES)
         .optional()
         .describe(
-          'Token category. Omit for overview with naming conventions and dark mode mechanism.'
+          'Token category — the z-index scale is part of `shadows`. Omit for overview with naming conventions and dark mode mechanism.'
         )
     },
     { readOnlyHint: true },

package/src/tools/validate-design.ts

@@ -6,7 +6,7 @@ import { z } from 'zod';
 const SEVERITY_LABEL: Record<Severity, string> = {
   error: '🔴 Errors',
   warning: '🟠 Warnings',
-  info: '🔵 Slop-floor'
+  info: '🔵 Craft'
 };
 
 function renderFindings(findings: Finding[], severity: Severity): string {
@@ -43,13 +43,13 @@ function renderReport(report: LintReport): string {
 
   let md = `# Design Validation — ${verdict}\n\n`;
   if (filename) md += `> \`${filename}\`\n\n`;
-  md += `**Correctness ${scores.correctness}/100 · Slop-floor ${scores.slop}/100** · ${counts.error} error(s), ${counts.warning} warning(s), ${counts.info} slop note(s)\n\n`;
+  md += `**Correctness ${scores.correctness}/100 · Craft ${scores.craft}/100** · ${counts.error} error(s), ${counts.warning} warning(s), ${counts.info} craft note(s)\n\n`;
   md +=
-    'Two axes, never mixed: **correctness** is the blocking gate (fix every error/warning to pass); **slop-floor** is advisory — system-agnostic "looks generic" signals to raise distinctiveness.\n\n';
+    'Two axes, never mixed: **correctness** is the blocking gate (fix every error/warning to pass); **craft** is advisory — system-agnostic "looks generic" signals to raise distinctiveness.\n\n';
 
   if (findings.length === 0) {
     md +=
-      'No issues found. Tokens are valid, no `dark:`/`focus:`/hardcoded z-index, and the slop-floor heuristics are satisfied.\n';
+      'No issues found. Tokens are valid, no `dark:`/`focus:`/hardcoded z-index, and the craft heuristics are satisfied.\n';
     md += renderSuppressed(report);
     return md;
   }
@@ -81,7 +81,7 @@ function renderReport(report: LintReport): string {
 export function registerValidateDesignTool(server: McpServer): void {
   server.tool(
     'validate_design',
-    'Lint generated Svelte/HTML markup against the Urbicon UI design rules. Two axes, never mixed: (1) **correctness** — deterministic defects (raw Tailwind colours, `dark:`/`focus:` misuse, hardcoded z-index, broken dynamic classes, hallucinated tokens, foreign-library component APIs like `tone=`/`variant="outline"`, icon-only buttons with no accessible name), the blocking gate; (2) **slop-floor** — system-agnostic "looks generic" heuristics (generic fonts, animated width/height, magic-number sizes, low-contrast text on colour, inline styles, `!important`, placeholder copy, emoji-as-icon, heading-level skips, small touch targets, intent-colour rainbow, uniform spacing/weights, identical Cards), advisory. Returns a correctness score and a slop-floor score (both 0–100; correctness −10/error, −5/warning; slop −10 per signal; floored) plus per-finding fixes. Run in a generate → validate → fix loop after producing UI code. Pass `extraTokens` to whitelist semantic tokens your project defines on top of Urbicon’s so they are not flagged as hallucinated. Class rules scan class attributes, slotClasses and tv()/script literals — prose that merely *quotes* an anti-pattern (docs, before/after examples) is not flagged. A deliberately off-system surface can exempt specific rules in-file via `<!-- urbicon-ignore rule-id … — reason -->`; suppressions are always reported, never silent.',
+    'Lint generated Svelte/HTML markup against the Urbicon UI design rules. Two axes, never mixed: (1) **correctness** — deterministic defects (raw Tailwind colours, `dark:`/`focus:` misuse, hardcoded z-index, broken dynamic classes, hallucinated tokens, foreign-library component APIs like `tone=`/`variant="outline"`, icon-only buttons with no accessible name), the blocking gate; (2) **craft** — system-agnostic "looks generic" heuristics (generic fonts, animated width/height, magic-number sizes, low-contrast text on colour, inline styles, `!important`, placeholder copy, emoji-as-icon, heading-level skips, small touch targets, intent-colour rainbow, uniform spacing/weights, identical Cards), advisory. Returns a correctness score and a craft score (both 0–100; correctness −10/error, −5/warning; craft −10 per signal; floored) plus per-finding fixes. Run in a generate → validate → fix loop after producing UI code. Pass `extraTokens` to whitelist semantic tokens your project defines on top of Urbicon’s so they are not flagged as hallucinated. Class rules scan class attributes, slotClasses and tv()/script literals — prose that merely *quotes* an anti-pattern (docs, before/after examples) is not flagged. A deliberately off-system surface can exempt specific rules in-file via `<!-- urbicon-ignore rule-id … — reason -->`; suppressions are always reported, never silent.',
     {
       code: z
         .string()

package/src/transports/http.ts

@@ -1,24 +1,36 @@
-import { createServer as createHttpServer } from 'node:http';
+import { createServer as createHttpServer, type ServerResponse } from 'node:http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { createServer as createMcpServer } from '../server.js';
 
+function respondError(res: ServerResponse, status: number, code: number, message: string): void {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id: null }));
+}
+
 /**
- * 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.
+ * Serve the MCP over Streamable HTTP on `/mcp`, **session-less**: every request
+ * is self-contained, so each `POST` gets a throw-away {@link createServer} +
+ * transport pair that is closed again when the response ends.
+ *
+ * The SDK's session mode (`sessionIdGenerator: () => randomUUID()`) is
+ * deliberately **not** used. It would keep a server instance per session in a
+ * map that only a client's explicit `DELETE` — or a clean transport close —
+ * ever empties, so every client that just goes away (crash, kill, dropped
+ * connection) strands ~0.4 MB of heap forever; on an unauthenticated endpoint a
+ * single anonymous `POST` is enough to do it. That leak reached ~1 GB in
+ * production. Sessions bought nothing here: the server sends no notifications
+ * and holds no per-client state, and rebuilding it per request costs ~0.2 ms.
  *
- * Any non-`/mcp` path returns a plain-text banner (a lightweight liveness ping).
- * Runs until the process exits; there is no returned stop handle.
+ * Consequently `GET` (the standalone SSE stream) and `DELETE` (session
+ * teardown) answer `405` — both explicitly permitted by the MCP spec for a
+ * server that offers no sessions. Any non-`/mcp` path returns a plain-text
+ * banner (a lightweight liveness ping).
  *
  * @param port - TCP port to listen on (binds `http://localhost:<port>/mcp`).
+ * @returns A stop handle; `index.ts` ignores it and runs until the process
+ *   exits, the transport test uses it to shut the listener down.
  */
-export async function startHttpTransport(port: number): Promise<void> {
-  const sessions = new Map<string, StreamableHTTPServerTransport>();
-
+export async function startHttpTransport(port: number): Promise<{ close: () => Promise<void> }> {
   const httpServer = createHttpServer(async (req, res) => {
     const url = new URL(req.url || '/', `http://localhost:${port}`);
 
@@ -28,69 +40,50 @@ export async function startHttpTransport(port: number): Promise<void> {
       return;
     }
 
-    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+    if (req.method !== 'POST') {
+      respondError(
+        res,
+        405,
+        -32600,
+        'Method not allowed — this server is session-less; every request must be a self-contained POST'
+      );
+      return;
+    }
 
-    if (req.method === 'POST') {
-      const session = sessionId ? sessions.get(sessionId) : undefined;
-      if (session) {
-        await session.handleRequest(req, res);
-      } else if (!sessionId) {
-        const transport = new StreamableHTTPServerTransport({
-          sessionIdGenerator: () => crypto.randomUUID()
-        });
-        transport.onclose = () => {
-          if (transport.sessionId) sessions.delete(transport.sessionId);
-        };
-        const server = createMcpServer();
-        await server.connect(transport);
-        await transport.handleRequest(req, res);
-        if (transport.sessionId) sessions.set(transport.sessionId, transport);
-      } else {
-        res.writeHead(400, { 'Content-Type': 'application/json' });
-        res.end(
-          JSON.stringify({
-            jsonrpc: '2.0',
-            error: { code: -32600, message: 'Invalid session' },
-            id: null
-          })
-        );
-      }
-    } else if (req.method === 'GET') {
-      const session = sessionId ? sessions.get(sessionId) : undefined;
-      if (session) {
-        await session.handleRequest(req, res);
-      } else {
-        res.writeHead(400, { 'Content-Type': 'application/json' });
-        res.end(
-          JSON.stringify({
-            jsonrpc: '2.0',
-            error: { code: -32600, message: 'Missing or invalid session' },
-            id: null
-          })
-        );
-      }
-    } else if (req.method === 'DELETE') {
-      const session = sessionId ? sessions.get(sessionId) : undefined;
-      if (session && sessionId) {
-        await session.handleRequest(req, res);
-        sessions.delete(sessionId);
-      } else {
-        res.writeHead(204);
+    const server = createMcpServer();
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+
+    // Tear down when the response ends — whether it completed or the client
+    // hung up. This is the only lifetime the pair has; nothing outlives it.
+    res.on('close', () => {
+      void transport.close();
+      void server.close();
+    });
+
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res);
+    } catch (err) {
+      console.error('MCP request failed:', err);
+      if (res.headersSent) {
         res.end();
+      } else {
+        respondError(res, 500, -32603, 'Internal server error');
       }
-    } else {
-      res.writeHead(405, { 'Content-Type': 'application/json' });
-      res.end(
-        JSON.stringify({
-          jsonrpc: '2.0',
-          error: { code: -32600, message: 'Method not allowed' },
-          id: null
-        })
-      );
     }
   });
 
-  httpServer.listen(port, () => {
-    console.error(`Urbicon UI MCP Server listening on http://localhost:${port}/mcp`);
+  await new Promise<void>((resolve) => {
+    httpServer.listen(port, () => {
+      console.error(`Urbicon UI MCP Server listening on http://localhost:${port}/mcp`);
+      resolve();
+    });
   });
+
+  return {
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        httpServer.close((err) => (err ? reject(err) : resolve()));
+      })
+  };
 }