@dynamic-labs-sdk/droplet-mcp 0.0.0 → 1.16.1

package/README.md

@@ -0,0 +1,51 @@
+# @dynamic-labs-sdk/droplet-mcp
+
+An MCP (Model Context Protocol) server that exposes Droplet's component manifest to coding agents. It provides three tools — `list-components`, `get-details`, and `search-components` — so AI coding assistants can discover and reason about the available UI components without reading raw source files.
+
+## Usage
+
+### Build
+
+```bash
+pnpm build
+```
+
+### Run
+
+```bash
+node dist/index.js
+```
+
+By default the server reads `./components.json`. Set `DROPLET_MANIFEST` to override:
+
+```bash
+# Local file
+DROPLET_MANIFEST=./manifests/components.json node dist/index.js
+
+# Remote URL (Storybook-generated manifest)
+DROPLET_MANIFEST=https://your-storybook.example.com/manifests/components.json node dist/index.js
+```
+
+### Environment variables
+
+| Variable           | Default             | Description                                                                 |
+| ------------------ | ------------------- | --------------------------------------------------------------------------- |
+| `DROPLET_MANIFEST` | `./components.json` | Path or `http(s)://` URL to the Storybook-generated `manifests/components.json` |
+
+### MCP registration (`.mcp.json`)
+
+Add the server to your project's `.mcp.json` so your coding agent picks it up automatically:
+
+```json
+{
+  "mcpServers": {
+    "droplet": {
+      "command": "node",
+      "args": ["./node_modules/@dynamic-labs-sdk/droplet-mcp/dist/index.js"],
+      "env": {
+        "DROPLET_MANIFEST": "./manifests/components.json"
+      }
+    }
+  }
+}
+```

package/dist/createServer/createServer.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ComponentsManifest } from '../manifest-types.js';
+/**
+ * Creates an MCP server pre-configured with three droplet knowledge tools:
+ * `list-components`, `get-details`, and `search-components`.
+ *
+ * @param manifest - The parsed components manifest used to answer tool queries.
+ * @returns A configured McpServer instance ready to be connected to a transport.
+ * @notInstrumented
+ */
+export declare const createServer: (manifest: ComponentsManifest) => McpServer;

package/dist/createServer/createServer.js

@@ -0,0 +1,54 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { getDetails } from '../getDetails/getDetails.js';
+import { listComponents } from '../listComponents/listComponents.js';
+import { sanitizeName } from '../sanitizeName/sanitizeName.js';
+import { searchComponents } from '../searchComponents/searchComponents.js';
+/**
+ * Creates an MCP server pre-configured with three droplet knowledge tools:
+ * `list-components`, `get-details`, and `search-components`.
+ *
+ * @param manifest - The parsed components manifest used to answer tool queries.
+ * @returns A configured McpServer instance ready to be connected to a transport.
+ * @notInstrumented
+ */
+export const createServer = (manifest) => {
+    const server = new McpServer({ name: 'droplet-mcp', version: '0.1.0' });
+    server.registerTool('list-components', {
+        description: 'List all droplet components with a one-line description. Call this before building UI to see what exists.',
+    }, async () => ({
+        content: [
+            { text: JSON.stringify(listComponents(manifest), null, 2), type: 'text' },
+        ],
+    }));
+    server.registerTool('get-details', {
+        description: 'Get the exact props, variants, and example for one droplet component. Use this instead of guessing the API from memory.',
+        inputSchema: { name: z.string().max(100).describe('Component name, e.g. "Button"') },
+    }, async ({ name }) => {
+        const details = getDetails({ manifest, name });
+        // Sanitize name before echoing to prevent control character injection in error messages
+        const safeName = sanitizeName({ name });
+        return {
+            content: [
+                {
+                    text: details
+                        ? JSON.stringify(details, null, 2)
+                        : `No droplet component named "${safeName}". Call list-components for valid names.`,
+                    type: 'text',
+                },
+            ],
+        };
+    });
+    server.registerTool('search-components', {
+        description: 'Search droplet components by keyword (name, description, variant, or prop name), e.g. "dialog", "toggle", "empty state".',
+        inputSchema: { query: z.string().max(200).describe('Keyword to search for') },
+    }, async ({ query }) => ({
+        content: [
+            {
+                text: JSON.stringify(searchComponents({ manifest, query }), null, 2),
+                type: 'text',
+            },
+        ],
+    }));
+    return server;
+};

package/dist/errors/ManifestLoadError/ManifestLoadError.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Error thrown when a droplet manifest cannot be loaded — e.g. the source uses
+ * plain HTTP, an HTTPS fetch returns a non-OK status, or the local file read fails.
+ *
+ * Using a dedicated subclass (instead of bare `new Error`) keeps load failures
+ * distinguishable from other runtime errors at the CLI boundary in `index.ts`.
+ */
+export declare class ManifestLoadError extends Error {
+    constructor(message: string);
+}

package/dist/errors/ManifestLoadError/ManifestLoadError.js

@@ -0,0 +1,14 @@
+/**
+ * Error thrown when a droplet manifest cannot be loaded — e.g. the source uses
+ * plain HTTP, an HTTPS fetch returns a non-OK status, or the local file read fails.
+ *
+ * Using a dedicated subclass (instead of bare `new Error`) keeps load failures
+ * distinguishable from other runtime errors at the CLI boundary in `index.ts`.
+ */
+export class ManifestLoadError extends Error {
+    // eslint-disable-next-line custom-rules/require-single-object-param
+    constructor(message) {
+        super(message);
+        this.name = 'ManifestLoadError';
+    }
+}

package/dist/getDetails/getDetails.d.ts

@@ -0,0 +1,15 @@
+import type { ComponentsManifest, ManifestComponent } from '../manifest-types.js';
+/**
+ * Parameters for {@link getDetails}.
+ */
+export type GetDetailsParams = {
+    /** The parsed components manifest to search. */
+    manifest: ComponentsManifest;
+    /** Component name to look up (matched case-insensitively). */
+    name: string;
+};
+/**
+ * Finds a component by name (case-insensitive). Returns null when not found.
+ * @notInstrumented
+ */
+export declare const getDetails: ({ manifest, name, }: GetDetailsParams) => ManifestComponent | null;

package/dist/getDetails/getDetails.js

@@ -0,0 +1,5 @@
+/**
+ * Finds a component by name (case-insensitive). Returns null when not found.
+ * @notInstrumented
+ */
+export const getDetails = ({ manifest, name, }) => manifest.components.find((c) => c.name.toLowerCase() === name.toLowerCase()) ?? null;

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadManifest } from './loadManifest/loadManifest.js';
+import { parseManifest } from './parseManifest/parseManifest.js';
+import { createServer } from './createServer/createServer.js';
+import { redactSource } from './redactSource/redactSource.js';
+const source = process.env.DROPLET_MANIFEST ?? './components.json';
+let raw;
+try {
+    raw = await loadManifest({ source });
+}
+catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // Redact credentials/tokens from URL before writing to stderr
+    const safeSource = redactSource({ source });
+    process.stderr.write(`Failed to load droplet manifest from "${safeSource}": ${message}\n`);
+    process.exit(1);
+}
+const server = createServer(parseManifest(raw));
+await server.connect(new StdioServerTransport());

package/dist/listComponents/listComponents.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentsManifest } from '../manifest-types.js';
+/**
+ * Returns a lightweight summary (name + description) for every component in the manifest.
+ * @notInstrumented
+ */
+export declare const listComponents: (m: ComponentsManifest) => {
+    description: string;
+    name: string;
+}[];

package/dist/listComponents/listComponents.js

@@ -0,0 +1,5 @@
+/**
+ * Returns a lightweight summary (name + description) for every component in the manifest.
+ * @notInstrumented
+ */
+export const listComponents = (m) => m.components.map((c) => ({ description: c.description ?? '', name: c.name }));

package/dist/loadManifest/loadManifest.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Parameters for {@link loadManifest}.
+ */
+export type LoadManifestParams = {
+    /**
+     * Where to load the manifest from: an `https://` URL (fetched over TLS) or a
+     * local file path. Plain `http://` URLs are rejected.
+     */
+    source: string;
+};
+/**
+ * Loads raw manifest JSON from a source string.
+ *
+ * - `https://` sources are fetched over TLS.
+ * - `http://` sources are rejected outright to prevent MITM attacks.
+ * - All other strings are treated as local file paths read via `readFileSync`.
+ *
+ * @throws {ManifestLoadError} When the source uses plain HTTP or the fetch fails.
+ * @notInstrumented
+ */
+export declare const loadManifest: ({ source, }: LoadManifestParams) => Promise<unknown>;

package/dist/loadManifest/loadManifest.js

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { ManifestLoadError } from '../errors/ManifestLoadError/ManifestLoadError.js';
+/**
+ * Loads raw manifest JSON from a source string.
+ *
+ * - `https://` sources are fetched over TLS.
+ * - `http://` sources are rejected outright to prevent MITM attacks.
+ * - All other strings are treated as local file paths read via `readFileSync`.
+ *
+ * @throws {ManifestLoadError} When the source uses plain HTTP or the fetch fails.
+ * @notInstrumented
+ */
+export const loadManifest = async ({ source, }) => {
+    if (source.startsWith('https://')) {
+        const res = await fetch(source);
+        if (!res.ok) {
+            throw new ManifestLoadError(`HTTP ${res.status} ${res.statusText}`);
+        }
+        return res.json();
+    }
+    if (source.startsWith('http://')) {
+        // Refuse plain HTTP to prevent MITM attacks on the manifest
+        throw new ManifestLoadError('Refusing to load manifest over plain HTTP — use https://');
+    }
+    return JSON.parse(readFileSync(source, 'utf8'));
+};

package/dist/manifest-types.d.ts

@@ -0,0 +1,18 @@
+export type ManifestProp = {
+    defaultValue?: string;
+    description?: string;
+    name: string;
+    required?: boolean;
+    type?: string;
+};
+export type ManifestComponent = {
+    description?: string;
+    examples?: string[];
+    name: string;
+    props?: ManifestProp[];
+    related?: string[];
+    variants?: Record<string, string[]>;
+};
+export type ComponentsManifest = {
+    components: ManifestComponent[];
+};

package/dist/manifest-types.js

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

package/dist/parseManifest/parseManifest.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentsManifest } from '../manifest-types.js';
+/**
+ * Adapts a raw Storybook-derived manifest (as stored on disk) into the normalized
+ * `ComponentsManifest` shape consumed by the MCP query functions.
+ *
+ * This function is intentionally defensive: any falsy, null, or structurally unexpected
+ * input returns `{ components: [] }` rather than throwing.
+ * @notInstrumented
+ */
+export declare const parseManifest: (raw: unknown) => ComponentsManifest;

package/dist/parseManifest/parseManifest.js

@@ -0,0 +1,23 @@
+import { parseRawComponent } from './parseRawComponent/parseRawComponent.js';
+/**
+ * Adapts a raw Storybook-derived manifest (as stored on disk) into the normalized
+ * `ComponentsManifest` shape consumed by the MCP query functions.
+ *
+ * This function is intentionally defensive: any falsy, null, or structurally unexpected
+ * input returns `{ components: [] }` rather than throwing.
+ * @notInstrumented
+ */
+export const parseManifest = (raw) => {
+    if (raw == null || typeof raw !== 'object') {
+        return { components: [] };
+    }
+    const rawObj = raw;
+    const componentsDict = rawObj['components'];
+    if (componentsDict == null ||
+        typeof componentsDict !== 'object' ||
+        Array.isArray(componentsDict)) {
+        return { components: [] };
+    }
+    const components = Object.entries(componentsDict).map(([storyId, entry]) => parseRawComponent({ rawEntry: entry, storyId }));
+    return { components };
+};

package/dist/parseManifest/parseRawComponent/parseRawComponent.d.ts

@@ -0,0 +1,16 @@
+import type { ManifestComponent } from '../../manifest-types.js';
+/**
+ * Parameters for {@link parseRawComponent}.
+ */
+export type ParseRawComponentParams = {
+    /** The raw component entry (one value from `raw.components`). */
+    rawEntry: unknown;
+    /** Storybook dict key used as the fallback component name. */
+    storyId: string;
+};
+/**
+ * Converts a single raw component entry (one value from `raw.components`) into a
+ * `ManifestComponent`. The storybook dict key (`storyId`) is used as fallback name.
+ * @notInstrumented
+ */
+export declare const parseRawComponent: ({ storyId, rawEntry, }: ParseRawComponentParams) => ManifestComponent;

package/dist/parseManifest/parseRawComponent/parseRawComponent.js

@@ -0,0 +1,47 @@
+import { parseRawProp } from '../parseRawProp/parseRawProp.js';
+import { parseVariantValues } from '../parseVariantValues/parseVariantValues.js';
+/**
+ * Converts a single raw component entry (one value from `raw.components`) into a
+ * `ManifestComponent`. The storybook dict key (`storyId`) is used as fallback name.
+ * @notInstrumented
+ */
+export const parseRawComponent = ({ storyId, rawEntry, }) => {
+    const entry = rawEntry;
+    const name = typeof entry['name'] === 'string' ? entry['name'] : storyId;
+    const rdgt = entry['reactDocgenTypescript'];
+    const rawDescription = rdgt?.['description'];
+    const description = typeof rawDescription === 'string' && rawDescription.length > 0
+        ? rawDescription
+        : undefined;
+    // Parse props from reactDocgenTypescript.props dict
+    const rawProps = (rdgt?.['props'] ?? {});
+    const props = Object.entries(rawProps).map(([key, val]) => parseRawProp({ propKey: key, rawProp: val }));
+    // Derive variant sets from props whose type is a union of quoted string literals
+    const variantEntries = [];
+    for (const prop of props) {
+        if (prop.type !== undefined) {
+            const values = parseVariantValues({ typeName: prop.type });
+            if (values !== undefined) {
+                variantEntries.push([prop.name, values]);
+            }
+        }
+    }
+    // Only include variants when at least one prop yields a variant set
+    const variants = variantEntries.length > 0 ? Object.fromEntries(variantEntries) : undefined;
+    // Extract example code snippets from stories; filter to strings only
+    const rawStories = Array.isArray(entry['stories']) ? entry['stories'] : [];
+    const examples = rawStories
+        .map((s) => {
+        const story = s;
+        return story['snippet'];
+    })
+        .filter((snippet) => typeof snippet === 'string');
+    return {
+        description,
+        // examples should be undefined when empty, consistent with props/variants
+        examples: examples.length > 0 ? examples : undefined,
+        name,
+        props: props.length > 0 ? props : undefined,
+        variants,
+    };
+};

package/dist/parseManifest/parseRawProp/parseRawProp.d.ts

@@ -0,0 +1,16 @@
+import type { ManifestProp } from '../../manifest-types.js';
+/**
+ * Parameters for {@link parseRawProp}.
+ */
+export type ParseRawPropParams = {
+    /** Canonical prop name used when the raw entry has no `name` field. */
+    propKey: string;
+    /** The raw prop entry from `reactDocgenTypescript.props`. */
+    rawProp: unknown;
+};
+/**
+ * Converts a single raw prop entry (from `reactDocgenTypescript.props`) into a `ManifestProp`.
+ * The prop key from the dict is used as the canonical name.
+ * @notInstrumented
+ */
+export declare const parseRawProp: ({ propKey, rawProp, }: ParseRawPropParams) => ManifestProp;

package/dist/parseManifest/parseRawProp/parseRawProp.js

@@ -0,0 +1,20 @@
+/**
+ * Converts a single raw prop entry (from `reactDocgenTypescript.props`) into a `ManifestProp`.
+ * The prop key from the dict is used as the canonical name.
+ * @notInstrumented
+ */
+export const parseRawProp = ({ propKey, rawProp, }) => {
+    const p = rawProp;
+    const name = typeof p['name'] === 'string' ? p['name'] : propKey;
+    const description = typeof p['description'] === 'string' && p['description'].length > 0
+        ? p['description']
+        : undefined;
+    const typeObj = p['type'];
+    const typeName = typeof typeObj?.['name'] === 'string' ? typeObj['name'] : undefined;
+    const defaultValueObj = p['defaultValue'];
+    const defaultValue = defaultValueObj != null && typeof defaultValueObj['value'] === 'string'
+        ? defaultValueObj['value']
+        : undefined;
+    const required = typeof p['required'] === 'boolean' ? p['required'] : undefined;
+    return { defaultValue, description, name, required, type: typeName };
+};

package/dist/parseManifest/parseVariantValues/parseVariantValues.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parameters for {@link parseVariantValues}.
+ */
+export type ParseVariantValuesParams = {
+    /** Raw prop type name, possibly a union like `"default" | "outline" | null`. */
+    typeName: string;
+};
+/**
+ * Parses a raw prop type name (which may be a union string like `"default" | "outline" | null`)
+ * into an array of string-literal values. Only quoted string members are kept;
+ * tokens like `null`, `undefined`, `boolean`, and `string` are discarded.
+ *
+ * Returns the array only when it has at least 2 members (i.e. a real variant set).
+ * Returns undefined otherwise.
+ * @notInstrumented
+ */
+export declare const parseVariantValues: ({ typeName, }: ParseVariantValuesParams) => string[] | undefined;

package/dist/parseManifest/parseVariantValues/parseVariantValues.js

@@ -0,0 +1,25 @@
+/**
+ * Quoted-string-literal pattern for detecting enum-like union types.
+ * Matches members like `"default"` and captures the inner string value.
+ */
+const QUOTED_LITERAL_RE = /^"([^"]+)"$/;
+/**
+ * Parses a raw prop type name (which may be a union string like `"default" | "outline" | null`)
+ * into an array of string-literal values. Only quoted string members are kept;
+ * tokens like `null`, `undefined`, `boolean`, and `string` are discarded.
+ *
+ * Returns the array only when it has at least 2 members (i.e. a real variant set).
+ * Returns undefined otherwise.
+ * @notInstrumented
+ */
+export const parseVariantValues = ({ typeName, }) => {
+    const members = typeName.split('|').map((t) => t.trim());
+    const literals = [];
+    for (const member of members) {
+        const match = QUOTED_LITERAL_RE.exec(member);
+        if (match) {
+            literals.push(match[1]);
+        }
+    }
+    return literals.length >= 2 ? literals : undefined;
+};

package/dist/redactSource/redactSource.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parameters for {@link redactSource}.
+ */
+export type RedactSourceParams = {
+    /** The manifest source (URL or file path) to redact before logging. */
+    source: string;
+};
+/**
+ * Redacts credentials (userinfo + query string) from http(s) URLs before logging,
+ * so we never leak secrets in error output. File paths are returned as-is.
+ * @notInstrumented
+ */
+export declare const redactSource: ({ source }: RedactSourceParams) => string;

package/dist/redactSource/redactSource.js

@@ -0,0 +1,22 @@
+/**
+ * Redacts credentials (userinfo + query string) from http(s) URLs before logging,
+ * so we never leak secrets in error output. File paths are returned as-is.
+ * @notInstrumented
+ */
+export const redactSource = ({ source }) => {
+    if (source.startsWith('https://') || source.startsWith('http://')) {
+        try {
+            const u = new URL(source);
+            // Strip userinfo (user:pass@) and query string — they may carry tokens
+            u.username = '';
+            u.password = '';
+            u.search = '';
+            return u.toString();
+        }
+        catch {
+            // If URL parsing fails, return a generic placeholder
+            return '[invalid url]';
+        }
+    }
+    return source;
+};

package/dist/sanitizeName/sanitizeName.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Parameters for {@link sanitizeName}.
+ */
+export type SanitizeNameParams = {
+    /** Maximum length of the returned string. Defaults to 50. */
+    maxLen?: number;
+    /** The user-supplied name to sanitize. */
+    name: string;
+};
+/**
+ * Strips control characters and newlines from a string, then truncates to maxLen.
+ * Used to sanitize user-supplied component names before echoing them in error messages.
+ * @notInstrumented
+ */
+export declare const sanitizeName: ({ name, maxLen, }: SanitizeNameParams) => string;

package/dist/sanitizeName/sanitizeName.js

@@ -0,0 +1,13 @@
+/**
+ * Default maximum length applied when truncating sanitized names.
+ */
+const DEFAULT_MAX_LEN = 50;
+/**
+ * Strips control characters and newlines from a string, then truncates to maxLen.
+ * Used to sanitize user-supplied component names before echoing them in error messages.
+ * @notInstrumented
+ */
+export const sanitizeName = ({ name, maxLen = DEFAULT_MAX_LEN, }) => 
+// Intentionally strips control characters from the name
+// eslint-disable-next-line no-control-regex
+name.replace(/[\x00-\x1F\x7F]/g, '').slice(0, maxLen);

package/dist/searchComponents/searchComponents.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentsManifest } from '../manifest-types.js';
+/**
+ * Parameters for {@link searchComponents}.
+ */
+export type SearchComponentsParams = {
+    /** The parsed components manifest to search. */
+    manifest: ComponentsManifest;
+    /** Keyword to match against name, description, variant values, and prop names. */
+    query: string;
+};
+/**
+ * Searches components by matching the query against name, description, variant values,
+ * and prop names. Returns an empty array when the query is blank.
+ * @notInstrumented
+ */
+export declare const searchComponents: ({ manifest, query }: SearchComponentsParams) => {
+    description: string;
+    name: string;
+}[];

package/dist/searchComponents/searchComponents.js

@@ -0,0 +1,21 @@
+/**
+ * Searches components by matching the query against name, description, variant values,
+ * and prop names. Returns an empty array when the query is blank.
+ * @notInstrumented
+ */
+export const searchComponents = ({ manifest, query }) => {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    return manifest.components
+        .filter((c) => c.name.toLowerCase().includes(q) ||
+        (c.description?.toLowerCase().includes(q) ?? false) ||
+        (c.variants
+            ? Object.values(c.variants)
+                .flat()
+                .some((v) => v.toLowerCase().includes(q))
+            : false) ||
+        // Also match if any prop name contains the query
+        (c.props ? c.props.some((p) => p.name.toLowerCase().includes(q)) : false))
+        .map((c) => ({ description: c.description ?? '', name: c.name }));
+};

package/package.json

@@ -1 +1,29 @@
-{ "name": "@dynamic-labs-sdk/droplet-mcp", "version": "0.0.0" }
+{
+  "name": "@dynamic-labs-sdk/droplet-mcp",
+  "version": "1.16.1",
+  "type": "module",
+  "bin": {
+    "droplet-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "4.0.5"
+  },
+  "devDependencies": {
+    "typescript": "~5.7.2",
+    "vitest": "4.1.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test-with-coverage": "vitest run --coverage",
+    "start": "node dist/index.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  }
+}