@douyinfe/semi-mcp 1.0.15 → 1.0.17

package/dist/http.js

@@ -383,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）、experience 分类下的文档（accessibility、content-guidelines、internationalization）、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、design-source、design-to-code、changelog-1（changelog第1页，最新）、changelog-2（changelog第2页）等、faq、react19、tailwind、update-to-v2、web-components、accessibility、content-guidelines、internationalization、getting-started、introduction、overview 等。注意：changelog 必须使用分页格式（changelog-1、changelog-2等），不能直接传入 changelog。如果不提供，则返回组件列表'
             },
             version: {
                 type: 'string',
@@ -400,12 +400,72 @@ const getSemiDocumentTool = {
     }
 };
 const LARGE_DOCUMENT_THRESHOLD = 888;
+const CHANGELOG_PAGE_SIZE = 300;
+function generateDocumentUrl(docPath) {
+    const pathParts = docPath.split('/');
+    let contentIndex = -1;
+    for(let i = 0; i < pathParts.length; i++)if ('content' === pathParts[i].toLowerCase()) {
+        contentIndex = i;
+        break;
+    }
+    if (-1 === contentIndex || contentIndex + 3 >= pathParts.length) return '';
+    const category = pathParts[contentIndex + 1];
+    const componentName = pathParts[contentIndex + 2];
+    if (!category || !componentName) return '';
+    return `https://semi.design/zh-CN/${category}/${componentName}`;
+}
+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: [
@@ -415,6 +475,47 @@ 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} 行]`;
+                const url = generateDocumentUrl(doc.path);
+                const urlFooter = url ? `\n\n文档链接: ${url}` : '';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${header}\n\n${paginated.content}${footer}${urlFooter}`
+                        }
+                    ]
+                };
+            }
             const documentsWithLines = result.documents.map((doc)=>({
                     ...doc,
                     lines: doc.content.split('\n').length
@@ -442,7 +543,9 @@ async function handleGetSemiDocument(args) {
                 const docContents = processedDocs.map((doc)=>{
                     let header = `===== ${doc.name} =====`;
                     if (doc.codeBlockCount > 0) header += `\n[注意: 此文档原有 ${doc.originalLines} 行，包含 ${doc.codeBlockCount} 个代码块已被隐藏。使用 get_semi_code_block 工具查看具体代码]`;
-                    return `${header}\n\n${doc.content}`;
+                    const url = generateDocumentUrl(doc.path);
+                    const urlFooter = url ? `\n\n文档链接: ${url}` : '';
+                    return `${header}\n\n${doc.content}${urlFooter}`;
                 }).join('\n\n');
                 return {
                     content: [
@@ -453,7 +556,11 @@ async function handleGetSemiDocument(args) {
                     ]
                 };
             }
-            const docContents = result.documents.map((doc)=>`===== ${doc.name} =====\n\n${doc.content}`).join('\n\n');
+            const docContents = result.documents.map((doc)=>{
+                const url = generateDocumentUrl(doc.path);
+                const urlFooter = url ? `\n\n文档链接: ${url}` : '';
+                return `===== ${doc.name} =====\n\n${doc.content}${urlFooter}`;
+            }).join('\n\n');
             return {
                 content: [
                     {

package/dist/index.js

@@ -382,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）、experience 分类下的文档（accessibility、content-guidelines、internationalization）、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、design-source、design-to-code、changelog-1（changelog第1页，最新）、changelog-2（changelog第2页）等、faq、react19、tailwind、update-to-v2、web-components、accessibility、content-guidelines、internationalization、getting-started、introduction、overview 等。注意：changelog 必须使用分页格式（changelog-1、changelog-2等），不能直接传入 changelog。如果不提供，则返回组件列表'
             },
             version: {
                 type: 'string',
@@ -399,12 +399,72 @@ const getSemiDocumentTool = {
     }
 };
 const LARGE_DOCUMENT_THRESHOLD = 888;
+const CHANGELOG_PAGE_SIZE = 300;
+function generateDocumentUrl(docPath) {
+    const pathParts = docPath.split('/');
+    let contentIndex = -1;
+    for(let i = 0; i < pathParts.length; i++)if ('content' === pathParts[i].toLowerCase()) {
+        contentIndex = i;
+        break;
+    }
+    if (-1 === contentIndex || contentIndex + 3 >= pathParts.length) return '';
+    const category = pathParts[contentIndex + 1];
+    const componentName = pathParts[contentIndex + 2];
+    if (!category || !componentName) return '';
+    return `https://semi.design/zh-CN/${category}/${componentName}`;
+}
+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: [
@@ -414,6 +474,47 @@ 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} 行]`;
+                const url = generateDocumentUrl(doc.path);
+                const urlFooter = url ? `\n\n文档链接: ${url}` : '';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${header}\n\n${paginated.content}${footer}${urlFooter}`
+                        }
+                    ]
+                };
+            }
             const documentsWithLines = result.documents.map((doc)=>({
                     ...doc,
                     lines: doc.content.split('\n').length
@@ -441,7 +542,9 @@ async function handleGetSemiDocument(args) {
                 const docContents = processedDocs.map((doc)=>{
                     let header = `===== ${doc.name} =====`;
                     if (doc.codeBlockCount > 0) header += `\n[注意: 此文档原有 ${doc.originalLines} 行，包含 ${doc.codeBlockCount} 个代码块已被隐藏。使用 get_semi_code_block 工具查看具体代码]`;
-                    return `${header}\n\n${doc.content}`;
+                    const url = generateDocumentUrl(doc.path);
+                    const urlFooter = url ? `\n\n文档链接: ${url}` : '';
+                    return `${header}\n\n${doc.content}${urlFooter}`;
                 }).join('\n\n');
                 return {
                     content: [
@@ -452,7 +555,11 @@ async function handleGetSemiDocument(args) {
                     ]
                 };
             }
-            const docContents = result.documents.map((doc)=>`===== ${doc.name} =====\n\n${doc.content}`).join('\n\n');
+            const docContents = result.documents.map((doc)=>{
+                const url = generateDocumentUrl(doc.path);
+                const urlFooter = url ? `\n\n文档链接: ${url}` : '';
+                return `===== ${doc.name} =====\n\n${doc.content}${urlFooter}`;
+            }).join('\n\n');
             return {
                 content: [
                     {

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

@@ -17,6 +17,12 @@ export declare function replaceCodeBlocksWithPlaceholders(content: string, compo
  * 工具定义：获取 Semi Design 组件文档
  */
 export declare const getSemiDocumentTool: Tool;
+/**
+ * 从文档路径生成 URL
+ * @param docPath - 文档路径，格式：/content/{category}/{componentName}/index.md
+ * @returns URL，格式：https://semi.design/zh-CN/{category}/{componentName}
+ */
+export declare function generateDocumentUrl(docPath: string): string;
 /**
  * 工具处理器：处理 get_semi_document 工具调用
  */

package/package.json

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