power-platform-mcp-connector-suite

Power Platform MCP Connector Suite

產生完整的 Power Platform 自訂連接器實作，並整合 Model Context Protocol 至 Microsoft Copilot Studio。

Copilot Studio 中的 MCP 功能

目前已支援：

• ✅ 工具 (Tools)：LLM 可呼叫的函式（需使用者核准）
• ✅ 資源 (Resources)：代理程式可讀取的檔案型資料（必須為工具輸出）

尚未支援：

• ❌ 提示 (Prompts)：預先撰寫的範本（請為未來支援做好準備）

連接器產生

建立完整的 Power Platform 連接器，包含：

核心檔案：

• apiDefinition.swagger.json 包含 x-ms-agentic-protocol: mcp-streamable-1.0
• apiProperties.json 包含連接器中繼資料與驗證
• script.csx 包含自訂 C# 轉換，用於 MCP JSON-RPC 處理
• readme.md 包含連接器文件

MCP 整合：

• POST /mcp 端點用於 JSON-RPC 2.0 通訊
• McpResponse 與 McpErrorResponse 結構描述定義
• 符合 Copilot Studio 限制（無參考型別、單一型別）
• 資源整合為工具輸出（支援資源與工具；提示尚未支援）

結構描述驗證與問題排除

驗證結構描述是否符合 Copilot Studio 規範：

• ✅ 工具輸入/輸出中無參考型別 ($ref)
• ✅ 僅使用單一型別值（非 ["string", "number"]）
• ✅ 基本型別：string、number、integer、boolean、array、object
• ✅ 資源作為工具輸出，而非獨立實體
• ✅ 所有端點使用完整 URI

常見問題與修正：

• 工具被過濾 → 移除參考型別，使用基本型別
• 型別錯誤 → 使用單一型別搭配驗證邏輯
• 資源無法使用 → 納入工具輸出
• 連線失敗 → 確認 x-ms-agentic-protocol 標頭

上下文變數

• 連接器名稱：[連接器的顯示名稱]
• 伺服器用途：[MCP 伺服器應達成的目標]
• 所需工具：[要實作的 MCP 工具清單]
• 資源：[要提供的資源類型]
• 驗證方式：[none、api-key、oauth2、basic]
• 主機環境：[Azure Function、Express.js 等]
• 目標 API：[要整合的外部 API]

產生模式

模式 1：全新連接器

從頭產生所有 Power Platform MCP 連接器檔案，包含 CLI 驗證設定。

模式 2：結構描述驗證

使用 paconn 與驗證工具分析並修正現有結構描述，使其符合 Copilot Studio 規範。

模式 3：整合問題排除

使用 CLI 除錯工具診斷並解決 Copilot Studio 的 MCP 整合問題。

模式 4：混合連接器

為現有 Power Platform 連接器新增 MCP 功能，並搭配適當的驗證工作流程。

模式 5：認證準備

準備連接器以提交 Microsoft 認證，包含完整中繼資料與驗證合規。

模式 6：OAuth 安全性強化

實作 OAuth 2.0 驗證，並結合 MCP 安全最佳實務與進階權杖驗證。

預期輸出

1. apiDefinition.swagger.json

• Swagger 2.0 格式，包含 Microsoft 擴充功能
• MCP 端點：POST /mcp 搭配正確的通訊協定標頭
• 符合規範的結構描述定義（僅基本型別）
• McpResponse/McpErrorResponse 定義

2. apiProperties.json

• 連接器中繼資料與品牌（需有 iconBrandColor）
• 驗證設定
• MCP 轉換的原則範本

3. script.csx

• JSON-RPC 2.0 訊息處理
• 請求/回應轉換
• MCP 通訊協定合規邏輯
• 錯誤處理與驗證

4. 實作指引

• 工具註冊與執行模式
• 資源管理策略
• Copilot Studio 整合步驟
• 測試與驗證程序

驗證檢查清單

技術合規

• [ ] MCP 端點包含 x-ms-agentic-protocol: mcp-streamable-1.0
• [ ] 所有結構描述定義中無參考型別
• [ ] 所有型別欄位皆為單一型別（非陣列）
• [ ] 資源包含在工具輸出中
• [ ] script.csx 符合 JSON-RPC 2.0 規範
• [ ] 所有端點使用完整 URI
• [ ] 為 Copilot Studio 代理程式提供清楚說明
• [ ] 驗證設定正確
• [ ] MCP 轉換的原則範本
• [ ] 與生成式協調相容

CLI 驗證

• [ ] paconn validate：paconn validate --api-def apiDefinition.swagger.json 通過無錯誤
• [ ] pac CLI 就緒：可使用 pac connector create/update 建立/更新連接器
• [ ] 指令碼驗證：script.csx 在 pac CLI 上傳期間通過自動驗證
• [ ] 套件驗證：ConnectorPackageValidator.ps1 成功執行

OAuth 與安全需求

• [ ] OAuth 2.0 強化：標準 OAuth 2.0 搭配 MCP 安全最佳實務實作
• [ ] 權杖驗證：實作權杖對象驗證以防止傳遞攻擊
• [ ] 自訂安全邏輯：在 script.csx 中為 MCP 合規進行強化驗證
• [ ] 狀態參數保護：保護狀態參數以防止 CSRF
• [ ] HTTPS 強制：所有生產端點僅使用 HTTPS
• [ ] MCP 安全實務：在 OAuth 2.0 中實作混淆代理人攻擊防護

認證需求

• [ ] 完整中繼資料：settings.json 包含產品與服務資訊
• [ ] 圖示合規：PNG 格式，尺寸 230x230 或 500x500
• [ ] 文件：準備好認證的 readme，包含完整範例
• [ ] 安全合規：OAuth 2.0 強化搭配 MCP 安全實務、隱私權政策
• [ ] 驗證流程：OAuth 2.0 搭配自訂安全驗證正確設定

使用範例

模式：全新連接器
連接器名稱：客戶分析 MCP
伺服器用途：客戶資料分析與洞察
所需工具：
  - searchCustomers：依條件搜尋客戶
  - getCustomerProfile：擷取詳細客戶資料
  - analyzeCustomerTrends：產生趨勢分析
資源：
  - 客戶資料（JSON 資料）
  - 分析報告（結構化資料）
驗證方式：oauth2
主機環境：Azure Function
目標 API：CRM REST API