@baseline-ui/mcp 0.46.1

package/dist/index.js

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+import { fileURLToPath } from "node:url";
+import fs from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import path from "node:path";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { mdxFromMarkdown } from "mdast-util-mdx";
+import { mdx } from "micromark-extension-mdx";
+import { toString } from "mdast-util-to-string";
+import packageJson from "../package.json" with { type: "json" };
+function errorToString(err) {
+    if (err &&
+        typeof err === "object" &&
+        "stack" in err &&
+        typeof err.stack === "string") {
+        return err.stack;
+    }
+    if (err &&
+        typeof err === "object" &&
+        "message" in err &&
+        typeof err.message === "string") {
+        return err.message;
+    }
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function readBundledJson(filename) {
+    try {
+        const p = path.resolve(__dirname, "data", filename);
+        if (!fs.existsSync(p)) {
+            return null;
+        }
+        const txt = fs.readFileSync(p, "utf8");
+        return JSON.parse(txt);
+    }
+    catch {
+        return null;
+    }
+}
+function listComponents() {
+    const bundled = readBundledJson("components.json");
+    return Array.isArray(bundled) ? bundled : [];
+}
+function listIcons() {
+    const bundled = readBundledJson("icons.json");
+    return Array.isArray(bundled)
+        ? [...bundled].toSorted((a, b) => a.localeCompare(b))
+        : [];
+}
+function parseSectionsFromMarkdown(content) {
+    const lines = content.split(/\r?\n/);
+    const ast = fromMarkdown(content, {
+        extensions: [mdx()],
+        mdastExtensions: [mdxFromMarkdown()],
+    });
+    const sections = [];
+    function findHeadings(node, startLine = 0) {
+        if (node &&
+            typeof node === "object" &&
+            "type" in node &&
+            node.type === "heading" &&
+            "depth" in node &&
+            node.depth === 2) {
+            const name = toString(node);
+            const position = "position" in node && typeof node.position === "object"
+                ? node.position
+                : null;
+            const start = position &&
+                "start" in position &&
+                position.start &&
+                typeof position.start === "object"
+                ? position.start
+                : null;
+            if (start && "line" in start && typeof start.line === "number") {
+                sections.push({
+                    name,
+                    startLine: start.line - 1,
+                    endLine: lines.length,
+                });
+            }
+        }
+        if (node &&
+            typeof node === "object" &&
+            "children" in node &&
+            Array.isArray(node.children)) {
+            for (const child of node.children) {
+                findHeadings(child, startLine);
+            }
+        }
+    }
+    findHeadings(ast);
+    for (let s = 0; s < sections.length - 1; s++) {
+        sections[s].endLine = sections[s + 1].startLine;
+    }
+    return sections;
+}
+function extractNameAndDescription(content) {
+    const ast = fromMarkdown(content, {
+        extensions: [mdx()],
+        mdastExtensions: [mdxFromMarkdown()],
+    });
+    let name = "";
+    let description = undefined;
+    if ("children" in ast && Array.isArray(ast.children)) {
+        for (let i = 0; i < ast.children.length; i++) {
+            const node = ast.children[i];
+            if (node.type === "heading" && node.depth === 1 && !name) {
+                name = toString(node);
+                continue;
+            }
+            if (name &&
+                !description &&
+                (node.type === "paragraph" || node.type === "text")) {
+                description = toString(node).trim();
+                break;
+            }
+        }
+    }
+    return { name, description };
+}
+let reactAriaComponentsCache = null;
+function getReactAriaComponentInfo(componentName) {
+    if (reactAriaComponentsCache === null) {
+        const racData = readBundledJson("react-aria-components.json");
+        reactAriaComponentsCache =
+            racData && typeof racData === "object"
+                ? racData
+                : {};
+    }
+    return reactAriaComponentsCache?.[componentName] ?? null;
+}
+function getComponentPage(componentName) {
+    const bundled = readBundledJson("component-docs.json");
+    if (!bundled || typeof bundled !== "object" || !(componentName in bundled)) {
+        return null;
+    }
+    try {
+        const content = String(bundled[componentName]);
+        const { name, description } = extractNameAndDescription(content);
+        const sections = parseSectionsFromMarkdown(content);
+        return {
+            name: name || componentName,
+            description,
+            sections,
+            content,
+        };
+    }
+    catch (error) {
+        console.error(`Error reading component page for ${componentName}:`, error);
+        return null;
+    }
+}
+async function startServer() {
+    const server = new McpServer({
+        name: "baseline-ui-docs-server",
+        version: packageJson.version,
+    });
+    // List components tool
+    server.registerTool("list_baseline_components", {
+        title: "List Baseline UI components",
+        description: "Returns a list of available components in Baseline UI design system. When presenting results to users, format them as a readable list or table, not as raw JSON.",
+        inputSchema: { includeDescription: z.boolean().optional() },
+    }, ({ includeDescription }) => {
+        const components = listComponents();
+        const items = components.map((c) => includeDescription
+            ? { name: c.name, description: c.description || "", path: c.path }
+            : { name: c.name });
+        return {
+            content: [{ type: "text", text: JSON.stringify(items, null, 2) }],
+        };
+    });
+    // Get component info tool
+    server.registerTool("get_baseline_component_info", {
+        title: "Get component info",
+        description: "Returns component description and list of documentation sections. Present the description naturally to users and mention available sections they can explore.",
+        inputSchema: { componentName: z.string() },
+    }, ({ componentName }) => {
+        const page = getComponentPage(componentName);
+        if (!page) {
+            // Check for React Aria Components documentation
+            const racInfo = getReactAriaComponentInfo(componentName);
+            if (racInfo) {
+                const out = {
+                    name: racInfo.name,
+                    description: racInfo.description,
+                    sections: ["Documentation", "Usage"],
+                    note: "This component is from React Aria Components. Full documentation is available at the provided URL.",
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(out, null, 2) }],
+                };
+            }
+            throw new Error(`Component '${componentName}' not found. Use list_baseline_components to see available components.`);
+        }
+        const out = {
+            name: page.name,
+            description: page.description ?? "",
+            sections: page.sections.map((s) => s.name),
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(out, null, 2) }],
+        };
+    });
+    // Get component documentation tool
+    server.registerTool("get_baseline_component_docs", {
+        title: "Get component documentation",
+        description: "Returns the full markdown documentation for a component, or a specific section if provided. Render markdown content appropriately when presenting to users, including code examples with proper syntax highlighting.",
+        inputSchema: {
+            componentName: z.string(),
+            sectionName: z.string().optional(),
+        },
+    }, ({ componentName, sectionName }) => {
+        const page = getComponentPage(componentName);
+        if (!page) {
+            // Check for React Aria Components documentation
+            const racInfo = getReactAriaComponentInfo(componentName);
+            if (racInfo) {
+                const docs = `# ${racInfo.name}
+
+${racInfo.description}
+
+## Documentation
+
+For detailed documentation, props, examples, and API reference, visit:
+${racInfo.docsUrl}
+
+## Source Code
+
+View the source code on GitHub:
+${racInfo.sourceUrl}
+
+## Usage
+
+Import from @baseline-ui/core:
+
+\`\`\`tsx
+import { ${racInfo.name} } from "@baseline-ui/core";
+\`\`\`
+
+For detailed usage examples and props, please refer to the React Aria Components documentation linked above.`;
+                return { content: [{ type: "text", text: docs }] };
+            }
+            throw new Error(`Component '${componentName}' not found. Use list_baseline_components to see available components.`);
+        }
+        if (!sectionName) {
+            return { content: [{ type: "text", text: page.content }] };
+        }
+        const lines = page.content.split(/\r?\n/);
+        let section = page.sections.find((s) => s.name === sectionName);
+        if (!section) {
+            section = page.sections.find((s) => s.name.toLowerCase() === sectionName.toLowerCase());
+        }
+        if (!section) {
+            const available = page.sections.map((s) => s.name).join(", ");
+            throw new Error(`Section '${sectionName}' not found in ${componentName}. Available: ${available}`);
+        }
+        const snippet = lines
+            .slice(section.startLine, section.endLine)
+            .join("\n");
+        return { content: [{ type: "text", text: snippet }] };
+    });
+    // Search icons tool
+    server.registerTool("search_baseline_icons", {
+        title: "Search Baseline UI icons",
+        description: "Searches the Baseline UI icon set by one or more terms; returns matching icon names. When presenting results, show icon names in a clear, organized format. Include import syntax example: import { IconName } from '@baseline-ui/icons';",
+        inputSchema: { terms: z.union([z.string(), z.array(z.string())]) },
+    }, ({ terms }) => {
+        const allNames = listIcons();
+        const rawTerms = Array.isArray(terms) ? terms : [terms];
+        const normalized = [
+            ...new Set(rawTerms
+                .map((t) => String(t ?? "")
+                .trim()
+                .toLowerCase())
+                .filter(Boolean)),
+        ];
+        if (normalized.length === 0) {
+            throw new Error("Provide at least one non-empty search term.");
+        }
+        const results = allNames.filter((name) => {
+            const nameLower = name.toLowerCase();
+            return normalized.some((term) => nameLower.includes(term) || term.includes(nameLower));
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    });
+    // Get component types/props tool
+    server.registerTool("get_baseline_component_types", {
+        title: "Get component types",
+        description: "Returns the TypeScript type definitions for a component. When presenting prop types to users, explain the types clearly and highlight required vs optional props, default values, and any important type constraints.",
+        inputSchema: { componentName: z.string() },
+    }, ({ componentName }) => {
+        const bundled = readBundledJson("component-types.json");
+        if (bundled && typeof bundled === "object" && componentName in bundled) {
+            const content = String(bundled[componentName]);
+            return { content: [{ type: "text", text: content }] };
+        }
+        // Check for React Aria Components
+        const racInfo = getReactAriaComponentInfo(componentName);
+        if (racInfo) {
+            const typeInfo = `// ${racInfo.name} type definitions
+
+${racInfo.description}
+
+For complete type definitions, visit:
+${racInfo.docsUrl}
+
+Or view the source code:
+${racInfo.sourceUrl}`;
+            return { content: [{ type: "text", text: typeInfo }] };
+        }
+        throw new Error(`Types file not found for '${componentName}'.`);
+    });
+    // Get component source code tool
+    server.registerTool("get_baseline_component_source", {
+        title: "Get component source code",
+        description: "Returns the source code for a component implementation. When showing source code to users, present it with proper syntax highlighting and explain key implementation details or patterns if relevant to the user's question.",
+        inputSchema: { componentName: z.string() },
+    }, ({ componentName }) => {
+        const bundled = readBundledJson("component-source.json");
+        if (bundled && typeof bundled === "object" && componentName in bundled) {
+            const content = String(bundled[componentName]);
+            return { content: [{ type: "text", text: content }] };
+        }
+        // Check for React Aria Components
+        const racInfo = getReactAriaComponentInfo(componentName);
+        if (racInfo) {
+            const sourceInfo = `// ${racInfo.name} source code
+
+${racInfo.description}
+
+Source code is available on GitHub:
+${racInfo.sourceUrl}
+
+For usage examples and documentation:
+${racInfo.docsUrl}`;
+            return { content: [{ type: "text", text: sourceInfo }] };
+        }
+        throw new Error(`Source file not found for '${componentName}'.`);
+    });
+    // Get getting started guide tool
+    server.registerTool("get_baseline_getting_started", {
+        title: "Get Baseline UI getting started guide",
+        description: "Returns the complete getting started guide for setting up Baseline UI in a new project. This includes installation instructions, required CSS imports, and provider setup. ALWAYS use this tool when helping users set up Baseline UI for the first time or when they encounter setup-related issues.",
+        inputSchema: {},
+    }, () => {
+        const bundled = readBundledJson("getting-started.json");
+        if (bundled && typeof bundled === "object" && "content" in bundled) {
+            return {
+                content: [{ type: "text", text: String(bundled.content) }],
+            };
+        }
+        throw new Error("Getting started guide not found.");
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function printUsage() {
+    const usage = `Usage: @baseline-ui/mcp
+
+Starts the MCP server for Baseline UI design system documentation.
+
+Environment Variables:
+  BASELINE_UI_ROOT    Path to the Baseline UI repository root (default: auto-detected)
+
+Examples:
+  npx @baseline-ui/mcp
+  BASELINE_UI_ROOT=/path/to/baseline-ui npx @baseline-ui/mcp`;
+    console.log(usage);
+}
+// CLI entry
+void (async () => {
+    try {
+        const arg = (process.argv[2] || "").trim();
+        if (arg === "--help" || arg === "-h" || arg === "help") {
+            printUsage();
+            process.exit(0);
+        }
+        await startServer();
+    }
+    catch (error) {
+        console.error(errorToString(error));
+        process.exit(1);
+    }
+})();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@baseline-ui/mcp",
+  "version": "0.46.1",
+  "description": "MCP server for Baseline UI design system documentation",
+  "type": "module",
+  "bin": "dist/index.js",
+  "dependencies": {
+    "@babel/parser": "^7.28.5",
+    "@babel/traverse": "^7.28.5",
+    "@modelcontextprotocol/sdk": "1.21.1",
+    "fast-glob": "^3.3.3",
+    "mdast-util-from-markdown": "^2.0.2",
+    "mdast-util-mdx": "^3.0.0",
+    "mdast-util-to-string": "^4.0.0",
+    "micromark-extension-mdx": "^2.1.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^24.7.0",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": ">=22.20.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ritz078/baseline-ui"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node ./scripts/build-data.mjs && tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "node --enable-source-maps dist/index.js",
+    "test:static": "tsc --noEmit"
+  }
+}