@urbicon-ui/mcp-server 6.28.0 → 6.29.0

package/README.md

@@ -97,7 +97,7 @@ All tools are read-only (`readOnlyHint: true`) — this server never touches the
 | `urbicon://guide/design-quality` | AVOID/INSTEAD patterns from A/B-tested design-quality guidance (+33.8 % improvement in user study) |
 | `urbicon://guide/component-families` | Six-family component taxonomy - ARIA roles and per-family border-token source                      |
 | `urbicon://guide/customization`  | `unstyled` / `slotClasses` / `preset` override system + `BlocksProvider` overrides                 |
-| `urbicon://guide/auth-setup`     | Auth package setup - handler factories, handle hook, adapter pattern, client stores                |
+| `urbicon://guide/auth`           | Complete auth reference - served verbatim from the bundled, tarball-canonical `AUTH.md`            |
 | `urbicon://guide/style-patterns` | Reusable style presets and composition templates                                                   |
 | `urbicon://guide/tokens`         | OKLCH token reference, same data as `get_css_reference`                                            |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/mcp-server",
-  "version": "6.28.0",
+  "version": "6.29.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.28.0",
-    "@urbicon-ui/design-engine": "6.28.0",
+    "@urbicon-ui/design-content": "6.29.0",
+    "@urbicon-ui/design-engine": "6.29.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/src/data/guide-loader.ts

@@ -0,0 +1,29 @@
+import { readFile } from 'node:fs/promises';
+import { getGuidePath } from '@urbicon-ui/design-content';
+
+/**
+ * Reader for the bundle's canonical package guides (`guides/<slug>.md`) — the
+ * tarball-shipped guide documents (e.g. `packages/auth/docs/AUTH.md`) that
+ * docs-gen distributes into the design-content bundle. Unlike the template
+ * sections (template-loader.ts) these are complete documents, served verbatim.
+ * Cached per process, like the template sections.
+ */
+const cachedGuides = new Map<string, string>();
+
+/**
+ * Load one bundled package guide by slug. `null` when the guide (or the
+ * bundle) is absent — the resource read degrades to a "not found" note, the
+ * same contract as a missing template section.
+ */
+export async function loadPackageGuide(slug: string): Promise<string | null> {
+  const cached = cachedGuides.get(slug);
+  if (cached !== undefined) return cached;
+
+  try {
+    const content = await readFile(getGuidePath(slug), 'utf-8');
+    cachedGuides.set(slug, content);
+    return content;
+  } catch {
+    return null;
+  }
+}

package/src/data/template-loader.ts

@@ -2,9 +2,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
+ * The six 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.
+ * the ids the guide resources ({@link registerGuideResources}) expose. The auth
+ * guide is deliberately NOT here — it is a canonical package guide served from
+ * the bundle's `guides/auth.md` (see `guide-loader.ts`), not a template slice.
  */
 export interface TemplateSections {
   'api-grammar': string;
@@ -13,7 +15,6 @@ export interface TemplateSections {
   'design-quality': string;
   customization: string;
   'style-patterns': string;
-  'auth-setup': string;
 }
 
 let cachedSections: TemplateSections | null = null;
@@ -34,9 +35,9 @@ function extractSection(lines: string[], startHeading: string, endMarker: string
 }
 
 /**
- * Load the template document once and slice it into the seven
+ * Load the template document once and slice it into the six
  * {@link TemplateSections} by `## …` heading (each running up to the next `---`
- * rule; auth-setup, the last section, runs to EOF). Cached per process.
+ * rule). Cached per process.
  */
 export async function loadTemplateSections(): Promise<TemplateSections> {
   if (cachedSections) return cachedSections;
@@ -51,10 +52,7 @@ export async function loadTemplateSections(): Promise<TemplateSections> {
     tokens: extractSection(lines, '## Design Token System', '---'),
     'design-quality': extractSection(lines, '## Design Quality', '---'),
     customization: extractSection(lines, '## Customization', '---'),
-    'style-patterns': extractSection(lines, '## Style Patterns', '---'),
-    // Auth Setup is the last section and contains no `---` rules of its own, so
-    // it extracts cleanly to EOF. Its `###` stage sub-headings carry the staging.
-    'auth-setup': extractSection(lines, '## Auth Setup', '---')
+    'style-patterns': extractSection(lines, '## Style Patterns', '---')
   };
 
   return cachedSections;

package/src/resources/guides.ts

@@ -1,67 +1,86 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { loadPackageGuide } from '../data/guide-loader.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`.
+ * The seven guide surfaces. Six slice a `## …` section out of the template
+ * bundle ({@link TemplateSections}); the auth guide is a canonical package
+ * guide served verbatim from the bundle's `guides/auth.md` (the tarball-shipped
+ * `packages/auth/docs/AUTH.md` — one source, all channels, docs/DOCS-SURFACES.md).
+ * The `urbicon` CLI lists every bundled package guide dynamically
+ * (`urbicon guide`); this static list names the ones the server advertises.
  */
-const GUIDE_RESOURCES: { id: string; name: string; key: keyof TemplateSections }[] = [
+const GUIDE_RESOURCES: (
+  | { id: string; name: string; source: 'template'; key: keyof TemplateSections }
+  | { id: string; name: string; source: 'package-guide'; slug: string }
+)[] = [
   {
     id: 'api-grammar',
     name: 'API Grammar Guide',
+    source: 'template',
     key: 'api-grammar'
   },
   {
     id: 'component-families',
     name: 'Component Families Guide',
+    source: 'template',
     key: 'component-families'
   },
   {
     id: 'tokens',
     name: 'Design Tokens Guide',
+    source: 'template',
     key: 'tokens'
   },
   {
     id: 'design-quality',
     name: 'Design Quality Guide',
+    source: 'template',
     key: 'design-quality'
   },
   {
     id: 'customization',
     name: 'Customization Guide',
+    source: 'template',
     key: 'customization'
   },
   {
     id: 'style-patterns',
     name: 'Style Patterns Guide',
+    source: 'template',
     key: 'style-patterns'
   },
   {
-    id: 'auth-setup',
-    name: 'Auth Setup Guide',
-    key: 'auth-setup'
+    id: 'auth',
+    name: 'Auth Reference',
+    source: 'package-guide',
+    slug: 'auth'
   }
 ];
 
 /**
  * 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.
+ * Each read resolves its content lazily (template slice or bundled package
+ * guide) and degrades to a "not found" note if the content 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) => {
-      const sections = await loadTemplateSections();
-      const content = sections[guide.key];
+      let content: string | null;
+      if (guide.source === 'template') {
+        const sections = await loadTemplateSections();
+        content = sections[guide.key] || null;
+      } else {
+        content = await loadPackageGuide(guide.slug);
+      }
 
       return {
         contents: [
           {
             uri: uri.href,
             mimeType: 'text/markdown',
-            text: content || `Guide section "${guide.id}" not found.`
+            text: content ?? `Guide "${guide.id}" not found.`
           }
         ]
       };