尧图网站建设 
基于 MCP 构建 Microsoft 365 Copilot 声明式 AgentM365 Copilot 插件开发全指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文聚焦于本仓库 instructions/mcp-m365-copilot.instructions.md 所沉淀的 MCP 化 M365 Copilot 开发规范并结合仓库内配套的专家 Agentagents/mcp-m365-agent-expert.agent.md、插件plugins/mcp-m365-copilot/plugin.json与三套实战技能mcp-create-declarative-agent、mcp-create-adaptive-cards、mcp-deploy-manage-agents进行纵深扩充。读完本文你将掌握如何以 Model Context ProtocolMCP为骨架用declarativeAgent.json、ai-plugin.json、mcp.json三个配置文件以声明式方式搭建一个接入外部系统的 Microsoft 365 Copilot Agent如何配置 OAuth 2.0 / SSO 认证、设计 JSONPath 响应语义与 Adaptive Card 模板以及如何完成本地测试、组织级部署、安全审查与治理合规的完整闭环。一、核心原则MCP First 与声明式优先本仓库的 MCP M365 开发规范在 instructions/mcp-m365-copilot.instructions.md 中提出了四条贯穿始终的核心原则它们决定了整个 Agent 的架构取向。1.1 Model Context Protocol FirstMCP 协议优先MCP 是外部系统接入 Copilot 的标准通道规范要求优先引入 MCP Server 作为外部系统集成层而不是为每个外部 API 手写胶水代码从 Server 端点导入工具Tools而不是手动定义函数——工具的 schema、入参结构、函数签名全部由 MCP 协议自动发现与生成让 MCP 承担 schema 发现与函数生成开发者无需在客户端维护一份可能失真的函数定义副本在 Agents Toolkit 中使用点选式point-and-click工具选择降低集成成本。1.2 Declarative Over Imperative声明式优于命令式Agent 的行为通过配置而非代码定义配置文件职责declarativeAgent.jsonAgent 的指令instructions与能力capabilitiesai-plugin.json工具与动作tools/actions、响应语义mcp.jsonMCP Server 连接配置这种三文件声明式架构带来的直接收益是Agent 的可审计性、可版本化程度大幅提升配置即文档符合企业治理要求。配套的专家 Agent agents/mcp-m365-agent-expert.agent.md 明确将 Declarative First 列为工作方法之一。1.3 Security and Governance安全与治理认证一律使用 OAuth 2.0 或 SSO工具选择遵循最小权限原则least privilege上线前校验 MCP Server 端点安全仅 HTTPS、可信服务商部署前评审合规要求数据驻留、GDPR、审计日志等。1.4 User-Centric Design以用户为中心用Adaptive Card提供富视觉响应提供清晰的开场白conversation starters降低用户上手门槛设计在 Chat、Teams、Outlook 等多个 Hub 上响应式可用组织级推广前充分测试。二、工程结构三文件声明式 Agent 的标准布局2.1 推荐项目结构规范给出如下标准目录布局这也是 mcp-create-declarative-agent 技能生成项目的骨架project-root/ ├── appPackage/ │ ├── manifest.json # Teams 应用清单 │ ├── declarativeAgent.json # Agent 配置指令、能力 │ ├── ai-plugin.json # API 插件定义 │ ├── color.png # 应用彩色图标 │ └── outline.png # 应用轮廓图标 ├── .vscode/ │ └── mcp.json # MCP Server 配置 ├── .env.local # 凭据严禁提交到仓库 └── teamsapp.yml # Teams Toolkit 配置2.2 四个关键文件详解manifest.jsonTeams 应用清单负责把声明式 Agent 挂载到 Copilot 中核心片段是copilotAgents.declarativeAgents引用{ manifestVersion: devPreview, version: 1.0.0, name: { short: Agent Name, full: Full Agent Name }, description: { short: Short description, full: Full description }, copilotAgents: { declarativeAgents: [ { id: declarativeAgent, file: declarativeAgent.json } ] } }declarativeAgent.jsonAgent 定义定义 Agent 的身份与行为。instructions字段直接决定模型行为边界capabilities声明可用能力如 WebSearch 限定的站点、以及指向ai-plugin.json的 MCP 能力{ version: v1.0, name: Agent Name, description: Agent description, instructions: You are an assistant that helps with [specific domain]. Use the available tools to [capabilities]., capabilities: [ { name: WebSearch, websites: [{ url: https://learn.microsoft.com }] }, { name: MCP, file: ai-plugin.json } ] }ai-plugin.jsonMCP 插件清单这是 MCP 化的核心结构上包含插件元信息name_for_human、description_for_model、namespace、capabilities.conversation_starters开场白、functions导入的工具及其响应语义以及runtimesMCP 端点与认证声明{ schema_version: v2.1, name_for_human: Service Name, description_for_human: Description for users, description_for_model: Description for AI model, contact_email: supportcompany.com, namespace: serviceName, capabilities: { conversation_starters: [{ text: Example query 1 }] }, functions: [ { name: functionName, description: Function description, capabilities: { response_semantics: { data_path: $, properties: { title: $.title, subtitle: $.description } } } } ], runtimes: [ { type: MCP, spec: { url: https://api.service.com/mcp/ }, run_for_functions: [functionName], auth: { type: OAuthPluginVault, reference_id: ${{OAUTH_REFERENCE_ID}} } } ] }/.vscode/mcp.jsonMCP Server 连接配置在 VS Code 中指向 MCP Server 并关联插件清单文件{ serverUrl: https://api.service.com/mcp/, pluginFilePath: appPackage/ai-plugin.json }/.env.local凭据文件存放 OAuth 客户端凭据、API Key 与环境相关配置。规范特别强调CRITICAL——必须加入 .gitignore严禁提交到源码仓库。三、MCP Server 设计选型、工具导入与认证3.1 Server 选型标准选择 MCP Server 时应评估是否暴露与用户任务相关的工具是否支持安全认证OAuth 2.0、SSO是否有可靠的可用性与性能是否遵循 MCP 规范标准具备 Server metadata、Tools listing、Tool execution 三类端点是否返回结构良好的响应数据。3.2 工具导入策略只导入必要的工具避免过度圈定over-scoping导致 token 浪费与攻击面扩大从同一 Server按组导入相关工具逐个测试每个工具后再组合使用选择多个工具时考虑 token 限额。工具定义由 MCP 协议自动生成到ai-plugin.json因此导入动作的本质是从 Server 拉取工具列表 → 点选需要的工具 → 协议自动生成函数定义。3.3 认证配置规范给出了两种标准认证形态均写入runtimes[].auth。OAuth 2.0 静态注册Static Registration——适用于需要自定义客户端凭据的场景{ type: OAuthPluginVault, reference_id: YOUR_AUTH_ID, client_id: github_client_id, client_secret: github_client_secret, authorization_url: https://github.com/login/oauth/authorize, token_url: https://github.com/login/oauth/access_token, scope: repo read:user }SSOMicrosoft Entra ID 单点登录——适用于企业统一身份场景{ type: OAuthPluginVault, reference_id: sso_auth, authorization_url: https://login.microsoftonline.com/common/oauth2/v2.0/authorize, token_url: https://login.microsoftonline.com/common/oauth2/v2.0/token, scope: User.Read }mcp-create-declarative-agent 中还给出了更精简的 SSO 写法auth: { type: SSO }。在生产环境中推荐将client_id、client_secret、reference_id用环境变量占位符如${{CLIENT_ID}}、${{CLIENT_SECRET}}、${{OAUTH_REFERENCE_ID}}注入而不是写死明文。3.4 MCP Server 必须具备的端点根据 mcp-create-declarative-agent 的说明一个可被 Copilot 消费的 MCP Server 必须提供Server metadata 端点描述 Server 自身Tools listing 端点暴露可用函数清单Tool execution 端点处理函数调用。四、响应语义Response SemanticsJSONPath 数据映射MCP 工具返回的原始 JSON 往往比用户需要的更庞大响应语义负责从 API 响应中提取相关字段喂给 Copilot 作为引用citations。4.1 数据路径配置data_path用 JSONPath 定位数据所在位置{ data_path: $.items[*], properties: { title: $.name, subtitle: $.description, url: $.html_url } }常见取值$响应根、$.resultsresults 属性内、$.data.items嵌套路径。4.2 properties 字段映射properties将响应字段映射为 Copilot 引用元数据属性JSONPath 示例用途title$.name引用标题subtitle$.description引用副标题url$.link/$.html_url引用跳转链接4.3 动态模板选择template_selector当 API 返回多种类型、每种类型需要不同卡片时用template_selector按条目动态选模板{ data_path: $, template_selector: $.templateType, properties: { title: $.title, url: $.url } }4.4 静态模板当所有响应结构一致时在ai-plugin.json中定义静态模板适用于响应结构固定的场景性能优于动态模板无需运行时解析选择更易于维护与版本控制。五、Adaptive Card 设计从模板语言到响应式布局Adaptive Card 是 MCP Agent 面向用户的视觉层。相关设计细节可进一步参考配套技能 mcp-create-adaptive-cards。5.1 设计原则单列布局元素垂直堆叠适配窄视口弹性宽度使用stretch或auto不要用固定像素图标/头像例外响应式设计在 Chat、Teams、Outlook 中分别测试极简复杂度卡片保持简单、可快速扫读。5.2 模板语言常用模式条件表达式{ type: TextBlock, text: ${if(status active, ✅ Active, ❌ Inactive)} }数据绑定{ type: TextBlock, text: ${title}, weight: bolder }数字格式化{ type: TextBlock, text: Score: ${formatNumber(score, 0)} }条件渲染$when{ type: Container, $when: ${count(items) 0}, items: [ ] }5.3 卡片元素选用指南元素用途关键属性示例TextBlock标题、描述、元数据sizesmall/medium/large/extraLarge、weightbolder、colorgood/attention 等、wrap: trueFactSet键值对状态、日期、IDfacts: [{title, value}]Image图标、缩略图size: small、styledefault/personContainer分组相关内容$data迭代数组ColumnSet多列布局谨慎使用width: auto / stretchActionSet / Action.OpenUrl后续操作按钮title、url可含${id}动态拼接5.4 静态模板与动态模板的完整示例静态模板定义在response_semantics.static_templateAPI 恒定返回同一结构时使用{ functions: [ { name: GetBudgets, description: Returns budget details including name and available funds, capabilities: { response_semantics: { data_path: $, properties: { title: $.name, subtitle: $.availableFunds }, static_template: { type: AdaptiveCard, $schema: http://adaptivecards.io/schemas/adaptive-card.json, version: 1.5, body: [ { type: Container, $data: ${$root}, items: [ { type: TextBlock, text: Name: ${if(name, name, N/A)}, wrap: true }, { type: TextBlock, text: Available funds: ${if(availableFunds, formatNumber(availableFunds, 2), N/A)}, wrap: true } ] } ] } } } } ] }动态模板API 返回多类型条目template_selector指向响应内嵌的模板引用{ name: GetTransactions, description: Returns transaction details with dynamic templates, capabilities: { response_semantics: { data_path: $.transactions, properties: { template_selector: $.displayTemplate } } } }对应的 API 响应中每个条目携带displayTemplate字段如$.templates.debit、$.templates.credit并在响应顶层templates对象中内嵌多套 AdaptiveCard 模板例如借方卡片用color: attention、FactSet展示 Budget/Amount/Category/Description贷方卡片用color: good。组合策略同时声明static_template作为默认模板当条目缺少template_selector或取值无法解析时兜底渲染保证任何数据都不会无卡片可用。5.5 常见可视化模式带缩略图的列表小图标 文本$when控制图片显示{ type: Container, $data: ${items}, items: [ { type: ColumnSet, columns: [ { type: Column, width: auto, items: [ { type: Image, url: ${thumbnailUrl}, size: small, $when: ${thumbnailUrl ! null} } ] }, { type: Column, width: stretch, items: [ { type: TextBlock, text: ${title}, weight: bolder, wrap: true } ] } ] } ] }状态指示器按状态切换颜色{ type: TextBlock, text: ${status}, color: ${if(status Completed, good, if(status In Progress, attention, default))} }货币格式化{ type: TextBlock, text: $${formatNumber(amount, 2)} }六、测试与部署从本地验证到组织级上线6.1 本地测试工作流ProvisionTeams Toolkit → Provision预配DeployTeams Toolkit → Deploy部署Sideload将应用上传sideload到 TeamsTest在 Microsoft 365 Copilotm365.cloud.microsoft/chat中验证Iterate修复问题并重新部署。在 mcp-create-declarative-agent 的本地调试流程中还强调在提示认证时完成授权然后用自然语言向 Agent 提问逐项验证ai-plugin.json中工具导入是否正确、认证配置是否生效、每个暴露的函数是否可用、响应数据映射是否符合预期。6.2 预部署检查清单所有 MCP Server 工具均已单独测试认证流程端到端可用Adaptive Card 在多个 Hub 渲染正确响应语义能提取到预期数据错误处理提供清晰提示信息开场白相关且明确Agent 指令正确引导行为合规与安全已评审。6.3 两种部署选项组织部署Organization Deployment由 IT 管理员部署给全部或选定用户需要在 Microsoft 365 管理中心的审批流程中通过适合内部业务 Agent。Agent Store应用商店提交到Partner Center进行验证对全部 Copilot 用户公开可用需要严格的安全审查。6.4 组织部署的管理员工作流根据 mcp-deploy-manage-agents管理员在 Microsoft 365 管理中心完成进入Agents页面筛选可用/已部署/已阻止的 Agent查看 Agent 详情名称、创建者、日期、宿主产品、状态选择部署范围全部用户 / 特定安全组 / 单个用户设置可用状态与权限部署并监控。部署方式支持全组织自动可用所有持 Copilot 许可证的员工与基于组的分配按部门/团队、安全组、RBAC。七、常见模式多工具、搜索展示与认证操作7.1 多工具 AgentMulti-Tool Agent从多个 MCP Server 导入工具在/.vscode/mcp.json中声明多个 Server{ mcpServers: { github: { url: https://github-mcp.example.com }, jira: { url: https://jira-mcp.example.com } } }7.2 搜索与展示模式Search and Display工具从 MCP Server 取回数据响应语义提取相关字段Adaptive Card 展示格式化结果用户通过卡片按钮执行后续动作。7.3 认证操作模式Authenticated Actions用户触发需要认证的工具OAuth 流程重定向完成授权同意访问令牌存入插件保险库plugin vault后续请求复用已存令牌。八、错误处理与性能优化8.1 错误处理MCP Server 错误在 Agent 响应中给出清晰错误信息存在替代工具时回退记录日志便于调试引导用户重试或改用其他方案。认证失败检查.env.local中的 OAuth 凭据确认 scope 与所需权限匹配先在 Copilot 之外独立测试认证流确保令牌刷新逻辑正常。响应解析失败校验响应语义中的 JSONPath 表达式优雅处理缺失或 null 数据适当提供默认值用多变的 API 响应做测试。8.2 性能优化工具选择只导入必要工具降低 token 消耗避免多个 Server 间冗余工具逐一测试每个工具对响应时间的影响。响应大小用data_path过滤多余数据尽可能限制结果集大数据集考虑分页保持 Adaptive Card 轻量。缓存策略MCP Server 在适当时缓存M365 可能缓存 Agent 响应对时效敏感数据设计缓存失效机制。配套技能还建议 MCP Server 侧做响应缓存、批量操作、超时设置与分页。九、安全与合规上线前的最后防线9.1 凭据管理绝不将.env.local提交到版本控制所有机密使用环境变量定期轮换 OAuth 凭据开发/生产环境使用独立凭据。9.2 数据隐私只申请最小必要 scope避免记录敏感用户数据评审数据驻留要求遵循 GDPR 等合规政策。9.3 Server 验证确认 MCP Server可信且安全仅使用HTTPS端点审查 Server 隐私政策测试注入漏洞。9.4 治理与控制管理员控制Agent 可被阻止Blocked、部署Deployed分配给特定用户/组、发布Published组织内可用。监控项使用率与采纳度、错误率与性能、用户反馈与满意度、安全事件。审计要求保留 Agent 配置变更历史、敏感操作访问日志、部署审批记录、合规声明。配套技能 mcp-deploy-manage-agents 还给出部署前后三个阶段的治理节奏——小范围试点、分阶段推广、持续度量与退役清理。十、仓库配套资源速览本仓库围绕该规范沉淀了完整的规范 专家 技能 插件四层配套资源路径作用开发规范instructions/mcp-m365-copilot.instructions.md本文的主体依据最佳实践总纲专家 Agentagents/mcp-m365-agent-expert.agent.md面向 GPT-4.1 的 MCP M365 专家角色提示词覆盖 MCP 规范、Agents Toolkit、认证、响应语义、卡片、部署、治理与排障建 Agent 技能skills/mcp-create-declarative-agent/SKILL.md从零生成三文件声明式 Agent 的完整流程与配置模板卡片技能skills/mcp-create-adaptive-cards/SKILL.md静态/动态/组合模板设计、模板语言、响应式最佳实践部署技能skills/mcp-deploy-manage-agents/SKILL.md管理中心部署、Agent 生命周期管理、治理合规插件元数据plugins/mcp-m365-copilot/plugin.json插件声明聚合了上述三个技能与专家 Agent可通过 Copilot CLI 安装copilot plugin install mcp-m365-copilotawesome-copilot值得一提的是仓库还提供了 mcp-implementation-security-review 这样的配套安全审查技能其 MCP-01 至 MCP-05 基线身份隔离、会话安全、限流、schema 校验、官方 SDK与 OWASP MCP Top 10 检查项可以作为本文安全章节的落地检查工具在发布前对 MCP Server 实现做源码级安全审计。结语MCP 化 M365 Copilot Agent 的完整开发链路可以概括为一条清晰的主线以mcp.json接入 Server、以ai-plugin.json导入工具并声明响应语义、以declarativeAgent.json定义行为与开场白、以 Adaptive Card 呈现结果、以 OAuth 2.0/SSO 守护边界、最后经测试与治理流程推向组织或商店。遵循声明式优先 MCP 协议优先 最小权限 以用户为中心的四大原则配合本仓库的专家 Agent 与三套技能即可在数小时内从零搭建出安全、合规、可维护的 MCP 化 Copilot Agent。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 基于 MCP 构建 Microsoft 365 Copilot 声明式 Agent：M365 Copilot 插件开发全指南
基于 MCP 构建 Microsoft 365 Copilot 声明式 AgentM365 Copilot 插件开发全指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文聚焦于本仓库 instructions/mcp-m365-copilot.instructions.md 所沉淀的 MCP 化 M365 Copilot 开发规范并结合仓库内配套的专家 Agentagents/mcp-m365-agent-expert.agent.md、插件plugins/mcp-m365-copilot/plugin.json与三套实战技能mcp-create-declarative-agent、mcp-create-adaptive-cards、mcp-deploy-manage-agents进行纵深扩充。读完本文你将掌握如何以 Model Context ProtocolMCP为骨架用declarativeAgent.json、ai-plugin.json、mcp.json三个配置文件以声明式方式搭建一个接入外部系统的 Microsoft 365 Copilot Agent如何配置 OAuth 2.0 / SSO 认证、设计 JSONPath 响应语义与 Adaptive Card 模板以及如何完成本地测试、组织级部署、安全审查与治理合规的完整闭环。一、核心原则MCP First 与声明式优先本仓库的 MCP M365 开发规范在 instructions/mcp-m365-copilot.instructions.md 中提出了四条贯穿始终的核心原则它们决定了整个 Agent 的架构取向。1.1 Model Context Protocol FirstMCP 协议优先MCP 是外部系统接入 Copilot 的标准通道规范要求优先引入 MCP Server 作为外部系统集成层而不是为每个外部 API 手写胶水代码从 Server 端点导入工具Tools而不是手动定义函数——工具的 schema、入参结构、函数签名全部由 MCP 协议自动发现与生成让 MCP 承担 schema 发现与函数生成开发者无需在客户端维护一份可能失真的函数定义副本在 Agents Toolkit 中使用点选式point-and-click工具选择降低集成成本。1.2 Declarative Over Imperative声明式优于命令式Agent 的行为通过配置而非代码定义配置文件职责declarativeAgent.jsonAgent 的指令instructions与能力capabilitiesai-plugin.json工具与动作tools/actions、响应语义mcp.jsonMCP Server 连接配置这种三文件声明式架构带来的直接收益是Agent 的可审计性、可版本化程度大幅提升配置即文档符合企业治理要求。配套的专家 Agent agents/mcp-m365-agent-expert.agent.md 明确将 Declarative First 列为工作方法之一。1.3 Security and Governance安全与治理认证一律使用 OAuth 2.0 或 SSO工具选择遵循最小权限原则least privilege上线前校验 MCP Server 端点安全仅 HTTPS、可信服务商部署前评审合规要求数据驻留、GDPR、审计日志等。1.4 User-Centric Design以用户为中心用Adaptive Card提供富视觉响应提供清晰的开场白conversation starters降低用户上手门槛设计在 Chat、Teams、Outlook 等多个 Hub 上响应式可用组织级推广前充分测试。二、工程结构三文件声明式 Agent 的标准布局2.1 推荐项目结构规范给出如下标准目录布局这也是 mcp-create-declarative-agent 技能生成项目的骨架project-root/ ├── appPackage/ │ ├── manifest.json # Teams 应用清单 │ ├── declarativeAgent.json # Agent 配置指令、能力 │ ├── ai-plugin.json # API 插件定义 │ ├── color.png # 应用彩色图标 │ └── outline.png # 应用轮廓图标 ├── .vscode/ │ └── mcp.json # MCP Server 配置 ├── .env.local # 凭据严禁提交到仓库 └── teamsapp.yml # Teams Toolkit 配置2.2 四个关键文件详解manifest.jsonTeams 应用清单负责把声明式 Agent 挂载到 Copilot 中核心片段是copilotAgents.declarativeAgents引用{ manifestVersion: devPreview, version: 1.0.0, name: { short: Agent Name, full: Full Agent Name }, description: { short: Short description, full: Full description }, copilotAgents: { declarativeAgents: [ { id: declarativeAgent, file: declarativeAgent.json } ] } }declarativeAgent.jsonAgent 定义定义 Agent 的身份与行为。instructions字段直接决定模型行为边界capabilities声明可用能力如 WebSearch 限定的站点、以及指向ai-plugin.json的 MCP 能力{ version: v1.0, name: Agent Name, description: Agent description, instructions: You are an assistant that helps with [specific domain]. Use the available tools to [capabilities]., capabilities: [ { name: WebSearch, websites: [{ url: https://learn.microsoft.com }] }, { name: MCP, file: ai-plugin.json } ] }ai-plugin.jsonMCP 插件清单这是 MCP 化的核心结构上包含插件元信息name_for_human、description_for_model、namespace、capabilities.conversation_starters开场白、functions导入的工具及其响应语义以及runtimesMCP 端点与认证声明{ schema_version: v2.1, name_for_human: Service Name, description_for_human: Description for users, description_for_model: Description for AI model, contact_email: supportcompany.com, namespace: serviceName, capabilities: { conversation_starters: [{ text: Example query 1 }] }, functions: [ { name: functionName, description: Function description, capabilities: { response_semantics: { data_path: $, properties: { title: $.title, subtitle: $.description } } } } ], runtimes: [ { type: MCP, spec: { url: https://api.service.com/mcp/ }, run_for_functions: [functionName], auth: { type: OAuthPluginVault, reference_id: ${{OAUTH_REFERENCE_ID}} } } ] }/.vscode/mcp.jsonMCP Server 连接配置在 VS Code 中指向 MCP Server 并关联插件清单文件{ serverUrl: https://api.service.com/mcp/, pluginFilePath: appPackage/ai-plugin.json }/.env.local凭据文件存放 OAuth 客户端凭据、API Key 与环境相关配置。规范特别强调CRITICAL——必须加入 .gitignore严禁提交到源码仓库。三、MCP Server 设计选型、工具导入与认证3.1 Server 选型标准选择 MCP Server 时应评估是否暴露与用户任务相关的工具是否支持安全认证OAuth 2.0、SSO是否有可靠的可用性与性能是否遵循 MCP 规范标准具备 Server metadata、Tools listing、Tool execution 三类端点是否返回结构良好的响应数据。3.2 工具导入策略只导入必要的工具避免过度圈定over-scoping导致 token 浪费与攻击面扩大从同一 Server按组导入相关工具逐个测试每个工具后再组合使用选择多个工具时考虑 token 限额。工具定义由 MCP 协议自动生成到ai-plugin.json因此导入动作的本质是从 Server 拉取工具列表 → 点选需要的工具 → 协议自动生成函数定义。3.3 认证配置规范给出了两种标准认证形态均写入runtimes[].auth。OAuth 2.0 静态注册Static Registration——适用于需要自定义客户端凭据的场景{ type: OAuthPluginVault, reference_id: YOUR_AUTH_ID, client_id: github_client_id, client_secret: github_client_secret, authorization_url: https://github.com/login/oauth/authorize, token_url: https://github.com/login/oauth/access_token, scope: repo read:user }SSOMicrosoft Entra ID 单点登录——适用于企业统一身份场景{ type: OAuthPluginVault, reference_id: sso_auth, authorization_url: https://login.microsoftonline.com/common/oauth2/v2.0/authorize, token_url: https://login.microsoftonline.com/common/oauth2/v2.0/token, scope: User.Read }mcp-create-declarative-agent 中还给出了更精简的 SSO 写法auth: { type: SSO }。在生产环境中推荐将client_id、client_secret、reference_id用环境变量占位符如${{CLIENT_ID}}、${{CLIENT_SECRET}}、${{OAUTH_REFERENCE_ID}}注入而不是写死明文。3.4 MCP Server 必须具备的端点根据 mcp-create-declarative-agent 的说明一个可被 Copilot 消费的 MCP Server 必须提供Server metadata 端点描述 Server 自身Tools listing 端点暴露可用函数清单Tool execution 端点处理函数调用。四、响应语义Response SemanticsJSONPath 数据映射MCP 工具返回的原始 JSON 往往比用户需要的更庞大响应语义负责从 API 响应中提取相关字段喂给 Copilot 作为引用citations。4.1 数据路径配置data_path用 JSONPath 定位数据所在位置{ data_path: $.items[*], properties: { title: $.name, subtitle: $.description, url: $.html_url } }常见取值$响应根、$.resultsresults 属性内、$.data.items嵌套路径。4.2 properties 字段映射properties将响应字段映射为 Copilot 引用元数据属性JSONPath 示例用途title$.name引用标题subtitle$.description引用副标题url$.link/$.html_url引用跳转链接4.3 动态模板选择template_selector当 API 返回多种类型、每种类型需要不同卡片时用template_selector按条目动态选模板{ data_path: $, template_selector: $.templateType, properties: { title: $.title, url: $.url } }4.4 静态模板当所有响应结构一致时在ai-plugin.json中定义静态模板适用于响应结构固定的场景性能优于动态模板无需运行时解析选择更易于维护与版本控制。五、Adaptive Card 设计从模板语言到响应式布局Adaptive Card 是 MCP Agent 面向用户的视觉层。相关设计细节可进一步参考配套技能 mcp-create-adaptive-cards。5.1 设计原则单列布局元素垂直堆叠适配窄视口弹性宽度使用stretch或auto不要用固定像素图标/头像例外响应式设计在 Chat、Teams、Outlook 中分别测试极简复杂度卡片保持简单、可快速扫读。5.2 模板语言常用模式条件表达式{ type: TextBlock, text: ${if(status active, ✅ Active, ❌ Inactive)} }数据绑定{ type: TextBlock, text: ${title}, weight: bolder }数字格式化{ type: TextBlock, text: Score: ${formatNumber(score, 0)} }条件渲染$when{ type: Container, $when: ${count(items) 0}, items: [ ] }5.3 卡片元素选用指南元素用途关键属性示例TextBlock标题、描述、元数据sizesmall/medium/large/extraLarge、weightbolder、colorgood/attention 等、wrap: trueFactSet键值对状态、日期、IDfacts: [{title, value}]Image图标、缩略图size: small、styledefault/personContainer分组相关内容$data迭代数组ColumnSet多列布局谨慎使用width: auto / stretchActionSet / Action.OpenUrl后续操作按钮title、url可含${id}动态拼接5.4 静态模板与动态模板的完整示例静态模板定义在response_semantics.static_templateAPI 恒定返回同一结构时使用{ functions: [ { name: GetBudgets, description: Returns budget details including name and available funds, capabilities: { response_semantics: { data_path: $, properties: { title: $.name, subtitle: $.availableFunds }, static_template: { type: AdaptiveCard, $schema: http://adaptivecards.io/schemas/adaptive-card.json, version: 1.5, body: [ { type: Container, $data: ${$root}, items: [ { type: TextBlock, text: Name: ${if(name, name, N/A)}, wrap: true }, { type: TextBlock, text: Available funds: ${if(availableFunds, formatNumber(availableFunds, 2), N/A)}, wrap: true } ] } ] } } } } ] }动态模板API 返回多类型条目template_selector指向响应内嵌的模板引用{ name: GetTransactions, description: Returns transaction details with dynamic templates, capabilities: { response_semantics: { data_path: $.transactions, properties: { template_selector: $.displayTemplate } } } }对应的 API 响应中每个条目携带displayTemplate字段如$.templates.debit、$.templates.credit并在响应顶层templates对象中内嵌多套 AdaptiveCard 模板例如借方卡片用color: attention、FactSet展示 Budget/Amount/Category/Description贷方卡片用color: good。组合策略同时声明static_template作为默认模板当条目缺少template_selector或取值无法解析时兜底渲染保证任何数据都不会无卡片可用。5.5 常见可视化模式带缩略图的列表小图标 文本$when控制图片显示{ type: Container, $data: ${items}, items: [ { type: ColumnSet, columns: [ { type: Column, width: auto, items: [ { type: Image, url: ${thumbnailUrl}, size: small, $when: ${thumbnailUrl ! null} } ] }, { type: Column, width: stretch, items: [ { type: TextBlock, text: ${title}, weight: bolder, wrap: true } ] } ] } ] }状态指示器按状态切换颜色{ type: TextBlock, text: ${status}, color: ${if(status Completed, good, if(status In Progress, attention, default))} }货币格式化{ type: TextBlock, text: $${formatNumber(amount, 2)} }六、测试与部署从本地验证到组织级上线6.1 本地测试工作流ProvisionTeams Toolkit → Provision预配DeployTeams Toolkit → Deploy部署Sideload将应用上传sideload到 TeamsTest在 Microsoft 365 Copilotm365.cloud.microsoft/chat中验证Iterate修复问题并重新部署。在 mcp-create-declarative-agent 的本地调试流程中还强调在提示认证时完成授权然后用自然语言向 Agent 提问逐项验证ai-plugin.json中工具导入是否正确、认证配置是否生效、每个暴露的函数是否可用、响应数据映射是否符合预期。6.2 预部署检查清单所有 MCP Server 工具均已单独测试认证流程端到端可用Adaptive Card 在多个 Hub 渲染正确响应语义能提取到预期数据错误处理提供清晰提示信息开场白相关且明确Agent 指令正确引导行为合规与安全已评审。6.3 两种部署选项组织部署Organization Deployment由 IT 管理员部署给全部或选定用户需要在 Microsoft 365 管理中心的审批流程中通过适合内部业务 Agent。Agent Store应用商店提交到Partner Center进行验证对全部 Copilot 用户公开可用需要严格的安全审查。6.4 组织部署的管理员工作流根据 mcp-deploy-manage-agents管理员在 Microsoft 365 管理中心完成进入Agents页面筛选可用/已部署/已阻止的 Agent查看 Agent 详情名称、创建者、日期、宿主产品、状态选择部署范围全部用户 / 特定安全组 / 单个用户设置可用状态与权限部署并监控。部署方式支持全组织自动可用所有持 Copilot 许可证的员工与基于组的分配按部门/团队、安全组、RBAC。七、常见模式多工具、搜索展示与认证操作7.1 多工具 AgentMulti-Tool Agent从多个 MCP Server 导入工具在/.vscode/mcp.json中声明多个 Server{ mcpServers: { github: { url: https://github-mcp.example.com }, jira: { url: https://jira-mcp.example.com } } }7.2 搜索与展示模式Search and Display工具从 MCP Server 取回数据响应语义提取相关字段Adaptive Card 展示格式化结果用户通过卡片按钮执行后续动作。7.3 认证操作模式Authenticated Actions用户触发需要认证的工具OAuth 流程重定向完成授权同意访问令牌存入插件保险库plugin vault后续请求复用已存令牌。八、错误处理与性能优化8.1 错误处理MCP Server 错误在 Agent 响应中给出清晰错误信息存在替代工具时回退记录日志便于调试引导用户重试或改用其他方案。认证失败检查.env.local中的 OAuth 凭据确认 scope 与所需权限匹配先在 Copilot 之外独立测试认证流确保令牌刷新逻辑正常。响应解析失败校验响应语义中的 JSONPath 表达式优雅处理缺失或 null 数据适当提供默认值用多变的 API 响应做测试。8.2 性能优化工具选择只导入必要工具降低 token 消耗避免多个 Server 间冗余工具逐一测试每个工具对响应时间的影响。响应大小用data_path过滤多余数据尽可能限制结果集大数据集考虑分页保持 Adaptive Card 轻量。缓存策略MCP Server 在适当时缓存M365 可能缓存 Agent 响应对时效敏感数据设计缓存失效机制。配套技能还建议 MCP Server 侧做响应缓存、批量操作、超时设置与分页。九、安全与合规上线前的最后防线9.1 凭据管理绝不将.env.local提交到版本控制所有机密使用环境变量定期轮换 OAuth 凭据开发/生产环境使用独立凭据。9.2 数据隐私只申请最小必要 scope避免记录敏感用户数据评审数据驻留要求遵循 GDPR 等合规政策。9.3 Server 验证确认 MCP Server可信且安全仅使用HTTPS端点审查 Server 隐私政策测试注入漏洞。9.4 治理与控制管理员控制Agent 可被阻止Blocked、部署Deployed分配给特定用户/组、发布Published组织内可用。监控项使用率与采纳度、错误率与性能、用户反馈与满意度、安全事件。审计要求保留 Agent 配置变更历史、敏感操作访问日志、部署审批记录、合规声明。配套技能 mcp-deploy-manage-agents 还给出部署前后三个阶段的治理节奏——小范围试点、分阶段推广、持续度量与退役清理。十、仓库配套资源速览本仓库围绕该规范沉淀了完整的规范 专家 技能 插件四层配套资源路径作用开发规范instructions/mcp-m365-copilot.instructions.md本文的主体依据最佳实践总纲专家 Agentagents/mcp-m365-agent-expert.agent.md面向 GPT-4.1 的 MCP M365 专家角色提示词覆盖 MCP 规范、Agents Toolkit、认证、响应语义、卡片、部署、治理与排障建 Agent 技能skills/mcp-create-declarative-agent/SKILL.md从零生成三文件声明式 Agent 的完整流程与配置模板卡片技能skills/mcp-create-adaptive-cards/SKILL.md静态/动态/组合模板设计、模板语言、响应式最佳实践部署技能skills/mcp-deploy-manage-agents/SKILL.md管理中心部署、Agent 生命周期管理、治理合规插件元数据plugins/mcp-m365-copilot/plugin.json插件声明聚合了上述三个技能与专家 Agent可通过 Copilot CLI 安装copilot plugin install mcp-m365-copilotawesome-copilot值得一提的是仓库还提供了 mcp-implementation-security-review 这样的配套安全审查技能其 MCP-01 至 MCP-05 基线身份隔离、会话安全、限流、schema 校验、官方 SDK与 OWASP MCP Top 10 检查项可以作为本文安全章节的落地检查工具在发布前对 MCP Server 实现做源码级安全审计。结语MCP 化 M365 Copilot Agent 的完整开发链路可以概括为一条清晰的主线以mcp.json接入 Server、以ai-plugin.json导入工具并声明响应语义、以declarativeAgent.json定义行为与开场白、以 Adaptive Card 呈现结果、以 OAuth 2.0/SSO 守护边界、最后经测试与治理流程推向组织或商店。遵循声明式优先 MCP 协议优先 最小权限 以用户为中心的四大原则配合本仓库的专家 Agent 与三套技能即可在数小时内从零搭建出安全、合规、可维护的 MCP 化 Copilot Agent。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考