@mdui/mcp 2.1.0

package/index.d.ts

@@ -0,0 +1 @@
+export { createServer } from './server.js';

package/index.js

@@ -0,0 +1 @@
+export { createServer } from './server.js';

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mdui/mcp",
+  "version": "2.1.0",
+  "description": "mdui MCP Server",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "mdui-mcp": "stdio.js"
+  },
+  "files": [
+    "data",
+    "tools",
+    "index.{js,d.ts}",
+    "server.{js,d.ts}",
+    "stdio.{js,d.ts}",
+    "LICENSE",
+    "package.json",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zdhxiong/mdui.git"
+  },
+  "author": "zdhxiong <zdhxiong@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/zdhxiong/mdui/issues"
+  },
+  "homepage": "https://www.mdui.org",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "zod": "^3.25.76",
+    "tslib": "^2.8.1"
+  }
+}

package/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;

package/server.js

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerGetComponentMetadata } from './tools/getComponentMetadata.js';
+import { registerGetDocument } from './tools/getDocument.js';
+import { registerListComponents } from './tools/listComponents.js';
+import { registerListCssClasses } from './tools/listCssClasses.js';
+import { registerListCssVariables } from './tools/listCssVariables.js';
+import { registerListDocuments } from './tools/listDocuments.js';
+import { registerListIconCodes } from './tools/listIconCodes.js';
+import { registerListIconComponents } from './tools/listIconComponents.js';
+export function createServer() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    const VERSION = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8')).version;
+    const server = new McpServer({
+        name: 'mdui-mcp',
+        version: VERSION,
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Register tool modules
+    registerListComponents(server);
+    registerGetComponentMetadata(server);
+    registerListCssClasses(server);
+    registerListCssVariables(server);
+    registerListDocuments(server);
+    registerGetDocument(server);
+    registerListIconCodes(server);
+    registerListIconComponents(server);
+    return server;
+}

package/stdio.d.ts

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

package/stdio.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('[mdui-mcp] fatal:', err);
+    process.exit(1);
+});

package/tools/getComponentMetadata.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * 获取指定组件的详细元数据
+ * @param server
+ */
+export declare function registerGetComponentMetadata(server: McpServer): void;

package/tools/getComponentMetadata.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { components } from '../data/components.js';
+/**
+ * 获取指定组件的详细元数据
+ * @param server
+ */
+export function registerGetComponentMetadata(server) {
+    const propertySchema = z
+        .object({
+        name: z.string().describe('The property name'),
+        attribute: z
+            .string()
+            .nullable()
+            .describe('The associated HTML attribute name, or null if none'),
+        reflects: z
+            .boolean()
+            .optional()
+            .describe('Whether the property reflects to an attribute'),
+        description: z.string().describe('A brief description of the property'),
+        type: z.string().describe('The property type as text'),
+        default: z
+            .string()
+            .optional()
+            .describe('The default value as text, if any'),
+    })
+        .strict();
+    const methodSchema = z
+        .object({
+        name: z.string().describe('The method name'),
+        signature: z
+            .string()
+            .describe('The full method signature as text, including parameters and return type'),
+        description: z.string().describe('A brief description of the method'),
+    })
+        .strict();
+    const eventSchema = z
+        .object({
+        name: z.string().describe("The event name (without the 'on' prefix)"),
+        description: z.string().describe('A brief description of the event'),
+    })
+        .strict();
+    const slotSchema = z
+        .object({
+        name: z.string().describe("The slot name ('' for the default slot)"),
+        description: z.string().describe('A brief description of the slot'),
+    })
+        .strict();
+    const cssPartSchema = z
+        .object({
+        name: z.string().describe('The CSS part name (for ::part)'),
+        description: z.string().describe('A brief description of the CSS part'),
+    })
+        .strict();
+    const cssPropertySchema = z
+        .object({
+        name: z
+            .string()
+            .describe('The CSS custom property name, including the leading --'),
+        description: z
+            .string()
+            .describe('A brief description of the CSS custom property'),
+    })
+        .strict();
+    // Reusable component schema and in-memory index for O(1) lookups
+    const componentSchema = z
+        .object({
+        tagName: z
+            .string()
+            .describe('The tag name of the component, e.g., mdui-button'),
+        description: z.string().describe('A brief description of the component'),
+        docUrl: z
+            .string()
+            .url()
+            .describe('The URL to the component documentation'),
+        usage: z.string().describe('Example HTML usage snippet of the component'),
+        properties: z.array(propertySchema).describe('Public properties'),
+        methods: z.array(methodSchema).describe('Public methods'),
+        events: z.array(eventSchema).describe('Dispatched events'),
+        slots: z.array(slotSchema).describe('Slots'),
+        cssParts: z.array(cssPartSchema).describe('Exposed CSS parts'),
+        cssProperties: z
+            .array(cssPropertySchema)
+            .describe('Supported CSS custom properties'),
+    })
+        .strict();
+    const componentsIndex = new Map(components.map((c) => [
+        c.tagName.toLowerCase(),
+        c,
+    ]));
+    server.registerTool('get_component_metadata', {
+        title: 'Get Component Metadata',
+        description: 'Get detailed API metadata for one mdui Web Component by tagName (case-insensitive). Read-only, offline, deterministic. Use list_components to discover available tag names. Returns: tagName, description, documentation URL, usage snippet, and arrays of properties, methods, events, slots, cssParts, and cssProperties. Note: attribute names may differ from property names; when both exist, the property may reflect to the attribute if "reflects" is true.',
+        inputSchema: {
+            tagName: z
+                .string()
+                .min(1)
+                .transform((s) => s.trim().toLowerCase())
+                .describe('The tag name of the component, e.g., mdui-button (case-insensitive).'),
+        },
+        outputSchema: componentSchema.shape,
+    }, async ({ tagName }) => {
+        const component = componentsIndex.get(tagName);
+        if (!component) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Component not found: ${tagName}. Use list_components to see all available tag names.`,
+                    },
+                ],
+            };
+        }
+        return {
+            structuredContent: component,
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(component, null, 2),
+                },
+            ],
+        };
+    });
+}

package/tools/getDocument.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * 根据 key 或 tagName 获取单个文档内容
+ * - key: 来自 list_documents 工具的 key，如 components--button
+ * - tagName: 来自 list_components 工具的 tagName，如 mdui-button
+ */
+export declare function registerGetDocument(server: McpServer): void;

package/tools/getDocument.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { documents } from '../data/documents.js';
+/**
+ * 根据 key 或 tagName 获取单个文档内容
+ * - key: 来自 list_documents 工具的 key，如 components--button
+ * - tagName: 来自 list_components 工具的 tagName，如 mdui-button
+ */
+export function registerGetDocument(server) {
+    // 输入：允许传入 key 或 tagName（至少其一，且两者互斥）
+    const normalizeOptionalNonEmptyLower = (label) => z
+        .preprocess((v) => {
+        if (typeof v === 'string') {
+            const s = v.trim();
+            return s.length === 0 ? undefined : s.toLowerCase();
+        }
+        return v;
+    }, z.string().min(1).optional())
+        .describe(label);
+    const inputSchema = {
+        key: normalizeOptionalNonEmptyLower('Document key from list_documents, e.g., components--button (case-insensitive).'),
+        tagName: normalizeOptionalNonEmptyLower('Component tag name from list_components, e.g., mdui-button (case-insensitive).'),
+    };
+    // 输出：文档对象
+    const outputSchema = {
+        key: z.string().describe('Unique document key, e.g., components--button'),
+        title: z.string().describe('Document title'),
+        description: z.string().describe('Short description of the document'),
+        content: z.string().describe('Full markdown content of the document'),
+    };
+    server.registerTool('get_document', {
+        title: 'Get Document',
+        description: 'Get a single mdui documentation page by key or by component tagName (inputs are mutually exclusive). Read-only, offline, deterministic. If both inputs are provided, the tool returns an error. If only tagName is provided, the tool selects the first document that references this tagName. Returns: key, title, description, and full markdown content.',
+        inputSchema,
+        outputSchema,
+    }, async ({ key, tagName }) => {
+        // 互斥与必填校验
+        if (!key && !tagName) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Either key or tagName is required.',
+                    },
+                ],
+            };
+        }
+        if (key && tagName) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Provide either key or tagName, not both (they are mutually exclusive).',
+                    },
+                ],
+            };
+        }
+        // 若未提供 key，则根据 tagName 在 documents 中查找包含该 tag 的页面，确定 key
+        let resolvedKey = key?.trim().toLowerCase();
+        if (!resolvedKey && tagName) {
+            const normalizedTag = tagName.trim().toLowerCase();
+            for (const [docKey, docItem] of Object.entries(documents)) {
+                const tags = docItem.tagNames;
+                if (Array.isArray(tags) &&
+                    tags.map((t) => t.toLowerCase()).includes(normalizedTag)) {
+                    resolvedKey = docKey;
+                    break;
+                }
+            }
+        }
+        const doc = resolvedKey ? documents[resolvedKey] : undefined;
+        if (!doc) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Document not found by ${key ? `key: ${key}` : `tagName: ${tagName}`}. Use list_documents to enumerate keys or verify that the component has an associated document.`,
+                    },
+                ],
+            };
+        }
+        const result = {
+            key: doc.key,
+            title: doc.title,
+            description: doc.description,
+            content: doc.content,
+        };
+        return {
+            structuredContent: result,
+            content: [
+                { type: 'text', text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+}

package/tools/listComponents.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * 列出所有 mdui 组件
+ * @param server
+ */
+export declare function registerListComponents(server: McpServer): void;

package/tools/listComponents.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { components } from '../data/components.js';
+/**
+ * 列出所有 mdui 组件
+ * @param server
+ */
+export function registerListComponents(server) {
+    server.registerTool('list_components', {
+        title: 'List Components',
+        description: 'List all mdui Web Components (custom elements) available in the local mdui index. Read-only, offline, and deterministic. No input required. For each item returns: tagName, description, documentation URL, and a minimal HTML usage snippet. Results are sorted by tagName (ascending). Note: this excludes stand‑alone icon components—use list_icon_components for icons, or list_icon_codes for attribute values.',
+        inputSchema: {},
+        outputSchema: {
+            components: z
+                .array(z.object({
+                tagName: z
+                    .string()
+                    .describe('The tag name of the component, e.g., mdui-button'),
+                description: z
+                    .string()
+                    .describe('A brief description of the component'),
+                docUrl: z
+                    .string()
+                    .url()
+                    .describe('The URL to the component documentation'),
+                usage: z
+                    .string()
+                    .describe('Example HTML usage snippet of the component'),
+            }))
+                .describe('A list of components with their tag names, descriptions, documentation URLs, and usage snippets (sorted by tagName).'),
+        },
+    }, async () => {
+        const list = components
+            .map((component) => ({
+            tagName: component.tagName,
+            description: component.description,
+            docUrl: component.docUrl,
+            usage: component.usage,
+        }))
+            .sort((a, b) => a.tagName.localeCompare(b.tagName));
+        return {
+            structuredContent: { components: list },
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ components: list }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/tools/listCssClasses.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * 列出所有 mdui 全局 CSS class
+ * @param server
+ */
+export declare function registerListCssClasses(server: McpServer): void;

package/tools/listCssClasses.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { cssClasses } from '../data/cssClasses.js';
+/**
+ * 列出所有 mdui 全局 CSS class
+ * @param server
+ */
+export function registerListCssClasses(server) {
+    server.registerTool('list_css_classes', {
+        title: 'List Global CSS Classes',
+        description: 'List all mdui global CSS classes from the local index (read-only, offline). For each class returns: name, description, documentation URL, and an example usage snippet. Results are sorted by name (ascending). Use this to discover utility/semantics classes, not component APIs.',
+        inputSchema: {},
+        outputSchema: {
+            classes: z
+                .array(z.object({
+                name: z
+                    .string()
+                    .describe('The CSS class name, e.g., mdui-theme-dark'),
+                description: z
+                    .string()
+                    .describe('A brief description of the CSS class'),
+                docUrl: z
+                    .string()
+                    .url()
+                    .describe('The URL to the CSS class documentation'),
+                example: z
+                    .string()
+                    .describe('Example usage snippet of the CSS class'),
+            }))
+                .describe('A list of global CSS classes with their names, descriptions, documentation URLs, and example usage snippets (sorted by name).'),
+        },
+    }, async () => {
+        const list = cssClasses.sort((a, b) => a.name.localeCompare(b.name));
+        return {
+            structuredContent: { classes: list },
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ classes: list }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/tools/listCssVariables.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * 列出所有 mdui 全局 CSS 变量（Design Tokens）
+ * @param server
+ */
+export declare function registerListCssVariables(server: McpServer): void;

package/tools/listCssVariables.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { cssVariables } from '../data/cssVariables.js';
+/**
+ * 列出所有 mdui 全局 CSS 变量（Design Tokens）
+ * @param server
+ */
+export function registerListCssVariables(server) {
+    server.registerTool('list_css_variables', {
+        title: 'List Global CSS Variables',
+        description: 'List all mdui global CSS custom properties (design tokens) from the local index. Read-only, offline, and deterministic. For each variable returns: name, description, and documentation URL. No input required. Results are sorted by name (ascending). Use this to theme/override styles at app level; for per-component tokens, see get_component_metadata.cssProperties.',
+        inputSchema: {},
+        outputSchema: {
+            variables: z
+                .array(z.object({
+                name: z
+                    .string()
+                    .describe('The CSS custom property name, e.g., --mdui-color-primary'),
+                description: z
+                    .string()
+                    .describe('A brief description of the CSS variable'),
+                docUrl: z
+                    .string()
+                    .url()
+                    .describe('The URL to the CSS variable documentation'),
+            }))
+                .describe('A list of CSS variables with their names, descriptions, and documentation URLs (sorted by name).'),
+        },
+    }, async () => {
+        const list = cssVariables.sort((a, b) => a.name.localeCompare(b.name));
+        return {
+            structuredContent: { variables: list },
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ variables: list }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/tools/listDocuments.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * 列出所有文档（key、title、description）
+ * @param server
+ */
+export declare function registerListDocuments(server: McpServer): void;

package/tools/listDocuments.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { documents } from '../data/documents.js';
+/**
+ * 列出所有文档（key、title、description）
+ * @param server
+ */
+export function registerListDocuments(server) {
+    server.registerTool('list_documents', {
+        title: 'List Documents',
+        description: 'List all mdui documentation pages from the local index (read-only, offline). For each document returns: key, title, and description. Results are sorted by key (ascending). Use get_document with a key from this list to fetch the full markdown content.',
+        inputSchema: {},
+        outputSchema: {
+            documents: z
+                .array(z.object({
+                key: z
+                    .string()
+                    .describe('Unique document key, e.g., components--button'),
+                title: z.string().describe('Document title'),
+                description: z
+                    .string()
+                    .describe('Short description of the document'),
+            }))
+                .describe('A list of documents with key, title, and description (sorted by key).'),
+        },
+    }, async () => {
+        const list = Object.values(documents)
+            .map((doc) => ({
+            key: doc.key,
+            title: doc.title,
+            description: doc.description,
+        }))
+            .sort((a, b) => a.key.localeCompare(b.key));
+        return {
+            structuredContent: { documents: list },
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ documents: list }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/tools/listIconCodes.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * 列出指定变体的所有图标名称
+ * @param server
+ */
+export declare function registerListIconCodes(server: McpServer): void;

package/tools/listIconCodes.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { icons } from '../data/icons.js';
+/**
+ * 列出指定变体的所有图标名称
+ * @param server
+ */
+export function registerListIconCodes(server) {
+    const variantSchema = z.enum([
+        'filled',
+        'outlined',
+        'rounded',
+        'sharp',
+        'two-tone',
+    ]);
+    const inputSchema = {
+        variant: variantSchema
+            .optional()
+            .describe("Icon variant to list. One of: 'filled' (default), 'outlined', 'rounded', 'sharp', 'two-tone'."),
+        query: z
+            .preprocess((v) => (typeof v === 'string' ? v.trim() : v), z.string().min(1).optional())
+            .describe('Case-insensitive substring to filter by human-readable name or code.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(5000)
+            .optional()
+            .describe('Maximum number of results to return (default: all).'),
+    };
+    const outputSchema = {
+        icons: z
+            .array(z.object({
+            name: z.string().describe('Human-readable icon label'),
+            code: z
+                .string()
+                .describe("Icon name to use in component attributes/APIs (e.g., 'search' or 'search--outlined')."),
+        }))
+            .describe("List of icon codes for the requested variant. Use these codes in attributes such as mdui-button's 'icon' or 'end-icon'."),
+    };
+    const toTitleCase = (s) => s
+        .split(' ')
+        .map((part) => (part ? part[0].toUpperCase() + part.slice(1) : part))
+        .join(' ');
+    server.registerTool('list_icon_codes', {
+        title: 'List Icon Codes',
+        description: "List icon codes (attribute values) for a single variant from the local index. Read-only, offline, deterministic. Use these codes wherever an icon name is required by a component or API, for example: <mdui-button icon=\"search\" end-icon=\"arrow_forward\">.\n\nOutput: array of { name, code }.\n- name: human-readable label.\n- code: value to use in attributes/APIs (e.g., 'search' or 'search--outlined').\n\nDiffers from list_icon_components: this returns attribute codes, not custom element tags/imports.\n\nInput: optional 'variant' — one of 'filled' (default), 'outlined', 'rounded', 'sharp', 'two-tone'; also supports optional 'query' — case-insensitive substring filter applied to the human-readable name or the code; and 'limit' — maximum number of results to return (1–5000, default: all).",
+        inputSchema,
+        outputSchema,
+    }, async ({ variant, query, limit, }) => {
+        const v = variant ?? 'filled';
+        const q = query?.toLowerCase();
+        let list = icons.map((n) => {
+            const display = toTitleCase(n.replace(/_/g, ' '));
+            const code = v === 'filled' ? n : `${n}--${v}`;
+            return { name: display, code };
+        });
+        if (q) {
+            list = list.filter((it) => it.name.toLowerCase().includes(q) ||
+                it.code.toLowerCase().includes(q));
+        }
+        if (typeof limit === 'number') {
+            list = list.slice(0, limit);
+        }
+        const result = { icons: list };
+        return {
+            structuredContent: result,
+            content: [
+                { type: 'text', text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+}

package/tools/listIconComponents.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * 列出指定变体的所有图标组件信息
+ * 返回 { name, tagName, import } 数组
+ * @param server
+ */
+export declare function registerListIconComponents(server: McpServer): void;