@douyinfe/semi-mcp 1.0.2 → 1.0.4

package/README.md

@@ -1,38 +1,40 @@
+[中文](README-zh_CN.md) | [English](README.md)
+
 # Semi MCP Server
 
-基于 Model Context Protocol (MCP) SDK 实现的 MCP 服务器，提供 Semi Design 组件文档和组件列表查询功能。
+An MCP (Model Context Protocol) server implementation based on the MCP SDK, providing Semi Design component documentation and component list query functionality.
 
-## 简介
+## Introduction
 
-Semi MCP Server 是一个 MCP (Model Context Protocol) 服务器，通过 stdio 传输层与支持 MCP 协议的客户端通信。它提供了获取 Semi Design 组件文档、组件列表等功能。
+Semi MCP Server is an MCP (Model Context Protocol) server that communicates with MCP-compatible clients through stdio transport. It provides functionality to fetch Semi Design component documentation, component lists, and more.
 
-## 安装
+## Installation
 
-### 全局安装
+### Global Installation
 
 ```bash
 npm install -g @douyinfe/semi-mcp
 ```
 
-### 本地安装
+### Local Installation
 
 ```bash
 npm install @douyinfe/semi-mcp
 ```
 
-## 使用方法
+## Usage
 
-### 作为命令行工具
+### As a Command Line Tool
 
-全局安装后，可以直接使用：
+After global installation, you can use it directly:
 
 ```bash
 semi-mcp
 ```
 
-### 在 MCP 客户端中配置
+### Configuration in MCP Clients
 
-在支持 MCP 的客户端（如 Claude Desktop）中配置：
+Configure in MCP-compatible clients (such as Claude Desktop):
 
 ```json
 {
@@ -45,7 +47,7 @@ semi-mcp
 }
 ```
 
-或者如果已全局安装：
+Or if installed globally:
 
 ```json
 {
@@ -57,28 +59,29 @@ semi-mcp
 }
 ```
 
-## 功能
+## Features
 
-### 工具 (Tools)
+### Tools
 
 #### `get_semi_document`
 
-获取 Semi Design 组件文档或组件列表。
+Get Semi Design component documentation or component list.
 
-**参数：**
-- `componentName` (可选): 组件名称，例如 `Button`、`Input` 等。如果不提供，则返回组件列表
-- `version` (可选): 版本号，例如 `2.89.2-alpha.3`。如果不提供，默认使用 `latest`
+**Parameters:**
+- `componentName` (optional): Component name, e.g., `Button`, `Input`, etc. If not provided, returns the component list
+- `version` (optional): Version number, e.g., `2.89.2-alpha.3`. If not provided, defaults to `latest`
+- `get_path` (optional): If `true`, saves documents to the system temporary directory and returns the path instead of returning document content in the response. Defaults to `false`
 
-**示例：**
+**Examples:**
 
-获取组件列表：
+Get component list:
 ```json
 {
   "name": "get_semi_document"
 }
 ```
 
-获取指定组件文档：
+Get specific component documentation:
 ```json
 {
   "name": "get_semi_document",
@@ -89,115 +92,137 @@ semi-mcp
 }
 ```
 
-**返回格式：**
+**Response Format:**
 
-获取组件列表时：
-```json
-{
-  "version": "2.89.2-alpha.3",
-  "components": ["button", "input", "select", ...],
-  "count": 70
-}
+All responses are returned as plain text for AI-friendly consumption.
+
+When getting component list:
 ```
+Semi Design 组件列表 (版本 2.89.2-alpha.3)，共 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
-}
+button, input, select, table, ...
+```
+
+When getting small component documentation (< 888 lines):
+```
+===== index.md =====
+
+---
+title: Button
+...
+---
+
+## Usage
+...
+
+===== index-en-US.md =====
+
+---
+title: Button
+...
+---
+
+## Usage
+...
+```
+
+When getting large component documentation (> 888 lines), the tool automatically saves to temp directory:
+```
+组件 Table (版本 2.89.2-alpha.3) 文档较大，已保存到临时目录。
+
+文档文件列表：
+  - /tmp/semi-docs-table-2.89.2-alpha.3-1234567890/index.md (6,055 行)
+  - /tmp/semi-docs-table-2.89.2-alpha.3-1234567890/index-en-US.md (5,660 行)
+
+请使用文件读取工具查看文档内容。
 ```
 
-### 资源 (Resources)
+### Resources
 
 #### `semi://components`
 
-Semi Design 组件列表资源。
+Semi Design component list resource.
 
-## 开发
+## Development
 
-### 环境要求
+### Requirements
 
 - Node.js >= 18.0.0
-- npm 或 yarn
+- npm or yarn
 
-### 安装依赖
+### Install Dependencies
 
 ```bash
 npm install
 ```
 
-### 构建
+### Build
 
-构建生产版本：
+Build production version:
 
 ```bash
 npm run build
 ```
 
-开发模式（监听文件变化并自动重建）：
+Development mode (watch for file changes and auto-rebuild):
 
 ```bash
 npm run dev
 ```
 
-### 测试
+### Test
 
-运行测试：
+Run tests:
 
 ```bash
 npm test
 ```
 
-### 运行
+### Run
 
-构建完成后运行服务器：
+Run the server after building:
 
 ```bash
 npm start
 ```
 
-或者直接运行构建后的文件：
+Or run the built file directly:
 
 ```bash
 node dist/index.js
 ```
 
-## 技术栈
+## Tech Stack
 
-- **TypeScript**: 类型安全的 JavaScript
-- **Rslib**: 快速构建工具
-- **@modelcontextprotocol/sdk**: MCP 官方 SDK
+- **TypeScript**: Type-safe JavaScript
+- **Rslib**: Fast build tool
+- **@modelcontextprotocol/sdk**: Official MCP SDK
 
-## 项目结构
+## Project Structure
 
 ```
 semi-mcp/
 ├── src/
-│   ├── index.ts              # 主入口文件
-│   ├── tools/                # 工具定义
+│   ├── index.ts              # Main entry file
+│   ├── tools/                # Tool definitions
 │   │   ├── index.ts
 │   │   └── get-semi-document.ts
-│   └── utils/                # 工具函数
+│   └── utils/                # Utility functions
 │       ├── fetch-directory-list.ts
-│       └── fetch-file-content.ts
-├── tests/                    # 测试文件
+│       ├── fetch-file-content.ts
+│       └── get-component-list.ts
+├── tests/                    # Test files
 │   └── get-semi-document.test.ts
-├── dist/                     # 构建输出
+├── dist/                     # Build output
 ├── package.json
 └── README.md
 ```
 
-## 许可证
+## License
 
 MIT
 
-## 相关链接
+## Related Links
 
-- [Semi Design 官网](https://semi.design)
-- [Model Context Protocol 文档](https://modelcontextprotocol.io)
+- [Semi Design Official Website](https://semi.design)
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io)

package/dist/index.js

@@ -16,8 +16,65 @@ function flattenDirectoryStructure(item, result = []) {
     if (item.files && Array.isArray(item.files)) for (const file of item.files)flattenDirectoryStructure(file, result);
     return result;
 }
+async function fetchNpmMirrorDirectoryRecursive(baseUrl, packageName, version, path, maxDepth = 10) {
+    if (maxDepth <= 0) return [];
+    const url = `${baseUrl}/${packageName}/${version}/files/${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'
+        };
+    };
+    const result = [];
+    if (data && 'object' == typeof data && 'files' in data && Array.isArray(data.files)) {
+        const promises = [];
+        for (const item of data.files){
+            const normalized = normalizeType(item);
+            result.push(normalized);
+            if ('directory' !== normalized.type || item.files && 0 !== item.files.length) {
+                if (item.files && Array.isArray(item.files) && item.files.length > 0) {
+                    const flattened = [];
+                    flattenDirectoryStructure(item, flattened);
+                    const subFiles = flattened.filter((f)=>f.path !== normalized.path).map(normalizeType);
+                    result.push(...subFiles);
+                }
+            } else {
+                const subPath = normalized.path.startsWith('/') ? normalized.path.slice(1) : normalized.path;
+                promises.push(fetchNpmMirrorDirectoryRecursive(baseUrl, packageName, version, subPath, maxDepth - 1).then((subFiles)=>subFiles.filter((f)=>f.path !== normalized.path)).catch(()=>[]));
+            }
+        }
+        if (promises.length > 0) {
+            const subResults = await Promise.all(promises);
+            for (const subFiles of subResults)result.push(...subFiles);
+        }
+    }
+    return result;
+}
 async function fetchDirectoryListFromSource(baseUrl, packageName, version, path, isNpmMirror = false) {
-    const url = isNpmMirror ? `${baseUrl}/${packageName}/${version}/files/${path}/?meta` : `${baseUrl}/${packageName}@${version}/${path}/?meta`;
+    if (isNpmMirror) return fetchNpmMirrorDirectoryRecursive(baseUrl, packageName, version, path);
+    const url = `${baseUrl}/${packageName}@${version}/${path}/?meta`;
     const response = await fetch(url, {
         headers: {
             Accept: 'application/json'
@@ -48,12 +105,8 @@ async function fetchDirectoryListFromSource(baseUrl, packageName, version, path,
     };
     if (Array.isArray(data)) return data.map(normalizeType);
     if (data && 'object' == typeof data && 'files' in data) {
-        if (Array.isArray(data.files)) {
-            const flattened = [];
-            for (const item of data.files)flattenDirectoryStructure(item, flattened);
-            return flattened.map(normalizeType);
-        }
-        return [];
+        const filesData = data;
+        if (Array.isArray(filesData.files)) return filesData.files.map(normalizeType);
     }
     if (data && 'object' == typeof data && 'path' in data) {
         const singleItem = data;
@@ -71,20 +124,28 @@ async function fetchDirectoryListFromSource(baseUrl, packageName, version, path,
 async function fetchDirectoryList(packageName, version, path) {
     const unpkgPromise = fetchDirectoryListFromSource(UNPKG_BASE_URL, packageName, version, path, false);
     const npmmirrorPromise = fetchDirectoryListFromSource(NPMMIRROR_BASE_URL, packageName, version, path, true);
-    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 successfulResults = [];
     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('; ')}`);
+    if ('fulfilled' === results[0].status) successfulResults.push({
+        source: 'unpkg',
+        files: results[0].value
+    });
+    else errors.push(results[0].reason instanceof Error ? results[0].reason : new Error(String(results[0].reason)));
+    if ('fulfilled' === results[1].status) successfulResults.push({
+        source: 'npmmirror',
+        files: results[1].value
+    });
+    else errors.push(results[1].reason instanceof Error ? results[1].reason : new Error(String(results[1].reason)));
+    if (0 === successfulResults.length) throw new Error(`所有数据源都失败了: ${errors.map((e)=>e.message).join('; ')}`);
+    successfulResults.sort((a, b)=>{
+        if (b.files.length !== a.files.length) return b.files.length - a.files.length;
+        return 'unpkg' === a.source ? -1 : 1;
+    });
+    return successfulResults[0].files;
 }
 const fetch_file_content_UNPKG_BASE_URL = 'https://unpkg.com';
 const fetch_file_content_NPMMIRROR_BASE_URL = 'https://registry.npmmirror.com';
@@ -219,15 +280,7 @@ async function handleGetSemiDocument(args) {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({
-                            componentName: componentName.toLowerCase(),
-                            version,
-                            error: '未找到组件文档',
-                            documents: [],
-                            count: 0,
-                            allComponents,
-                            allComponentsCount: allComponents.length
-                        }, null, 2)
+                        text: `未找到组件 "${componentName}" 的文档 (版本 ${version})。\n\n可用组件列表：${allComponents.join(', ')}`
                     }
                 ]
             };
@@ -245,68 +298,32 @@ async function handleGetSemiDocument(args) {
                 await mkdir(tempDir, {
                     recursive: true
                 });
-                const filePaths = [];
                 for (const doc of result.documents){
                     const filePath = join(tempDir, doc.name);
                     await writeFile(filePath, doc.content, 'utf-8');
-                    filePaths.push(filePath);
-                }
-                const largeDocs = documentsWithLines.filter((doc)=>doc.lines > 888);
-                let message = `文档已保存到临时目录: ${tempDir}\n请使用文件读取工具查看文档内容。`;
-                if (hasLargeDocument && !userExplicitlySetGetPath) {
-                    const largeDocNames = largeDocs.map((doc)=>`${doc.name} (${doc.lines.toLocaleString()} 行)`).join(', ');
-                    message = `文档已保存到临时目录: ${tempDir}\n注意：以下文档文件较大，已自动保存到临时目录：${largeDocNames}\n请使用文件读取工具查看文档内容。`;
-                } else if (hasLargeDocument) {
-                    const largeDocNames = largeDocs.map((doc)=>`${doc.name} (${doc.lines.toLocaleString()} 行)`).join(', ');
-                    message = `文档已保存到临时目录: ${tempDir}\n注意：以下文档文件较大：${largeDocNames}\n请使用文件读取工具查看文档内容。`;
                 }
+                const fileList = documentsWithLines.map((doc)=>`  - ${join(tempDir, doc.name)} (${doc.lines.toLocaleString()} 行)`).join('\n');
+                const message = `组件 ${componentName} (版本 ${version}) 文档较大，已保存到临时目录。
+
+文档文件列表：
+${fileList}
+
+请使用文件读取工具查看文档内容。`;
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify({
-                                componentName: componentName.toLowerCase(),
-                                version,
-                                category: result.category,
-                                tempDirectory: tempDir,
-                                files: documentsWithLines.map((doc)=>({
-                                        name: doc.name,
-                                        path: join(tempDir, doc.name),
-                                        contentLength: doc.content.length,
-                                        lines: doc.lines
-                                    })),
-                                count: result.documents.length,
-                                message,
-                                autoGetPath: hasLargeDocument && !userExplicitlySetGetPath,
-                                allComponents,
-                                allComponentsCount: allComponents.length
-                            }, null, 2)
+                            text: message
                         }
                     ]
                 };
             }
+            const docContents = result.documents.map((doc)=>`===== ${doc.name} =====\n\n${doc.content}`).join('\n\n');
             return {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({
-                            componentName: componentName.toLowerCase(),
-                            version,
-                            category: result.category,
-                            documents: result.documents.map((doc)=>({
-                                    name: doc.name,
-                                    path: doc.path,
-                                    contentLength: doc.content.length
-                                })),
-                            contents: result.documents.map((doc)=>({
-                                    name: doc.name,
-                                    path: doc.path,
-                                    content: doc.content
-                                })),
-                            count: result.documents.length,
-                            allComponents,
-                            allComponentsCount: allComponents.length
-                        }, null, 2)
+                        text: docContents
                     }
                 ]
             };
@@ -317,12 +334,7 @@ async function handleGetSemiDocument(args) {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({
-                            version,
-                            error: `未找到组件列表，请检查版本号 ${version} 是否正确`,
-                            components: [],
-                            count: 0
-                        }, null, 2)
+                        text: `未找到组件列表，请检查版本号 ${version} 是否正确`
                     }
                 ],
                 isError: true
@@ -331,11 +343,7 @@ async function handleGetSemiDocument(args) {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({
-                            version,
-                            components,
-                            count: components.length
-                        }, null, 2)
+                        text: `Semi Design 组件列表 (版本 ${version})，共 ${components.length} 个组件：\n\n${components.join(', ')}`
                     }
                 ]
             };
@@ -346,11 +354,7 @@ async function handleGetSemiDocument(args) {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify({
-                        error: errorMessage,
-                        componentName: componentName?.toLowerCase(),
-                        version
-                    }, null, 2)
+                    text: `获取文档失败: ${errorMessage}`
                 }
             ],
             isError: true

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

@@ -14,7 +14,7 @@ export declare function fetchDirectoryListFromSource(baseUrl: string, packageNam
 }>>;
 /**
  * 从 unpkg 或 npmmirror 获取目录列表
- * 同时向两个数据源发送请求，使用第一个成功返回的结果
+ * 同时向两个数据源发送请求，优先使用返回更多文件的结果
  */
 export declare function fetchDirectoryList(packageName: string, version: string, path: string): Promise<Array<{
     path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@douyinfe/semi-mcp",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Semi Design MCP Server - Model Context Protocol server for Semi Design components and documentation",
   "type": "module",
   "main": "./dist/index.js",