❓ 常見問答

常見問題解答

🚀 快速開始相關

Q: 如何確認工具是否正常運行？

啟動 MCP 客戶端後，檢查工具列表是否包含 word_*、excel_* 等工具。如果沒有，請檢查：

  1. 配置檔案路徑是否正確
  2. 可執行檔案是否有執行權限（Linux/macOS）
  3. 授權檔案是否正確配置
  4. 查看 MCP 客戶端的錯誤日誌
Q: 可以同時啟用多個工具類型嗎？

可以。不帶任何工具參數時，預設啟用所有工具。也可以使用 --all 達到相同效果，或指定多個參數只啟用部分工具：

{ "args": ["--word", "--excel", "--pdf"] }
Q: 轉換工具何時可用？
  • convert_document：啟用任何文檔工具（--word、--excel、--ppt、--pdf）時自動可用，支援跨格式轉換、Word/Excel/PDF 轉圖片、特殊格式轉 PDF
Q: 支援哪些文檔格式？
  • Word: DOC、DOCX、RTF、ODT、HTML、TXT 等
  • Excel: XLS、XLSX、CSV、ODS、HTML 等
  • PowerPoint: PPT、PPTX、ODP、HTML 等
  • PDF: PDF（讀寫、編輯、簽名等）
  • Email: EML、MSG、EMLX、MHT、ICS、VCF 等
  • BarCode: QR、Code128、EAN13、DataMatrix、PDF417 等（產生與辨識）
Q: 如何在 Linux/macOS 上設置執行權限？

使用 .tar.gz 格式下載的版本已包含執行權限。如遇權限問題：

chmod +x AsposeMcpServer

macOS 還需移除系統隔離標記（僅需一次）：

xattr -d com.apple.quarantine AsposeMcpServer

或使用 Homebrew 安裝可自動處理：brew install xjustloveux/tap/aspose-mcp-server

Q: Linux/macOS 需要安裝 libgdiplus 嗎？

不需要。所有功能已原生支援跨平台運行：

  • PowerPoint 使用 Aspose.Slides.NET6.CrossPlatform（內建 C++ 圖形引擎）
  • PDF 使用 Aspose.PDF.Drawing（Aspose.Drawing 後端）
  • Word / Excel 透過 SkiaSharp 原生資源提供圖形支援

Linux 環境建議安裝字型套件（fonts-liberation 或 ttf-mscorefonts-installer）以確保文檔正確呈現。macOS 已內建常用字型，無需額外安裝。

🔑 授權配置相關

Q: 為什麼生成的文檔有試用版標記？

這表示授權檔案未正確載入。請檢查：

  1. 授權檔案路徑是否正確
  2. 授權檔案是否與 Aspose 版本相容（當前版本：23.10.0）
  3. 授權檔案是否有效且未過期
Q: 找不到授權檔案會怎樣？

如果找不到授權檔案，系統會以試用模式運行，生成的文檔會有試用版標記。

Q: 支援哪些授權類型？
  • 總授權：Aspose.Total.lic（包含所有組件，推薦）
  • 單一組件授權：Aspose.Words.lic、Aspose.Cells.lic、Aspose.Slides.lic、Aspose.Pdf.lic
Q: 如何配置授權檔案？

有三種方式（按優先順序）：

  1. 命令列參數（最高優先級）：--license:路徑 或 --license=路徑
  2. 環境變數：設定 ASPOSE_LICENSE_PATH 環境變數
  3. 自動搜尋（預設）：在可執行檔案同一目錄搜尋常見授權檔案名稱
Q: 本專案的源代碼使用什麼授權？

本專案的源代碼採用 MIT License 授權。

您可以：

  • ✅ 自由使用、修改和分發源代碼
  • ✅ 用於商業或非商業項目
  • ✅ 私有使用

注意：雖然源代碼使用 MIT License，但使用本專案需要有效的 Aspose 授權檔案才能正常運行（Aspose 是商業軟體）。

Q: 評估模式（無授權）有什麼限制？

在無授權（評估模式）下運行時，Aspose 組件會有以下限制：

組件 限制說明
Aspose.Words 字型格式（名稱、大小、顏色）可能無法正確應用；文檔會包含評估版水印
Aspose.Cells 多工作表操作受限（如跨工作表存取）；工作簿會包含評估版工作表
Aspose.Slides 文字替換時可能包含水印文字；投影片可能包含評估版標記
Aspose.PDF 集合限制為最多 4 個元素（如頁面數限制）；PDF 會包含評估版水印
💡 注意事項
  • 大部分基本操作（讀取、創建、簡單編輯）在評估模式下仍可正常運行
  • 評估模式適合測試和開發，但不建議用於生產環境
  • 使用 test.ps1 -SkipLicense 可在評估模式下運行單元測試

🔢 索引行為相關

Q: 為什麼刪除操作後索引會變化？

當執行刪除操作（如刪除段落、表格、圖片等）後，後續元素的索引會自動調整。這是正常行為，因為索引是基於當前文檔狀態的。

建議：在執行刪除操作後，重新使用 get 操作獲取最新的索引列表。

範例：

1. word_image(operation='get', path='doc.docx') # 返回圖片索引: 0, 1, 2 2. word_image(operation='delete', path='doc.docx', imageIndex=1) # 刪除索引1的圖片 3. word_image(operation='get', path='doc.docx') # 現在返回: 0, 1 (原索引2變成1)
Q: paragraphIndex 的有效範圍是什麼？

有效範圍：0 到 段落總數-1，或使用 -1 表示最後一個段落。

  • 使用 get 操作可以獲取當前文檔的段落總數
  • 某些操作（如 word_hyperlink 的 add）會在指定段落之後創建新段落，而不是插入到段落內部
  • 刪除段落後，後續段落的索引會自動調整

⚙️ 功能使用相關

Q: 轉換功能什麼時候自動可用？
  • 啟用任何文檔工具（--word、--excel、--ppt、--pdf）時，自動包含 convert_document（跨格式轉換，支援 Word/Excel/PDF 轉圖片、特殊格式轉 PDF）
Q: 參數命名有哪些兼容方式？

為了向後兼容，某些參數支援多種命名方式：

  • startColumn / startCol
  • columnIndex / colIndex
  • tableIndex / sourceTableIndex
  • text / replyText (用於評論回覆)
Q: 可以自訂工具嗎？

可以。工具使用 MCP SDK 的 [McpServerToolType] 屬性自動發現：

  1. 創建新的工具類並添加 [McpServerToolType] 屬性
  2. 遵循命名約定（*Tool.cs）
  3. 放在對應的 Tools/ 子目錄中
  4. 工具會透過 MCP SDK 自動註冊

🔒 安全與錯誤相關

Q: 錯誤訊息顯示路徑無效怎麼辦？

檢查：

  1. 路徑是否使用正確的分隔符（Windows 可用 / 或 \\）
  2. 路徑長度是否超過 260 字元（Windows 限制）
  3. 檔案名稱是否包含非法字元
  4. 是否啟用了絕對路徑（某些工具可能需要）
Q: 如何查看詳細的錯誤資訊？

檢查 MCP 客戶端的錯誤日誌。生產環境中，詳細錯誤資訊會被清理以防止資訊洩露。開發環境（DEBUG 模式）會顯示完整錯誤資訊。

Q: 有哪些安全限制？
  • 最大路徑長度：260 字元
  • 最大檔案名稱長度：255 字元
  • 最大陣列大小：1000 項
  • 最大字串長度：10000 字元