botrun-horse 2.29.2 → 2.31.0

package/botrun-c/dev/mcp-token-calculator/calculate-mcp-tokens.ts

@@ -0,0 +1,464 @@
+/**
+ * 計算所有 MCP Server 的 Tool Definitions 會佔用多少 tokens
+ *
+ * 這個腳本會：
+ * 1. 收集所有 8 個 MCP Server 的 tool definitions
+ * 2. 計算每個 tool definition 的 token 數量
+ * 3. 輸出詳細的統計資訊
+ */
+
+import { encoding_for_model } from 'tiktoken';
+
+// 使用 Claude 3.5 Sonnet 的 tokenizer (cl100k_base)
+const encoder = encoding_for_model('gpt-4');
+
+/**
+ * 計算文字的 token 數量
+ */
+function countTokens(text: string): number {
+  const tokens = encoder.encode(text);
+  return tokens.length;
+}
+
+/**
+ * 所有 MCP Server Tool Definitions
+ * 直接從源碼中提取的實際 tool definitions
+ */
+const MCP_TOOLS = [
+  // 1. botrun-pdf-split
+  {
+    name: 'split_pdf',
+    server: 'botrun-pdf-split',
+    description: '拆解多頁 PDF 為單頁檔案。使用 qpdf 確保最佳檔案大小(無膨脹)。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        filePath: {
+          type: 'string',
+          description: 'PDF 檔案的完整路徑或相對路徑',
+        },
+        outputDir: {
+          type: 'string',
+          description: '輸出目錄路徑(可選，預設為 {檔名}_pages)',
+        },
+      },
+      required: ['filePath'],
+    },
+  },
+
+  // 2. botrun-pdf-to-text
+  {
+    name: 'pdf_to_text',
+    server: 'botrun-pdf-to-text',
+    description: '將分頁 PDF 目錄轉換為純文字檔案。使用 pdftotext 確保最佳文字擷取品質。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        inputDir: {
+          type: 'string',
+          description: 'PDF 檔案目錄的完整路徑(例如：分頁後的 PDF 目錄)',
+        },
+        outputDir: {
+          type: 'string',
+          description: '輸出目錄路徑(可選，預設為 {輸入目錄}_text)',
+        },
+      },
+      required: ['inputDir'],
+    },
+  },
+
+  // 3. botrun-secure-rg
+  {
+    name: 'secure_rg_search',
+    server: 'botrun-secure-rg',
+    description: '安全的 ripgrep 搜尋工具。支援完整 rg 參數，但嚴格限制在工作目錄內，防止路徑遍歷攻擊。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pattern: {
+          type: 'string',
+          description: '搜尋的正則表達式模式',
+        },
+        path: {
+          type: 'string',
+          description: '搜尋路徑(相對於工作目錄，可選，預設為 .)',
+        },
+        args: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'ripgrep 額外參數(如 -i, -C 3, --type js 等)',
+        },
+      },
+      required: ['pattern'],
+    },
+  },
+
+  // 4. botrun-secure-read
+  {
+    name: 'read_files',
+    server: 'botrun-secure-read',
+    description:
+      '安全地讀取多個純文字檔案。支援 glob patterns(如 *.txt, src/**/*.js)。只能讀取工作目錄及其子目錄的檔案，防止路徑遍歷攻擊。輸出使用 XML tags 區隔不同檔案，方便 AI 解析。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        patterns: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          description: '檔案路徑或 glob patterns 陣列。範例：["file.txt", "*.md", "src/**/*.ts"]',
+        },
+      },
+      required: ['patterns'],
+    },
+  },
+
+  // 5. botrun-tree-view
+  {
+    name: 'list_files',
+    server: 'botrun-tree-view',
+    description:
+      '列出當前工作目錄的所有檔案(樹狀結構)。當使用者說「列出檔案」、「我想看檔案列表」、「list files」、「檔案列表」、「看檔案」、「看有哪些檔案」、「顯示檔案」、「檔案結構」、「目錄結構」、「tree」、「ls」時使用。無參數，自動列出 process.cwd() 下的所有檔案。',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+
+  // 6. botrun-multimodal-reader
+  {
+    name: 'read_multimodal',
+    server: 'botrun-multimodal-reader',
+    description:
+      '使用 Vertex AI Claude Haiku 4.5(台灣端點)多模態閱讀本地檔案。支援多種格式：\n\n' +
+      '📄 **文件**：PDF, TXT\n' +
+      '🖼️ **圖片**：PNG, JPEG, WebP\n' +
+      '🎬 **影片**：MP4, MOV, WebM, MPEG, FLV, WMV, 3GP\n' +
+      '🎵 **音訊**：MP3, WAV, AAC, FLAC, M4A, Opus, PCM\n\n' +
+      '支援單一檔案、多檔案、或使用萬用字元(如 *.pdf, *.mp4)。可平行處理最多 30 個檔案，理解文字、圖片、圖表、影片、音訊等所有多模態內容。所有路徑嚴格限制在工作目錄內，防止路徑遍歷攻擊。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        filePaths: {
+          type: ['string', 'array'],
+          description:
+            '檔案路徑(字串或字串陣列)。支援萬用字元(如 "*.pdf", "*.mp4", "audio-*.mp3")。所有路徑必須在工作目錄內。\n\n' +
+            '支援的格式：\n' +
+            '- 文件：.pdf, .txt\n' +
+            '- 圖片：.png, .jpg, .jpeg, .webp\n' +
+            '- 影片：.mp4, .mov, .webm, .mpeg, .mpg, .flv, .wmv, .3gp\n' +
+            '- 音訊：.mp3, .wav, .aac, .flac, .m4a, .opus, .pcm\n\n' +
+            '範例：\n' +
+            '- 單一檔案："document.pdf" 或 "video.mp4" 或 "audio.mp3"\n' +
+            '- 多檔案：["page-1.pdf", "video.mp4", "audio.mp3"]\n' +
+            '- 萬用字元："*.pdf" 或 "video-*.mp4" 或 "*.mp3"',
+          items: {
+            type: 'string',
+          },
+        },
+        prompt: {
+          type: 'string',
+          description: '要問的問題或分析指示(可選，預設為完整描述)',
+        },
+      },
+      required: ['filePaths'],
+    },
+  },
+
+  // 7. botrun-web-search
+  {
+    name: 'web_search',
+    server: 'botrun-web-search',
+    description:
+      `使用 Claude Haiku 4.5(台灣端點 asia-east1) + Brave Search 進行網路搜尋。
+
+**核心功能**：
+- 搜尋引擎：Brave Search(Anthropic 提供)
+- 自動取得最新網路資訊
+- 用繁體中文總結結果
+- 回傳來源網址和引證內容
+
+**支援功能**：
+1. 單一查詢或平行多個查詢
+2. 限制搜尋網域(只搜尋特定網站)
+3. 排除特定網域
+4. 本地化搜尋結果
+5. 限制搜尋次數
+
+**回傳內容**：
+- result: 繁體中文總結
+- citations[]: 引用來源(含 url, title, cited_text)
+- sources[]: 搜尋結果來源(含 url, title, page_age)
+- usage: Token 使用統計
+
+**何時使用**：
+- 使用者詢問最新資訊、新聞、天氣、股市等即時資訊
+- 需要引證來源網址時
+- 需要搜尋特定網域的資訊(如政府網站、教育機構)
+- 需要排除不可信來源時`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        queries: {
+          type: ['string', 'array'],
+          description: `**搜尋查詢**(必填)
+
+支援格式：
+- 單一查詢：字串
+- 多個平行查詢：字串陣列
+
+範例：
+- 基本搜尋："台灣今天新聞"
+- 平行搜尋：["台灣今天新聞", "台北天氣", "台股行情"]
+
+使用建議：
+- 查詢要具體明確
+- 多個查詢會平行執行，速度更快
+- 每個查詢獨立回傳結果`,
+          items: {
+            type: 'string',
+          },
+        },
+        max_uses: {
+          type: 'number',
+          description: `**限制搜尋次數**(選填)
+
+限制 Claude 在單次對話中最多執行幾次搜尋。
+
+範例：
+- max_uses: 3(最多搜尋 3 次)
+- max_uses: 1(只搜尋 1 次)
+
+何時使用：
+- 需要控制成本時
+- 快速回應不需要多次搜尋時
+- 避免過度搜尋時`,
+        },
+        allowed_domains: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          description: `**允許的網域白名單**(選填)
+
+只搜尋來自這些網域的結果，其他來源會被過濾。
+
+範例：
+- ["gov.tw", "edu.tw"] → 只搜尋台灣政府和教育機構
+- ["law.moj.gov.tw"] → 只搜尋全國法規資料庫
+- ["wikipedia.org"] → 只搜尋維基百科
+- ["github.com", "stackoverflow.com"] → 只搜尋技術網站
+
+何時使用：
+- 需要權威來源時(政府、教育機構)
+- 需要特定領域資訊時
+- 需要可信度高的內容時
+- 使用者明確要求引證特定網站時
+
+注意：
+- 網域不需要加 https://
+- 可以使用子網域(如 law.moj.gov.tw)
+- 越具體越精確`,
+        },
+        blocked_domains: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          description: `**封鎖的網域黑名單**(選填)
+
+永不包含來自這些網域的搜尋結果。
+
+範例：
+- ["example.com"] → 排除範例網站
+- ["ads-site.com", "spam-site.com"] → 排除廣告和垃圾網站
+
+何時使用：
+- 排除不可信來源
+- 排除廣告網站
+- 使用者明確要求排除特定網站時
+
+注意：
+- 與 allowed_domains 互斥
+- 如果同時設定，allowed_domains 優先`,
+        },
+        user_location: {
+          type: 'object',
+          properties: {
+            type: {
+              type: 'string',
+              enum: ['approximate'],
+            },
+            city: {
+              type: 'string',
+            },
+            region: {
+              type: 'string',
+            },
+            country: {
+              type: 'string',
+            },
+            timezone: {
+              type: 'string',
+            },
+          },
+          description: `**使用者位置(本地化)**(選填)
+
+根據位置本地化搜尋結果，提供更相關的地區性內容。
+
+格式：
+{
+  "type": "approximate",
+  "city": "城市名稱",
+  "region": "地區/州/省",
+  "country": "國家代碼",
+  "timezone": "時區"
+}
+
+範例：
+- 台北：{"type": "approximate", "city": "Taipei", "region": "Taiwan", "country": "TW", "timezone": "Asia/Taipei"}
+- 東京：{"type": "approximate", "city": "Tokyo", "region": "Kanto", "country": "JP", "timezone": "Asia/Tokyo"}
+- 紐約：{"type": "approximate", "city": "New York", "region": "New York", "country": "US", "timezone": "America/New_York"}
+
+何時使用：
+- 搜尋「天氣」、「新聞」等地區性資訊時
+- 搜尋「餐廳」、「景點」等本地服務時
+- 需要特定地區的搜尋結果時
+
+注意：
+- 所有欄位都是選填，但建議至少填 city 和 country
+- country 使用 ISO 3166-1 alpha-2 代碼(如 TW, US, JP)
+- timezone 使用 IANA 時區資料庫格式`,
+        },
+      },
+      required: ['queries'],
+    },
+  },
+
+  // 8. botrun-audio-transcribe
+  {
+    name: 'transcribe_audio_file',
+    server: 'botrun-audio-transcribe',
+    description: `使用 NCHC Whisper 轉錄音訊檔案。支援大檔案自動切割(每 3 分鐘)和平行處理(最多 50 個並發)。`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        filePath: {
+          type: 'string',
+          description: '音訊檔案的路徑(相對於工作目錄或絕對路徑)',
+        },
+        model: {
+          type: 'string',
+          description: 'Whisper 模型名稱(預設: whisper-Breeze-ASR-25)',
+          enum: ['whisper-Breeze-ASR-25', 'Whisper-Large-V3'],
+        },
+      },
+      required: ['filePath'],
+    },
+  },
+];
+
+/**
+ * 主函數：計算並輸出統計資訊
+ */
+function main() {
+  console.log('='.repeat(80));
+  console.log('📊 MCP Server Tool Definitions Token 使用量分析');
+  console.log('='.repeat(80));
+  console.log();
+
+  let totalTokens = 0;
+  const results: Array<{ name: string; server: string; tokens: number; jsonLength: number }> = [];
+
+  // 計算每個 tool 的 token 數量
+  for (const tool of MCP_TOOLS) {
+    const toolJson = JSON.stringify(tool, null, 2);
+    const tokens = countTokens(toolJson);
+    totalTokens += tokens;
+
+    results.push({
+      name: tool.name,
+      server: tool.server,
+      tokens,
+      jsonLength: toolJson.length,
+    });
+  }
+
+  // 排序：按 token 數量降序
+  results.sort((a, b) => b.tokens - a.tokens);
+
+  // 輸出詳細統計
+  console.log('📋 各個 MCP Tool 的 Token 使用量 (按 Token 數量降序)：');
+  console.log();
+  console.log('| # | Tool Name                | Server                      | Tokens | JSON 字元數 |');
+  console.log('|---|--------------------------|-----------------------------| ------:| -----------:|');
+
+  results.forEach((result, index) => {
+    console.log(
+      `| ${String(index + 1).padStart(2, ' ')} | ${result.name.padEnd(24, ' ')} | ${result.server.padEnd(27, ' ')} | ${String(
+        result.tokens
+      ).padStart(6, ' ')} | ${String(result.jsonLength).padStart(11, ' ')} |`
+    );
+  });
+
+  console.log();
+  console.log('='.repeat(80));
+  console.log('📊 總結：');
+  console.log('='.repeat(80));
+  console.log(`總計 MCP Tools 數量: ${MCP_TOOLS.length} 個`);
+  console.log(`總 Token 使用量: ${totalTokens.toLocaleString()} tokens`);
+  console.log(`平均每個 Tool: ${Math.round(totalTokens / MCP_TOOLS.length).toLocaleString()} tokens`);
+  console.log();
+
+  // 計算各種情境下的負擔
+  console.log('='.repeat(80));
+  console.log('💡 不同情境下的 Token 負擔：');
+  console.log('='.repeat(80));
+  console.log();
+
+  // 情境 1: 初始載入所有 tools (ListTools)
+  console.log('1️⃣  初始載入 (ListTools)：');
+  console.log(`   - 一次性載入所有 ${MCP_TOOLS.length} 個 MCP Tools`);
+  console.log(`   - 初始負擔：${totalTokens.toLocaleString()} tokens`);
+  console.log();
+
+  // 情境 2: 每次對話都要傳遞 tools (假設使用 Claude Agent SDK)
+  console.log('2️⃣  每次對話傳遞 Tools (如果使用 allowedTools)：');
+  console.log(`   - 每次 API 呼叫都會傳遞所有 tools 定義`);
+  console.log(`   - 每次對話負擔：${totalTokens.toLocaleString()} tokens`);
+  console.log(`   - 10 次對話：${(totalTokens * 10).toLocaleString()} tokens`);
+  console.log(`   - 100 次對話：${(totalTokens * 100).toLocaleString()} tokens`);
+  console.log();
+
+  // 情境 3: Top 3 最大的 tools
+  const top3 = results.slice(0, 3);
+  const top3Tokens = top3.reduce((sum, r) => sum + r.tokens, 0);
+  console.log('3️⃣  最消耗 Token 的前 3 個 Tools：');
+  top3.forEach((result, index) => {
+    console.log(`   ${index + 1}. ${result.name}: ${result.tokens.toLocaleString()} tokens`);
+  });
+  console.log(`   合計：${top3Tokens.toLocaleString()} tokens (佔總量 ${((top3Tokens / totalTokens) * 100).toFixed(1)}%)`);
+  console.log();
+
+  // 情境 4: 最小的 tools
+  const bottom3 = results.slice(-3).reverse();
+  const bottom3Tokens = bottom3.reduce((sum, r) => sum + r.tokens, 0);
+  console.log('4️⃣  最輕量的 3 個 Tools：');
+  bottom3.forEach((result, index) => {
+    console.log(`   ${index + 1}. ${result.name}: ${result.tokens.toLocaleString()} tokens`);
+  });
+  console.log(`   合計：${bottom3Tokens.toLocaleString()} tokens (佔總量 ${((bottom3Tokens / totalTokens) * 100).toFixed(1)}%)`);
+  console.log();
+
+  console.log('='.repeat(80));
+  console.log('✅ 分析完成！');
+  console.log('='.repeat(80));
+
+  // 清理 encoder
+  encoder.free();
+}
+
+// 執行主函數
+main();