@solid-design-system/mcp 0.0.1

package/CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog

package/LICENSE.md

@@ -0,0 +1,10 @@
+This repository is licensed under MIT, except the fonts, icons and images, which are licensed under their respective licenses.
+
+Read the full license for the
+
+- [components](./packages/components/LICENSE.md)
+- [tokens](./packages/tokens/LICENSE.md)
+- [placeholders](./packages/placeholders/LICENSE.md)
+- [theming](./packages/theming/LICENSE.md)
+
+package for more information.

package/README.md

@@ -0,0 +1,408 @@
+# @solid-design-system/mcp
+
+Solid Design System MCP Server – Component, Style, and Design Metadata
+
+The `@solid-design-system/mcp` package provides a Model Context Protocol (MCP) server enabling AI assistants and development tools to access structured information about Solid Design System components, styles, templates, design tokens, and icons.
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install --save-dev @solid-design-system/mcp
+```
+
+### Running the Server
+
+```bash
+npx @solid-design-system/mcp
+```
+
+### VS Code Integration
+
+Add to your VS Code `settings.json`:
+
+```jsonc
+{
+  "mcp": {
+    "servers": {
+      "solid": {
+        "type": "stdio",
+        "command": "npx",
+        "args": ["@solid-design-system/mcp"]
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop Integration
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "solid": {
+      "command": "npx",
+      "args": ["@solid-design-system/mcp"]
+    }
+  }
+}
+```
+
+## Features
+
+- **Quick Start Tool**: List and retrieve package-level quick-start docs
+- **Unified Component Tool**: List all components, view full specs, retrieve HTML examples, and access package-level guides
+- **Unified Styles Tool**: List all CSS utilities, view full specs, retrieve HTML examples, and access package-level guides
+- **Templates**: List, filter by component/style, and retrieve template source code
+- **Icons**: Search icon libraries across keywords, category, and library
+- **Design Tokens**: Get design token information and guidance
+- **Version Info**: Check MCP server version and metadata
+
+## Available Tools
+
+### 1. `quickstart`
+
+**Quick-start package documentation across Solid packages.**
+
+**Behavior:**
+
+- **No arguments** → Lists available quick-start docs
+- **`doc` arg** (e.g. `"Quickstart"`, `"components/Installation"`) → Returns full doc content
+
+**Parameters:**
+
+- `doc` (string, optional): Quick-start doc slug
+
+**Example prompts:**
+
+- "Show me all quickstart docs"
+- "Show me components installation quickstart"
+- "Get the tokens usage quickstart"
+
+---
+
+### 2. `components`
+
+**Unified entry point for all component-related queries.**
+
+**Behavior:**
+
+- **No arguments** → Lists all available `sd-*` components + available package doc topics
+- **`component` arg** (e.g. `"sd-button"` or `"button"`) → Returns full component spec: usage guidelines, API (properties, events, slots, CSS parts), related components and templates
+- **`component` + `example` args** → Returns HTML code example for a specific usage pattern (e.g. `"sd-button"` + `"inverted"`)
+- **`doc` arg** (e.g. `"localization"`, `"installation"`, `"customization"`) → Returns package-level guide
+
+**Parameters:**
+
+- `component` (string, optional): component tag name (e.g. `"sd-button"` or `"button"`)
+- `example` (string, optional): Example slug for HTML example (e.g. `"inverted"` or `"no-shadow"`) (requires `component`)
+- `doc` (string, optional): Package doc slug (e.g. `"localization"` or `"installation"`)
+
+**Example prompts:**
+
+- "Show me all available Solid components"
+- "What is the sd-button component?"
+- "Show me an inverted sd-button example"
+- "How do I localize components?"
+- "Tell me about component customization"
+
+---
+
+### 3. `styles`
+
+**Unified entry point for all CSS style utilities.**
+
+**Behavior:**
+
+- **No arguments** → Lists all available style utilities + available package doc topics
+- **`style` arg** (e.g. `"sd-chip"` or `"chip"`) → Returns full style spec: usage guidelines, available CSS class names, related components/templates
+- **`style` + `example` args** → Returns HTML code example for a specific usage pattern (e.g. `"sd-chip"` + `"inverted"`)
+- **`doc` arg** (e.g. `"installation"` or `"usage"`) → Returns package-level guide
+
+**Parameters:**
+
+- `style` (string, optional): Style name with or without `sd-` prefix, e.g. `"chip"` or `"sd-chip"`
+- `example` (string, optional): Story slug for HTML example, e.g. `"inverted"` or `"size"` (requires `style`)
+- `doc` (string, optional): Package doc slug, e.g. `"installation"` or `"usage"`
+
+**Example prompts:**
+
+- "Show me all available Solid styles"
+- "What is the sd-chip style?"
+- "Show me a size variant of sd-chip"
+- "How do I install the styles package?"
+- "Tell me about using Solid styles"
+
+---
+
+### 4. `templates`
+
+**Access real-world compositions of Solid components.**
+
+**Behavior:**
+
+- **No arguments** → Lists all available templates
+- **`template` arg** (e.g. `"forms"` or `"button-group"`) → Returns template source code and component inventory
+- **`component` arg** (e.g. `"sd-button"` or `"button"`) → Filters list to templates that use that component
+- **`style` arg** (e.g. `"sd-chip"` or `"chip"`) → Filters list to templates that use that style
+
+**Parameters:**
+
+- `template` (string, optional): Template name, e.g. `"forms"`
+- `component` (string, optional): Component tag to filter by (e.g. `"sd-button"` or `"button"`)
+- `style` (string, optional): Style name to filter by (e.g. `"sd-chip"` or `"chip"`)
+
+**Example prompts:**
+
+- "Show me all available templates"
+- "What is the forms template?"
+- "Show me templates that use sd-button"
+- "Which templates use the sd-chip style?"
+
+---
+
+### 5. `icon-search`
+
+**Search the Solid Design System icon libraries.**
+
+**Parameters:**
+
+- `keywords` (array of strings, required): English and/or German synonyms to search for, e.g. `["download", "save"]`
+- `library` (string, optional): One of `"default"`, `"sd-status-assets"`, `"sd-multi-theming"`
+- `category` (string, optional): One of `"content"`, `"system"`, `"status"`, `"all"`
+
+**Example prompts:**
+
+- "Search for a download icon"
+- "Find icons related to close or dismiss"
+- "Show me icons for user or profile"
+
+---
+
+### 6. `tokens`
+
+**Access design tokens from the Solid Design System.**
+
+**Behavior:**
+
+- **No arguments** → Returns all available tokens with Tailwind and CSS usage guidance
+- **`token` arg** (e.g. `"spacing"`) → Returns matching token names
+- **`doc` arg** (e.g. "installation" or "usage") → Returns package-level guide
+
+**Parameters:**
+
+- `token` (string, optional): Full or partial token query
+- `doc` (string, optional): Package doc slug (e.g. `"installation"`, `"usage"`)
+
+**Example prompts:**
+
+- "Show me the available CSS design tokens"
+- "List tokens for background"
+
+---
+
+### 7. `version`
+
+**Get version and metadata about the Solid Design System MCP Server.**
+
+**Parameters:** None
+
+**Example prompts:**
+
+- "What version of the Solid MCP server is running?"
+- "Show me server information"
+
+---
+
+### MCP Caller Cheat Sheet
+
+Use these argument shapes for MCP tool calls:
+
+```json
+{ "tool": "quickstart", "arguments": {} }
+{ "tool": "quickstart", "arguments": { "doc": "components/Installation" } }
+
+{ "tool": "components", "arguments": { "component": "button" } }
+{ "tool": "components", "arguments": { "component": "sd-button", "example": "inverted" } }
+{ "tool": "components", "arguments": { "doc": "installation" } }
+
+{ "tool": "styles", "arguments": { "style": "chip" } }
+{ "tool": "styles", "arguments": { "style": "sd-chip", "example": "size" } }
+{ "tool": "styles", "arguments": { "doc": "usage" } }
+
+{ "tool": "templates", "arguments": { "component": "button" } }
+{ "tool": "templates", "arguments": { "style": "chip" } }
+{ "tool": "templates", "arguments": { "template": "forms" } }
+
+{ "tool": "icon-search", "arguments": { "keywords": ["download", "herunterladen"], "library": "default", "category": "all" } }
+
+{ "tool": "tokens", "arguments": {} }
+{ "tool": "tokens", "arguments": { "token": "background" } }
+{ "tool": "tokens", "arguments": { "doc": "installation" } }
+
+{ "tool": "version", "arguments": {} }
+```
+
+## Developer Documentation
+
+### Project Structure
+
+```
+src/
+├── bin/
+│   └── index.ts              # CLI entry point
+├── build/                    # Metadata generation
+│   ├── build.ts              # Main orchestrator
+│   ├── components.ts         # Component metadata
+│   ├── icons.ts              # Icon metadata
+│   ├── package-docs.ts       # Package-level docs (Installation, Localization, etc.)
+│   ├── static.ts             # Static content
+│   ├── styles.ts             # Styles metadata
+│   ├── templates.ts          # Templates metadata
+│   └── tokens.ts             # Tokens metadata
+├── server.ts                 # MCP server setup
+├── tools/                    # Tool implementations
+│   ├── quickstart.ts         # Package quick-start docs
+│   ├── components.ts         # Unified components tool
+│   ├── icon-search.ts        # Icon search
+│   ├── styles.ts             # Unified styles tool
+│   ├── templates.ts          # Unified templates tool
+│   ├── tokens.ts             # tokens tool
+│   ├── version.ts            # Version information
+│   └── index.ts              # Tool exports
+└── utilities/                # Helper functions
+    ├── checksum.ts           # Metadata checksums
+    ├── components.ts         # Component utilities
+    ├── config.ts             # Configuration paths
+    ├── file.ts               # File utilities
+    ├── metadata.ts           # Metadata loading
+    ├── stdio.ts              # I/O utilities
+    ├── styles.ts             # Style utilities
+    ├── templates.ts          # Template utilities
+    ├── tokens.ts             # Token utilities
+    ├── version.ts            # Version utilities
+    └── index.ts              # Utility exports
+
+metadata/                    # Generated and static metadata
+├── packages/
+│   ├── components/          # Component metadata
+│   │   ├── sd-*/            # Per-component dirs
+│   │   │   ├── info.md      # Full spec (API, guidelines, examples list)
+│   │   │   └── stories/     # HTML examples
+│   │   │       └── *.md
+│   │   └── docs/            # Package-level docs
+│   │       ├── installation.md
+│   │       ├── localization.md
+│   │       ├── customization.md
+│   │       └── *.md
+│   ├── styles/              # Style metadata
+│   │   ├── sd-*/
+│   │   │   ├── info.md
+│   │   │   └── stories/
+│   │   └── docs/            # Package-level docs
+│   │       ├── installation.md
+│   │       └── *.md
+│   ├── templates/           # Template metadata (.md files)
+│   ├── icons/               # Icon library metadata
+│   ├── quickstart/          # Quickstart docs metadata
+│   └── tokens/              # Tokens metada
+└── static/                  # Static AI-rule files
+```
+
+### Key Changes in v2.6.0
+
+**Tool Consolidation:** Reduced from 10 tools to 5 unified tools:
+
+| Old Tools                                                    | New Tool     | Key Difference                                        |
+| ------------------------------------------------------------ | ------------ | ----------------------------------------------------- |
+| `component-list`, `component-docs`, `component-api-examples` | `components` | Single tool handles list, spec, and examples via args |
+| `styles-list`, `styles-info`, `style-api-examples`           | `styles`     | Single tool handles list, spec, and examples via args |
+| `template-list`, `template-info`                             | `templates`  | Single tool with optional filtering                   |
+
+**Package Documentation:** Added package-level guides (Installation, Localization, Customization, Usage) extracted from MDX files in `packages/docs/src/stories/packages/`:
+
+- `components` tool with `doc` arg accesses these
+- `styles` tool with `doc` arg accesses these
+- Automatically built from source during `build:metadata`
+
+### Building
+
+```bash
+# Build TypeScript and metadata
+pnpm build
+
+# Or separately:
+pnpm build:ts          # Compile TypeScript only
+pnpm build:metadata    # Generate metadata from source
+pnpm build:hash        # Generate integrity checksum
+```
+
+### Metadata Generation
+
+The `build:metadata` script currently runs builders in this sequence:
+
+1. **Components** — Extracts component metadata
+2. **Styles** — Extracts style metadata
+3. **Templates** — Finalizes template metadata and relationships
+4. **Tokens** — Generates token definitions
+5. **Icons** — Generates icon indexes by library/category
+6. **Package docs** — Converts package MDX docs to build-time markdown
+7. **Static files** — Copies static guidance content
+
+### Adding a New Tool
+
+1. Create `src/tools/my-tool.ts`:
+
+   ```typescript
+   import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+   import { z } from 'zod';
+
+   export const myTool = (server: McpServer) => {
+     server.registerTool(
+       'my-tool',
+       {
+         description: 'What this tool does',
+         inputSchema: {
+           param: z.string().describe('A parameter')
+         },
+         title: 'My Tool'
+       },
+       async ({ param }) => {
+         return { content: [{ type: 'text', text: 'Result' }] };
+       }
+     );
+   };
+   ```
+
+2. Export from `src/tools/index.ts`:
+
+   ```typescript
+   export * from './my-tool.js';
+   ```
+
+3. Register in `src/server.ts` (via `tools/index.ts` exports)
+
+### Testing the Server
+
+```bash
+# Start the server
+npx @solid-design-system/mcp
+
+# In another terminal, you can test tool invocation
+# (requires MCP client or integration with Claude/VS Code)
+```
+
+## Related Packages
+
+- `@solid-design-system/components` — Web Components library
+- `@solid-design-system/styles` — CSS utility classes
+- `@solid-design-system/tokens` — Design token definitions
+- `@solid-design-system/icons` — Icon library
+- `@solid-design-system/theming` — Theme management
+
+## License
+
+See [LICENSE.md](../../LICENSE.md)

package/dist/bin/start.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/start.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from '../server.js';
+import { handleCommandLineArgs } from '../utilities/index.js';
+handleCommandLineArgs();
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/build/build.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/build/build.js

@@ -0,0 +1,36 @@
+import ora from 'ora';
+import { buildComponents } from './components.js';
+import { buildIcons } from './icons.js';
+import { buildPackageDocs } from './package-docs.js';
+import { buildStaticFiles } from './static.js';
+import { buildTemplates } from './templates.js';
+import { buildTokens } from './tokens.js';
+import { buildStyles } from './styles.js';
+const spinner = ora({
+    prefixText: 'MCP:',
+    text: 'Generating static metadata...'
+});
+const build = async () => {
+    spinner.start();
+    // components must run before templates (templates writes into component dirs)
+    await buildComponents();
+    await buildStyles();
+    await buildTemplates();
+    await buildTokens();
+    await buildIcons();
+    await buildPackageDocs();
+    // Should be run last as we will copy files where we see fit and paths must exist
+    await buildStaticFiles();
+};
+build()
+    .then(() => {
+    spinner.succeed('Static metadata generated successfully.');
+    process.exit(0);
+})
+    .catch(error => {
+    spinner.fail(`Failed to generate static metadata. Error: ${error}`);
+    process.exit(1);
+})
+    .finally(() => {
+    spinner.stop();
+});

package/dist/build/components.d.ts

@@ -0,0 +1,9 @@
+export interface Example {
+    /** kebab-case slug used as the filename, e.g. "no-shadow" */
+    slug: string;
+    /** JSDoc description extracted from the comment above the export */
+    description: string;
+    /** Rendered HTML content */
+    html: string;
+}
+export declare const buildComponents: () => Promise<void>;