Aspose MCP Server

格式支援：

基於 .NET 8.0 和 Aspose.Total 的 Model Context Protocol (MCP) 伺服器，為 MCP 客戶端提供強大的辦公文檔處理能力。

✨ 特性

核心功能

• 118 個統一工具 - Word(28)、Excel(32)、PowerPoint(26)、PDF(19)、OCR(2)、Email(6)、BarCode(2)、轉換(1)、Session(1)、Extension(1) 已整合
• 按需啟用 - 只啟用需要的文檔類型，減少資源佔用
• 跨平台 - Windows、Linux、macOS (Intel + ARM)，單一可執行檔案
• 開箱即用 - 預編譯版本無需安裝 .NET Runtime
• 完整讀寫 - 支援從A文檔讀取格式應用到B文檔

傳輸模式

• Stdio 模式 (預設) - 標準輸入輸出，適用於本地 MCP 客戶端
• HTTP 模式 - Streamable HTTP（MCP 2025-03-26+），適用於網頁應用
• WebSocket 模式 - 雙向通訊，適用於即時互動

進階功能

• Session 管理 - 在記憶體中編輯文件，支援 open/save/close 操作，支援多租戶隔離
• 擴充功能系統 - 外部程序訂閱 Session 變更，實現即時預覽、雲端同步、合規檢查等
• 認證機制 - 可選的 API Key 和 JWT 認證（4 種驗證模式）
• 追蹤系統 - 結構化日誌、Webhook 通知、Prometheus Metrics
• Origin 驗證 - 防止 DNS 重綁定攻擊（HTTP/WebSocket 模式）

技術特性

• MCP SDK 1.4.0 - 使用官方 ModelContextProtocol NuGet 套件，支援 Tool Annotations 和 outputSchema
• Tool Annotations - 所有工具標註 ReadOnly、Destructive、Idempotent、OpenWorld 行為特性
• 結構化輸出 - Handler 返回強型別結果，SDK 自動生成 outputSchema（oneOf JSON Schema）
• 統一字型設定 - 多個工具支援中英文字型分別設定（fontNameAscii 和 fontNameFarEast 參數）
• 靈活的授權配置 - 支援總授權或單一組件授權，自動搜尋、環境變數或命令列參數配置
• 安全加固 - 全面的路徑驗證、輸入驗證和錯誤處理

🚀 快速開始

1. 下載

方法 A：從 GitHub Releases 下載

從 GitHub Releases 下載對應平台版本：

方法 B：macOS 使用 Homebrew 安裝（推薦）

brew install xjustloveux/tap/aspose-mcp-server

2. 配置 MCP 客戶端

{
  "mcpServers": {
    "aspose-word": {
      "command": "C:/Tools/aspose-mcp-server/AsposeMcpServer.exe",
      "args": ["--word"]
    }
  }
}

可用參數（不帶任何工具參數時，預設啟用所有工具）:

• --word - Word 工具（自動包含轉換功能）
• --excel - Excel 工具（自動包含轉換功能）
• --powerpoint / --ppt - PowerPoint 工具（自動包含轉換功能）
• --pdf - PDF 工具
• --ocr - OCR 文字辨識工具
• --email - Email 工具
• --barcode - BarCode 工具
• --all - 所有工具（等同不帶工具參數）
• --session-enabled - 啟用 Session 管理（document_session 工具）
• --extension-enabled - 啟用擴充功能系統（需搭配 --session-enabled）
• --extension-config 路徑 - 指定擴充功能配置檔案路徑（extension 工具）
• --license 路徑 - 指定授權檔案路徑（可選）
• --allowed-path 路徑 - 限制檔案存取於指定基礎目錄下（可重複指定；未指定則不限制，建議在 HTTP/WebSocket 部署時啟用）
• --max-extract-all-bytes 位元組 - OLE 工具單次 extract_all 累計寫出上限（預設 10 GiB；≤ 0 表示不設上限；環境變數 MAX_EXTRACT_ALL_BYTES）

工具過濾：指定工具參數時，只有啟用的工具類別會出現在 MCP 工具列表中。例如使用 --word 時，只會顯示 word_* 相關工具。

轉換功能說明：

• 啟用任何文檔工具（--word、--excel、--ppt、--pdf）時，自動包含 convert_document（跨格式轉換，支援 Word/Excel/PDF 轉圖片、特殊格式轉 PDF）

📋 更多配置範例： config_example.json（配置格式適用於所有 MCP 客戶端）

3. 重啟 MCP 客戶端

完成配置後，重啟您使用的 MCP 客戶端（如 Claude Desktop、Cursor 等）即可開始使用。

🖥️ Claude Desktop Extension (.mcpb)

Claude Desktop 使用者可將 Aspose MCP Server 以原生擴充功能安裝，繞過 Linux 沙箱限制，讓 Windows 路徑（C:\Users\...）直接可用。

三步驟安裝：

1. 從 GitHub Releases 下載對應平台的 .mcpb 檔案。
2. 雙擊檔案 — Claude Desktop 會開啟安裝對話框。
3. 依提示選擇 Aspose.Total.lic 授權檔；若跳過則以評估模式執行（輸出文件將帶有 Aspose 浮水印）。

macOS 使用者：Claude Desktop 會自動處理隔離標記，無需手動執行 xattr 指令。

非 Claude Desktop 客戶端（Cursor、Continue 等）請使用 .zip / .tar.gz 安裝方式，詳見 快速開始。

📦 功能概覽

📖 完整工具列表與操作說明請參閱 工具列表

🔌 傳輸模式

環境變數：

注意: Docker/Kubernetes 部署時需設定 ASPOSE_HOST=0.0.0.0 以便容器外部可以訪問。

🔒 安全特性

• 路徑驗證 - 所有檔案路徑經 SecurityHelper.ValidateFilePath() 驗證，防止路徑遍歷攻擊；額外拒絕控制字元、NTFS Alternate Data Stream 冒號語法、路徑段末尾點號/空白、及 Windows 保留裝置名稱（CON/NUL/COM1–9 等）；符號連結（symbolic link）在任何 I/O 操作前均會解析至最終目標，並再次比對白名單，確保符號連結無法繞過路徑限制
• 路徑白名單（可選強化）- 透過 --allowed-path 限制檔案存取於指定基礎目錄下（可重複指定）；未設定時不限制，建議 HTTP/WebSocket 部署時啟用；符號連結的最終目標若位於白名單之外，將被拒絕
• 輸入驗證 - 陣列大小上限 1000 項、字串長度上限 10000 字元
• 錯誤處理 - 結構化錯誤翻譯器（per-family translator 模式）將 Aspose/BCL 例外對應為固定安全哨兵字串；移除路徑、堆疊追蹤等敏感資訊，確保原始例外訊息不傳遞給呼叫方
• Origin 驗證 - HTTP/WebSocket 模式預設啟用，防止 DNS 重綁定攻擊

📖 完整安全配置請參閱 功能特性

🌍 跨平台支援

跨平台方案： PowerPoint 使用 Aspose.Slides.NET6.CrossPlatform、PDF 使用 Aspose.PDF.Drawing、Word/Excel 使用 SkiaSharp，全部無需外部圖形庫。

Linux 字型： 建議安裝 fonts-liberation（英文）和 fonts-noto-cjk（中日韓文），Docker 映像已內建基本 CJK 字型。

📖 詳細平台需求與字型配置請參閱 部署指南

📄 授權

本專案源代碼採用 MIT License 授權。運行時需要 Aspose 授權，支援：

• Aspose.Total.lic - 總授權（包含所有組件，推薦）
• 單一組件授權：Aspose.Words.lic、Aspose.Cells.lic、Aspose.Slides.lic、Aspose.Pdf.lic、Aspose.OCR.lic、Aspose.Email.lic、Aspose.BarCode.lic

配置方式（按優先順序）：

1. 命令列參數：--license 路徑
2. 環境變數：ASPOSE_LICENSE_PATH
3. 自動搜尋（預設）：在可執行檔案同一目錄搜尋

找不到授權時以試用模式運行（文檔含評估版標記）。使用 test.ps1 -SkipLicense 可在評估模式下運行測試。

⚠️ 重要說明

索引行為說明

索引在刪除操作後會變化：

• 當執行刪除操作（如刪除段落、表格、圖片等）後，後續元素的索引會自動調整
• 建議：在執行刪除操作後，重新使用 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)

Word 段落定址（paragraphIndex，僅 word_ 工具）：*

• paragraphIndex 是**故事相對（story-relative）**索引：「該故事內」的 0-based 位置（預設 Body），不是全文件全域索引。範圍 0～「該故事段落數-1」，-1 表示最後一段。
• 定址非 Body 故事時加 storyType（Body/Header/Footer/TextBox/Comment/Footnote/Endnote），必要時搭配 sectionIndex/headerFooterType/containerIndex。
• get（及 word_text 的 search）會回報每段的 storyType＋paragraphIndex，原樣帶回即可定址同一段；session 模式另回傳穩定的 handle，索引位移後仍精準命中。
• 某些操作會在指定段落之後創建新段落，而不是插入到段落內部。

參數命名一致性： 為向後兼容，某些參數支援多種命名（如 startColumn / startCol、columnIndex / colIndex）。

📝 使用範例

從A文檔複製格式到B文檔

複製段落格式：

1. word_paragraph(path="A.docx", operation="get_format", paragraphIndex=0)
2. 使用返回的格式資訊
3. word_paragraph(path="B.docx", operation="edit", paragraphIndex=0, ...)

複製樣式：

word_style(path="B.docx", operation="copy_styles", sourceDocument="A.docx")

🔗 相關資源

📖 進階主題（Session 管理、認證機制、追蹤系統、部署指南、開發者指南、常見問答）請參閱 完整文檔。