@starklab/stark-mcp 0.2.0 → 0.3.0

package/src/server.js

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 
@@ -10,12 +12,13 @@ import {
   getLayoutSchema,
   validateLayout,
   getGenerationProtocol,
+  whispererContext,
 } from './data.js';
 
-const json = value => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
-const error = message => ({ content: [{ type: 'text', text: message }], isError: true });
+const json = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
+const error = (message) => ({ content: [{ type: 'text', text: message }], isError: true });
 
-const wrap = fn => async args => {
+const wrap = (fn) => async (args) => {
   try {
     return json(await fn(args));
   } catch (err) {
@@ -23,8 +26,16 @@ const wrap = fn => async args => {
   }
 };
 
+// Read rather than written down: a hand-maintained literal here goes stale on
+// the first release nobody remembers to update it in, and no client ever
+// complains loudly enough to notice — it shipped as 0.1.0 alongside the
+// package's own 0.2.0. cli.js already derives SCANNER_VERSION this way.
+const VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf-8')
+).version;
+
 export function createServer() {
-  const server = new McpServer({ name: 'stark-design-system', version: '0.1.0' });
+  const server = new McpServer({ name: 'stark-design-system', version: VERSION });
 
   server.registerTool(
     'list_components',
@@ -46,7 +57,9 @@ export function createServer() {
         'Get the dos/donts, prop table, and Figma link for one Stark component. ' +
         'Read this before placing the component in a layout.',
       inputSchema: {
-        component: z.string().describe('Component name, e.g. "Button" or "TextInput" (case-insensitive)'),
+        component: z
+          .string()
+          .describe('Component name, e.g. "Button" or "TextInput" (case-insensitive)'),
       },
     },
     wrap(({ component }) => getComponentUsage(component))
@@ -71,7 +84,9 @@ export function createServer() {
           ),
       },
     },
-    wrap(({ component, platform, includeTokens }) => getComponentProps(component, platform, includeTokens))
+    wrap(({ component, platform, includeTokens }) =>
+      getComponentProps(component, platform, includeTokens)
+    )
   );
 
   server.registerTool(
@@ -93,7 +108,7 @@ export function createServer() {
       title: 'Get the full layout catalog',
       description:
         'Get every component that can be used as a standalone layout node, with its props ' +
-        'and slots. This is the same catalog Stark\'s own layout generator (Vecna) is restricted to.',
+        "and slots. This is the same catalog Stark's own layout generator (Vecna) is restricted to.",
       inputSchema: {
         platform: z.enum(['web', 'native']).default('web').describe('Target platform'),
       },
@@ -104,7 +119,7 @@ export function createServer() {
   server.registerTool(
     'get_layout_schema',
     {
-      title: 'Get one component\'s layout schema',
+      title: "Get one component's layout schema",
       description: 'Get the props/slots schema for a single layout-capable component.',
       inputSchema: {
         component: z.string().describe('Component name, e.g. "Card"'),
@@ -119,18 +134,28 @@ export function createServer() {
     {
       title: 'Validate a generated layout',
       description:
-        'Run Stark\'s deterministic conformance checks (no LLM) against a LayoutConfig JSON: ' +
+        "Run Stark's deterministic conformance checks (no LLM) against a LayoutConfig JSON: " +
         'catalog membership, component do/dont rules, guardrails, and prop shape. Returns findings ' +
-        'ranked Critical/Warning/Info. Pass `canvasCases` (your renderer\'s supported node-type list) ' +
+        "ranked Critical/Warning/Info. Pass `canvasCases` (your renderer's supported node-type list) " +
         'if you have one — without it, the catalog<->renderer parity check is skipped.',
       inputSchema: {
-        layout: z.record(z.string(), z.any()).describe('The LayoutConfig JSON, shaped { page: { sections: [...] } }'),
-        intent: z.record(z.string(), z.any()).optional().describe('Intent/guardrails object the layout was generated from'),
+        layout: z
+          .record(z.string(), z.any())
+          .describe('The LayoutConfig JSON, shaped { page: { sections: [...] } }'),
+        intent: z
+          .record(z.string(), z.any())
+          .optional()
+          .describe('Intent/guardrails object the layout was generated from'),
         platform: z.enum(['web', 'native']).default('web'),
-        canvasCases: z.array(z.string()).optional().describe('Node types your renderer actually supports'),
+        canvasCases: z
+          .array(z.string())
+          .optional()
+          .describe('Node types your renderer actually supports'),
       },
     },
-    wrap(({ layout, intent, platform, canvasCases }) => validateLayout({ layout, intent, platform, canvasCases }))
+    wrap(({ layout, intent, platform, canvasCases }) =>
+      validateLayout({ layout, intent, platform, canvasCases })
+    )
   );
 
   server.registerTool(
@@ -145,5 +170,35 @@ export function createServer() {
     wrap(() => getGenerationProtocol())
   );
 
+  server.registerTool(
+    'whisperer_context',
+    {
+      title: 'Ground an answer about the design system',
+      description:
+        'Everything a model needs to answer one question about Stark: the rules to answer under and ' +
+        'the facts to answer from — every component with its props per platform, every token with ' +
+        'its value, dark value, alias chain and React Native name — with the components and tokens ' +
+        'the question names expanded in full. The same brain behind Whisperer, the concierge in ' +
+        "Stark Dominion. Put the result in the system prompt and answer the question from it alone. " +
+        'Returns prose, not JSON.',
+      inputSchema: {
+        question: z.string().describe('What is being asked about the design system, verbatim'),
+        context: z
+          .array(z.string())
+          .optional()
+          .describe('The prior turns of the conversation, newest first, so a follow-up keeps its subject'),
+      },
+    },
+    // Not `wrap`: the answer is a system prompt, and a system prompt is text —
+    // a JSON-encoded string would hand the client every newline as `\n`.
+    async ({ question, context }) => {
+      try {
+        return { content: [{ type: 'text', text: whispererContext(question, context ?? []).text }] };
+      } catch (err) {
+        return error(err instanceof Error ? err.message : String(err));
+      }
+    }
+  );
+
   return server;
 }

package/src/whisperer.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Types for whisperer.js — the shared Whisperer brain. TypeScript consumers
+ * (Dominion) resolve this file ahead of the .js it sits beside.
+ */
+
+export interface UsageDoc {
+  dos?: string[];
+  donts?: string[];
+  codeExample?: string;
+}
+
+export interface NativeUsageProp {
+  name: string;
+  type: string;
+  default?: string;
+  required?: boolean | string;
+  description?: string;
+}
+
+export interface NativeUsageDoc extends UsageDoc {
+  props?: NativeUsageProp[];
+}
+
+export interface PropMapEntry {
+  react: string;
+  type?: string;
+  values?: Record<string, string>;
+  transform?: string;
+  description?: string;
+  componentProp?: boolean;
+}
+
+export interface ManifestComponent {
+  name: string;
+  slug: string;
+  status: string;
+  description: string;
+  platforms?: string[];
+  usage?: UsageDoc | null;
+  nativeUsage?: NativeUsageDoc | null;
+  props?: { web?: { propMap?: PropMapEntry[] } | null } | null;
+  tokens?: Record<string, unknown> | null;
+}
+
+export interface PropEntry {
+  name: string;
+  hasDefault?: boolean;
+  defaultSource?: string;
+  rest?: boolean;
+}
+
+export interface SignaturePlatform {
+  package?: string;
+  components?: Record<string, { props?: PropEntry[] }>;
+}
+
+export interface TokenMeta {
+  value: unknown;
+  type: string;
+  layer: 'primitive' | 'semantic' | 'component' | null;
+  alias: string | null;
+  description: string | null;
+  rn: { name: string; module: string } | null;
+}
+
+export interface WhispererData {
+  manifest: { components: ManifestComponent[] };
+  catalog: { platforms: Record<string, { exports: Record<string, { kind: string }> }> };
+  componentProps: { platforms: { web?: SignaturePlatform; native?: SignaturePlatform } };
+  tokenMeta: Record<string, TokenMeta>;
+  tokenDark: Record<string, unknown>;
+}
+
+export interface Grounding {
+  /** The grounding block, ready to sit under the system prompt. */
+  text: string;
+  /** The components whose full detail the block carries. */
+  components: string[];
+  /** The subset the question itself named. */
+  named: string[];
+  /** The tokens the question named outright. */
+  tokens: string[];
+}
+
+export interface Whisperer {
+  /** Where each platform's components are imported from. */
+  PACKAGES: { web: string | null; native: string | null };
+  /** The grounding block for one question; `context` is the prior turns, newest first. */
+  buildGrounding(question: string, context?: string[]): Grounding;
+  /** Every component the text names, in reading order, uncapped. */
+  componentsNamedIn(text: string): { name: string; platforms: string[] }[];
+  isKnownComponent(name: string): boolean;
+  /** Whether a token name (with or without its leading `--`) exists. */
+  isKnownToken(name: string): boolean;
+  /** Every token the text names, as CSS name or React Native export. */
+  tokensInQuestion(text: string): string[];
+}
+
+/** The grounding functions, built over one set of generated files. */
+export function createWhisperer(data: WhispererData): Whisperer;
+
+/**
+ * The design-system rules the grounding is handed to a model under. A
+ * surface appends its own rules — how it renders, what it can see.
+ */
+export const WHISPERER_SYSTEM_PROMPT: string;