@douyinfe/semi-mcp 1.0.1 → 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

@@ -2,10 +2,79 @@
 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";
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
 const UNPKG_BASE_URL = 'https://unpkg.com';
 const NPMMIRROR_BASE_URL = 'https://registry.npmmirror.com';
-async function fetchFromSource(baseUrl, packageName, version, path, isNpmMirror = false) {
-    const url = isNpmMirror ? `${baseUrl}/${packageName}/${version}/files/${path}/?meta` : `${baseUrl}/${packageName}@${version}/${path}/?meta`;
+function flattenDirectoryStructure(item, result = []) {
+    result.push({
+        path: item.path,
+        type: item.type,
+        size: item.size
+    });
+    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) {
+    if (isNpmMirror) return fetchNpmMirrorDirectoryRecursive(baseUrl, packageName, version, path);
+    const url = `${baseUrl}/${packageName}@${version}/${path}/?meta`;
     const response = await fetch(url, {
         headers: {
             Accept: 'application/json'
@@ -35,15 +104,66 @@ async function fetchFromSource(baseUrl, packageName, version, path, isNpmMirror
         };
     };
     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)
-    ];
+    if (data && 'object' == typeof data && 'files' in data) {
+        const filesData = data;
+        if (Array.isArray(filesData.files)) return filesData.files.map(normalizeType);
+    }
+    if (data && 'object' == typeof data && 'path' in data) {
+        const singleItem = data;
+        if (singleItem.files && Array.isArray(singleItem.files)) {
+            const flattened = [];
+            flattenDirectoryStructure(singleItem, flattened);
+            return flattened.map(normalizeType);
+        }
+        return [
+            normalizeType(singleItem)
+        ];
+    }
     throw new Error('无法解析目录列表数据格式');
 }
 async function fetchDirectoryList(packageName, version, path) {
-    const unpkgPromise = fetchFromSource(UNPKG_BASE_URL, packageName, version, path, false);
-    const npmmirrorPromise = fetchFromSource(NPMMIRROR_BASE_URL, packageName, version, path, true);
+    const unpkgPromise = fetchDirectoryListFromSource(UNPKG_BASE_URL, packageName, version, path, false);
+    const npmmirrorPromise = fetchDirectoryListFromSource(NPMMIRROR_BASE_URL, packageName, version, path, true);
+    const results = await Promise.allSettled([
+        unpkgPromise,
+        npmmirrorPromise
+    ]);
+    const successfulResults = [];
+    const errors = [];
+    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';
+async function fetchFileContentFromSource(baseUrl, packageName, version, filePath, isNpmMirror = false) {
+    const url = isNpmMirror ? `${baseUrl}/${packageName}/${version}/files/${filePath}` : `${baseUrl}/${packageName}@${version}/${filePath}`;
+    const response = await fetch(url, {
+        headers: {
+            Accept: 'text/plain, application/json, */*'
+        }
+    });
+    if (!response.ok) throw new Error(`获取文件失败: ${response.status} ${response.statusText}`);
+    const content = await response.text();
+    if (content.trim().startsWith('<!DOCTYPE html>') || content.includes('npmmirror 镜像站')) throw new Error('返回了 HTML 错误页面');
+    return content;
+}
+async function fetchFileContent(packageName, version, filePath) {
+    const unpkgPromise = fetchFileContentFromSource(fetch_file_content_UNPKG_BASE_URL, packageName, version, filePath, false);
+    const npmmirrorPromise = fetchFileContentFromSource(fetch_file_content_NPMMIRROR_BASE_URL, packageName, version, filePath, true);
     const unpkgWithFallback = unpkgPromise.catch(()=>new Promise(()=>{}));
     const npmmirrorWithFallback = npmmirrorPromise.catch(()=>new Promise(()=>{}));
     const raceResult = await Promise.race([
@@ -91,6 +211,11 @@ const getSemiDocumentTool = {
             version: {
                 type: 'string',
                 description: '版本号，例如 2.89.1。如果不提供，默认使用 latest'
+            },
+            get_path: {
+                type: 'boolean',
+                description: '如果为 true，将文档写入操作系统临时目录并返回路径，而不是在响应中返回文档内容。默认为 false',
+                default: false
             }
         },
         required: []
@@ -117,18 +242,36 @@ async function getComponentDocuments(componentName, version) {
     }
     if (-1 === categoryIndex || categoryIndex >= pathParts.length) return null;
     const category = pathParts[categoryIndex];
-    const documents = componentFiles.map((file)=>{
+    const documentPromises = componentFiles.map(async (file)=>{
+        const filePath = file.path.startsWith('/') ? file.path.slice(1) : file.path;
         const parts = file.path.split('/');
-        return parts[parts.length - 1].toLowerCase();
-    }).filter((name)=>name);
+        const fileName = parts[parts.length - 1];
+        try {
+            const content = await fetchFileContent(packageName, version, filePath);
+            return {
+                name: fileName,
+                path: file.path,
+                content: content
+            };
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                name: fileName,
+                path: file.path,
+                content: `获取文档内容失败: ${errorMessage}`
+            };
+        }
+    });
+    const documents = await Promise.all(documentPromises);
     return {
         category,
-        documents: Array.from(new Set(documents)).sort()
+        documents: documents.sort((a, b)=>a.name.localeCompare(b.name))
     };
 }
 async function handleGetSemiDocument(args) {
     const componentName = args?.componentName;
     const version = args?.version || 'latest';
+    const getPath = args?.get_path || false;
     try {
         if (componentName) {
             const result = await getComponentDocuments(componentName, version);
@@ -149,6 +292,60 @@ async function handleGetSemiDocument(args) {
                     }
                 ]
             };
+            const documentsWithLines = result.documents.map((doc)=>({
+                    ...doc,
+                    lines: doc.content.split('\n').length
+                }));
+            const hasLargeDocument = documentsWithLines.some((doc)=>doc.lines > 888);
+            const userExplicitlySetGetPath = 'get_path' in args;
+            const shouldUsePath = getPath || hasLargeDocument && !userExplicitlySetGetPath;
+            if (shouldUsePath) {
+                const baseTempDir = tmpdir();
+                const tempDirName = `semi-docs-${componentName.toLowerCase()}-${version}-${Date.now()}`;
+                const tempDir = join(baseTempDir, tempDirName);
+                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请使用文件读取工具查看文档内容。`;
+                }
+                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)
+                        }
+                    ]
+                };
+            }
             return {
                 content: [
                     {
@@ -157,7 +354,16 @@ async function handleGetSemiDocument(args) {
                             componentName: componentName.toLowerCase(),
                             version,
                             category: result.category,
-                            documents: result.documents,
+                            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

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

@@ -2,9 +2,19 @@
  * 从 unpkg 或 npmmirror 获取目录列表
  * 同时向两个数据源发送请求，使用第一个成功返回的结果
  */
+export declare const UNPKG_BASE_URL = "https://unpkg.com";
+export declare const NPMMIRROR_BASE_URL = "https://registry.npmmirror.com";
+/**
+ * 从单个源获取目录列表
+ * 导出用于测试
+ */
+export declare function fetchDirectoryListFromSource(baseUrl: string, packageName: string, version: string, path: string, isNpmMirror?: boolean): Promise<Array<{
+    path: string;
+    type: string;
+}>>;
 /**
  * 从 unpkg 或 npmmirror 获取目录列表
- * 同时向两个数据源发送请求，使用第一个成功返回的结果
+ * 同时向两个数据源发送请求，优先使用返回更多文件的结果
  */
 export declare function fetchDirectoryList(packageName: string, version: string, path: string): Promise<Array<{
     path: string;

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

@@ -2,6 +2,13 @@
  * 从 unpkg 或 npmmirror 获取具体文件内容
  * 同时向两个数据源发送请求，使用第一个成功返回的结果
  */
+export declare const UNPKG_BASE_URL = "https://unpkg.com";
+export declare const NPMMIRROR_BASE_URL = "https://registry.npmmirror.com";
+/**
+ * 从单个源获取文件内容
+ * 导出用于测试
+ */
+export declare function fetchFileContentFromSource(baseUrl: string, packageName: string, version: string, filePath: string, isNpmMirror?: boolean): Promise<string>;
 /**
  * 从 unpkg 或 npmmirror 获取具体文件内容
  * 同时向两个数据源发送请求，使用第一个成功返回的结果

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@douyinfe/semi-mcp",
-  "version": "1.0.1",
+  "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",