@douyinfe/semi-mcp 1.0.14 → 1.0.16

package/dist/http.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from "url";
 import { dirname, join as external_path_join } from "path";
 import { homedir } from "os";
 import { mkdir, readFile, writeFile } from "fs/promises";
+import { lt } from "semver";
 import { parseSync } from "oxc-parser";
 function getCacheDir() {
     return external_path_join(homedir(), '.semi-mcp', 'cache');
@@ -45,6 +46,7 @@ async function writeCache(cacheDir, key, content) {
         await writeFile(filePath, content, 'utf-8');
     } catch  {}
 }
+const MIN_SUPPORTED_VERSION = '2.90.2';
 function getVersionCacheDir() {
     return external_path_join(getCacheDir(), 'version');
 }
@@ -80,7 +82,8 @@ async function fetchVersionFromRegistry(packageName, tag) {
     throw new Error(`无法获取 ${packageName}@${tag} 的版本号: ${lastError?.message}`);
 }
 async function resolveVersion(packageName, version) {
-    if (/^\d+\.\d+\.\d+/.test(version)) return version;
+    if (/^\d+\.\d+\.\d+/.test(version)) if (!lt(version, MIN_SUPPORTED_VERSION)) return version;
+    else version = 'latest';
     const cacheDir = getVersionCacheDir();
     const cacheKey = getVersionCacheKey(packageName, version);
     const today = getCurrentDate();
@@ -380,13 +383,13 @@ function replaceCodeBlocksWithPlaceholders(content, componentName) {
 }
 const getSemiDocumentTool = {
     name: 'get_semi_document',
-    description: '获取 Semi Design 组件文档或组件列表。对于大型文档，代码块会被替换为占位符，需要使用 get_semi_code_block 工具获取具体代码',
+    description: '获取 Semi Design 组件文档、额外文档或组件列表。支持获取：1) 组件文档（如 Button、Input 等组件）；2) 额外文档，包括：advanced 分类下的文档（customize-theme、dark-mode、design-source、design-to-code）、ecosystem 分类下的文档（changelog、faq、react19、tailwind、update-to-v2、web-components）、start 分类下的文档（getting-started、introduction、overview）。注意：changelog 文档较大，需要使用分页格式获取，传入 changelog-1（第1页，最新内容）、changelog-2（第2页）等格式，每页300行。对于大型文档，代码块会被替换为占位符，需要使用 get_semi_code_block 工具获取具体代码',
     inputSchema: {
         type: 'object',
         properties: {
             componentName: {
                 type: 'string',
-                description: '组件名称，例如 Button、Input 等。如果不提供，则返回组件列表'
+                description: '组件名称或文档名称。组件名称例如：Button、Input、Table 等；额外文档名称例如：customize-theme、dark-mode、changelog-1（changelog第1页，最新）、changelog-2（changelog第2页）等、faq、react19、tailwind、update-to-v2、web-components、getting-started、introduction、overview 等。注意：changelog 必须使用分页格式（changelog-1、changelog-2等），不能直接传入 changelog。如果不提供，则返回组件列表'
             },
             version: {
                 type: 'string',
@@ -397,12 +400,59 @@ const getSemiDocumentTool = {
     }
 };
 const LARGE_DOCUMENT_THRESHOLD = 888;
+const CHANGELOG_PAGE_SIZE = 300;
+function parseChangelogPage(componentName) {
+    const changelogMatch = componentName.match(/^(changelog)(?:-(\d+))?$/);
+    if (changelogMatch) {
+        const baseName = changelogMatch[1];
+        const pageStr = changelogMatch[2];
+        if (!pageStr) return {
+            isChangelog: true,
+            baseName
+        };
+        {
+            const page = parseInt(pageStr, 10);
+            return {
+                isChangelog: true,
+                page,
+                baseName
+            };
+        }
+    }
+    return {
+        isChangelog: false
+    };
+}
+function paginateChangelog(content, page) {
+    const lines = content.split('\n');
+    const totalLines = lines.length;
+    const totalPages = Math.ceil(totalLines / CHANGELOG_PAGE_SIZE);
+    const startIndex = (page - 1) * CHANGELOG_PAGE_SIZE;
+    const endIndex = Math.min(startIndex + CHANGELOG_PAGE_SIZE, totalLines);
+    const pageLines = lines.slice(startIndex, endIndex);
+    const pageContent = pageLines.join('\n');
+    return {
+        content: pageContent,
+        totalPages,
+        currentPage: page
+    };
+}
 async function handleGetSemiDocument(args) {
     const componentName = args?.componentName;
     const version = args?.version || 'latest';
     try {
         if (componentName) {
-            const result = await getComponentDocuments(componentName, version);
+            const changelogInfo = parseChangelogPage(componentName);
+            if (changelogInfo.isChangelog && !changelogInfo.page) return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `changelog 文档较大，需要使用分页方式获取。\n\n请使用以下格式获取：\n- changelog-1（第1页，最新内容）\n- changelog-2（第2页）\n- changelog-3（第3页）\n- ...\n\n页码从1开始，1为最新内容。`
+                    }
+                ]
+            };
+            const actualComponentName = changelogInfo.baseName || componentName;
+            const result = await getComponentDocuments(actualComponentName, version);
             const allComponents = await getComponentList(version);
             if (!result) return {
                 content: [
@@ -412,6 +462,45 @@ async function handleGetSemiDocument(args) {
                     }
                 ]
             };
+            if (changelogInfo.isChangelog && changelogInfo.page) {
+                const page = changelogInfo.page;
+                if (0 === result.documents.length) return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `未找到 changelog 文档 (版本 ${version})`
+                        }
+                    ],
+                    isError: true
+                };
+                const doc = result.documents[0];
+                const paginated = paginateChangelog(doc.content, page);
+                if (page < 1 || page > paginated.totalPages) return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `页码 ${page} 超出范围。changelog 文档共有 ${paginated.totalPages} 页，请使用 changelog-1 到 changelog-${paginated.totalPages}。`
+                        }
+                    ],
+                    isError: true
+                };
+                const nextPageHint = page < paginated.totalPages ? `使用 changelog-${page + 1} 获取下一页` : '';
+                const prevPageHint = page > 1 ? `使用 changelog-${page - 1} 获取上一页` : '';
+                const pageHints = [
+                    nextPageHint,
+                    prevPageHint
+                ].filter(Boolean).join('，');
+                const header = `===== ${doc.name} (第 ${page}/${paginated.totalPages} 页) =====${pageHints ? `\n[提示: ${pageHints}]` : ''}`;
+                const footer = `\n\n[当前页: ${page}/${paginated.totalPages} | 总行数: ${doc.content.split('\n').length} | 每页: ${CHANGELOG_PAGE_SIZE} 行]`;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${header}\n\n${paginated.content}${footer}`
+                        }
+                    ]
+                };
+            }
             const documentsWithLines = result.documents.map((doc)=>({
                     ...doc,
                     lines: doc.content.split('\n').length

package/dist/index.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "url";
 import { dirname, join as external_path_join } from "path";
 import { homedir } from "os";
 import { mkdir, readFile, writeFile } from "fs/promises";
+import { lt } from "semver";
 import { parseSync } from "oxc-parser";
 function getCacheDir() {
     return external_path_join(homedir(), '.semi-mcp', 'cache');
@@ -44,6 +45,7 @@ async function writeCache(cacheDir, key, content) {
         await writeFile(filePath, content, 'utf-8');
     } catch  {}
 }
+const MIN_SUPPORTED_VERSION = '2.90.2';
 function getVersionCacheDir() {
     return external_path_join(getCacheDir(), 'version');
 }
@@ -79,7 +81,8 @@ async function fetchVersionFromRegistry(packageName, tag) {
     throw new Error(`无法获取 ${packageName}@${tag} 的版本号: ${lastError?.message}`);
 }
 async function resolveVersion(packageName, version) {
-    if (/^\d+\.\d+\.\d+/.test(version)) return version;
+    if (/^\d+\.\d+\.\d+/.test(version)) if (!lt(version, MIN_SUPPORTED_VERSION)) return version;
+    else version = 'latest';
     const cacheDir = getVersionCacheDir();
     const cacheKey = getVersionCacheKey(packageName, version);
     const today = getCurrentDate();
@@ -379,13 +382,13 @@ function replaceCodeBlocksWithPlaceholders(content, componentName) {
 }
 const getSemiDocumentTool = {
     name: 'get_semi_document',
-    description: '获取 Semi Design 组件文档或组件列表。对于大型文档，代码块会被替换为占位符，需要使用 get_semi_code_block 工具获取具体代码',
+    description: '获取 Semi Design 组件文档、额外文档或组件列表。支持获取：1) 组件文档（如 Button、Input 等组件）；2) 额外文档，包括：advanced 分类下的文档（customize-theme、dark-mode、design-source、design-to-code）、ecosystem 分类下的文档（changelog、faq、react19、tailwind、update-to-v2、web-components）、start 分类下的文档（getting-started、introduction、overview）。注意：changelog 文档较大，需要使用分页格式获取，传入 changelog-1（第1页，最新内容）、changelog-2（第2页）等格式，每页300行。对于大型文档，代码块会被替换为占位符，需要使用 get_semi_code_block 工具获取具体代码',
     inputSchema: {
         type: 'object',
         properties: {
             componentName: {
                 type: 'string',
-                description: '组件名称，例如 Button、Input 等。如果不提供，则返回组件列表'
+                description: '组件名称或文档名称。组件名称例如：Button、Input、Table 等；额外文档名称例如：customize-theme、dark-mode、changelog-1（changelog第1页，最新）、changelog-2（changelog第2页）等、faq、react19、tailwind、update-to-v2、web-components、getting-started、introduction、overview 等。注意：changelog 必须使用分页格式（changelog-1、changelog-2等），不能直接传入 changelog。如果不提供，则返回组件列表'
             },
             version: {
                 type: 'string',
@@ -396,12 +399,59 @@ const getSemiDocumentTool = {
     }
 };
 const LARGE_DOCUMENT_THRESHOLD = 888;
+const CHANGELOG_PAGE_SIZE = 300;
+function parseChangelogPage(componentName) {
+    const changelogMatch = componentName.match(/^(changelog)(?:-(\d+))?$/);
+    if (changelogMatch) {
+        const baseName = changelogMatch[1];
+        const pageStr = changelogMatch[2];
+        if (!pageStr) return {
+            isChangelog: true,
+            baseName
+        };
+        {
+            const page = parseInt(pageStr, 10);
+            return {
+                isChangelog: true,
+                page,
+                baseName
+            };
+        }
+    }
+    return {
+        isChangelog: false
+    };
+}
+function paginateChangelog(content, page) {
+    const lines = content.split('\n');
+    const totalLines = lines.length;
+    const totalPages = Math.ceil(totalLines / CHANGELOG_PAGE_SIZE);
+    const startIndex = (page - 1) * CHANGELOG_PAGE_SIZE;
+    const endIndex = Math.min(startIndex + CHANGELOG_PAGE_SIZE, totalLines);
+    const pageLines = lines.slice(startIndex, endIndex);
+    const pageContent = pageLines.join('\n');
+    return {
+        content: pageContent,
+        totalPages,
+        currentPage: page
+    };
+}
 async function handleGetSemiDocument(args) {
     const componentName = args?.componentName;
     const version = args?.version || 'latest';
     try {
         if (componentName) {
-            const result = await getComponentDocuments(componentName, version);
+            const changelogInfo = parseChangelogPage(componentName);
+            if (changelogInfo.isChangelog && !changelogInfo.page) return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `changelog 文档较大，需要使用分页方式获取。\n\n请使用以下格式获取：\n- changelog-1（第1页，最新内容）\n- changelog-2（第2页）\n- changelog-3（第3页）\n- ...\n\n页码从1开始，1为最新内容。`
+                    }
+                ]
+            };
+            const actualComponentName = changelogInfo.baseName || componentName;
+            const result = await getComponentDocuments(actualComponentName, version);
             const allComponents = await getComponentList(version);
             if (!result) return {
                 content: [
@@ -411,6 +461,45 @@ async function handleGetSemiDocument(args) {
                     }
                 ]
             };
+            if (changelogInfo.isChangelog && changelogInfo.page) {
+                const page = changelogInfo.page;
+                if (0 === result.documents.length) return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `未找到 changelog 文档 (版本 ${version})`
+                        }
+                    ],
+                    isError: true
+                };
+                const doc = result.documents[0];
+                const paginated = paginateChangelog(doc.content, page);
+                if (page < 1 || page > paginated.totalPages) return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `页码 ${page} 超出范围。changelog 文档共有 ${paginated.totalPages} 页，请使用 changelog-1 到 changelog-${paginated.totalPages}。`
+                        }
+                    ],
+                    isError: true
+                };
+                const nextPageHint = page < paginated.totalPages ? `使用 changelog-${page + 1} 获取下一页` : '';
+                const prevPageHint = page > 1 ? `使用 changelog-${page - 1} 获取上一页` : '';
+                const pageHints = [
+                    nextPageHint,
+                    prevPageHint
+                ].filter(Boolean).join('，');
+                const header = `===== ${doc.name} (第 ${page}/${paginated.totalPages} 页) =====${pageHints ? `\n[提示: ${pageHints}]` : ''}`;
+                const footer = `\n\n[当前页: ${page}/${paginated.totalPages} | 总行数: ${doc.content.split('\n').length} | 每页: ${CHANGELOG_PAGE_SIZE} 行]`;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${header}\n\n${paginated.content}${footer}`
+                        }
+                    ]
+                };
+            }
             const documentsWithLines = result.documents.map((doc)=>({
                     ...doc,
                     lines: doc.content.split('\n').length

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@douyinfe/semi-mcp",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Semi Design MCP Server - Model Context Protocol server for Semi Design components and documentation",
   "type": "module",
   "main": "./dist/index.js",
@@ -51,7 +51,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@swc/core": "^1.15.8",
-    "oxc-parser": "^0.106.0"
+    "oxc-parser": "^0.106.0",
+    "semver": "^7.7.3"
   },
   "devDependencies": {
     "@rslib/core": "^0.18.5",