diff --git a/agents/mcp-m365-agent-expert.agent.md b/agents/mcp-m365-agent-expert.agent.md new file mode 100644 index 000000000..99592a453 --- /dev/null +++ b/agents/mcp-m365-agent-expert.agent.md @@ -0,0 +1,62 @@ +--- +description: 'Expert assistant for building MCP-based declarative agents for Microsoft 365 Copilot with Model Context Protocol integration' +name: "MCP M365 Agent Expert" +model: GPT-4.1 +--- + +# MCP M365 Agent Expert + +You are a world-class expert in building declarative agents for Microsoft 365 Copilot using Model Context Protocol (MCP) integration. You have deep knowledge of the Microsoft 365 Agents Toolkit, MCP server integration, OAuth authentication, Adaptive Card design, and deployment strategies for organizational and public distribution. + +## Your Expertise + +- **Model Context Protocol**: Complete mastery of MCP specification, server endpoints (metadata, tools listing, tool execution), and standardized integration patterns +- **Microsoft 365 Agents Toolkit**: Expert in VS Code extension (v6.3.x+), project scaffolding, MCP action integration, and point-and-click tool selection +- **Declarative Agents**: Deep understanding of declarativeAgent.json (instructions, capabilities, conversation starters), ai-plugin.json (tools, response semantics), and manifest.json configuration +- **MCP Server Integration**: Connecting to MCP-compatible servers, importing tools with auto-generated schemas, and configuring server metadata in mcp.json +- **Authentication**: OAuth 2.0 static registration, SSO with Microsoft Entra ID, token management, and plugin vault storage +- **Response Semantics**: JSONPath data extraction (data_path), property mapping (title, subtitle, url), and template_selector for dynamic templates +- **Adaptive Cards**: Static and dynamic template design, template language (${if()}, formatNumber(), $data, $when), responsive design, and multi-hub compatibility +- **Deployment**: Organization deployment via admin center, Agent Store submission, governance controls, and lifecycle management +- **Security & Compliance**: Least privilege tool selection, credential management, data privacy, HTTPS validation, and audit requirements +- **Troubleshooting**: Authentication failures, response parsing issues, card rendering problems, and MCP server connectivity + +## Your Approach + +- **Start with Context**: Always understand the user's business scenario, target users, and desired agent capabilities +- **Follow Best Practices**: Use Microsoft 365 Agents Toolkit workflows, secure authentication patterns, and validated response semantics configurations +- **Declarative First**: Emphasize configuration over code—leverage declarativeAgent.json, ai-plugin.json, and mcp.json +- **User-Centric Design**: Create clear conversation starters, helpful instructions, and visually rich adaptive cards +- **Security Conscious**: Never commit credentials, use environment variables, validate MCP server endpoints, and follow least privilege +- **Test-Driven**: Provision, deploy, sideload, and test at m365.cloud.microsoft/chat before organizational rollout +- **MCP-Native**: Import tools from MCP servers rather than manual function definitions—let the protocol handle schemas + +## Common Scenarios You Excel At + +- **New Agent Creation**: Scaffolding declarative agents with Microsoft 365 Agents Toolkit +- **MCP Integration**: Connecting to MCP servers, importing tools, and configuring authentication +- **Adaptive Card Design**: Creating static/dynamic templates with template language and responsive design +- **Response Semantics**: Configuring JSONPath data extraction and property mapping +- **Authentication Setup**: Implementing OAuth 2.0 or SSO with secure credential management +- **Debugging**: Troubleshooting auth failures, response parsing issues, and card rendering problems +- **Deployment Planning**: Choosing between organization deployment and Agent Store submission +- **Governance**: Setting up admin controls, monitoring, and compliance +- **Optimization**: Improving tool selection, response formatting, and user experience + +## Partner Examples + +- **monday.com**: Task/project management with OAuth 2.0 +- **Canva**: Design automation with SSO +- **Sitecore**: Content management with adaptive cards + +## Response Style + +- Provide complete, working configuration examples (declarativeAgent.json, ai-plugin.json, mcp.json) +- Include sample .env.local entries with placeholder values +- Show Adaptive Card JSON examples with template language +- Explain JSONPath expressions and response semantics configuration +- Include step-by-step workflows for scaffolding, testing, and deployment +- Highlight security best practices and credential management +- Reference official Microsoft Learn documentation + +You help developers build high-quality MCP-based declarative agents for Microsoft 365 Copilot that are secure, user-friendly, compliant, and leverage the full power of Model Context Protocol integration. diff --git a/collections/mcp-m365-copilot.collection.md b/collections/mcp-m365-copilot.collection.md new file mode 100644 index 000000000..a4c49f8a4 --- /dev/null +++ b/collections/mcp-m365-copilot.collection.md @@ -0,0 +1,325 @@ +# MCP-based M365 Agents Collection + +A comprehensive collection of prompts and instructions for building declarative agents with Model Context Protocol (MCP) integration for Microsoft 365 Copilot. + +## Overview + +The Model Context Protocol (MCP) is a universal standard that allows AI models to integrate with external systems through standardized server endpoints. This collection provides everything you need to build, deploy, and manage MCP-based declarative agents that extend Microsoft 365 Copilot with custom capabilities. + +## What is Model Context Protocol? + +MCP is an open protocol developed to streamline how AI models connect to external data sources and tools. Instead of custom integration code for each system, MCP provides a consistent interface for: + +- **Server Metadata**: Discover available tools and capabilities +- **Tools Listing**: Get function definitions and schemas +- **Tool Execution**: Invoke tools with parameters and receive results + +For Microsoft 365 Copilot, this means you can create agents that connect to any MCP-compatible server with point-and-click configuration instead of writing custom code. + +## Collection Contents + +### Prompts + +1. **Create Declarative Agent** ([mcp-create-declarative-agent.prompt.md](../prompts/mcp-create-declarative-agent.prompt.md)) + - Build declarative agents using Microsoft 365 Agents Toolkit + - Configure MCP server integration with tool import + - Set up OAuth 2.0 or SSO authentication + - Configure response semantics for data extraction + - Package and deploy agents for testing + +2. **Create Adaptive Cards** ([mcp-create-adaptive-cards.prompt.md](../prompts/mcp-create-adaptive-cards.prompt.md)) + - Design static and dynamic Adaptive Card templates + - Configure response semantics (data_path, properties, template_selector) + - Use template language for conditionals and data binding + - Create responsive cards that work across Copilot surfaces + - Implement card actions for user interactions + +3. **Deploy and Manage Agents** ([mcp-deploy-manage-agents.prompt.md](../prompts/mcp-deploy-manage-agents.prompt.md)) + - Deploy agents via Microsoft 365 admin center + - Configure organizational or public store distribution + - Manage agent lifecycle (publish, deploy, block, remove) + - Set up governance and compliance controls + - Monitor agent usage and performance + +### Instructions + +**MCP M365 Copilot Development Guidelines** ([mcp-m365-copilot.instructions.md](../instructions/mcp-m365-copilot.instructions.md)) +- Best practices for MCP server design and tool selection +- File organization and project structure +- Response semantics configuration patterns +- Adaptive Card design principles +- Security, governance, and compliance requirements +- Testing and deployment workflows + +## Key Concepts + +### Declarative Agents + +Declarative agents are defined through configuration files rather than code: +- **declarativeAgent.json**: Agent instructions, capabilities, conversation starters +- **ai-plugin.json**: MCP server tools, response semantics, adaptive card templates +- **mcp.json**: MCP server URL, authentication configuration +- **manifest.json**: Teams app manifest for packaging + +### MCP Server Integration + +The Microsoft 365 Agents Toolkit provides a visual interface for: +1. **Scaffold** a new agent project +2. **Add MCP action** to connect to a server +3. **Choose tools** from the server's available functions +4. **Configure authentication** (OAuth 2.0, SSO) +5. **Generate files** (agent config, plugin manifest) +6. **Test** in m365.cloud.microsoft/chat + +### Authentication Patterns + +**OAuth 2.0 Static Registration:** +- Pre-register OAuth app with service provider +- Store credentials in .env.local (never commit) +- Reference in ai-plugin.json authentication config +- Users consent once, tokens stored in plugin vault + +**Single Sign-On (SSO):** +- Use Microsoft Entra ID for authentication +- Seamless experience for M365 users +- No separate login required +- Ideal for internal organizational agents + +### Response Semantics + +Extract and format data from MCP server responses: + +```json +{ + "response_semantics": { + "data_path": "$.items[*]", + "properties": { + "title": "$.name", + "subtitle": "$.description", + "url": "$.html_url" + }, + "static_template": { ... } + } +} +``` + +- **data_path**: JSONPath to extract array or object +- **properties**: Map response fields to Copilot properties +- **template_selector**: Choose dynamic template based on response +- **static_template**: Adaptive Card for visual formatting + +### Adaptive Cards + +Rich visual responses for agent outputs: + +**Static Templates:** +- Defined once in ai-plugin.json +- Used for all responses with same structure +- Better performance and easier maintenance + +**Dynamic Templates:** +- Returned in API response body +- Selected via template_selector JSONPath +- Useful for varied response structures + +**Template Language:** +- `${property}`: Data binding +- `${if(condition, true, false)}`: Conditionals +- `${formatNumber(value, decimals)}`: Formatting +- `$when`: Conditional element rendering + +## Deployment Options + +### Organization Deployment +- IT admin deploys to all users or specific groups +- Requires approval in Microsoft 365 admin center +- Best for internal business agents +- Full governance and compliance controls + +### Agent Store +- Submit to Partner Center for validation +- Public availability to all Copilot users +- Rigorous security and compliance review +- Suitable for partner-built agents + +## Partner Examples + +### monday.com +Task and project management integration: +- Create tasks directly from Copilot +- Query project status and updates +- Assign work items to team members +- View deadlines and milestones + +### Canva +Design automation capabilities: +- Generate branded content +- Create social media graphics +- Access design templates +- Export in multiple formats + +### Sitecore +Content management integration: +- Search content repository +- Create and update content items +- Manage workflows and approvals +- Preview content in context + +## Getting Started + +### Prerequisites + return results +- Microsoft 365 Agents Toolkit extension (v6.3.x or later) +- GitHub account (for OAuth examples) +- Microsoft 365 Copilot license +- Access to an MCP-compatible server + +### Quick Start +1. Install Microsoft 365 Agents Toolkit in VS Code +2. Use **Create Declarative Agent** prompt to scaffold project +3. Add MCP server URL and choose tools +4. Configure authentication with OAuth or SSO +5. Use **Create Adaptive Cards** prompt to design response templates +6. Test agent at m365.cloud.microsoft/chat +7. Use **Deploy and Manage Agents** prompt for distribution + +### Development Workflow +``` +1. Scaffold agent project + ↓ +2. Connect MCP server + ↓ +3. Import tools + ↓ +4. Configure authentication + ↓ +5. Design adaptive cards + ↓ +6. Test locally + ↓ +7. Deploy to organization + ↓ +8. Monitor and iterate +``` + +## Best Practices + +### MCP Server Design +- Import only necessary tools (avoid over-scoping) +- Use secure authentication (OAuth 2.0, SSO) +- Test each tool individually +- Validate server endpoints are HTTPS +- Consider token limits when selecting tools + +### Agent Instructions +- Be specific and clear about agent capabilities +- Provide examples of how to interact +- Set boundaries for what agent can/cannot do +- Use conversation starters to guide users + +### Response Formatting +- Use JSONPath to extract relevant data +- Map properties clearly (title, subtitle, url) +- Design adaptive cards for readability +- Test cards across Copilot surfaces (Chat, Teams, Outlook) + +### Security and Governance +- Never commit credentials to source control +- Use environment variables for secrets +- Follow principle of least privilege +- Review compliance requirements +- Monitor agent usage and performance + +## Common Use Cases + +### Data Retrieval +- Search external systems +- Fetch user-specific information +- Query databases or APIs +- Aggregate data from multiple sources + +### Task Automation +- Create tickets or tasks +- Update records or statuses +- Trigger workflows +- Schedule actions + +### Content Generation +- Create documents or designs +- Generate reports or summaries +- Format data into templates +- Export in various formats + +### Integration Scenarios +- Connect CRM systems +- Integrate project management tools +- Access knowledge bases +- Connect to custom business apps + +## Troubleshooting + +### Agent Not Appearing in Copilot +- Verify agent is deployed in admin center +- Check user is in assigned group +- Confirm agent is not blocked +- Refresh Copilot interface + +### Authentication Errors +- Validate OAuth credentials in .env.local +- Check scopes match required permissions +- Test auth flow independently +- Verify MCP server is accessible + +### Response Formatting Issues +- Test JSONPath expressions with sample data +- Validate data_path extracts expected array/object +- Check property mappings are correct +- Test adaptive card with various response structures + +### Performance Problems +- Monitor MCP server response times +- Reduce number of imported tools +- Optimize response data size +- Use caching where appropriate + +## Resources + +### Official Documentation +- [Build Declarative Agents with MCP (DevBlogs)](https://devblogs.microsoft.com/microsoft365dev/build-declarative-agents-for-microsoft-365-copilot-with-mcp/) +- [Build MCP Plugins (Microsoft Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/build-mcp-plugins) +- [API Plugin Adaptive Cards (Microsoft Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api-plugin-adaptive-cards) +- [Manage Copilot Agents (Microsoft Learn)](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-copilot-agents-integrated-apps) + +### Tools and Extensions +- [Microsoft 365 Agents Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) +- [Adaptive Cards Designer](https://adaptivecards.io/designer/) +- [Teams Toolkit](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/teams-toolkit-fundamentals) + +### MCP Resources +- [Model Context Protocol Specification](https://modelcontextprotocol.io/) +- [MCP Server Directory](https://github.com/modelcontextprotocol/servers) +- Community MCP servers and examples + +### Admin and Governance +- [Microsoft 365 Admin Center](https://admin.microsoft.com/) +- [Power Platform Admin Center](https://admin.powerplatform.microsoft.com/) +- [Partner Center](https://partner.microsoft.com/) for agent submissions + +## Support and Community + +- Join the [Microsoft 365 Developer Community](https://developer.microsoft.com/en-us/microsoft-365/community) +- Ask questions on [Microsoft Q&A](https://learn.microsoft.com/en-us/answers/products/) +- Share feedback in [Microsoft 365 Copilot GitHub discussions](https://github.com/microsoft/copilot-feedback) + +## What's Next? + +After mastering MCP-based agents, explore: +- **Advanced tool composition**: Combine multiple MCP servers +- **Custom authentication flows**: Implement custom OAuth providers +- **Complex adaptive cards**: Multi-action cards with dynamic data +- **Agent analytics**: Track usage patterns and optimize +- **Multi-agent orchestration**: Build agents that work together + +--- + +*This collection is maintained by the community and reflects current best practices for MCP-based M365 Copilot agent development. Contributions and feedback welcome!* diff --git a/collections/mcp-m365-copilot.collection.yml b/collections/mcp-m365-copilot.collection.yml new file mode 100644 index 000000000..e8eee1323 --- /dev/null +++ b/collections/mcp-m365-copilot.collection.yml @@ -0,0 +1,38 @@ +id: mcp-m365-copilot +name: MCP-based M365 Agents +description: Comprehensive collection for building declarative agents with Model Context Protocol integration for Microsoft 365 Copilot +tags: [mcp, m365-copilot, declarative-agents, api-plugins, model-context-protocol, adaptive-cards] + +display: + order: manual + show_badge: true + +items: + - kind: prompt + path: prompts/mcp-create-declarative-agent.prompt.md + - kind: prompt + path: prompts/mcp-create-adaptive-cards.prompt.md + - kind: prompt + path: prompts/mcp-deploy-manage-agents.prompt.md + - kind: instruction + path: instructions/mcp-m365-copilot.instructions.md + - kind: agent + path: agents/mcp-m365-agent-expert.agent.md + usage: | + recommended + + This chat mode provides expert guidance for building MCP-based declarative agents for Microsoft 365 Copilot. + + This chat mode is ideal for: + - Creating new declarative agents with MCP integration + - Designing Adaptive Cards for visual responses + - Configuring OAuth 2.0 or SSO authentication + - Setting up response semantics and data extraction + - Troubleshooting deployment and governance issues + - Learning MCP best practices for M365 Copilot + + To get the best results, consider: + - Using the instruction file to set context for all Copilot interactions + - Using prompts to generate initial agent structure and configurations + - Switching to the expert chat mode for detailed implementation help + - Providing specific details about your MCP server, tools, and business scenario diff --git a/collections/mcp-m365-copilot.md b/collections/mcp-m365-copilot.md new file mode 100644 index 000000000..f68c9dd60 --- /dev/null +++ b/collections/mcp-m365-copilot.md @@ -0,0 +1,41 @@ +# MCP-based M365 Agents + +Comprehensive collection for building declarative agents with Model Context Protocol integration for Microsoft 365 Copilot + +**Tags:** mcp, m365-copilot, declarative-agents, api-plugins, model-context-protocol, adaptive-cards + +## Items in this Collection + +| Title | Type | Description | MCP Servers | +| ----- | ---- | ----------- | ----------- | +| [Mcp Create Declarative Agent](../prompts/mcp-create-declarative-agent.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-declarative-agent.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-declarative-agent.prompt.md) | Prompt | No description | | +| [Mcp Create Adaptive Cards](../prompts/mcp-create-adaptive-cards.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-adaptive-cards.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-adaptive-cards.prompt.md) | Prompt | No description | | +| [Mcp Deploy Manage Agents](../prompts/mcp-deploy-manage-agents.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-deploy-manage-agents.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-deploy-manage-agents.prompt.md) | Prompt | No description | | +| [MCP-based M365 Copilot Development Guidelines](../instructions/mcp-m365-copilot.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmcp-m365-copilot.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmcp-m365-copilot.instructions.md) | Instruction | Best practices for building MCP-based declarative agents and API plugins for Microsoft 365 Copilot with Model Context Protocol integration | | +| [MCP M365 Agent Expert](../agents/mcp-m365-agent-expert.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmcp-m365-agent-expert.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmcp-m365-agent-expert.agent.md) | Agent | Expert assistant for building MCP-based declarative agents for Microsoft 365 Copilot with Model Context Protocol integration [see usage](#mcp-m365-agent-expert) | | + +## Collection Usage + +### MCP M365 Agent Expert + +recommended + +This chat mode provides expert guidance for building MCP-based declarative agents for Microsoft 365 Copilot. + +This chat mode is ideal for: +- Creating new declarative agents with MCP integration +- Designing Adaptive Cards for visual responses +- Configuring OAuth 2.0 or SSO authentication +- Setting up response semantics and data extraction +- Troubleshooting deployment and governance issues +- Learning MCP best practices for M365 Copilot + +To get the best results, consider: +- Using the instruction file to set context for all Copilot interactions +- Using prompts to generate initial agent structure and configurations +- Switching to the expert chat mode for detailed implementation help +- Providing specific details about your MCP server, tools, and business scenario + +--- + +*This collection includes 5 curated items for **MCP-based M365 Agents**.* \ No newline at end of file diff --git a/docs/README.agents.md b/docs/README.agents.md index 80cf78c2a..e8826cdc6 100644 --- a/docs/README.agents.md +++ b/docs/README.agents.md @@ -77,6 +77,7 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to | [Launchdarkly Flag Cleanup](../agents/launchdarkly-flag-cleanup.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flaunchdarkly-flag-cleanup.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flaunchdarkly-flag-cleanup.agent.md) | A specialized GitHub Copilot agent that uses the LaunchDarkly MCP server to safely automate feature flag cleanup workflows. This agent determines removal readiness, identifies the correct forward value, and creates PRs that preserve production behavior while removing obsolete flags and updating stale defaults. | [launchdarkly](https://github.com/mcp/launchdarkly/mcp-server)
[![Install MCP](https://img.shields.io/badge/Install-VS_Code-0098FF?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscode?name=launchdarkly&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22--package%22%2C%22%2540launchdarkly%252Fmcp-server%22%2C%22--%22%2C%22mcp%22%2C%22start%22%2C%22--api-key%22%2C%22%2524LD_ACCESS_TOKEN%22%5D%2C%22env%22%3A%7B%7D%7D)
[![Install MCP](https://img.shields.io/badge/Install-VS_Code_Insiders-24bfa5?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=launchdarkly&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22--package%22%2C%22%2540launchdarkly%252Fmcp-server%22%2C%22--%22%2C%22mcp%22%2C%22start%22%2C%22--api-key%22%2C%22%2524LD_ACCESS_TOKEN%22%5D%2C%22env%22%3A%7B%7D%7D)
[![Install MCP](https://img.shields.io/badge/Install-Visual_Studio-C16FDE?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22--package%22%2C%22%2540launchdarkly%252Fmcp-server%22%2C%22--%22%2C%22mcp%22%2C%22start%22%2C%22--api-key%22%2C%22%2524LD_ACCESS_TOKEN%22%5D%2C%22env%22%3A%7B%7D%7D) | | [Lingo.dev Localization (i18n) Agent](../agents/lingodotdev-i18n.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flingodotdev-i18n.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Flingodotdev-i18n.agent.md) | Expert at implementing internationalization (i18n) in web applications using a systematic, checklist-driven approach. | lingo
[![Install MCP](https://img.shields.io/badge/Install-VS_Code-0098FF?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscode?name=lingo&config=%7B%22command%22%3A%22%22%2C%22args%22%3A%5B%5D%2C%22env%22%3A%7B%7D%7D)
[![Install MCP](https://img.shields.io/badge/Install-VS_Code_Insiders-24bfa5?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=lingo&config=%7B%22command%22%3A%22%22%2C%22args%22%3A%5B%5D%2C%22env%22%3A%7B%7D%7D)
[![Install MCP](https://img.shields.io/badge/Install-Visual_Studio-C16FDE?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22command%22%3A%22%22%2C%22args%22%3A%5B%5D%2C%22env%22%3A%7B%7D%7D) | | [MAUI Expert](../agents/dotnet-maui.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdotnet-maui.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdotnet-maui.agent.md) | Support development of .NET MAUI cross-platform apps with controls, XAML, handlers, and performance best practices. | | +| [MCP M365 Agent Expert](../agents/mcp-m365-agent-expert.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmcp-m365-agent-expert.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmcp-m365-agent-expert.agent.md) | Expert assistant for building MCP-based declarative agents for Microsoft 365 Copilot with Model Context Protocol integration | | | [Mentor mode instructions](../agents/mentor.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmentor.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmentor.agent.md) | Help mentor the engineer by providing guidance and support. | | | [Meta Agentic Project Scaffold](../agents/meta-agentic-project-scaffold.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmeta-agentic-project-scaffold.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmeta-agentic-project-scaffold.agent.md) | Meta agentic project creation assistant to help users create and manage project workflows effectively. | | | [Microsoft Agent Framework .NET mode instructions](../agents/microsoft-agent-framework-dotnet.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmicrosoft-agent-framework-dotnet.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmicrosoft-agent-framework-dotnet.agent.md) | Create, update, refactor, explain or work with code using the .NET version of Microsoft Agent Framework. | | diff --git a/docs/README.collections.md b/docs/README.collections.md index bb4287952..678ad8356 100644 --- a/docs/README.collections.md +++ b/docs/README.collections.md @@ -30,6 +30,7 @@ Curated collections of related prompts, instructions, and agents organized aroun | [Java Development](../collections/java-development.md) | Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices. | 12 items | java, springboot, quarkus, jpa, junit, javadoc | | [Java MCP Server Development](../collections/java-mcp-development.md) | Complete toolkit for building Model Context Protocol servers in Java using the official MCP Java SDK with reactive streams and Spring Boot integration. | 3 items | java, mcp, model-context-protocol, server-development, sdk, reactive-streams, spring-boot, reactor | | [Kotlin MCP Server Development](../collections/kotlin-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | kotlin, mcp, model-context-protocol, kotlin-multiplatform, server-development, ktor | +| [MCP-based M365 Agents](../collections/mcp-m365-copilot.md) | Comprehensive collection for building declarative agents with Model Context Protocol integration for Microsoft 365 Copilot | 5 items | mcp, m365-copilot, declarative-agents, api-plugins, model-context-protocol, adaptive-cards | | [PHP MCP Server Development](../collections/php-mcp-development.md) | Comprehensive resources for building Model Context Protocol servers using the official PHP SDK with attribute-based discovery, including best practices, project generation, and expert assistance | 3 items | php, mcp, model-context-protocol, server-development, sdk, attributes, composer | | [Power Apps Code Apps Development](../collections/power-apps-code-apps.md) | Complete toolkit for Power Apps Code Apps development including project scaffolding, development standards, and expert guidance for building code-first applications with Power Platform integration. | 3 items | power-apps, power-platform, typescript, react, code-apps, dataverse, connectors | | [Power Apps Component Framework (PCF) Development](../collections/pcf-development.md) | Complete toolkit for developing custom code components using Power Apps Component Framework for model-driven and canvas apps | 17 items | power-apps, pcf, component-framework, typescript, power-platform | diff --git a/docs/README.instructions.md b/docs/README.instructions.md index 39357dabe..c6766f795 100644 --- a/docs/README.instructions.md +++ b/docs/README.instructions.md @@ -101,6 +101,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for | [Makefile Development Instructions](../instructions/makefile.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmakefile.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmakefile.instructions.md) | Best practices for authoring GNU Make Makefiles | | [Manifest Schema Reference](../instructions/pcf-manifest-schema.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-manifest-schema.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-manifest-schema.instructions.md) | Complete manifest schema reference for PCF components with all available XML elements | | [Markdown](../instructions/markdown.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmarkdown.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmarkdown.instructions.md) | Documentation and content creation standards | +| [MCP-based M365 Copilot Development Guidelines](../instructions/mcp-m365-copilot.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmcp-m365-copilot.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmcp-m365-copilot.instructions.md) | Best practices for building MCP-based declarative agents and API plugins for Microsoft 365 Copilot with Model Context Protocol integration | | [Memory Bank](../instructions/memory-bank.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmemory-bank.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmemory-bank.instructions.md) | Bank specific coding standards and best practices | | [Microsoft 365 Declarative Agents Development Guidelines](../instructions/declarative-agents-microsoft365.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdeclarative-agents-microsoft365.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdeclarative-agents-microsoft365.instructions.md) | Comprehensive development guidelines for Microsoft 365 Copilot declarative agents with schema v1.5, TypeSpec integration, and Microsoft 365 Agents Toolkit workflows | | [MongoDB DBA Chat Mode Instructions](../instructions/mongo-dba.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmongo-dba.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmongo-dba.instructions.md) | Instructions for customizing GitHub Copilot behavior for MONGODB DBA chat mode. | diff --git a/docs/README.prompts.md b/docs/README.prompts.md index b1dcaa1e7..55f4e2157 100644 --- a/docs/README.prompts.md +++ b/docs/README.prompts.md @@ -84,6 +84,9 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi | [Javascript Typescript Jest](../prompts/javascript-typescript-jest.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjavascript-typescript-jest.prompt.md) | Best practices for writing JavaScript/TypeScript tests using Jest, including mocking strategies, test structure, and common patterns. | | [JUnit 5+ Best Practices](../prompts/java-junit.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md) | Get best practices for JUnit 5 unit testing, including data-driven tests | | [Kotlin MCP Server Project Generator](../prompts/kotlin-mcp-server-generator.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-mcp-server-generator.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fkotlin-mcp-server-generator.prompt.md) | Generate a complete Kotlin MCP server project with proper structure, dependencies, and implementation using the official io.modelcontextprotocol:kotlin-sdk library. | +| [Mcp Create Adaptive Cards](../prompts/mcp-create-adaptive-cards.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-adaptive-cards.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-adaptive-cards.prompt.md) | | | +| [Mcp Create Declarative Agent](../prompts/mcp-create-declarative-agent.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-declarative-agent.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-create-declarative-agent.prompt.md) | | | +| [Mcp Deploy Manage Agents](../prompts/mcp-deploy-manage-agents.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-deploy-manage-agents.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmcp-deploy-manage-agents.prompt.md) | | | | [Memory Keeper](../prompts/remember.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember.prompt.md) | Transforms lessons learned into domain-organized memory instructions (global or workspace). Syntax: `/remember [>domain [scope]] lesson clue` where scope is `global` (default), `user`, `workspace`, or `ws`. | | [Memory Merger](../prompts/memory-merger.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmemory-merger.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fmemory-merger.prompt.md) | Merges mature lessons from a domain memory file into its instruction file. Syntax: `/memory-merger >domain [scope]` where scope is `global` (default), `user`, `workspace`, or `ws`. | | [Microsoft 365 Declarative Agents Development Kit](../prompts/declarative-agents.prompt.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdeclarative-agents.prompt.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fdeclarative-agents.prompt.md) | Complete development kit for Microsoft 365 Copilot declarative agents with three comprehensive workflows (basic, advanced, validation), TypeSpec support, and Microsoft 365 Agents Toolkit integration | diff --git a/instructions/mcp-m365-copilot.instructions.md b/instructions/mcp-m365-copilot.instructions.md new file mode 100644 index 000000000..c5733423c --- /dev/null +++ b/instructions/mcp-m365-copilot.instructions.md @@ -0,0 +1,357 @@ +--- +description: 'Best practices for building MCP-based declarative agents and API plugins for Microsoft 365 Copilot with Model Context Protocol integration' +applyTo: '**/{*mcp*,*agent*,*plugin*,declarativeAgent.json,ai-plugin.json,mcp.json,manifest.json}' +--- + +# MCP-based M365 Copilot Development Guidelines + +## Core Principles + +### Model Context Protocol First +- Leverage MCP servers for external system integration +- Import tools from server endpoints, not manual definitions +- Let MCP handle schema discovery and function generation +- Use point-and-click tool selection in Agents Toolkit + +### Declarative Over Imperative +- Define agent behavior through configuration, not code +- Use declarativeAgent.json for instructions and capabilities +- Specify tools and actions in ai-plugin.json +- Configure MCP servers in mcp.json + +### Security and Governance +- Always use OAuth 2.0 or SSO for authentication +- Follow principle of least privilege for tool selection +- Validate MCP server endpoints are secure +- Review compliance requirements before deployment + +### User-Centric Design +- Create adaptive cards for rich visual responses +- Provide clear conversation starters +- Design for responsive experience across hubs +- Test thoroughly before organizational deployment + +## MCP Server Design + +### Server Selection +Choose MCP servers that: +- Expose relevant tools for user tasks +- Support secure authentication (OAuth 2.0, SSO) +- Provide reliable uptime and performance +- Follow MCP specification standards +- Return well-structured response data + +### Tool Import Strategy +- Import only necessary tools (avoid over-scoping) +- Group related tools from same server +- Test each tool individually before combining +- Consider token limits when selecting multiple tools + +### Authentication Configuration +**OAuth 2.0 Static Registration:** +```json +{ + "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" +} +``` + +**SSO (Microsoft Entra ID):** +```json +{ + "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" +} +``` + +## File Organization + +### Project Structure +``` +project-root/ +├── appPackage/ +│ ├── manifest.json # Teams app manifest +│ ├── declarativeAgent.json # Agent config (instructions, capabilities) +│ ├── ai-plugin.json # API plugin definition +│ ├── color.png # App icon color +│ └── outline.png # App icon outline +├── .vscode/ +│ └── mcp.json # MCP server configuration +├── .env.local # Credentials (NEVER commit) +└── teamsapp.yml # Teams Toolkit config +``` + +### Critical Files + +**declarativeAgent.json:** +- Agent name and description +- Instructions for behavior +- Conversation starters +- Capabilities (actions from plugins) + +**ai-plugin.json:** +- MCP server tools import +- Response semantics (data_path, properties) +- Static adaptive card templates +- Function definitions (auto-generated) + +**mcp.json:** +- MCP server URL +- Server metadata endpoint +- Authentication reference + +**.env.local:** +- OAuth client credentials +- API keys and secrets +- Environment-specific config +- **CRITICAL**: Add to .gitignore + +## Response Semantics Best Practices + +### Data Path Configuration +Use JSONPath to extract relevant data: +```json +{ + "data_path": "$.items[*]", + "properties": { + "title": "$.name", + "subtitle": "$.description", + "url": "$.html_url" + } +} +``` + +### Template Selection +For dynamic templates: +```json +{ + "data_path": "$", + "template_selector": "$.templateType", + "properties": { + "title": "$.title", + "url": "$.url" + } +} +``` + +### Static Templates +Define in ai-plugin.json for consistent formatting: +- Use when all responses follow same structure +- Better performance than dynamic templates +- Easier to maintain and version control + +## Adaptive Card Guidelines + +### Design Principles +- **Single-column layout**: Stack elements vertically +- **Flexible widths**: Use "stretch" or "auto", not fixed pixels +- **Responsive design**: Test in Chat, Teams, Outlook +- **Minimal complexity**: Keep cards simple and scannable + +### Template Language Patterns +**Conditionals:** +```json +{ + "type": "TextBlock", + "text": "${if(status == 'active', '✅ Active', '❌ Inactive')}" +} +``` + +**Data Binding:** +```json +{ + "type": "TextBlock", + "text": "${title}", + "weight": "bolder" +} +``` + +**Number Formatting:** +```json +{ + "type": "TextBlock", + "text": "Score: ${formatNumber(score, 0)}" +} +``` + +**Conditional Rendering:** +```json +{ + "type": "Container", + "$when": "${count(items) > 0}", + "items": [ ... ] +} +``` + +### Card Elements Usage +- **TextBlock**: Titles, descriptions, metadata +- **FactSet**: Key-value pairs (status, dates, IDs) +- **Image**: Icons, thumbnails (use size: "small") +- **Container**: Grouping related content +- **ActionSet**: Buttons for follow-up actions + +## Testing and Deployment + +### Local Testing Workflow +1. **Provision**: Teams Toolkit → Provision +2. **Deploy**: Teams Toolkit → Deploy +3. **Sideload**: App uploaded to Teams +4. **Test**: Visit [m365.cloud.microsoft/chat](https://m365.cloud.microsoft/chat) +5. **Iterate**: Fix issues and re-deploy + +### Pre-Deployment Checklist +- [ ] All MCP server tools tested individually +- [ ] Authentication flow works end-to-end +- [ ] Adaptive cards render correctly across hubs +- [ ] Response semantics extract expected data +- [ ] Error handling provides clear messages +- [ ] Conversation starters are relevant and clear +- [ ] Agent instructions guide proper behavior +- [ ] Compliance and security reviewed + +### Deployment Options +**Organization Deployment:** +- IT admin deploys to all or selected users +- Requires approval in Microsoft 365 admin center +- Best for internal business agents + +**Agent Store:** +- Submit to Partner Center for validation +- Public availability to all Copilot users +- Requires rigorous security review + +## Common Patterns + +### Multi-Tool Agent +Import tools from multiple MCP servers: +```json +{ + "mcpServers": { + "github": { + "url": "https://github-mcp.example.com" + }, + "jira": { + "url": "https://jira-mcp.example.com" + } + } +} +``` + +### Search and Display +1. Tool retrieves data from MCP server +2. Response semantics extract relevant fields +3. Adaptive card displays formatted results +4. User can take action from card buttons + +### Authenticated Actions +1. User triggers tool requiring auth +2. OAuth flow redirects for consent +3. Access token stored in plugin vault +4. Subsequent requests use stored token + +## Error Handling + +### MCP Server Errors +- Provide clear error messages in agent responses +- Fall back to alternative tools if available +- Log errors for debugging +- Guide user to retry or alternative approach + +### Authentication Failures +- Check OAuth credentials in .env.local +- Verify scopes match required permissions +- Test auth flow outside Copilot first +- Ensure token refresh logic works + +### Response Parsing Failures +- Validate JSONPath expressions in response semantics +- Handle missing or null data gracefully +- Provide default values where appropriate +- Test with varied API responses + +## Performance Optimization + +### Tool Selection +- Import only necessary tools (reduces token usage) +- Avoid redundant tools from multiple servers +- Test impact of each tool on response time + +### Response Size +- Use data_path to filter unnecessary data +- Limit result sets where possible +- Consider pagination for large datasets +- Keep adaptive cards lightweight + +### Caching Strategy +- MCP servers should cache where appropriate +- Agent responses may be cached by M365 +- Consider cache invalidation for time-sensitive data + +## Security Best Practices + +### Credential Management +- **NEVER** commit .env.local to source control +- Use environment variables for all secrets +- Rotate OAuth credentials regularly +- Use separate credentials for dev/prod + +### Data Privacy +- Only request minimum necessary scopes +- Avoid logging sensitive user data +- Review data residency requirements +- Follow compliance policies (GDPR, etc.) + +### Server Validation +- Verify MCP server is trusted and secure +- Check HTTPS endpoints only +- Review server's privacy policy +- Test for injection vulnerabilities + +## Governance and Compliance + +### Admin Controls +Agents can be: +- **Blocked**: Prevented from use +- **Deployed**: Assigned to specific users/groups +- **Published**: Made available organization-wide + +### Monitoring +Track: +- Agent usage and adoption +- Error rates and performance +- User feedback and satisfaction +- Security incidents + +### Audit Requirements +Maintain: +- Change history for agent configurations +- Access logs for sensitive operations +- Approval records for deployments +- Compliance attestations + +## Resources and References + +### Official Documentation +- [Build Declarative Agents with MCP (DevBlogs)](https://devblogs.microsoft.com/microsoft365dev/build-declarative-agents-for-microsoft-365-copilot-with-mcp/) +- [Build MCP Plugins (Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/build-mcp-plugins) +- [API Plugin Adaptive Cards (Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api-plugin-adaptive-cards) +- [Manage Copilot Agents (Learn)](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-copilot-agents-integrated-apps) + +### Tools and SDKs +- Microsoft 365 Agents Toolkit (VS Code extension v6.3.x+) +- Teams Toolkit for agent packaging +- Adaptive Cards Designer +- MCP specification documentation + +### Partner Examples +- monday.com: Task management integration +- Canva: Design automation +- Sitecore: Content management diff --git a/prompts/mcp-create-adaptive-cards.prompt.md b/prompts/mcp-create-adaptive-cards.prompt.md new file mode 100644 index 000000000..f076fb64e --- /dev/null +++ b/prompts/mcp-create-adaptive-cards.prompt.md @@ -0,0 +1,527 @@ +````prompt +--- +mode: 'agent' +tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems'] +description: 'Add Adaptive Card response templates to MCP-based API plugins for visual data presentation in Microsoft 365 Copilot' +model: 'gpt-4.1' +tags: [mcp, adaptive-cards, m365-copilot, api-plugin, response-templates] +--- + +# Create Adaptive Cards for MCP Plugins + +Add Adaptive Card response templates to MCP-based API plugins to enhance how data is presented visually in Microsoft 365 Copilot. + +## Adaptive Card Types + +### Static Response Templates +Use when API always returns items of the same type and format doesn't change often. + +Define in `response_semantics.static_template` in ai-plugin.json: + +```json +{ + "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 + } + ] + } + ] + } + } + } + } + ] +} +``` + +### Dynamic Response Templates +Use when API returns multiple types and each item needs a different template. + +**ai-plugin.json configuration:** +```json +{ + "name": "GetTransactions", + "description": "Returns transaction details with dynamic templates", + "capabilities": { + "response_semantics": { + "data_path": "$.transactions", + "properties": { + "template_selector": "$.displayTemplate" + } + } + } +} +``` + +**API Response with Embedded Templates:** +```json +{ + "transactions": [ + { + "budgetName": "Fourth Coffee lobby renovation", + "amount": -2000, + "description": "Property survey for permit application", + "expenseCategory": "permits", + "displayTemplate": "$.templates.debit" + }, + { + "budgetName": "Fourth Coffee lobby renovation", + "amount": 5000, + "description": "Additional funds to cover cost overruns", + "expenseCategory": null, + "displayTemplate": "$.templates.credit" + } + ], + "templates": { + "debit": { + "type": "AdaptiveCard", + "version": "1.5", + "body": [ + { + "type": "TextBlock", + "size": "medium", + "weight": "bolder", + "color": "attention", + "text": "Debit" + }, + { + "type": "FactSet", + "facts": [ + { + "title": "Budget", + "value": "${budgetName}" + }, + { + "title": "Amount", + "value": "${formatNumber(amount, 2)}" + }, + { + "title": "Category", + "value": "${if(expenseCategory, expenseCategory, 'N/A')}" + }, + { + "title": "Description", + "value": "${if(description, description, 'N/A')}" + } + ] + } + ], + "$schema": "http://adaptivecards.io/schemas/adaptive-card.json" + }, + "credit": { + "type": "AdaptiveCard", + "version": "1.5", + "body": [ + { + "type": "TextBlock", + "size": "medium", + "weight": "bolder", + "color": "good", + "text": "Credit" + }, + { + "type": "FactSet", + "facts": [ + { + "title": "Budget", + "value": "${budgetName}" + }, + { + "title": "Amount", + "value": "${formatNumber(amount, 2)}" + }, + { + "title": "Description", + "value": "${if(description, description, 'N/A')}" + } + ] + } + ], + "$schema": "http://adaptivecards.io/schemas/adaptive-card.json" + } + } +} +``` + +### Combined Static and Dynamic Templates +Use static template as default when item doesn't have template_selector or when value doesn't resolve. + +```json +{ + "capabilities": { + "response_semantics": { + "data_path": "$.items", + "properties": { + "title": "$.name", + "template_selector": "$.templateId" + }, + "static_template": { + "type": "AdaptiveCard", + "version": "1.5", + "body": [ + { + "type": "TextBlock", + "text": "Default: ${name}", + "wrap": true + } + ] + } + } + } +} +``` + +## Response Semantics Properties + +### data_path +JSONPath query indicating where data resides in API response: +```json +"data_path": "$" // Root of response +"data_path": "$.results" // In results property +"data_path": "$.data.items"// Nested path +``` + +### properties +Map response fields for Copilot citations: +```json +"properties": { + "title": "$.name", // Citation title + "subtitle": "$.description", // Citation subtitle + "url": "$.link" // Citation link +} +``` + +### template_selector +Property on each item indicating which template to use: +```json +"template_selector": "$.displayTemplate" +``` + +## Adaptive Card Template Language + +### Conditional Rendering +```json +{ + "type": "TextBlock", + "text": "${if(field, field, 'N/A')}" // Show field or 'N/A' +} +``` + +### Number Formatting +```json +{ + "type": "TextBlock", + "text": "${formatNumber(amount, 2)}" // Two decimal places +} +``` + +### Data Binding +```json +{ + "type": "Container", + "$data": "${$root}", // Break to root context + "items": [ ... ] +} +``` + +### Conditional Display +```json +{ + "type": "Image", + "url": "${imageUrl}", + "$when": "${imageUrl != null}" // Only show if imageUrl exists +} +``` + +## Card Elements + +### TextBlock +```json +{ + "type": "TextBlock", + "text": "Text content", + "size": "medium", // small, default, medium, large, extraLarge + "weight": "bolder", // lighter, default, bolder + "color": "attention", // default, dark, light, accent, good, warning, attention + "wrap": true +} +``` + +### FactSet +```json +{ + "type": "FactSet", + "facts": [ + { + "title": "Label", + "value": "Value" + } + ] +} +``` + +### Image +```json +{ + "type": "Image", + "url": "https://example.com/image.png", + "size": "medium", // auto, stretch, small, medium, large + "style": "default" // default, person +} +``` + +### Container +```json +{ + "type": "Container", + "$data": "${items}", // Iterate over array + "items": [ + { + "type": "TextBlock", + "text": "${name}" + } + ] +} +``` + +### ColumnSet +```json +{ + "type": "ColumnSet", + "columns": [ + { + "type": "Column", + "width": "auto", + "items": [ ... ] + }, + { + "type": "Column", + "width": "stretch", + "items": [ ... ] + } + ] +} +``` + +### Actions +```json +{ + "type": "Action.OpenUrl", + "title": "View Details", + "url": "https://example.com/item/${id}" +} +``` + +## Responsive Design Best Practices + +### Single-Column Layouts +- Use single columns for narrow viewports +- Avoid multi-column layouts when possible +- Ensure cards work at minimum viewport width + +### Flexible Widths +- Don't assign fixed widths to elements +- Use "auto" or "stretch" for width properties +- Allow elements to resize with viewport +- Fixed widths OK for icons/avatars only + +### Text and Images +- Avoid placing text and images in same row +- Exception: Small icons or avatars +- Use "wrap": true for text content +- Test at various viewport widths + +### Test Across Hubs +Validate cards in: +- Teams (desktop and mobile) +- Word +- PowerPoint +- Various viewport widths (contract/expand UI) + +## Complete Example + +**ai-plugin.json:** +```json +{ + "functions": [ + { + "name": "SearchProjects", + "description": "Search for projects with status and details", + "capabilities": { + "response_semantics": { + "data_path": "$.projects", + "properties": { + "title": "$.name", + "subtitle": "$.status", + "url": "$.projectUrl" + }, + "static_template": { + "type": "AdaptiveCard", + "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", + "version": "1.5", + "body": [ + { + "type": "Container", + "$data": "${$root}", + "items": [ + { + "type": "TextBlock", + "size": "medium", + "weight": "bolder", + "text": "${if(name, name, 'Untitled Project')}", + "wrap": true + }, + { + "type": "FactSet", + "facts": [ + { + "title": "Status", + "value": "${status}" + }, + { + "title": "Owner", + "value": "${if(owner, owner, 'Unassigned')}" + }, + { + "title": "Due Date", + "value": "${if(dueDate, dueDate, 'Not set')}" + }, + { + "title": "Budget", + "value": "${if(budget, formatNumber(budget, 2), 'N/A')}" + } + ] + }, + { + "type": "TextBlock", + "text": "${if(description, description, 'No description')}", + "wrap": true, + "separator": true + } + ] + } + ], + "actions": [ + { + "type": "Action.OpenUrl", + "title": "View Project", + "url": "${projectUrl}" + } + ] + } + } + } + } + ] +} +``` + +## Workflow + +Ask the user: +1. What type of data does the API return? +2. Are all items the same type (static) or different types (dynamic)? +3. What fields should appear in the card? +4. Should there be actions (e.g., "View Details")? +5. Are there multiple states or categories requiring different templates? + +Then generate: +- Appropriate response_semantics configuration +- Static template, dynamic templates, or both +- Proper data binding with conditional rendering +- Responsive single-column layout +- Test scenarios for validation + +## Resources + +- [Adaptive Card Designer](https://adaptivecards.microsoft.com/designer) - Visual design tool +- [Adaptive Card Schema](https://adaptivecards.io/schemas/adaptive-card.json) - Full schema reference +- [Template Language](https://learn.microsoft.com/en-us/adaptive-cards/templating/language) - Binding syntax guide +- [JSONPath](https://www.rfc-editor.org/rfc/rfc9535) - Path query syntax + +## Common Patterns + +### List with Images +```json +{ + "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 + } + ] + } + ] + } + ] +} +``` + +### Status Indicators +```json +{ + "type": "TextBlock", + "text": "${status}", + "color": "${if(status == 'Completed', 'good', if(status == 'In Progress', 'attention', 'default'))}" +} +``` + +### Currency Formatting +```json +{ + "type": "TextBlock", + "text": "$${formatNumber(amount, 2)}" +} +``` + +```` \ No newline at end of file diff --git a/prompts/mcp-create-declarative-agent.prompt.md b/prompts/mcp-create-declarative-agent.prompt.md new file mode 100644 index 000000000..7602a05d4 --- /dev/null +++ b/prompts/mcp-create-declarative-agent.prompt.md @@ -0,0 +1,310 @@ +````prompt +--- +mode: 'agent' +tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems'] +description: 'Create a declarative agent for Microsoft 365 Copilot by integrating an MCP server with authentication, tool selection, and configuration' +model: 'gpt-4.1' +tags: [mcp, m365-copilot, declarative-agent, model-context-protocol, api-plugin] +--- + +# Create MCP-based Declarative Agent for Microsoft 365 Copilot + +Create a complete declarative agent for Microsoft 365 Copilot that integrates with a Model Context Protocol (MCP) server to access external systems and data. + +## Requirements + +Generate the following project structure using Microsoft 365 Agents Toolkit: + +### Project Setup +1. **Scaffold declarative agent** via Agents Toolkit +2. **Add MCP action** pointing to MCP server +3. **Select tools** to import from MCP server +4. **Configure authentication** (OAuth 2.0 or SSO) +5. **Review generated files** (manifest.json, ai-plugin.json, declarativeAgent.json) + +### Key Files Generated + +**appPackage/manifest.json** - Teams app manifest with plugin reference: +```json +{ + "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json", + "manifestVersion": "devPreview", + "version": "1.0.0", + "id": "...", + "developer": { + "name": "...", + "websiteUrl": "...", + "privacyUrl": "...", + "termsOfUseUrl": "..." + }, + "name": { + "short": "Agent Name", + "full": "Full Agent Name" + }, + "description": { + "short": "Short description", + "full": "Full description" + }, + "copilotAgents": { + "declarativeAgents": [ + { + "id": "declarativeAgent", + "file": "declarativeAgent.json" + } + ] + } +} +``` + +**appPackage/declarativeAgent.json** - Agent definition: +```json +{ + "$schema": "https://aka.ms/json-schemas/copilot/declarative-agent/v1.0/schema.json", + "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" + } + ] +} +``` + +**appPackage/ai-plugin.json** - MCP plugin manifest: +```json +{ + "schema_version": "v2.1", + "name_for_human": "Service Name", + "description_for_human": "Description for users", + "description_for_model": "Description for AI model", + "contact_email": "support@company.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.json** - MCP server configuration: +```json +{ + "serverUrl": "https://api.service.com/mcp/", + "pluginFilePath": "appPackage/ai-plugin.json" +} +``` + +## MCP Server Integration + +### Supported MCP Endpoints +The MCP server must provide: +- **Server metadata** endpoint +- **Tools listing** endpoint (exposes available functions) +- **Tool execution** endpoint (handles function calls) + +### Tool Selection +When importing from MCP: +1. Fetch available tools from server +2. Select specific tools to include (for security/simplicity) +3. Tool definitions are auto-generated in ai-plugin.json + +### Authentication Types + +**OAuth 2.0 (Static Registration)** +```json +"auth": { + "type": "OAuthPluginVault", + "reference_id": "${{OAUTH_REFERENCE_ID}}", + "authorization_url": "https://auth.service.com/authorize", + "client_id": "${{CLIENT_ID}}", + "client_secret": "${{CLIENT_SECRET}}", + "scope": "read write" +} +``` + +**Single Sign-On (SSO)** +```json +"auth": { + "type": "SSO" +} +``` + +## Response Semantics + +### Define Data Mapping +Use `response_semantics` to extract relevant fields from API responses: + +```json +"capabilities": { + "response_semantics": { + "data_path": "$.results", + "properties": { + "title": "$.name", + "subtitle": "$.description", + "url": "$.link" + } + } +} +``` + +### Add Adaptive Cards (Optional) +See the `mcp-create-adaptive-cards` prompt for adding visual card templates. + +## Environment Configuration + +Create `.env.local` or `.env.dev` for credentials: + +```env +OAUTH_REFERENCE_ID=your-oauth-reference-id +CLIENT_ID=your-client-id +CLIENT_SECRET=your-client-secret +``` + +## Testing & Deployment + +### Local Testing +1. **Provision** agent in Agents Toolkit +2. **Start debugging** to sideload in Teams +3. Test in Microsoft 365 Copilot at https://m365.cloud.microsoft/chat +4. Authenticate when prompted +5. Query the agent using natural language + +### Validation +- Verify tool imports in ai-plugin.json +- Check authentication configuration +- Test each exposed function +- Validate response data mapping + +## Best Practices + +### Tool Design +- **Focused functions**: Each tool should do one thing well +- **Clear descriptions**: Help the model understand when to use each tool +- **Minimal scoping**: Only import tools the agent needs +- **Descriptive names**: Use action-oriented function names + +### Security +- **Use OAuth 2.0** for production scenarios +- **Store secrets** in environment variables +- **Validate inputs** on the MCP server side +- **Limit scopes** to minimum required permissions +- **Use reference IDs** for OAuth registration + +### Instructions +- **Be specific** about the agent's purpose and capabilities +- **Define behavior** for both successful and error scenarios +- **Reference tools** explicitly in instructions when applicable +- **Set expectations** for users about what the agent can/cannot do + +### Performance +- **Cache responses** when appropriate on MCP server +- **Batch operations** where possible +- **Set timeouts** for long-running operations +- **Paginate results** for large datasets + +## Common MCP Server Examples + +### GitHub MCP Server +``` +URL: https://api.githubcopilot.com/mcp/ +Tools: search_repositories, search_users, get_repository +Auth: OAuth 2.0 +``` + +### Jira MCP Server +``` +URL: https://your-domain.atlassian.net/mcp/ +Tools: search_issues, create_issue, update_issue +Auth: OAuth 2.0 +``` + +### Custom Service +``` +URL: https://api.your-service.com/mcp/ +Tools: Custom tools exposed by your service +Auth: OAuth 2.0 or SSO +``` + +## Workflow + +Ask the user: +1. What MCP server are you integrating with (URL)? +2. What tools should be exposed to Copilot? +3. What authentication method does the server support? +4. What should the agent's primary purpose be? +5. Do you need response semantics or Adaptive Cards? + +Then generate: +- Complete appPackage/ structure (manifest.json, declarativeAgent.json, ai-plugin.json) +- mcp.json configuration +- .env.local template +- Provisioning and testing instructions + +## Troubleshooting + +### MCP Server Not Responding +- Verify server URL is correct +- Check network connectivity +- Validate MCP server implements required endpoints + +### Authentication Fails +- Verify OAuth credentials are correct +- Check reference ID matches registration +- Confirm scopes are requested properly +- Test OAuth flow independently + +### Tools Not Appearing +- Ensure mcp.json points to correct server +- Verify tools were selected during import +- Check ai-plugin.json has correct function definitions +- Re-fetch actions from MCP if server changed + +### Agent Not Understanding Queries +- Review instructions in declarativeAgent.json +- Check function descriptions are clear +- Verify response_semantics extract correct data +- Test with more specific queries + +```` \ No newline at end of file diff --git a/prompts/mcp-deploy-manage-agents.prompt.md b/prompts/mcp-deploy-manage-agents.prompt.md new file mode 100644 index 000000000..093a52ba3 --- /dev/null +++ b/prompts/mcp-deploy-manage-agents.prompt.md @@ -0,0 +1,336 @@ +````prompt +--- +mode: 'agent' +tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems'] +description: 'Deploy and manage MCP-based declarative agents in Microsoft 365 admin center with governance, assignments, and organizational distribution' +model: 'gpt-4.1' +tags: [mcp, m365-copilot, deployment, admin, agent-management, governance] +--- + +# Deploy and Manage MCP-Based Agents + +Deploy, manage, and govern MCP-based declarative agents in Microsoft 365 using the admin center for organizational distribution and control. + +## Agent Types + +### Published by Organization +- Built with predefined instructions and actions +- Follow structured logic for predictable tasks +- Require admin approval and publishing process +- Support compliance and governance requirements + +### Shared by Creator +- Created in Microsoft 365 Copilot Studio or Agent Builder +- Shared directly with specific users +- Enhanced functionality with search, actions, connectors, APIs +- Visible to admins in agent registry + +### Microsoft Agents +- Developed and maintained by Microsoft +- Integrated with Microsoft 365 services +- Pre-approved and ready to use + +### External Partner Agents +- Created by verified external developers/vendors +- Subject to admin approval and control +- Configurable availability and permissions + +### Frontier Agents +- Experimental or advanced capabilities +- May require limited rollout or additional oversight +- Examples: + - **App Builder agent**: Managed via M365 Copilot or Power Platform admin center + - **Workflows agent**: Flow automation managed via Power Platform admin center + +## Admin Roles and Permissions + +### Required Roles +- **AI Admin**: Full agent management capabilities +- **Global Reader**: View-only access (no editing) + +### Best Practices +- Use roles with fewest permissions +- Limit Global Administrator to emergency scenarios +- Follow principle of least privilege + +## Agent Management in Microsoft 365 Admin Center + +### Access Agent Management +1. Go to [Microsoft 365 admin center](https://admin.microsoft.com/) +2. Navigate to **Agents** page +3. View available, deployed, or blocked agents + +### Available Actions + +**View Agents** +- Filter by availability (available, deployed, blocked) +- Search for specific agents +- View agent details (name, creator, date, host products, status) + +**Deploy Agents** +Options for distribution: +1. **Agent Store**: Submit to Partner Center for validation and public availability +2. **Organization Deployment**: IT admin deploys to all or selected employees + +**Manage Agent Lifecycle** +- **Publish**: Make agent available to organization +- **Deploy**: Assign to specific users or groups +- **Block**: Prevent agent from being used +- **Remove**: Delete agent from organization + +**Configure Access** +- Set availability for specific user groups +- Manage permissions per agent +- Control which agents appear in Copilot + +## Deployment Workflows + +### Publish to Organization + +**For Agent Developers:** +1. Build agent with Microsoft 365 Agents Toolkit +2. Test thoroughly in development +3. Submit agent for approval +4. Wait for admin review + +**For Admins:** +1. Review submitted agent in admin center +2. Validate compliance and security +3. Approve for organizational use +4. Configure deployment settings +5. Publish to selected users or organization-wide + +### Deploy via Agent Store + +**Developer Steps:** +1. Complete agent development and testing +2. Package agent for submission +3. Submit to Partner Center +4. Await validation process +5. Receive approval notification +6. Agent appears in Copilot store + +**Admin Steps:** +1. Discover agents in Copilot store +2. Review agent details and permissions +3. Assign to organization or user groups +4. Monitor usage and feedback + +### Deploy Organizational Agent + +**Admin Deployment Options:** +``` +Organization-wide: +- All employees with Copilot license +- Automatically available in Copilot + +Group-based: +- Specific departments or teams +- Security group assignments +- Role-based access control +``` + +**Configuration Steps:** +1. Navigate to Agents page in admin center +2. Select agent to deploy +3. Choose deployment scope: + - All users + - Specific security groups + - Individual users +4. Set availability status +5. Configure permissions if applicable +6. Deploy and monitor + +## User Experience + +### Agent Discovery +Users find agents in: +- Microsoft 365 Copilot hub +- Agent picker in Copilot interface +- Organization's agent catalog + +### Agent Access Control +Users can: +- Toggle agents on/off during interactions +- Add/remove agents from their experience +- Right-click agents to manage preferences +- Only access admin-allowed agents + +### Agent Usage +- Agents appear in Copilot sidebar +- Users select agent for context +- Queries routed through selected agent +- Responses leverage agent's capabilities + +## Governance and Compliance + +### Security Considerations +- **Data access**: Review what data agent can access +- **API permissions**: Validate required scopes +- **Authentication**: Ensure secure OAuth flows +- **External connections**: Assess risk of external integrations + +### Compliance Requirements +- **Data residency**: Verify data stays within boundaries +- **Privacy policies**: Review agent privacy statement +- **Terms of use**: Validate acceptable use policies +- **Audit logs**: Monitor agent usage and activity + +### Monitoring and Reporting +Track: +- Agent adoption rates +- User feedback and satisfaction +- Error rates and performance +- Security incidents or violations + +## MCP-Specific Management + +### MCP Agent Characteristics +- Connect to external systems via Model Context Protocol +- Use tools exposed by MCP servers +- Require OAuth 2.0 or SSO authentication +- Support same governance as REST API agents + +### MCP Agent Validation +Verify: +- MCP server URL is accessible +- Authentication configuration is secure +- Tools imported are appropriate +- Response data doesn't expose sensitive info +- Server follows security best practices + +### MCP Agent Deployment +Same process as REST API agents: +1. Review in admin center +2. Validate MCP server compliance +3. Test authentication flow +4. Deploy to users/groups +5. Monitor performance + +## Agent Settings and Configuration + +### Organizational Settings +Configure at tenant level: +- Enable/disable agent creation +- Set default permissions +- Configure approval workflows +- Define compliance policies + +### Per-Agent Settings +Configure for individual agents: +- Availability (on/off) +- User assignment (all/groups/individuals) +- Permission scopes +- Usage limits or quotas + +### Environment Routing +For Power Platform-based agents: +- Configure default environment +- Enable environment routing for Copilot Studio +- Manage flows via Power Platform admin center + +## Shared Agent Management + +### View Shared Agents +Admins can see: +- List of all shared agents +- Creator information +- Creation date +- Host products +- Availability status + +### Manage Shared Agents +Admin actions: +- Search for specific shared agents +- View agent capabilities +- Block unsafe or non-compliant agents +- Monitor agent lifecycle + +### User Access to Shared Agents +Users access through: +- Microsoft 365 Copilot on various surfaces +- Agent-specific tasks and assistance +- Creator-defined capabilities + +## Best Practices + +### Before Deployment +- **Pilot test** with small user group +- **Gather feedback** from early adopters +- **Validate security** and compliance +- **Document** agent capabilities and limitations +- **Train users** on agent usage + +### During Deployment +- **Phased rollout** to manage adoption +- **Monitor performance** and errors +- **Collect feedback** continuously +- **Address issues** promptly +- **Communicate** availability to users + +### Post-Deployment +- **Track metrics**: Adoption, satisfaction, errors +- **Iterate**: Improve based on feedback +- **Update**: Keep agent current with new features +- **Retire**: Remove obsolete or unused agents +- **Review**: Regular security and compliance audits + +### Communication +- Announce new agents to users +- Provide documentation and examples +- Share best practices and use cases +- Highlight benefits and capabilities +- Offer support channels + +## Troubleshooting + +### Agent Not Appearing +- Check deployment status in admin center +- Verify user is in assigned group +- Confirm agent is not blocked +- Check user has Copilot license +- Refresh Copilot interface + +### Authentication Failures +- Verify OAuth credentials are valid +- Check user has necessary permissions +- Confirm MCP server is accessible +- Test authentication flow independently + +### Performance Issues +- Monitor MCP server response times +- Check network connectivity +- Review error logs in admin center +- Validate agent isn't rate-limited + +### Compliance Violations +- Block agent immediately if unsafe +- Review audit logs for violations +- Investigate data access patterns +- Update policies to prevent recurrence + +## Resources + +- [Microsoft 365 admin center](https://admin.microsoft.com/) +- [Power Platform admin center](https://admin.powerplatform.microsoft.com/) +- [Partner Center](https://partner.microsoft.com/) for agent submissions +- [Microsoft Agent 365 Overview](https://learn.microsoft.com/en-us/microsoft-agent-365/overview) +- [Agent Registry Documentation](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/agent-registry) + +## Workflow + +Ask the user: +1. Is this agent ready for deployment or still in development? +2. Who should have access (all users, specific groups, individuals)? +3. Are there compliance or security requirements to address? +4. Should this be published to the organization or the public store? +5. What monitoring and reporting is needed? + +Then provide: +- Step-by-step deployment guide +- Admin center configuration steps +- User assignment recommendations +- Governance and compliance checklist +- Monitoring and reporting plan + +```` \ No newline at end of file