@cascivo/mcp 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 # @cascivo/mcp
 
-> MCP server exposing the cascade component registry to AI agents
+> MCP server exposing the cascivo component registry to AI agents
 
 [cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/urbanisierung/cascivo)
 
@@ -25,17 +25,40 @@ The server speaks the MCP stdio transport. By default it reads the `registry.jso
 
 ## Tools
 
-| Tool                | Input                                 | Returns                                                  |
-| ------------------- | ------------------------------------- | -------------------------------------------------------- |
-| `list_components`   | `{ category? }`                       | All component manifests, optionally filtered by category |
-| `get_component`     | `{ name }`                            | The full manifest for one component                      |
-| `search_components` | `{ query }`                           | Components matching name, tags, or description           |
-| `add_to_project`    | `{ name, outputDir? }`                | Runs `cascivo add <name>` as a child process             |
-| `create_theme`      | `{ primary, neutral, accent, name? }` | A custom theme as CSS (semantic token layer)             |
-| `scaffold_page`     | `{ description, components? }`        | A JSX page layout string                                 |
+| Tool                | Input                                 | Returns                                                                              |
+| ------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `list_components`   | `{ category? }`                       | All component manifests, optionally filtered by category                             |
+| `get_component`     | `{ name }`                            | The full manifest for one component                                                  |
+| `search_components` | `{ query }`                           | Components matching name, tags, or description                                       |
+| `add_to_project`    | `{ name, outputDir? }`                | Runs `cascivo add <name>` as a child process                                         |
+| `create_theme`      | `{ primary, neutral, accent, name? }` | A custom theme as CSS (semantic token layer)                                         |
+| `scaffold_page`     | `{ description, components? }`        | A JSX page layout string                                                             |
+| `scaffold_view`     | `{ description, components? }`        | A validated starter `ViewConfig` + the bound-vocabulary `grammar` for its components |
+| `validate_view`     | `{ config }`                          | Validation errors (component, prop type/enum, refs) with exact paths                 |
+| `get_view_grammar`  | `{ components? }`                     | Bound-vocabulary grammar + generation prompt for valid `ViewConfig` JSON             |
 
 `category` is one of `inputs`, `display`, `overlay`, `navigation`, `feedback`.
 
+### Bound-vocabulary generation (anti-hallucination)
+
+`get_view_grammar` derives — from the `component.meta.ts` manifests — a **system
+prompt** plus a compact **allowed-vocabulary grammar** (each component → its
+props → enum/size/variant values) for emitting valid `ViewConfig` JSON rendered
+by `@cascivo/render` `<CascadeView />`. This is [OpenUI](https://openui.com)'s
+"generate the system prompt from the component library" mechanism (see
+[`docs/ROADMAP-V40.md`](../../docs/ROADMAP-V40.md)): because the grammar is
+**derived**, not authored, an LLM is structurally prevented from inventing
+components, props, or enum values, and the grammar can never drift from the
+components. Pair it with `validate_view` (which now also checks prop types/enums)
+as the enforcement backstop.
+
+```ts
+import { buildGenerationPrompt, loadRegistry } from '@cascivo/mcp'
+
+const prompt = buildGenerationPrompt(loadRegistry(), { components: ['Badge', 'Button'] })
+// → use as the system prompt; the model can only emit Badge/Button with their real props.
+```
+
 ## Programmatic use
 
 ```ts

package/dist/index.d.mts

@@ -21,7 +21,7 @@ interface ThemeColors {
   accent: string;
 }
 /**
- * Generate a custom cascade theme as CSS. Maps the three input colors onto the
+ * Generate a custom cascivo theme as CSS. Maps the three input colors onto the
  * semantic token layer; component tokens inherit automatically.
  */
 declare function generateThemeCss(colors: ThemeColors, name?: string): string;
@@ -91,10 +91,56 @@ declare function getComponent(registry: Registry, name: string): ComponentManife
 /** Fuzzy search over name, tags, and description. */
 declare function searchComponents(registry: Registry, query: string): ComponentManifest[];
 //#endregion
+//#region src/grammar.d.ts
+interface GrammarProp {
+  name: string;
+  required: boolean;
+  /** Raw TypeScript type string from the manifest. */
+  type: string;
+  /** Allowed values, when `type` is a string-literal union (e.g. `'sm' | 'md'`). */
+  enum?: string[];
+}
+interface GrammarComponent {
+  name: string;
+  category: string;
+  props: GrammarProp[];
+  variants: string[];
+  sizes: string[];
+}
+interface ViewGrammar {
+  components: GrammarComponent[];
+}
+/**
+ * Parse a string-literal union type (`'a' | 'b' | "c"`) into its allowed
+ * values. Returns `undefined` for any non-enum type (primitives, functions,
+ * named types, object shapes) so the grammar only constrains what it can.
+ */
+declare function parseEnum(type: string): string[] | undefined;
+declare function buildGrammar(registry: Registry, subset?: string[]): ViewGrammar;
+/**
+ * Render the grammar as a compact, model-friendly table: one line per
+ * component. Terser than verbose JSON; a `*` marks a required prop.
+ *
+ *   Badge(size: sm|md, variant: default|secondary|success|warning|destructive|outline)
+ */
+declare function formatGrammar(grammar: ViewGrammar): string;
+//#endregion
+//#region src/prompt.d.ts
+interface GenerationPromptOptions {
+  /** Scope the vocabulary to a subset of component names. Defaults to all. */
+  components?: string[];
+}
+/**
+ * Build the bound-vocabulary system prompt for emitting `ViewConfig` JSON.
+ * Parameterizable by an optional component subset (defaults to the full
+ * registry).
+ */
+declare function buildGenerationPrompt(registry: Registry, options?: GenerationPromptOptions): string;
+//#endregion
 //#region src/index.d.ts
 declare const VERSION = "0.0.0";
 /** Start the MCP server over stdio. */
 declare function main(): Promise<void>;
 //#endregion
-export { type ComponentManifest, type Registry, type RegistryComponent, type ScaffoldOptions, type ServerOptions, type ThemeColors, VERSION, createServer, generateThemeCss, getComponent, listComponents, loadRegistry, main, scaffoldPage, searchComponents };
+export { type ComponentManifest, type GenerationPromptOptions, type GrammarComponent, type GrammarProp, type Registry, type RegistryComponent, type ScaffoldOptions, type ServerOptions, type ThemeColors, VERSION, type ViewGrammar, buildGenerationPrompt, buildGrammar, createServer, formatGrammar, generateThemeCss, getComponent, listComponents, loadRegistry, main, parseEnum, scaffoldPage, searchComponents };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/server.ts","../src/theme.ts","../src/scaffold.ts","../src/registry.ts","../src/index.ts"],"mappings":";;;KAsBK,OAAA,IAAW,GAAA,UAAa,IAAA,GAAO,WAAA,KAAgB,OAAA,CAAQ,QAAA;AAAA,UAE3C,aAAA;EACf,YAAA;EACA,OAAA;;EAEA,OAAA,GAAU,OAAO;AAAA;;iBAeH,YAAA,CAAa,OAAA,GAAS,aAAA,GAAqB,SAAS;;;UC3CnD,WAAA;;EAEf,OAAA;EDoBG;EClBH,OAAA;;EAEA,MAAA;AAAA;;;;;iBAiBc,gBAAA,CAAiB,MAAA,EAAQ,WAAW,EAAE,IAAA;;;UCvBrC,eAAA;EACf,WAAA;EACA,UAAU;AAAA;;;;;iBAgCI,YAAA,CAAa,OAAwB,EAAf,eAAe;;;UC9BpC,YAAA;EACf,IAAA;EACA,IAAA;EACA,QAAA;EACA,OAAA;EACA,WAAA;AAAA;AAAA,UAGe,iBAAA;EACf,IAAA;EACA,WAAA;EACA,QAAA;EACA,MAAA;EACA,QAAA;EACA,KAAA;EACA,KAAA,EAAO,YAAY;EACnB,MAAA;EACA,aAAA;IAAiB,IAAA;IAAc,IAAA;IAAc,QAAA;EAAA;EAC7C,QAAA;IAAY,KAAA;IAAe,IAAA;IAAc,WAAA;EAAA;EACzC,YAAA;EACA,IAAA;AAAA;AAAA,UAGe,iBAAA;EACf,IAAA;EACA,IAAA;EACA,WAAA;EACA,QAAA;EACA,OAAA;EACA,KAAA;EACA,YAAA;EACA,IAAA;EACA,IAAA,EAAM,iBAAiB;AAAA;AAAA,UAGR,QAAA;EACf,OAAA;EACA,WAAA;EACA,UAAA,EAAY,iBAAiB;AAAA;AAAA,iBAwBf,YAAA,CAAa,IAAA,YAAgB,QAAQ;;iBAUrC,cAAA,CACd,QAAA,EAAU,QAAA,EACV,QAAA,WACA,IAAA,YACC,iBAAiB;;iBAQJ,YAAA,CAAa,QAAA,EAAU,QAAA,EAAU,IAAA,WAAe,iBAAiB;;iBAoGjE,gBAAA,CAAiB,QAAA,EAAU,QAAA,EAAU,KAAA,WAAgB,iBAAiB;;;cCvLzE,OAAA;;iBAiBS,IAAA,IAAQ,OAAO"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/server.ts","../src/theme.ts","../src/scaffold.ts","../src/registry.ts","../src/grammar.ts","../src/prompt.ts","../src/index.ts"],"mappings":";;;KAwBK,OAAA,IAAW,GAAA,UAAa,IAAA,GAAO,WAAA,KAAgB,OAAA,CAAQ,QAAA;AAAA,UAE3C,aAAA;EACf,YAAA;EACA,OAAA;;EAEA,OAAA,GAAU,OAAO;AAAA;;iBAeH,YAAA,CAAa,OAAA,GAAS,aAAA,GAAqB,SAAS;;;UC7CnD,WAAA;;EAEf,OAAA;EDsBG;ECpBH,OAAA;;EAEA,MAAA;AAAA;;;;;iBAiBc,gBAAA,CAAiB,MAAA,EAAQ,WAAW,EAAE,IAAA;;;UCvBrC,eAAA;EACf,WAAA;EACA,UAAU;AAAA;;;;;iBAgCI,YAAA,CAAa,OAAwB,EAAf,eAAe;;;UC9BpC,YAAA;EACf,IAAA;EACA,IAAA;EACA,QAAA;EACA,OAAA;EACA,WAAA;AAAA;AAAA,UAGe,iBAAA;EACf,IAAA;EACA,WAAA;EACA,QAAA;EACA,MAAA;EACA,QAAA;EACA,KAAA;EACA,KAAA,EAAO,YAAY;EACnB,MAAA;EACA,aAAA;IAAiB,IAAA;IAAc,IAAA;IAAc,QAAA;EAAA;EAC7C,QAAA;IAAY,KAAA;IAAe,IAAA;IAAc,WAAA;EAAA;EACzC,YAAA;EACA,IAAA;AAAA;AAAA,UAGe,iBAAA;EACf,IAAA;EACA,IAAA;EACA,WAAA;EACA,QAAA;EACA,OAAA;EACA,KAAA;EACA,YAAA;EACA,IAAA;EACA,IAAA,EAAM,iBAAiB;AAAA;AAAA,UAGR,QAAA;EACf,OAAA;EACA,WAAA;EACA,UAAA,EAAY,iBAAiB;AAAA;AAAA,iBAwBf,YAAA,CAAa,IAAA,YAAgB,QAAQ;;iBAUrC,cAAA,CACd,QAAA,EAAU,QAAA,EACV,QAAA,WACA,IAAA,YACC,iBAAiB;;iBAQJ,YAAA,CAAa,QAAA,EAAU,QAAA,EAAU,IAAA,WAAe,iBAAiB;;iBAoGjE,gBAAA,CAAiB,QAAA,EAAU,QAAA,EAAU,KAAA,WAAgB,iBAAiB;;;UChLrE,WAAA;EACf,IAAA;EACA,QAAA;EJUU;EIRV,IAAA;EJQkC;EINlC,IAAA;AAAA;AAAA,UAGe,gBAAA;EACf,IAAA;EACA,QAAA;EACA,KAAA,EAAO,WAAW;EAClB,QAAA;EACA,KAAA;AAAA;AAAA,UAGe,WAAA;EACf,UAAA,EAAY,gBAAgB;AAAA;;;;;;iBAQd,SAAA,CAAU,IAAY;AAAA,iBA8BtB,YAAA,CAAa,QAAA,EAAU,QAAA,EAAU,MAAA,cAAoB,WAAW;;AJtC7D;AAenB;;;;iBI8EgB,aAAA,CAAc,OAAoB,EAAX,WAAW;;;UChHjC,uBAAA;;EAEf,UAAU;AAAA;;;;;;iBAsCI,qBAAA,CACd,QAAA,EAAU,QAAA,EACV,OAAA,GAAS,uBAA4B;;;cChD1B,OAAA;;iBA0BS,IAAA,IAAQ,OAAO"}

package/dist/index.mjs

@@ -120,14 +120,14 @@ function lighten(color, amount) {
 	return `color-mix(in oklab, ${color}, white ${amount}%)`;
 }
 /**
-* Generate a custom cascade theme as CSS. Maps the three input colors onto the
+* Generate a custom cascivo theme as CSS. Maps the three input colors onto the
 * semantic token layer; component tokens inherit automatically.
 */
 function generateThemeCss(colors, name = "custom") {
 	const { primary, neutral, accent } = colors;
-	return `/* Cascade — Generated theme: ${name} */
+	return `/* cascivo — Generated theme: ${name} */
 
-@layer cascade.theme {
+@layer cascivo.theme {
   [data-theme='${name}'] {
     color-scheme: light;
 
@@ -323,6 +323,78 @@ function validateView(config, componentNames) {
 	};
 }
 //#endregion
+//#region src/grammar.ts
+/**
+* Parse a string-literal union type (`'a' | 'b' | "c"`) into its allowed
+* values. Returns `undefined` for any non-enum type (primitives, functions,
+* named types, object shapes) so the grammar only constrains what it can.
+*/
+function parseEnum(type) {
+	const branches = type.split("|").map((s) => s.trim()).filter((s) => s.length > 0);
+	if (branches.length === 0) return void 0;
+	const values = [];
+	for (const branch of branches) {
+		const quoted = branch.match(/^['"](.+)['"]$/);
+		if (!quoted?.[1]) return void 0;
+		values.push(quoted[1]);
+	}
+	return values;
+}
+/**
+* Build the bound-vocabulary descriptor from the registry, optionally scoped to
+* a subset of component names (case-insensitive). Output is deterministic
+* (components and props sorted by name) for reproducible prompts and tests.
+*/
+const TYPE_RANK = {
+	component: 0,
+	block: 1,
+	chart: 2,
+	section: 3,
+	layout: 4
+};
+function buildGrammar(registry, subset) {
+	const wanted = subset && subset.length > 0 ? new Set(subset.map((n) => n.toLowerCase())) : null;
+	const canonical = /* @__PURE__ */ new Map();
+	for (const c of registry.components) {
+		const key = c.meta.name.toLowerCase();
+		const current = canonical.get(key);
+		if (!current || (TYPE_RANK[c.type ?? ""] ?? 9) < (TYPE_RANK[current.type ?? ""] ?? 9)) canonical.set(key, c);
+	}
+	return { components: [...canonical.values()].filter((c) => !wanted || wanted.has(c.meta.name.toLowerCase()) || wanted.has(c.name.toLowerCase())).map((c) => {
+		const props = (c.meta.props ?? []).map((p) => {
+			const values = parseEnum(p.type);
+			return {
+				name: p.name,
+				required: p.required === true,
+				type: p.type,
+				...values ? { enum: values } : {}
+			};
+		}).sort((a, b) => a.name.localeCompare(b.name));
+		return {
+			name: c.meta.name,
+			category: c.category,
+			props,
+			variants: c.meta.variants ?? [],
+			sizes: c.meta.sizes ?? []
+		};
+	}).sort((a, b) => a.name.localeCompare(b.name)) };
+}
+/** Render one prop as `name`, `name*` (required), with enum choices or its type. */
+function formatProp(prop) {
+	const mark = prop.required ? "*" : "";
+	const value = prop.enum ? prop.enum.join("|") : prop.type;
+	return `${prop.name}${mark}: ${value}`;
+}
+/**
+* Render the grammar as a compact, model-friendly table: one line per
+* component. Terser than verbose JSON; a `*` marks a required prop.
+*
+*   Badge(size: sm|md, variant: default|secondary|success|warning|destructive|outline)
+*/
+function formatGrammar(grammar) {
+	return grammar.components.map((c) => `${c.name}(${c.props.map(formatProp).join(", ")})`).join("\n");
+}
+//#endregion
 //#region src/scaffold-view.ts
 /** Simple keyword matcher — returns region layout name based on description keywords. */
 function pickLayout(description) {
@@ -374,10 +446,55 @@ function scaffoldView(input, registry) {
 	const { errors } = validateView(config, new Set(registry.components.map((c) => c.meta.name)));
 	return {
 		config,
-		errors
+		errors,
+		grammar: formatGrammar(buildGrammar(registry, componentNames))
 	};
 }
 //#endregion
+//#region src/prompt.ts
+const SCHEMA_DOC = `A ViewConfig is a JSON object:
+
+{
+  "version": 1,
+  "view": {
+    "layout": "<optional layout name, e.g. dashboard | settings | auth>",
+    "regions": {
+      "<regionName>": [ <ComponentNode>, ... ]
+    }
+  }
+}
+
+A ComponentNode is:
+
+{
+  "component": "<one of the registered component names below>",
+  "props": { "<propName>": <value> },
+  "bind": { "<propName>": "$data.<path>" },
+  "events": { "<eventPropName>": "$actions.<name>" },
+  "children": <ComponentNode[] | string | { "$t": "<i18n.key>" }>
+}
+
+Rules:
+- "component" MUST be one of the registered components listed below — never invent one.
+- Only use props listed for that component; enum props MUST use one of the listed values.
+- "bind" values are host-data references and MUST start with "$data.".
+- "events" values are host-action references and MUST start with "$actions.".
+- "children" is an array of nodes, a plain string, or an i18n ref { "$t": "key" }.
+- Output ONLY the JSON ViewConfig — no prose, no markdown fences.`;
+/**
+* Build the bound-vocabulary system prompt for emitting `ViewConfig` JSON.
+* Parameterizable by an optional component subset (defaults to the full
+* registry).
+*/
+function buildGenerationPrompt(registry, options = {}) {
+	return [
+		"You generate UI as a cascivo ViewConfig — a JSON description rendered by @cascivo/render <CascadeView />.",
+		SCHEMA_DOC,
+		"Registered components (allowed vocabulary — `name*` marks a required prop):",
+		formatGrammar(buildGrammar(registry, options.components))
+	].join("\n\n");
+}
+//#endregion
 //#region src/tokens.ts
 const HERE$1 = dirname(fileURLToPath(import.meta.url));
 const CATALOG_BASE_URL = "https://cascivo.com";
@@ -445,6 +562,7 @@ function selectComponent(need, components) {
 			name: c.name,
 			score,
 			why,
+			whenNotToUse: c.intent.whenNotToUse ?? [],
 			related: c.intent.related ?? []
 		};
 	});
@@ -457,7 +575,9 @@ function selectComponent(need, components) {
 	return scored.map((r) => ({
 		name: r.name,
 		score: r.score + (relatedBonus.get(r.name) ?? 0),
-		why: r.why
+		why: r.why,
+		whenNotToUse: r.whenNotToUse,
+		related: r.related
 	})).filter((r) => r.score >= 0).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, 5);
 }
 //#endregion
@@ -490,8 +610,7 @@ function createServer(options = {}) {
 		description: "List available component registries: the cascade directory plus any configured via CASCADE_REGISTRIES env.",
 		inputSchema: {}
 	}, async () => {
-		const [directory] = await Promise.all([fetchDirectory(fetchFn)]);
-		return json(mergeRegistries(directory, getEnvRegistries()).map(({ namespace, name, description, verified, homepage }) => ({
+		return json(mergeRegistries(await fetchDirectory(fetchFn), getEnvRegistries()).map(({ namespace, name, description, verified, homepage }) => ({
 			namespace,
 			name,
 			description,
@@ -627,18 +746,32 @@ function createServer(options = {}) {
 			components: z.array(z.string()).optional().describe("Component names to include")
 		}
 	}, ({ description, components }) => {
-		const { config, errors } = scaffoldView({
+		const { config, errors, grammar } = scaffoldView({
 			description,
 			...components ? { components } : {}
 		}, registry);
 		if (errors.length > 0) return json({
 			valid: false,
 			errors,
-			config
+			config,
+			grammar
 		});
 		return json({
 			valid: true,
-			config
+			config,
+			grammar
+		});
+	});
+	server.registerTool("get_view_grammar", {
+		title: "Get view grammar",
+		description: "Get the bound-vocabulary grammar + system prompt for generating valid ViewConfig JSON, derived from the component manifests. Use this to constrain an LLM to cascivo's real components, props, and enum values (anti-hallucination). Optionally scope to a subset of components.",
+		inputSchema: { components: z.array(z.string()).optional().describe("Scope the vocabulary to these component names. Omit for the full registry.") }
+	}, ({ components }) => {
+		const grammar = buildGrammar(registry, components);
+		return json({
+			grammar: formatGrammar(grammar),
+			prompt: buildGenerationPrompt(registry, components ? { components } : {}),
+			components: grammar.components
 		});
 	});
 	server.registerTool("get_tokens", {
@@ -716,6 +849,6 @@ if (argv[1] !== void 0 && import.meta.url === pathToFileURL(argv[1]).href) main(
 	process.exitCode = 1;
 });
 //#endregion
-export { VERSION, createServer, generateThemeCss, getComponent, listComponents, loadRegistry, main, scaffoldPage, searchComponents };
+export { VERSION, buildGenerationPrompt, buildGrammar, createServer, formatGrammar, generateThemeCss, getComponent, listComponents, loadRegistry, main, parseEnum, scaffoldPage, searchComponents };
 
 //# sourceMappingURL=index.mjs.map