@douyinfe/semi-mcp 1.0.2 → 1.0.3

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,9 +92,9 @@ semi-mcp
 }
 ```
 
-**返回格式：**
+**Response Format:**
 
-获取组件列表时：
+When getting component list:
 ```json
 {
   "version": "2.89.2-alpha.3",
@@ -100,7 +103,7 @@ semi-mcp
 }
 ```
 
-获取组件文档时：
+When getting component documentation:
 ```json
 {
   "componentName": "button",
@@ -113,91 +116,94 @@ semi-mcp
 }
 ```
 
-### 资源 (Resources)
+**Note:** For large documents (over 888 lines), the tool will automatically save them to a temporary directory and return the file paths instead of content.
+
+### 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';

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.3",
   "description": "Semi Design MCP Server - Model Context Protocol server for Semi Design components and documentation",
   "type": "module",
   "main": "./dist/index.js",