@greese/mcp 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createGreeseServer, componentMarkdown } from './server.ts';
+export { loadData, type ComponentDoc, type GreeseData, type PropDoc } from './data.ts';
+export { search, type Hit } from './search.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createGreeseServer, componentMarkdown } from "./server.js";
+export { loadData } from "./data.js";
+export { search } from "./search.js";

package/dist/search.d.ts

@@ -0,0 +1,17 @@
+import type { GreeseData } from './data.ts';
+export interface Hit {
+    kind: 'component' | 'guide' | 'template' | 'theme';
+    name: string;
+    summary: string;
+    score: number;
+}
+/**
+ * Scores text against a query: every query word must appear; a match in the
+ * name counts most, then the summary, then the body. Small and predictable,
+ * which suits a few hundred documents better than an index.
+ */
+export declare const score: (query: string, name: string, summary: string, body?: string) => number;
+/** The first sentence of a description (TSDoc wraps lines mid-sentence). */
+export declare const firstSentence: (text: string) => string;
+/** Components, guides, templates and themes that match, best first. */
+export declare const search: (data: GreeseData, query: string, limit?: number) => Hit[];

package/dist/search.js

@@ -0,0 +1,58 @@
+const words = (text) => text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+/**
+ * Scores text against a query: every query word must appear; a match in the
+ * name counts most, then the summary, then the body. Small and predictable,
+ * which suits a few hundred documents better than an index.
+ */
+export const score = (query, name, summary, body = '') => {
+    const terms = words(query);
+    if (!terms.length)
+        return 0;
+    const fields = [
+        [name.toLowerCase(), 10],
+        [summary.toLowerCase(), 3],
+        [body.toLowerCase(), 1],
+    ];
+    let total = 0;
+    for (const term of terms) {
+        let best = 0;
+        for (const [text, weight] of fields) {
+            if (text === term)
+                best = Math.max(best, weight * 3);
+            else if (text.includes(term))
+                best = Math.max(best, weight);
+        }
+        if (!best)
+            return 0;
+        total += best;
+    }
+    return total;
+};
+/** The first sentence of a description (TSDoc wraps lines mid-sentence). */
+export const firstSentence = (text) => {
+    const flat = text
+        .split(/\n\s*\n/)[0]
+        .replace(/\s+/g, ' ')
+        .trim();
+    return /^.*?[.!?](?=\s|$)/.exec(flat)?.[0] ?? flat;
+};
+/** Components, guides, templates and themes that match, best first. */
+export const search = (data, query, limit = 10) => {
+    const hits = [];
+    const add = (kind, name, summary, body) => {
+        const s = score(query, name, summary, body);
+        if (s)
+            hits.push({ kind, name, summary: firstSentence(summary), score: s });
+    };
+    for (const c of data.components)
+        add('component', c.name, c.description, c.props.map((p) => `${p.name} ${p.description}`).join(' '));
+    for (const g of data.guides)
+        add('guide', g.name, g.title, g.text);
+    for (const t of data.templates)
+        add('template', t.id, t.description, t.source);
+    for (const t of data.themes)
+        add('theme', t.id, t.description, t.scss);
+    return hits
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+        .slice(0, limit);
+};

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ComponentDoc, GreeseData } from './data.ts';
+/** A component as Markdown: what it is, its props, what a theme can target, and an example. */
+export declare const componentMarkdown: (c: ComponentDoc, example?: boolean) => string;
+/**
+ * The greese ui MCP server: tools and resources over the data baked at build
+ * time (ADR 0022). Connect it to any transport; the CLI uses stdio.
+ */
+export declare const createGreeseServer: (data: GreeseData) => McpServer;

package/dist/server.js

@@ -0,0 +1,301 @@
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createTheme, cssVar } from '@greese/ui';
+import { firstSentence, score, search } from "./search.js";
+const text = (value) => ({ content: [{ type: 'text', text: value }] });
+const error = (value) => ({ ...text(value), isError: true });
+/** The closest names to a miss, so a typo gets a suggestion instead of a dead end. */
+const suggest = (query, names) => {
+    const close = names
+        .map((name) => ({
+        name,
+        s: score(query, name, '') ||
+            (name.toLowerCase().startsWith(query.toLowerCase().slice(0, 3)) ? 1 : 0),
+    }))
+        .filter((c) => c.s)
+        .sort((a, b) => b.s - a.s)
+        .slice(0, 5)
+        .map((c) => c.name);
+    return close.length ? ` Did you mean: ${close.join(', ')}?` : '';
+};
+const findByName = (items, name, key) => items.find((item) => key(item) === name) ??
+    items.find((item) => key(item).toLowerCase() === name.toLowerCase());
+const cell = (value) => value.replace(/\|/g, '\\|').replace(/\n+/g, ' ');
+/** A component as Markdown: what it is, its props, what a theme can target, and an example. */
+export const componentMarkdown = (c, example = true) => {
+    const lines = [
+        `# ${c.name}`,
+        '',
+        `Category: ${c.category}. Source: \`${c.file}\`.`,
+        '',
+        c.description,
+        '',
+    ];
+    lines.push('```tsx', `import { ${c.name} } from '@greese/react'`, '```', '');
+    if (c.props.length) {
+        lines.push('## Props', '', '| Prop | Type | Default | Description |', '| --- | --- | --- | --- |');
+        for (const p of c.props)
+            lines.push(`| \`${p.name}\`${p.required ? ' (required)' : ''} | \`${cell(p.type)}\` | ${p.default === undefined ? '' : `\`${cell(p.default)}\``} | ${cell(p.description)} |`);
+        lines.push('', 'Other props pass through to the root element (DOM attributes, `ref`, `className`, `style`). Every component also takes the `greese` motion prop.', '');
+    }
+    if (c.styles) {
+        const s = c.styles;
+        lines.push('## Styling', '', `Root class: \`.${s.className}\`.`);
+        if (s.parts.length)
+            lines.push(`Parts: ${s.parts.map((p) => `\`.${s.className}-${p}\``).join(', ')}.`);
+        if (s.modifiers.length)
+            lines.push(`Modifiers: ${s.modifiers.map((m) => `\`.${s.className}--${m}\``).join(', ')}.`);
+        if (s.attributes.length)
+            lines.push(`State attributes: ${s.attributes.map((a) => `\`${a}\``).join(', ')}.`);
+        if (s.variables.length)
+            lines.push(`Variables: ${s.variables.map((v) => `\`${v}\``).join(', ')}.`);
+        lines.push('', 'Restyle it with the SCSS kit (`@include greese.component(' +
+            c.name +
+            ') { … }`), which writes into `@layer greese.overrides`, or with plain CSS on these classes.', '');
+    }
+    if (example && c.example)
+        lines.push('## Example (its stories file)', '', '```tsx', c.example.trim(), '```');
+    return lines.join('\n');
+};
+/**
+ * The greese ui MCP server: tools and resources over the data baked at build
+ * time (ADR 0022). Connect it to any transport; the CLI uses stdio.
+ */
+export const createGreeseServer = (data) => {
+    const server = new McpServer({ name: 'greese', version: data.version }, {
+        instructions: 'greese ui is a mobile-first React 19 component library (@greese/react) styled by framework-free CSS (@greese/ui), with icons in @greese/icons and motion via the `greese` prop. Before writing UI code, look components up with get_component instead of guessing props, use tokens (list_tokens) rather than raw values, and use icons from @greese/icons (list_icons) rather than inline SVG. Templates (list_templates) are complete pages to start from.',
+    });
+    const names = data.components.map((c) => c.name);
+    server.registerTool('list_components', {
+        title: 'List components',
+        description: 'Every greese ui React component, by docs category, with a one-line summary.',
+        inputSchema: {
+            category: z
+                .string()
+                .optional()
+                .describe('Only this category: Layout, Forms, Content, Overlays, Navigation, Motion or Utilities.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, ({ category }) => {
+        const chosen = data.components.filter((c) => !category || c.category.toLowerCase() === category.toLowerCase());
+        if (!chosen.length)
+            return error(`No components in category "${category}".`);
+        const byCategory = new Map();
+        for (const c of chosen)
+            byCategory.set(c.category, [...(byCategory.get(c.category) ?? []), c]);
+        const out = [...byCategory]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([cat, list]) => `## ${cat}\n${list.map((c) => `- **${c.name}**: ${firstSentence(c.description)}`).join('\n')}`);
+        return text(out.join('\n\n'));
+    });
+    server.registerTool('get_component', {
+        title: 'Get a component',
+        description: "A component's documentation: description, every prop with its type, default and meaning, the classes, parts, modifiers and CSS variables a theme can target, and its stories file as working example code.",
+        inputSchema: {
+            name: z
+                .string()
+                .describe('The component, as exported: Button, Dialog, TextField…'),
+            example: z
+                .boolean()
+                .optional()
+                .describe('Include the example code. Defaults to true.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, ({ name, example }) => {
+        const c = findByName(data.components, name, (c) => c.name);
+        return c
+            ? text(componentMarkdown(c, example ?? true))
+            : error(`No component named "${name}".${suggest(name, names)}`);
+    });
+    server.registerTool('search', {
+        title: 'Search greese ui',
+        description: 'Searches components, guides, templates and themes by keyword. Every word must match.',
+        inputSchema: {
+            query: z
+                .string()
+                .min(1)
+                .describe('Words to look for: "date picker", "dark mode", "toast".'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe('At most this many results. Defaults to 10.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, ({ query, limit }) => {
+        const hits = search(data, query, limit ?? 10);
+        return hits.length
+            ? text(hits.map((h) => `- [${h.kind}] **${h.name}**: ${h.summary}`).join('\n'))
+            : text(`Nothing matches "${query}". Try fewer or broader words.`);
+    });
+    server.registerTool('list_tokens', {
+        title: 'List design tokens',
+        description: 'The design tokens and their CSS custom properties: colors (light and dark), space, radius, font, shadow, z-index, duration, easing, breakpoints, the palette and the type scale. Without a group, lists the groups.',
+        inputSchema: {
+            group: z
+                .string()
+                .optional()
+                .describe('A group: color, space, radius, font, shadow, palette, typography, breakpoints…'),
+        },
+        annotations: { readOnlyHint: true },
+    }, ({ group }) => {
+        const groups = Object.keys(data.tokens);
+        if (!group)
+            return text(`Token groups: ${groups.join(', ')}.\n\nA token is used as \`var(--greese-<group>-<name>)\`, names in kebab-case: \`var(${cssVar('color', 'primaryStrong')})\`, \`var(${cssVar('space', '4')})\`. Palette colors are \`var(--greese-palette-<hue>-<shade>)\`.`);
+        const values = data.tokens[group];
+        if (values === undefined)
+            return error(`No token group "${group}". Groups: ${groups.join(', ')}.`);
+        const scalar = !['palette', 'typography', 'breakpoints'].includes(group);
+        const rows = scalar && values && typeof values === 'object'
+            ? Object.entries(values).map(([name, value]) => `- \`${cssVar(group, name)}\`: ${JSON.stringify(value)}`)
+            : ['```json', JSON.stringify(values, null, 2), '```'];
+        return text(`# ${group}\n\n${rows.join('\n')}`);
+    });
+    server.registerTool('list_icons', {
+        title: 'List icons',
+        description: 'The icons in @greese/icons. Use these rather than inline <svg>: every greese ui icon lives in that package.',
+        inputSchema: {
+            query: z.string().optional().describe('Only icons whose name contains this.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, ({ query }) => {
+        const icons = data.icons.filter((i) => !query || i.toLowerCase().includes(query.toLowerCase()));
+        if (!icons.length)
+            return text(`No icon matches "${query}". Add one to packages/icons/src/icons.tsx with createIcon().`);
+        return text(`${icons.join(', ')}\n\n\`\`\`tsx\nimport { ${icons[0]} } from '@greese/icons'\n\n<Icon label="…"><${icons[0]} /></Icon>  // or as a Button's startIcon\n\`\`\``);
+    });
+    server.registerTool('create_theme', {
+        title: 'Create a theme',
+        description: "Runs @greese/ui's createTheme and returns the theme's CSS: every token, with your overrides. Setting a brand color also derives its readable content color and its strong shade.",
+        inputSchema: {
+            name: z
+                .string()
+                .regex(/^[a-z][a-z0-9-]*$/i)
+                .describe('The theme name: data-greese-theme="<name>" applies it.'),
+            options: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe('createTheme options besides name, e.g. { "color": { "primary": { "light": "#7c3aed", "dark": "#c4b5fd" } }, "radius": { "md": "12px" } }. Groups: color, space, radius, font, shadow, duration, easing, typography, extend.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, ({ name, options }) => {
+        try {
+            const theme = createTheme({ ...options, name });
+            return text(`\`\`\`css\n${theme.css}\n\`\`\`\n\nServe this after greese ui's styles and set \`data-greese-theme="${name}"\` on any element, or in React: \`<ThemeProvider theme={createTheme({ name: '${name}', … })}>\`.`);
+        }
+        catch (e) {
+            return error(e instanceof Error ? e.message : String(e));
+        }
+    });
+    server.registerTool('list_templates', {
+        title: 'List templates',
+        description: 'Complete page templates (finance, admin dashboard, email client, blog, SaaS, e-commerce…) built from greese ui components.',
+        annotations: { readOnlyHint: true },
+    }, () => text(data.templates.length
+        ? data.templates
+            .map((t) => `- **${t.id}**: ${firstSentence(t.description)}`)
+            .join('\n')
+        : 'No templates in this build.'));
+    server.registerTool('get_template', {
+        title: 'Get a template',
+        description: "A template's full source: a React page to copy and adapt.",
+        inputSchema: {
+            id: z.string().describe('The template, as list_templates names it.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, ({ id }) => {
+        const t = findByName(data.templates, id, (t) => t.id);
+        return t
+            ? text(`# ${t.id}\n\n${t.description}\n\n\`\`\`tsx\n${t.source.trim()}\n\`\`\`${data.templateStyles
+                ? `\n\nThe \`tpl-*\` classes it uses (templates.scss, shared by every template):\n\n\`\`\`scss\n${data.templateStyles.trim()}\n\`\`\``
+                : ''}`)
+            : error(`No template "${id}".${suggest(id, data.templates.map((t) => t.id))}`);
+    });
+    server.registerTool('list_themes', {
+        title: 'List themes',
+        description: "greese ui's theme files, one layer each (ADR 0025): color themes (brand colors and neutrals), shape themes (clip-path outlines and radii), motion themes and color variants.",
+        annotations: { readOnlyHint: true },
+    }, () => text(data.themes.length
+        ? data.themes
+            .map((t) => `- **${t.id}**: ${firstSentence(t.description)}`)
+            .join('\n')
+        : 'No themes in this build.'));
+    server.registerTool('get_theme', {
+        title: 'Get a shape theme',
+        description: "A shape theme's source: kit SCSS (compile after greese ui's styles, or read as a recipe) and its compiled CSS (@greese/ui/themes/<id>.css).",
+        inputSchema: {
+            id: z.string().describe('The theme, as list_themes names it.'),
+            format: z
+                .enum(['scss', 'css', 'both'])
+                .optional()
+                .describe('Which source. Defaults to scss.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, ({ id, format }) => {
+        const t = findByName(data.themes, id, (t) => t.id);
+        if (!t)
+            return error(`No theme "${id}".${suggest(id, data.themes.map((t) => t.id))}`);
+        const want = format ?? 'scss';
+        const parts = [
+            `# ${t.id}\n\n${t.description}\n\nUse it: \`import '@greese/ui/themes/${t.id}.css'\` after greese ui's styles.`,
+        ];
+        if (want !== 'css')
+            parts.push(`\`\`\`scss\n${t.scss.trim()}\n\`\`\``);
+        if (want !== 'scss')
+            parts.push(`\`\`\`css\n${t.css.trim()}\n\`\`\``);
+        return text(parts.join('\n\n'));
+    });
+    server.registerResource('guide', new ResourceTemplate('greese://guides/{name}', {
+        list: () => ({
+            resources: data.guides.map((g) => ({
+                uri: `greese://guides/${g.name}`,
+                name: g.name,
+                title: g.title,
+                mimeType: 'text/markdown',
+            })),
+        }),
+    }), {
+        title: 'greese ui guides',
+        description: 'Getting started, theming, styling, animation, utilities…',
+        mimeType: 'text/markdown',
+    }, (uri, { name }) => {
+        const g = data.guides.find((g) => g.name === name);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'text/markdown',
+                    text: g?.text ?? `No guide "${String(name)}".`,
+                },
+            ],
+        };
+    });
+    server.registerResource('component', new ResourceTemplate('greese://components/{name}', {
+        list: () => ({
+            resources: data.components.map((c) => ({
+                uri: `greese://components/${c.name}`,
+                name: c.name,
+                description: firstSentence(c.description),
+                mimeType: 'text/markdown',
+            })),
+        }),
+    }), {
+        title: 'greese ui components',
+        description: 'One document per component: props, classes, example.',
+        mimeType: 'text/markdown',
+    }, (uri, { name }) => {
+        const c = data.components.find((c) => c.name === name);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'text/markdown',
+                    text: c ? componentMarkdown(c) : `No component "${String(name)}".`,
+                },
+            ],
+        };
+    });
+    return server;
+};

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@greese/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "An MCP server for greese ui: components and their props, classes and examples, tokens, icons, guides, themes and page templates, for coding assistants.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "greese",
+    "design-system",
+    "ai"
+  ],
+  "author": "Chris Moody",
+  "license": "MIT",
+  "homepage": "https://chris-moody.github.io/greese/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chris-moody/greese.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/chris-moody/greese/issues"
+  },
+  "type": "module",
+  "bin": {
+    "greese-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "LICENSE",
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/build-data.ts",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint src scripts --max-warnings 0",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@greese/ui": "*",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.6"
+  },
+  "devDependencies": {
+    "@greese/eslint-config": "*",
+    "@greese/icons": "*",
+    "@greese/react": "*",
+    "@greese/typescript-config": "*",
+    "@types/node": "^24.0.0",
+    "eslint": "^9.39.0",
+    "react-docgen-typescript": "^2.4.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.26.0",
+    "vitest": "^5.0.5"
+  }
+}