@mijadesign/nut-mcp 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,147 @@
+# Mija Design MCP
+
+专为 `@mijadesign/mjui-react-taro` 定制的 MCP Server，用于让 AI 编码工具按组件库文档生成代码。
+
+它会读取组件索引、组件 Markdown 文档和中文别名配置，提供组件列表、组件搜索、组件 API 与示例查询能力。
+
+## 工具列表
+
+| 工具                | 作用                                     | 使用建议                                   |
+| ------------------- | ---------------------------------------- | ------------------------------------------ |
+| `list_components`   | 列出全部组件，并按分组归类               | 不确定组件名时先调用                       |
+| `search_components` | 按关键词、中文别名、组件名、描述搜索组件 | 找到候选组件后继续调用 `get_component_doc` |
+| `get_component_doc` | 获取指定组件的 props、示例、版本和说明   | 生成代码前必须调用，避免使用不存在的 prop  |
+
+## 数据来源
+
+运行时依赖以下文档数据：
+
+- `docs/docs/components-index.json`
+- `docs/docs/aliases.json`
+- `docs/docs/components/**/index.md`
+
+运行时优先读取当前包内的 `docs/docs`。未生成包内文档时，本地开发会回退读取仓库根目录的 `docs/docs`。发布前会通过 `prepare:docs` 复制一份到当前包内，发布后的 npm 包会读取包内文档。
+
+## 本地开发
+
+```bash
+cd packages/mcp-mjui
+npm install
+npm run dev
+```
+
+本地 MCP 客户端配置示例：
+
+```json
+{
+  "mcpServers": {
+    "mija-design": {
+      "command": "npx",
+      "args": [
+        "tsx",
+        "/Users/moon/Desktop/work/frontend-mobile-core/packages/mcp-mjui/src/index.ts"
+      ]
+    }
+  }
+}
+```
+
+也可以先构建后用 Node 启动：
+
+```bash
+cd packages/mcp-mjui
+npm run prepare:docs
+npm run build
+npm run start
+```
+
+对应配置：
+
+```json
+{
+  "mcpServers": {
+    "mija-design": {
+      "command": "node",
+      "args": [
+        "/Users/moon/Desktop/work/frontend-mobile-core/packages/mcp-mjui/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+## 发布
+
+发布前确认包内文档和构建产物都已生成：
+
+```bash
+cd packages/mcp-mjui
+npm run prepack
+npm pack --dry-run
+```
+
+确认 `npm pack --dry-run` 输出中包含：
+
+- `dist/index.js`
+- `dist/services/**`
+- `docs/docs/components-index.json`
+- `docs/docs/aliases.json`
+- `docs/docs/components/**/index.md`
+
+发布：
+
+```bash
+npm publish --access public
+```
+
+## 发布后如何使用
+
+发布后，在支持 MCP 的 IDE 或 AI 编码工具中添加 stdio server 配置：
+
+```json
+{
+  "mcpServers": {
+    "mija-design": {
+      "command": "npx",
+      "args": ["-y", "@mijadesign/nut-mcp"]
+    }
+  }
+}
+```
+
+如果已经全局安装：
+
+```bash
+npm install -g @mijadesign/nut-mcp
+```
+
+可配置为：
+
+```json
+{
+  "mcpServers": {
+    "mija-design": {
+      "command": "mija-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+客户端连接成功后，AI 工具应按这个顺序使用：
+
+1. 不确定组件时，调用 `search_components` 或 `list_components`。
+2. 确认组件后，调用 `get_component_doc` 获取 props 与 demos。
+3. 生成代码时只使用文档返回的 prop 和示例结构。
+
+示例提问：
+
+```text
+使用 Mija Design 的按钮和弹窗组件实现确认删除流程。生成代码前先查询组件文档。
+```
+
+## 维护说明
+
+- 新增组件后，需要同步更新 `docs/docs/components-index.json`。
+- 新增中文叫法或业务别名后，更新 `docs/docs/aliases.json`。
+- 组件文档中的 Props 表格和示例代码会被 MCP 解析，修改 Markdown 结构时要确认 `get_component_doc` 返回正常。

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListComponentsTool, GetComponentDocTool, SearchComponentsTool, } from "./tools/index.js";
+async function main() {
+    const server = new McpServer({
+        name: "mija-design-mcp",
+        version: "1.0.0",
+    });
+    // 所有 MCP 能力统一在这里注册，便于客户端从同一个 stdio 服务发现完整组件工作流。
+    new ListComponentsTool().register(server);
+    new GetComponentDocTool().register(server);
+    new SearchComponentsTool().register(server);
+    await server.connect(new StdioServerTransport());
+}
+main().catch(console.error);

package/dist/services/aliases.service.d.ts

@@ -0,0 +1 @@
+export declare function loadAliases(): Promise<Record<string, string>>;

package/dist/services/aliases.service.js

@@ -0,0 +1,19 @@
+import fs from "fs/promises";
+import * as path from "path";
+import { resolveDocsDir } from "./paths.service.js";
+const ALIASES_FILE = path.join(resolveDocsDir(), "aliases.json");
+let aliasesCache = null;
+export async function loadAliases() {
+    if (aliasesCache !== null)
+        return aliasesCache;
+    try {
+        const content = await fs.readFile(ALIASES_FILE, "utf-8");
+        const config = JSON.parse(content);
+        aliasesCache = config.aliases ?? {};
+    }
+    catch (error) {
+        console.error("加载别名配置文件失败，将使用空别名表:", error);
+        aliasesCache = {};
+    }
+    return aliasesCache;
+}

package/dist/services/doc-parser.service.d.ts

@@ -0,0 +1,3 @@
+import { ComponentDoc, ComponentSummary } from "../types/index.js";
+export declare function buildDocPathMap(): Promise<void>;
+export declare function loadDoc(summary: ComponentSummary): Promise<ComponentDoc>;

package/dist/services/doc-parser.service.js

@@ -0,0 +1,162 @@
+import fs from "fs/promises";
+import * as path from "path";
+import yaml from "js-yaml";
+import { resolveDocsDir } from "./paths.service.js";
+const DOCS_DIR = path.join(resolveDocsDir(), "components");
+const docCache = new Map();
+const docPathMap = new Map();
+export async function buildDocPathMap() {
+    if (docPathMap.size > 0)
+        return;
+    async function scan(dir) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const full = path.join(dir, entry.name);
+            const mdPath = path.join(full, "index.md");
+            try {
+                await fs.access(mdPath);
+                docPathMap.set(entry.name.toLowerCase(), mdPath);
+            }
+            catch { }
+            await scan(full);
+        }
+    }
+    await scan(DOCS_DIR);
+}
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return { frontmatter: {}, body: content };
+    try {
+        const frontmatter = yaml.load(match[1]);
+        return { frontmatter, body: content.slice(match[0].length) };
+    }
+    catch {
+        return { frontmatter: {}, body: content };
+    }
+}
+function extractVersion(body, frontmatter) {
+    const m = body.match(/<Badge[^>]*>([^<]+)<\/Badge>/);
+    return m ? m[1] : (frontmatter.version ?? "");
+}
+function extractProps(body) {
+    const props = [];
+    const lines = body.split("\n");
+    let inTable = false;
+    const headerNames = new Set([
+        "参数",
+        "name",
+        "属性",
+        "prop",
+        "property",
+        "名称",
+        "方法名",
+    ]);
+    for (const line of lines) {
+        if (/^###\s*(Props|API|属性)/i.test(line)) {
+            inTable = true;
+            continue;
+        }
+        if (inTable && /^#{2,3}\s/.test(line) && !/Props|API|属性/i.test(line)) {
+            inTable = false;
+            continue;
+        }
+        if (inTable && line.startsWith("|") && !line.includes("---")) {
+            // API 表格里可能会转义联合类型分隔符，例如 `left\|right`。
+            // 拆分表格列前先保护这些已转义的竖线。
+            const ESCAPED_PIPE = "\x00";
+            const cols = line
+                .replace(/\\\|/g, ESCAPED_PIPE)
+                .split("|")
+                .map((c) => c.trim().replace(/\x00/g, "|"))
+                .filter(Boolean);
+            if (cols.length >= 3 && !headerNames.has(cols[0].toLowerCase())) {
+                props.push({
+                    name: cols[0],
+                    description: cols[1],
+                    type: cols[2],
+                    default: cols[3] ?? "-",
+                });
+            }
+        }
+    }
+    return props;
+}
+function extractDemos(body) {
+    const demos = [];
+    const lines = body.split("\n");
+    let title = "";
+    let code = [];
+    let inBlock = false;
+    let inDemoSection = false;
+    for (const line of lines) {
+        if (/^##\s+(示例代码|代码演示|代码示例|Examples?|Demos?)/i.test(line)) {
+            inDemoSection = true;
+            continue;
+        }
+        if (inDemoSection && !inBlock && /^##[^#]/.test(line)) {
+            break;
+        }
+        if (!inDemoSection)
+            continue;
+        if (/^```/.test(line)) {
+            if (inBlock) {
+                // 示例区里的每个代码块都会作为一个可直接提供给模型的示例。
+                if (code.length)
+                    demos.push({ title: title || "示例", code: code.join("\n") });
+                code = [];
+                inBlock = false;
+            }
+            else {
+                inBlock = true;
+            }
+            continue;
+        }
+        if (inBlock) {
+            code.push(line);
+        }
+        else {
+            const m = line.match(/^###\s+(.+)/);
+            if (m)
+                title = m[1].trim();
+        }
+    }
+    return demos;
+}
+export async function loadDoc(summary) {
+    const key = summary.dirName.toLowerCase();
+    if (docCache.has(key))
+        return docCache.get(key);
+    const mdPath = docPathMap.get(key) ?? path.join(DOCS_DIR, summary.dirName, "index.md");
+    let content = "";
+    try {
+        content = await fs.readFile(mdPath, "utf-8");
+    }
+    catch {
+        const fallback = {
+            ...summary,
+            version: "",
+            props: [],
+            demos: [],
+        };
+        docCache.set(key, fallback);
+        return fallback;
+    }
+    const { frontmatter, body } = parseFrontmatter(content);
+    const doc = {
+        ...summary,
+        version: extractVersion(body, frontmatter),
+        props: extractProps(body),
+        demos: extractDemos(body),
+    };
+    docCache.set(key, doc);
+    return doc;
+}

package/dist/services/index.services.d.ts

@@ -0,0 +1,3 @@
+import { RuntimeIndex, ComponentSummary } from "../types/index.js";
+export declare function getIndex(): Promise<RuntimeIndex>;
+export declare function findSummary(query: string, idx: RuntimeIndex): ComponentSummary | undefined;

package/dist/services/index.services.js

@@ -0,0 +1,71 @@
+import fs from "fs/promises";
+import * as path from "path";
+import { loadAliases } from "./aliases.service.js";
+import { buildDocPathMap } from "./doc-parser.service.js";
+import { resolveDocsDir } from "./paths.service.js";
+const INDEX_FILE = path.join(resolveDocsDir(), "components-index.json");
+let runtimeIndex = null;
+function tokenize(text) {
+    const tokens = new Set();
+    const lower = text.toLowerCase();
+    // 英文组件名和中文描述需要不同的分词粒度。
+    for (const word of lower.match(/[a-z]+/g) ?? []) {
+        if (word.length > 1)
+            tokens.add(word);
+    }
+    for (const char of lower.match(/[\u4e00-\u9fa5]/g) ?? []) {
+        tokens.add(char);
+    }
+    return [...tokens];
+}
+function buildRuntimeIndex(summaries, aliases) {
+    const byDirName = new Map();
+    const byEnName = new Map();
+    const invertedIndex = new Map();
+    const aliasMap = new Map();
+    for (const [alias, dirName] of Object.entries(aliases)) {
+        aliasMap.set(alias, dirName.toLowerCase());
+    }
+    for (const s of summaries) {
+        const dirKey = s.dirName.toLowerCase();
+        byDirName.set(dirKey, s);
+        const enName = s.name.split(/\s+/)[0].toLowerCase();
+        byEnName.set(enName, s);
+        const fields = [s.name, s.description, s.whenToUse, s.group ?? ""].join(" ");
+        // 倒排索引只保存 dirName，搜索结果再回到规范的组件摘要表取详情。
+        for (const token of tokenize(fields)) {
+            if (!invertedIndex.has(token))
+                invertedIndex.set(token, []);
+            const list = invertedIndex.get(token);
+            if (!list.includes(s.dirName))
+                list.push(s.dirName);
+        }
+    }
+    return {
+        summaries,
+        byDirName,
+        byEnName,
+        invertedIndex,
+        aliasMap,
+        buildTime: Date.now(),
+    };
+}
+export async function getIndex() {
+    if (runtimeIndex)
+        return runtimeIndex;
+    const [raw, aliases] = await Promise.all([
+        fs.readFile(INDEX_FILE, "utf-8"),
+        loadAliases(),
+        buildDocPathMap(),
+    ]);
+    const summaries = JSON.parse(raw);
+    runtimeIndex = buildRuntimeIndex(summaries, aliases);
+    return runtimeIndex;
+}
+export function findSummary(query, idx) {
+    const q = query.toLowerCase().trim();
+    return (idx.byDirName.get(q) ??
+        idx.byEnName.get(q) ??
+        idx.byDirName.get(idx.aliasMap.get(query) ?? "") ??
+        idx.summaries.find((s) => s.name.toLowerCase().includes(q)));
+}

package/dist/services/paths.service.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 同时兼容发布包和 monorepo 本地开发两种文档读取方式。
+ * 发布包读取 packages/mcp-mjui/docs/docs，本地 tsx 开发可回退到仓库根目录的 docs/docs。
+ */
+export declare function resolveDocsDir(): string;

package/dist/services/paths.service.js

@@ -0,0 +1,18 @@
+import fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// 构建后从 dist/services 回到包根目录；本地开发时从 src/services 回到包根目录。
+const packageRoot = path.resolve(__dirname, "../..");
+const packagedDocsDir = path.join(packageRoot, "docs/docs");
+const workspaceDocsDir = path.resolve(packageRoot, "../../docs/docs");
+/**
+ * 同时兼容发布包和 monorepo 本地开发两种文档读取方式。
+ * 发布包读取 packages/mcp-mjui/docs/docs，本地 tsx 开发可回退到仓库根目录的 docs/docs。
+ */
+export function resolveDocsDir() {
+    if (fs.existsSync(packagedDocsDir))
+        return packagedDocsDir;
+    return workspaceDocsDir;
+}

package/dist/tools/base.tool.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare abstract class BaseTool {
+    abstract name: string;
+    abstract description: string;
+    abstract inputSchema: any;
+    abstract execute(args: any): Promise<any>;
+    register(server: McpServer): void;
+}

package/dist/tools/base.tool.js

@@ -0,0 +1,27 @@
+export class BaseTool {
+    register(server) {
+        server.registerTool(this.name, {
+            description: this.description,
+            inputSchema: this.inputSchema,
+        }, async (args) => {
+            try {
+                const result = await this.execute(args);
+                // MCP stdio 响应必须是 content blocks；工具实现只需要产出纯文本或 JSON 字符串。
+                return {
+                    content: [{ type: "text", text: result }],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: error instanceof Error ? error.message : String(error),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+}

package/dist/tools/get-component-doc.tool.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { BaseTool } from "./base.tool.js";
+export declare class GetComponentDocTool extends BaseTool {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>;
+    execute(args: {
+        name: string;
+    }): Promise<string>;
+}

package/dist/tools/get-component-doc.tool.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { BaseTool } from "./base.tool.js";
+import { getIndex, findSummary } from "../services/index.services.js";
+import { loadDoc } from "../services/doc-parser.service.js";
+export class GetComponentDocTool extends BaseTool {
+    name = "get_component_doc";
+    description = `获取指定组件的完整文档（props、示例代码）。
+
+【生成代码前必须完成】
+1. 确认已拿到 props 列表，不得使用文档外的 prop
+2. 参考 demos 中的示例代码结构
+3. 样式优先用组件 props 控制（type/size/disabled 等），其次用 CSS 变量，禁止 div+CSS 手写模拟
+4. padding/margin/font-size/color 等数值必须还原设计稿，不得使用默认猜测值
+5. 布局使用组件库 View/Flex，间距使用 spacing 系统，不硬编码`;
+    inputSchema = z.object({
+        name: z
+            .string()
+            .describe("组件名，支持英文（Button/button）、中文（按钮）、dirName（button）"),
+    });
+    async execute(args) {
+        const { name: query } = args;
+        const idx = await getIndex();
+        const summary = findSummary(query, idx);
+        if (!summary) {
+            throw new Error(`未找到组件"${query}"，请先调用 search_components 确认组件名。`);
+        }
+        const doc = await loadDoc(summary);
+        return JSON.stringify({
+            componentName: doc.name,
+            dirName: doc.dirName,
+            group: doc.group,
+            version: doc.version,
+            description: doc.description,
+            whenToUse: doc.whenToUse,
+            importFrom: "@mijadesign/mjui-react-taro",
+            props: doc.props,
+            demos: doc.demos,
+        }, null, 2);
+    }
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { BaseTool } from "./base.tool.js";
+export { ListComponentsTool } from "./list-components.tool.js";
+export { GetComponentDocTool } from "./get-component-doc.tool.js";
+export { SearchComponentsTool } from "./search-components.tool.js";

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+export { BaseTool } from "./base.tool.js";
+export { ListComponentsTool } from "./list-components.tool.js";
+export { GetComponentDocTool } from "./get-component-doc.tool.js";
+export { SearchComponentsTool } from "./search-components.tool.js";

package/dist/tools/list-components.tool.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { BaseTool } from "./base.tool.js";
+export declare class ListComponentsTool extends BaseTool {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{}, z.core.$strip>;
+    execute(_args: Record<string, unknown>): Promise<string>;
+}

package/dist/tools/list-components.tool.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { BaseTool } from "./base.tool.js";
+import { getIndex } from "../services/index.services.js";
+export class ListComponentsTool extends BaseTool {
+    name = "list_components";
+    description = "列出 Mija Design 所有组件，按分组归类输出。" +
+        "调用后若需生成代码，必须再调用 get_component_doc 获取完整 props 和示例，不得凭印象生成。";
+    inputSchema = z.object({});
+    async execute(_args) {
+        const idx = await getIndex();
+        const groups = new Map();
+        for (const s of idx.summaries) {
+            const g = s.group ?? "其他";
+            if (!groups.has(g))
+                groups.set(g, []);
+            groups.get(g).push(s);
+        }
+        const lines = [
+            "# Mija Design 组件索引",
+            "> 找到目标组件后，调用 get_component_doc 获取 props 和示例，再生成代码。",
+            "",
+        ];
+        for (const [group, items] of groups) {
+            lines.push(`## ${group}`);
+            for (const s of items) {
+                lines.push(`- **${s.name}**（${s.dirName}）：${s.description}`);
+            }
+            lines.push("");
+        }
+        return lines.join("\n");
+    }
+}

package/dist/tools/search-components.tool.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { BaseTool } from "./base.tool.js";
+export declare class SearchComponentsTool extends BaseTool {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        query: z.ZodString;
+    }, z.core.$strip>;
+    execute(args: {
+        query: string;
+    }): Promise<string>;
+}