AGENTS.md · microsoft/mcp

Sections

1. Do
2. Don't
3. Commands
4. Safety and Permissions
5. Project Overview
6. Project Structure
7. Development Environment Setup
8. API Docs and References
9. When Stuck
10. PR Checklist
11. Architecture and Project Structure
12. Build Commands and Development Workflow
13. Testing Strategy and Patterns
14. Code Style and Standards
15. Error Handling Patterns
16. Service Implementation Patterns
17. Adding New Commands and Services
18. Local Development and Testing
19. Performance and Compatibility
20. Remote MCP Server Architecture

First lines (shown under the repo's MIT license)

# AGENTS.md

## Do
- Use primary constructors for all C# classes
- Use `System.Text.Json`
- Make command classes sealed unless designed for inheritance
- Make members static when possible for AOT compatibility
- Put each class and interface in separate files
- Use `subscription` parameter (never `subscriptionId`) - supports both IDs and names
- Use `resourceGroup` (not `resourceGroupName`)
- Use singular nouns for resource names (e.g., `server`, not `serverName`)
- Run `dotnet build` after making changes
- Follow the `{Resource}{Operation}Command` naming pattern
- Use the two-generic pattern `SubscriptionCommand<TOptions, TResult>` for new commands
- Use `[Option]` attributes on flat POCO option classes for option declaration
- Use `ISubscriptionOption` interface on options classes that need subscription/tenant
- Always call `HandleException(context, ex)` in catch blocks
- Include live tests for all commands that interact with Azure resources
- Create Bicep templates for Azure service commands (`test-resources.bicep`)
- Include post-deployment scripts (`test-resources-post.ps1`)
- Record all live tests according to the guidelines in `/docs/recorded-tests.md`
- Submit one tool per pull request
- Use `BaseAzureResourceService` for Resource Graph queries when possible
- Register all response models in JSON serialization context for AOT safety
- Register all commands in the appropriate Setup.cs file
- Use concatenated lowercase for command group names (no dashes)
- Prefer file-scoped changes over project-wide modifications when possible
- Always review your own code for consistency, maintainability, and testability
- Always ask for clarifications if the request is ambiguous or lacks sufficient context
- Write transport-agnostic commands that work in both stdio and HTTP modes
- Keep commands stateless and thread-safe for multi-user remote scenarios
- Test commands with different RBAC permissions for OBO scenarios

## Don't
- Use `subscriptionId` parameter name
- Add unnecessary "-name" suffixes (use `--account` vs `--account-name`)
- Use the old one-generic `RegisterOptions`/`BindOptions` pattern for new commands (see `/docs/option-conversion.md`)
- Use `OptionDefinitions` static classes for new commands (use `[Option]` attributes instead)
- Use options class inheritance hierarchies (use flat POCOs with interface constraints)
- Skip live tests, live test infrastructure, or test recordings for Azure service commands
- Redefine base class properties in Options classes
- Leave commands unregistered
- Skip error handling or comprehensive tests
- Use dashes in command group names (use concatenated lowercase)
- Make project-wide changes when file-scoped changes suffice
- Check transport type in commands (stdio vs HTTP)
- Store per-request state in command instance fields
- Access HttpContext directly from commands
- Make transport-specific decisions in command logic
- Assume single-user scenarios when implementing services
- Use `git stash` in linked worktrees; the stash stack is shared across worktrees and can collide during concurrent work

## Commands

### File-scoped commands (preferred for faster feedback)
```powershell
# Build single project
dotnet build tools/Azure.Mcp.Tools.Storage/src

# Format specific files
dotnet format --include="tools/Azure.Mcp.Tools.Storage/**/*.cs"

# Test specific class
dotnet test --filter "FullyQualifiedName~StorageAccountListCommandTests"

# Type check and validate
./eng/scripts/Build-Local.ps1 -VerifyNpx

# Note: Don't run local builds to check pipeline YAML files (e.g., files in `eng/pipelines/` with `.yml` extension)
```

### Project-wide commands (use sparingly)
```powershell
# Full build (when explicitly requested)
dotnet build

# All tests (when needed)
./eng/scripts/Test-Code.ps1

# AOT compatibility check (for new toolsets)
./eng/scripts/Build-Local.ps1 -BuildNative
```

## Safety and Permissions

### Allowed without prompt
- Read files, list directories
- Single file builds (`dotnet build path/to/project`)
- Code formatting (`dotnet format --include="specific/path/**"`)
- Spelling checks (`.\eng\common\spelling\Invoke-Cspell.ps1`)
- Unit tests for specific classes
- Creating/updating documentation

### Ask first
- Installing new packages or dependencies
- Running project-wide builds or tests
- Modifying `.csproj`, `.slnx`, or configuration files
- Deploying test resources (`New-TestResources.ps1`)
- Making breaking changes to public APIs
- Adding new toolsets to the solution

## Project Overview
Microsoft MCP (Model Context Protocol) servers provide AI agents with structured access to Azure, Microsoft Fabric, and other Microsoft services. This repository contains the core libraries, multiple MCP servers, service-specific tools, and comprehensive testing infrastructure for building agent-integrated Microsoft service interactions.

**Key Components:**
- **Azure MCP Server**: Complete Azure service integration with 100+ tools
- **Microsoft Fabric MCP Server**: Fabric workspace and data platform operations
- **Core Libraries**: Shared infrastructure for command patterns, authentication, and MCP protocol
- **Toolsets**: Individual Azure service implementations (Storage, SQL, KeyVault, etc.)
- **Engineering System**: Build pipelines, testing infrastructure, and deployment automation

## Project Structure

### Key directories
- `core/Azure.Mcp.Core/` - Azure MCP core library with shared infrastructure
- `servers/Azure.Mcp.Server/` - Main Azure MCP server implementation
- `tools/Azure.Mcp.Tools.{Service}/` - Individual service toolsets (Storage, SQL, etc.)
- `eng/scripts/` - Build, test, and deployment PowerShell scripts
- `.github/skills/add-azure-mcp-tools/SKILL.md` - Implementation guide for new commands
- `docs/option-conversion.md` - Guide for converting to two-generic option pattern
- `CONTRIBUTING.md` - Contribution guidelines and workflows

### Good examples to follow
- Command implementation: `tools/Azure.Mcp.Tools.Storage/src/Commands/Account/AccountGetCommand.cs`
- Service pattern: `tools/Azure.Mcp.Tools.Storage/src/Services/StorageService.cs`
- Unit tests: `tools/Azure.Mcp.Tools.Storage/tests/Azure.Mcp.Tools.Storage.Tests/Account/StorageAccountGetCommandTests.cs`
- Integration tests: `tools/Azure.Mcp.Tools.Storage/tests/Azure.Mcp.Tools.Storage.Tests/StorageCommandTests.cs`
- Live test infrastructure: `tools/Azure.Mcp.Tools.Storage/tests/test-resources.bicep`
- Option conversion guide: `docs/option-conversion.md`

### Legacy patterns to avoid
- Old one-generic `RegisterOptions`/`BindOptions` pattern (use two-generic with `[Option]` attributes)
- `OptionDefinitions` static classes with `.AsRequired()`/`.AsOptional()` (use `[Option]` on flat POCOs)
- Options class inheritance hierarchies (use flat classes with interface constraints)
- Commands without proper error handling
- Missing live test infrastructure for Azure services
- Non-sealed command classes

## Development Environment Setup

### Prerequisites
1. **Visual Studio Code**: [VS Code Stable](https://code.visualstudio.com/download) or [Insiders](https://code.visualstudio.com/insiders)
2. **GitHub Copilot**: Install [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) and [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) extensions
3. **Node.js**: [Latest Node.js LTS](https://nodejs.org/en/download) (ensure `node` and `npm` are in PATH)
4. **PowerShell**: [PowerShell 7.0+](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) (required for build/test scripts)
5. **.NET SDK**: .NET 10 SDK (configured in `global.json`)
6. **Azure PowerShell**: For live tests - [Install Azure PowerShell](https://learn.microsoft.com/powershell/azure/install-azure-powershell)
7. **Azure Bicep**: For test infrastructure - [Install Azure Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/install#install-manually)

### Quick Start Commands
```powershell
# Clone and build the project
git clone https://github.com/microsoft/mcp.git
cd mcp
dotnet build

# Verify everything works
./eng/scripts/Build-Local.ps1 -VerifyNpx

# Run unit tests for specific toolset