@starklab/stark-mcp 0.2.1 → 0.3.0

package/src/server.js

@@ -12,6 +12,7 @@ import {
   getLayoutSchema,
   validateLayout,
   getGenerationProtocol,
+  whispererContext,
 } from './data.js';
 
 const json = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
@@ -169,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;