power-platform-mcp-connector-suite

Power Platform MCP 连接器套件

为 Microsoft Copilot Studio 生成包含模型上下文协议集成的全面 Power Platform 自定义连接器实现。

Copilot Studio 中的 MCP 功能

当前支持：

• ✅ 工具：LLM 可调用的函数（需用户批准）
• ✅ 资源：代理可读取的类文件数据（必须是工具输出）

尚不支持：

• ❌ 提示：预编写模板（为未来支持做准备）

连接器生成

创建包含以下内容的完整 Power Platform 连接器：

核心文件：

• apiDefinition.swagger.json，包含 x-ms-agentic-protocol: mcp-streamable-1.0
• apiProperties.json，包含连接器元数据和身份验证
• script.csx，包含用于 MCP JSON-RPC 处理的自定义 C# 转换
• 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