開發者指南 - Aspose MCP Server

📁 倉庫結構

aspose-mcp-server/ ├── Tools/ 📁 工具原始碼（MCP Tool 入口點） │ ├── Word/ 27 個工具 │ ├── Excel/ 31 個工具 │ ├── PowerPoint/ 25 個工具 │ ├── PDF/ 19 個工具 │ ├── OCR/ 2 個工具 │ ├── Email/ 6 個工具 │ ├── BarCode/ 2 個工具 │ ├── Conversion/ 2 個工具 │ ├── Session/ 1 個工具 │ └── Extension/ 1 個工具 ├── Handlers/ 📁 操作處理器（業務邏輯實作） │ ├── Word/ Word 處理器 │ ├── Excel/ Excel 處理器 │ ├── PowerPoint/ PowerPoint 處理器 │ └── Pdf/ PDF 處理器 ├── Helpers/ 🛠️ 通用輔助工具 │ ├── Excel/ Excel 專用 Helper │ ├── Word/ Word 專用 Helper │ ├── PowerPoint/ PowerPoint 專用 Helper │ └── Pdf/ PDF 專用 Helper ├── Results/ 📊 結果類型定義 │ ├── Common/ 通用結果類型 │ ├── Word/ Word 操作結果 │ ├── Excel/ Excel 操作結果 │ ├── PowerPoint/ PowerPoint 操作結果 │ └── Pdf/ PDF 操作結果 ├── Core/ 🔧 MCP 伺服器核心 │ ├── Handlers/ Handler 基礎架構 │ ├── Security/ 安全模組（認證、Origin 驗證） │ ├── Session/ Session 管理模組 │ ├── Progress/ 📊 MCP Progress 支援（文檔處理進度回報） │ ├── Tracking/ 追蹤模組 │ ├── Transport/ 傳輸層模組 │ ├── Extension/ 擴展系統模組（24 類別） │ │ └── Transport/ 傳輸層（mmap、stdin、file） │ ├── Conversion/ 文件轉換模組 │ └── ShapeDetailProviders/ PowerPoint 形狀詳細資訊提供者 ├── Tests/ 🧪 單元測試與整合測試 │ ├── Core/ 核心功能測試 │ ├── Handlers/ Handler 測試 │ ├── Tools/ 工具測試 │ ├── Helpers/ Helper 單元測試 │ ├── Integration/ 整合測試（Auth、Config、Schema、Session、Transport） │ └── Infrastructure/ 測試基礎設施 ├── deploy/ 🚢 部署配置 ├── docs/ 📚 GitHub Pages 文檔 ├── .github/workflows/ 🔄 GitHub Actions └── bin/ ❌ 本地編譯輸出（不在版本控制）

🏗️ 架構設計

Tool-Handler 模式

專案採用 Tool-Handler 分離架構，Tool 負責 MCP 介面，Handler 負責業務邏輯：

Tool.Execute(operation, ...) ↓ HandlerRegistry.GetHandler(operation) ↓ Handler.Execute(context, parameters) ↓ ResultHelper.FinalizeResult(result, context) ↓ 結構化輸出（含 outputSchema）

結構化輸出（outputSchema）

所有 Handler 回傳強型別結果物件，SDK 自動生成 outputSchema：

[ResultType(typeof(TResult))] - Handler 聲明結果類型
[ToolHandlerMapping("namespace")] - Tool 聲明對應的 Handler namespace
OutputSchemaGenerator - 從 Handler namespace 收集結果類型，生成 oneOf JSON Schema

Tool Annotations

所有工具使用 MCP SDK 0.6.0 的 Tool Annotations 描述行為特性：

Title - 人類可讀的工具標題
ReadOnly - 是否只讀取不修改
Destructive - 是否可能造成破壞性變更
Idempotent - 重複調用是否產生相同結果
OpenWorld = false - 所有工具都是本地檔案操作

結果類型目錄結構

結果類型按文檔類型和操作類別組織在 Results/：

Common/ - 通用結果類型（SuccessResult 等）
Word/Content/ - Word 內容操作結果
Excel/Cell/ - Excel 儲存格操作結果
PowerPoint/Slide/ - PowerPoint 投影片操作結果
Pdf/Page/ - PDF 頁面操作結果

💻 本地開發

1. 複製倉庫

            git clone https://github.com/xjustloveux/aspose-mcp-server.git
            cd aspose-mcp-server
        

2. 編譯 Release 版本

pwsh deploy/build.ps1 --configuration Release

3. 發布版本

發布 Windows 版本：

pwsh deploy/publish.ps1 -Windows

發布所有平台：

pwsh deploy/publish.ps1 -All

🌍 多平台構建

GitHub Actions 會在推送到 main/master 分支時自動構建所有平台版本。

支援的平台

✅ Windows (x64) - win-x64
✅ Linux (x64) - linux-x64
✅ macOS Intel (x64) - osx-x64
✅ macOS ARM (arm64 - M1/M2/M3) - osx-arm64

本地構建

發布 Windows 版本：

pwsh deploy/publish.ps1 -Windows

發布 Linux 版本：

pwsh deploy/publish.ps1 -Linux

發布 macOS 版本（Intel + ARM）：

pwsh deploy/publish.ps1 -MacOS

發布所有平台：

pwsh deploy/publish.ps1 -All

清理後構建：

pwsh deploy/publish.ps1 -All -Clean

構建產物位置

Windows: publish/windows-x64/AsposeMcpServer.exe
Linux: publish/linux-x64/AsposeMcpServer
macOS Intel: publish/macos-x64/AsposeMcpServer
macOS ARM: publish/macos-arm64/AsposeMcpServer

注意： 構建產物為自包含單一可執行檔案，無需安裝 .NET Runtime 即可運行。

🧪 運行測試

本專案包含完整的單元測試套件，使用 xUnit 測試框架。推薦使用 test.ps1 腳本運行測試，它提供了 UTF-8 編碼支援和便捷的參數選項。

測試統計

測試類: 730+ 個測試類（含 Core、Security、Session 測試）
測試用例: 9,000+ 個測試用例
測試框架: xUnit 2.9.3

運行測試

運行所有測試：

pwsh test.ps1

運行測試（詳細輸出）：

pwsh test.ps1 -Verbose

運行測試並收集覆蓋率：

pwsh test.ps1 -Coverage

運行特定類別的測試：

pwsh test.ps1 -Filter "FullyQualifiedName~Word"

test.ps1 參數說明

-Verbose - 顯示詳細測試輸出
-NoBuild - 跳過構建步驟（使用已構建的版本）
-Coverage - 收集測試覆蓋率數據
-Filter <filter> - 過濾特定測試（支援 dotnet test 的過濾語法）
-SkipLicense - 跳過授權載入，強制使用評估模式

測試結構

Tests/Core/ - 核心功能測試（Handlers、Helpers、Security、Session、Tracking、Extension）
Tests/Handlers/ - Handler 測試（531 個測試類）
- Word/ - Word Handler 測試
- Excel/ - Excel Handler 測試
- PowerPoint/ - PowerPoint Handler 測試
- Pdf/ - PDF Handler 測試
- Ocr/ - OCR Handler 測試
- Email/ - Email Handler 測試
- BarCode/ - BarCode Handler 測試
Tests/Tools/Word/ - Word 工具測試（27 個測試類）
Tests/Tools/Excel/ - Excel 工具測試（31 個測試類）
Tests/Tools/PowerPoint/ - PowerPoint 工具測試（25 個測試類）
Tests/Tools/Pdf/ - PDF 工具測試（19 個測試類）
Tests/Tools/Ocr/ - OCR 工具測試（2 個測試類）
Tests/Tools/Email/ - Email 工具測試（6 個測試類）
Tests/Tools/BarCode/ - BarCode 工具測試（2 個測試類）
Tests/Tools/Conversion/ - 轉換工具測試（2 個測試類）
Tests/Helpers/ - Helper 單元測試（Excel、Word、PowerPoint、PDF Helper 測試）
Tests/Infrastructure/ - 測試基礎設施（TestBase、WordTestBase、ExcelTestBase、PdfTestBase、HandlerTestBase）

CI/CD 集成

測試已集成到 GitHub Actions 工作流中
每次推送或創建 Pull Request 時會自動運行測試
測試在評估模式下運行（無需授權檔案）

🔍 代碼品質檢查

本專案使用 JetBrains 工具進行代碼品質檢查和格式化。推薦使用 code-quality.ps1 腳本運行代碼檢查。

運行代碼品質檢查

執行 CleanupCode 和 InspectCode（預設）：

pwsh code-quality.ps1

只執行 CleanupCode（代碼格式化）：

pwsh code-quality.ps1 -CleanupCode

只執行 InspectCode（代碼檢查）：

pwsh code-quality.ps1 -InspectCode

code-quality.ps1 參數說明

-CleanupCode - 執行 JetBrains CleanupCode（代碼格式化）
-InspectCode - 執行 JetBrains InspectCode（代碼檢查，輸出到 report.xml）
-Profile <profile> - 指定 CleanupCode 配置檔（預設：Built-in: Full Cleanup）
-Exclude <patterns> - 排除的文件模式（預設：*.txt）

注意事項

code-quality.ps1 腳本會自動設置 UTF-8 編碼，確保中文輸出正常顯示
CleanupCode 會格式化代碼，HTML 文件也會被格式化（但 CSS 確保程式碼區塊不會跑版）
InspectCode 會生成 report.xml 報告文件，可用於分析代碼問題

🔧 核心組件

Core/Handlers/

Handler 基礎架構：IOperationHandler（介面）、OperationHandlerBase（基類）、OperationContext（上下文）、OperationParameters（參數）、HandlerRegistry（註冊器）。實現 Tool 與業務邏輯的分離。

Handlers/

操作處理器：531 個 Handler 實作業務邏輯。每個 Handler 對應一個操作（如 AddWordBookmarkHandler），並透過 HandlerRegistry 註冊。100% 單元測試覆蓋（531 個測試類）。

Helpers/

通用輔助工具：SecurityHelper（安全驗證）、ColorHelper（顏色處理）、FontHelper（字型設定）、ValueHelper（值轉換）等。包含各文檔類型的專用 Helper（Excel/、Word/、PowerPoint/、Pdf/）。

Results/

結果類型定義：所有操作的結構化輸出類型，按文檔類型和操作類別組織（Common/、Word/、Excel/、PowerPoint/、Pdf/）。

Core/Security/

認證模組：API Key 認證、JWT 認證中間件，支援多種驗證模式。

Core/Tracking/

追蹤模組：結構化日誌、Webhook 通知、Prometheus Metrics 中間件。

Core/Session/

Session 管理模組：DocumentSession（會話生命週期）、DocumentSessionManager（並發管理）、SessionConfig（配置）等。

Core/Extension/

擴展系統模組：ExtensionManager（擴展實例管理）、ExtensionSessionBridge（Session 橋接）、SnapshotManager（快照管理），支援 mmap、stdin、file 三種傳輸方式。

Core/Conversion/

文件轉換模組：DocumentConversionService（統一轉換服務），支援 Word、Excel、PowerPoint、PDF 之間的文件格式轉換。

ServerConfig.cs

伺服器配置管理，處理命令行參數和環境變數，支援三種傳輸模式。

LicenseManager.cs

授權管理：自動搜尋授權檔案、環境變數配置、組件授權載入。

🛠️ 開發者指南