@douyinfe/semi-mcp 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,203 @@
+# Semi MCP Server
+
+基于 Model Context Protocol (MCP) SDK 实现的 MCP 服务器，提供 Semi Design 组件文档和组件列表查询功能。
+
+## 简介
+
+Semi MCP Server 是一个 MCP (Model Context Protocol) 服务器，通过 stdio 传输层与支持 MCP 协议的客户端通信。它提供了获取 Semi Design 组件文档、组件列表等功能。
+
+## 安装
+
+### 全局安装
+
+```bash
+npm install -g @douyinfe/semi-mcp
+```
+
+### 本地安装
+
+```bash
+npm install @douyinfe/semi-mcp
+```
+
+## 使用方法
+
+### 作为命令行工具
+
+全局安装后，可以直接使用：
+
+```bash
+semi-mcp
+```
+
+### 在 MCP 客户端中配置
+
+在支持 MCP 的客户端（如 Claude Desktop）中配置：
+
+```json
+{
+  "mcpServers": {
+    "semi-mcp": {
+      "command": "npx",
+      "args": ["-y", "@douyinfe/semi-mcp"]
+    }
+  }
+}
+```
+
+或者如果已全局安装：
+
+```json
+{
+  "mcpServers": {
+    "semi-mcp": {
+      "command": "semi-mcp"
+    }
+  }
+}
+```
+
+## 功能
+
+### 工具 (Tools)
+
+#### `get_semi_document`
+
+获取 Semi Design 组件文档或组件列表。
+
+**参数：**
+- `componentName` (可选): 组件名称，例如 `Button`、`Input` 等。如果不提供，则返回组件列表
+- `version` (可选): 版本号，例如 `2.89.2-alpha.3`。如果不提供，默认使用 `latest`
+
+**示例：**
+
+获取组件列表：
+```json
+{
+  "name": "get_semi_document"
+}
+```
+
+获取指定组件文档：
+```json
+{
+  "name": "get_semi_document",
+  "arguments": {
+    "componentName": "Button",
+    "version": "2.89.2-alpha.3"
+  }
+}
+```
+
+**返回格式：**
+
+获取组件列表时：
+```json
+{
+  "version": "2.89.2-alpha.3",
+  "components": ["button", "input", "select", ...],
+  "count": 70
+}
+```
+
+获取组件文档时：
+```json
+{
+  "componentName": "button",
+  "version": "2.89.2-alpha.3",
+  "category": "basic",
+  "documents": ["index.md", "index-en-us.md"],
+  "count": 2,
+  "allComponents": ["button", "input", "select", ...],
+  "allComponentsCount": 70
+}
+```
+
+### 资源 (Resources)
+
+#### `semi://components`
+
+Semi Design 组件列表资源。
+
+## 开发
+
+### 环境要求
+
+- Node.js >= 18.0.0
+- npm 或 yarn
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 构建
+
+构建生产版本：
+
+```bash
+npm run build
+```
+
+开发模式（监听文件变化并自动重建）：
+
+```bash
+npm run dev
+```
+
+### 测试
+
+运行测试：
+
+```bash
+npm test
+```
+
+### 运行
+
+构建完成后运行服务器：
+
+```bash
+npm start
+```
+
+或者直接运行构建后的文件：
+
+```bash
+node dist/index.js
+```
+
+## 技术栈
+
+- **TypeScript**: 类型安全的 JavaScript
+- **Rslib**: 快速构建工具
+- **@modelcontextprotocol/sdk**: MCP 官方 SDK
+
+## 项目结构
+
+```
+semi-mcp/
+├── src/
+│   ├── index.ts              # 主入口文件
+│   ├── tools/                # 工具定义
+│   │   ├── index.ts
+│   │   └── get-semi-document.ts
+│   └── utils/                # 工具函数
+│       ├── fetch-directory-list.ts
+│       └── fetch-file-content.ts
+├── tests/                    # 测试文件
+│   └── get-semi-document.test.ts
+├── dist/                     # 构建输出
+├── package.json
+└── README.md
+```
+
+## 许可证
+
+MIT
+
+## 相关链接
+
+- [Semi Design 官网](https://semi.design)
+- [Model Context Protocol 文档](https://modelcontextprotocol.io)

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+const UNPKG_BASE_URL = 'https://unpkg.com';
+const NPMMIRROR_BASE_URL = 'https://npmmirror.com';
+async function fetchFromSource(baseUrl, packageName, version, path) {
+    const url = `${baseUrl}/${packageName}@${version}/${path}/?meta`;
+    const response = await fetch(url, {
+        headers: {
+            Accept: 'application/json'
+        }
+    });
+    if (!response.ok) throw new Error(`获取目录列表失败: ${response.status} ${response.statusText}`);
+    const contentType = response.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) throw new Error(`API 返回了非 JSON 格式: ${contentType}`);
+    const data = await response.json();
+    const normalizeType = (item)=>{
+        const path = item.path;
+        if (path.endsWith('/')) return {
+            path,
+            type: 'directory'
+        };
+        if (item.type && item.type.includes('/')) return {
+            path,
+            type: 'file'
+        };
+        if ('directory' === item.type) return {
+            path,
+            type: 'directory'
+        };
+        return {
+            path,
+            type: 'file'
+        };
+    };
+    if (Array.isArray(data)) return data.map(normalizeType);
+    if (data && 'object' == typeof data && 'files' in data && Array.isArray(data.files)) return data.files.map(normalizeType);
+    if (data && 'object' == typeof data && 'path' in data) return [
+        normalizeType(data)
+    ];
+    throw new Error('无法解析目录列表数据格式');
+}
+async function fetchDirectoryList(packageName, version, path) {
+    const unpkgPromise = fetchFromSource(UNPKG_BASE_URL, packageName, version, path);
+    const npmmirrorPromise = fetchFromSource(NPMMIRROR_BASE_URL, packageName, version, path);
+    const unpkgWithFallback = unpkgPromise.catch(()=>new Promise(()=>{}));
+    const npmmirrorWithFallback = npmmirrorPromise.catch(()=>new Promise(()=>{}));
+    const raceResult = await Promise.race([
+        unpkgWithFallback,
+        npmmirrorWithFallback
+    ]).catch(()=>null);
+    if (raceResult) return raceResult;
+    const results = await Promise.allSettled([
+        unpkgPromise,
+        npmmirrorPromise
+    ]);
+    const errors = [];
+    for (const result of results)if ('rejected' === result.status) errors.push(result.reason instanceof Error ? result.reason : new Error(String(result.reason)));
+    throw new Error(`所有数据源都失败了: ${errors.map((e)=>e.message).join('; ')}`);
+}
+const getSemiDocumentTool = {
+    name: 'get_semi_document',
+    description: '获取 Semi Design 组件文档或组件列表',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            componentName: {
+                type: 'string',
+                description: '组件名称，例如 Button、Input 等。如果不提供，则返回组件列表'
+            },
+            version: {
+                type: 'string',
+                description: '版本号，例如 2.89.1。如果不提供，默认使用 latest'
+            }
+        },
+        required: []
+    }
+};
+async function getComponentList(version) {
+    const packageName = '@douyinfe/semi-ui';
+    const files = await fetchDirectoryList(packageName, version, 'lib');
+    if (!files || 0 === files.length) return [];
+    const components = files.filter((file)=>'directory' === file.type).map((file)=>{
+        const parts = file.path.split('/');
+        const componentName = parts[parts.length - 1] || parts[0];
+        return componentName.toLowerCase();
+    }).filter((name)=>name && 'lib' !== name);
+    return Array.from(new Set(components)).sort();
+}
+async function getComponentDocuments(componentName, version) {
+    const packageName = '@douyinfe/semi-ui';
+    const componentNameLower = componentName.toLowerCase();
+    const contentDirs = await fetchDirectoryList(packageName, version, 'content');
+    if (!contentDirs || 0 === contentDirs.length) return null;
+    const categories = contentDirs.filter((file)=>'directory' === file.type).map((file)=>{
+        const parts = file.path.split('/');
+        return parts[parts.length - 1] || parts[0];
+    }).filter((name)=>name && 'content' !== name);
+    for (const category of categories)try {
+        const categoryFiles = await fetchDirectoryList(packageName, version, `content/${category}`);
+        const componentDir = categoryFiles.find((file)=>'directory' === file.type && file.path.toLowerCase().endsWith(`/${componentNameLower}`));
+        if (componentDir) {
+            const componentFiles = await fetchDirectoryList(packageName, version, `content/${category}/${componentNameLower}`);
+            if (componentFiles && componentFiles.length > 0) {
+                const documents = componentFiles.filter((file)=>'file' === file.type).map((file)=>{
+                    const parts = file.path.split('/');
+                    return parts[parts.length - 1].toLowerCase();
+                }).filter((name)=>name);
+                return {
+                    category,
+                    documents: Array.from(new Set(documents)).sort()
+                };
+            }
+        }
+    } catch (error) {
+        continue;
+    }
+    return null;
+}
+async function handleGetSemiDocument(args) {
+    const componentName = args?.componentName;
+    const version = args?.version || 'latest';
+    try {
+        if (componentName) {
+            const result = await getComponentDocuments(componentName, version);
+            const allComponents = await getComponentList(version);
+            if (!result) return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            componentName: componentName.toLowerCase(),
+                            version,
+                            error: '未找到组件文档',
+                            documents: [],
+                            count: 0,
+                            allComponents,
+                            allComponentsCount: allComponents.length
+                        }, null, 2)
+                    }
+                ]
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            componentName: componentName.toLowerCase(),
+                            version,
+                            category: result.category,
+                            documents: result.documents,
+                            count: result.documents.length,
+                            allComponents,
+                            allComponentsCount: allComponents.length
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+        {
+            const components = await getComponentList(version);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            version,
+                            components,
+                            count: components.length
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: errorMessage,
+                        componentName: componentName?.toLowerCase(),
+                        version
+                    }, null, 2)
+                }
+            ],
+            isError: true
+        };
+    }
+}
+const tools = [
+    getSemiDocumentTool
+];
+const toolHandlers = {
+    [getSemiDocumentTool.name]: handleGetSemiDocument
+};
+async function main() {
+    const server = new Server({
+        name: 'semi-mcp',
+        version: '0.0.0'
+    }, {
+        capabilities: {
+            tools: {},
+            resources: {}
+        }
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async ()=>({
+            tools: tools
+        }));
+    server.setRequestHandler(CallToolRequestSchema, async (request)=>{
+        const { name, arguments: args } = request.params;
+        const handler = toolHandlers[name];
+        if (!handler) throw new Error(`未知的工具: ${name}`);
+        return handler(args || {});
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async ()=>({
+            resources: [
+                {
+                    uri: 'semi://components',
+                    name: 'Semi Components',
+                    description: 'Semi Design 组件列表',
+                    mimeType: 'application/json'
+                }
+            ]
+        }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request)=>{
+        const { uri } = request.params;
+        if ('semi://components' === uri) return {
+            contents: [
+                {
+                    uri,
+                    mimeType: 'application/json',
+                    text: JSON.stringify({
+                        components: [
+                            'Button',
+                            'Input',
+                            'Select',
+                            'Table',
+                            'Form'
+                        ],
+                        description: 'Semi Design 组件列表'
+                    }, null, 2)
+                }
+            ]
+        };
+        throw new Error(`未知的资源 URI: ${uri}`);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Semi MCP Server 已启动，使用 stdio 传输');
+}
+main().catch((error)=>{
+    console.error('服务器启动失败:', error);
+    process.exit(1);
+});

package/dist/tools/get-semi-document.d.ts

@@ -0,0 +1,10 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * 工具定义：获取 Semi Design 组件文档
+ */
+export declare const getSemiDocumentTool: Tool;
+/**
+ * 工具处理器：处理 get_semi_document 工具调用
+ */
+export declare function handleGetSemiDocument(args: Record<string, unknown>): Promise<CallToolResult>;

package/dist/tools/index.d.ts

@@ -0,0 +1,9 @@
+import { Tool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * 所有工具的定义
+ */
+export declare const tools: Tool[];
+/**
+ * 工具名称到处理器的映射
+ */
+export declare const toolHandlers: Record<string, (args: Record<string, unknown>) => Promise<CallToolResult>>;

package/dist/utils/fetch-directory-list.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 从 unpkg 或 npmmirror 获取目录列表
+ * 同时向两个数据源发送请求，使用第一个成功返回的结果
+ */
+/**
+ * 从 unpkg 或 npmmirror 获取目录列表
+ * 同时向两个数据源发送请求，使用第一个成功返回的结果
+ */
+export declare function fetchDirectoryList(packageName: string, version: string, path: string): Promise<Array<{
+    path: string;
+    type: string;
+}>>;

package/dist/utils/fetch-file-content.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 从 unpkg 或 npmmirror 获取具体文件内容
+ * 同时向两个数据源发送请求，使用第一个成功返回的结果
+ */
+/**
+ * 从 unpkg 或 npmmirror 获取具体文件内容
+ * 同时向两个数据源发送请求，使用第一个成功返回的结果
+ */
+export declare function fetchFileContent(packageName: string, version: string, filePath: string): Promise<string>;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@douyinfe/semi-mcp",
+  "version": "1.0.0-alpha.0",
+  "description": "Semi Design MCP Server - Model Context Protocol server for Semi Design components and documentation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "semi-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "semi",
+    "semi-design",
+    "mcp",
+    "model-context-protocol",
+    "design-system",
+    "component-library",
+    "documentation"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "test": "rstest",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@rslib/core": "^0.18.5",
+    "@rstest/core": "^0.7.2",
+    "@types/node": "^24.10.4",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3"
+  }
+}