From cc0322b6b948900112b6e97282d5f5b9427a80cf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 13 Oct 2025 18:45:40 +0000 Subject: [PATCH 1/8] Initial plan From 94b1338bb1cf8cf08e0aa18cf31545a2696c6c99 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 13 Oct 2025 18:51:53 +0000 Subject: [PATCH 2/8] Add Copilot instructions for repository Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com> --- .github/copilot-instructions.md | 159 ++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..0cace1511 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,159 @@ +# Copilot Instructions for MCP C# SDK + +This repository contains the official C# SDK for the Model Context Protocol (MCP), enabling .NET applications to implement and interact with MCP clients and servers. + +## Project Overview + +The SDK consists of three main packages: +- **ModelContextProtocol** - The main package with hosting and dependency injection extensions +- **ModelContextProtocol.AspNetCore** - HTTP-based MCP server implementations +- **ModelContextProtocol.Core** - Client and low-level server APIs with minimal dependencies + +## C# Coding Standards + +### Language Features +- Use **file-scoped namespaces** for all C# files +- Enable **implicit usings** and **nullable reference types** +- Use **preview language features** (LangVersion: preview) +- Treat warnings as errors + +### Code Style +- Follow the conventions in `.editorconfig` +- Use clear, descriptive XML documentation comments for public APIs +- Follow async/await patterns consistently +- Use file-scoped namespaces: `namespace ModelContextProtocol.Client;` + +### Naming Conventions +- Use `McpClient`, `McpServer`, `McpSession` for MCP-related classes (capitalize MCP) +- Prefix MCP-specific types with `Mcp` (e.g., `McpException`, `McpEndpoint`) +- Use descriptive names for parameters with `[Description("...")]` attributes when exposing to MCP + +## Architecture Patterns + +### Dependency Injection +- Use Microsoft.Extensions.DependencyInjection patterns +- Register services with `.AddMcpServer()` and `.AddMcpClient()` extension methods +- Support both builder patterns and options configuration + +### JSON Serialization +- Use `System.Text.Json` for all JSON operations +- Use `McpJsonUtilities.DefaultOptions` for consistent serialization +- Support source generation for Native AOT compatibility +- Set `JsonIgnoreCondition.WhenWritingNull` for optional properties + +### Async Patterns +- All I/O operations should be async +- Use `ValueTask` for hot paths that may complete synchronously +- Always accept `CancellationToken` parameters for async operations +- Name parameters consistently: `cancellationToken` + +### MCP Protocol +- Follow the MCP specification at https://spec.modelcontextprotocol.io/ +- Use JSON-RPC 2.0 for message transport +- Support standard MCP capabilities: tools, prompts, resources, sampling +- Implement proper error handling with `McpException` and `McpErrorCode` + +## Testing + +### Test Organization +- Unit tests in `tests/ModelContextProtocol.Tests` +- Integration tests in `tests/ModelContextProtocol.AspNetCore.Tests` +- Test helpers in `tests/Common` +- Filter manual tests with `[Trait("Execution", "Manual")]` + +### Test Infrastructure +- Use xUnit for all tests +- Run tests with: `dotnet test --filter '(Execution!=Manual)'` +- Tests should be isolated and not depend on external services (except manual tests) + +## Build and Development + +### Build Commands +- **Restore**: `dotnet restore` or `make restore` +- **Build**: `dotnet build` or `make build` +- **Test**: `dotnet test` or `make test` +- **Clean**: `dotnet clean` or `make clean` + +### SDK Requirements +- The project uses .NET SDK preview versions +- Target frameworks: .NET 8.0, .NET 9.0, .NET Standard 2.0 +- Support Native AOT compilation + +### Project Structure +- Source code: `src/` +- Tests: `tests/` +- Samples: `samples/` +- Documentation: `docs/` +- Build artifacts: `artifacts/` (not committed) + +## Common Patterns + +### MCP Server Tools +Tools are exposed using attributes: +```csharp +[McpServerToolType] +public class MyTools +{ + [McpServerTool, Description("Tool description")] + public static async Task MyTool( + [Description("Parameter description")] string param, + CancellationToken cancellationToken) + { + // Implementation + } +} +``` + +### MCP Server Prompts +Prompts are exposed similarly: +```csharp +[McpServerPromptType] +public static class MyPrompts +{ + [McpServerPrompt, Description("Prompt description")] + public static ChatMessage MyPrompt([Description("Parameter description")] string content) => + new(ChatRole.User, $"Prompt template: {content}"); +} +``` + +### Client Usage +```csharp +var client = await McpClient.CreateAsync( + new StdioClientTransport(new() { Command = "...", Arguments = [...] }), + clientOptions: new() { /* ... */ }, + loggerFactory: loggerFactory); + +var tools = await client.ListToolsAsync(); +var result = await client.CallToolAsync("tool-name", arguments, cancellationToken); +``` + +## OpenTelemetry Integration + +- The SDK includes built-in observability support +- Use ActivitySource name: `"Experimental.ModelContextProtocol"` +- Use Meter name: `"Experimental.ModelContextProtocol"` +- Export traces and metrics using OTLP when appropriate + +## Documentation + +- API documentation is generated using DocFX +- Conceptual documentation is in `docs/concepts/` +- Keep README files up to date in package directories +- Use `///` XML comments for all public APIs +- Include `` sections for detailed explanations + +## Security + +- Never commit secrets or API keys +- Use environment variables for sensitive configuration +- Support authentication mechanisms (OAuth, API keys) +- Validate all user inputs +- Follow secure coding practices per SECURITY.md + +## Additional Notes + +- This is a preview SDK; breaking changes may occur +- Follow the Model Context Protocol specification +- Integrate with Microsoft.Extensions.AI patterns where applicable +- Support both stdio and HTTP transports +- Maintain compatibility with the broader MCP ecosystem From 780e1a92f2bb3977c8a8116838312e035d94d1f2 Mon Sep 17 00:00:00 2001 From: Stephen Toub Date: Mon, 13 Oct 2025 15:00:00 -0400 Subject: [PATCH 3/8] Apply suggestions from code review --- .github/copilot-instructions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0cace1511..6afd1781c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -5,9 +5,9 @@ This repository contains the official C# SDK for the Model Context Protocol (MCP ## Project Overview The SDK consists of three main packages: -- **ModelContextProtocol** - The main package with hosting and dependency injection extensions -- **ModelContextProtocol.AspNetCore** - HTTP-based MCP server implementations - **ModelContextProtocol.Core** - Client and low-level server APIs with minimal dependencies +- **ModelContextProtocol** - The main package with hosting and dependency injection extensions and which references ModelContextProtocol.Core +- **ModelContextProtocol.AspNetCore** - HTTP-based MCP server implementations for ASP.NET Core, referencing ModelContextProtocol ## C# Coding Standards @@ -48,9 +48,9 @@ The SDK consists of three main packages: - Name parameters consistently: `cancellationToken` ### MCP Protocol -- Follow the MCP specification at https://spec.modelcontextprotocol.io/ +- Follow the MCP specification at https://spec.modelcontextprotocol.io/ (https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs/specification) - Use JSON-RPC 2.0 for message transport -- Support standard MCP capabilities: tools, prompts, resources, sampling +- Support all standard MCP capabilities (e.g. tools, prompts, resources, sampling) - Implement proper error handling with `McpException` and `McpErrorCode` ## Testing From c4db42832f58b89624b05a7307b6d06dea372916 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 13 Oct 2025 19:27:01 +0000 Subject: [PATCH 4/8] Refocus instructions on library implementation and architecture Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com> --- .github/copilot-instructions.md | 142 +++++++++++++++++++++++++------- 1 file changed, 114 insertions(+), 28 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6afd1781c..8eaa382d9 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -36,10 +36,13 @@ The SDK consists of three main packages: - Support both builder patterns and options configuration ### JSON Serialization -- Use `System.Text.Json` for all JSON operations -- Use `McpJsonUtilities.DefaultOptions` for consistent serialization -- Support source generation for Native AOT compatibility -- Set `JsonIgnoreCondition.WhenWritingNull` for optional properties +- Use `System.Text.Json` exclusively for all JSON operations +- Use `McpJsonUtilities.DefaultOptions` for consistent serialization settings across the SDK +- Support source generation for Native AOT compatibility via `McpJsonUtilities` source generators +- Set `JsonIgnoreCondition.WhenWritingNull` for optional properties to minimize payload size +- Use `JsonSerializerDefaults.Web` for camelCase property naming +- Protocol types are decorated with `[JsonSerializable]` attributes for AOT support +- Custom converters: `CustomizableJsonStringEnumConverter` for flexible enum serialization ### Async Patterns - All I/O operations should be async @@ -53,18 +56,38 @@ The SDK consists of three main packages: - Support all standard MCP capabilities (e.g. tools, prompts, resources, sampling) - Implement proper error handling with `McpException` and `McpErrorCode` +### Error Handling +- Throw `McpException` for MCP protocol-level errors with appropriate `McpErrorCode` +- Use standard error codes: `InvalidRequest`, `MethodNotFound`, `InvalidParams`, `InternalError` +- Let domain exceptions bubble up and convert to `InternalError` at transport boundary +- Include detailed error messages in exception `Message` property for debugging +- Errors are automatically converted to JSON-RPC error responses by the server infrastructure + ## Testing ### Test Organization -- Unit tests in `tests/ModelContextProtocol.Tests` -- Integration tests in `tests/ModelContextProtocol.AspNetCore.Tests` -- Test helpers in `tests/Common` -- Filter manual tests with `[Trait("Execution", "Manual")]` - -### Test Infrastructure -- Use xUnit for all tests +- Unit tests in `tests/ModelContextProtocol.Tests` for core functionality +- Integration tests in `tests/ModelContextProtocol.AspNetCore.Tests` for HTTP/SSE transports +- Shared test utilities in `tests/Common/Utils/` +- Test servers in `tests/ModelContextProtocol.Test*Server/` for integration scenarios +- Filter manual tests with `[Trait("Execution", "Manual")]` - these require external dependencies + +### Test Infrastructure and Helpers +- **LoggedTest**: Base class for tests that need logging output captured to xUnit test output + - Provides `ILoggerFactory` and `ITestOutputHelper` for test logging + - Use when debugging or when tests need to verify log output +- **TestServerTransport**: In-memory transport for testing client-server interactions without network I/O +- **MockLoggerProvider**: For capturing and asserting on log messages +- **XunitLoggerProvider**: Routes `ILogger` output to xUnit's `ITestOutputHelper` +- **KestrelInMemoryTransport** (AspNetCore.Tests): In-memory Kestrel connection for HTTP transport testing without network stack + +### Test Best Practices +- Inherit from `LoggedTest` for tests needing logging infrastructure +- Use `TestServerTransport` for in-memory client-server testing +- Mock external dependencies (filesystem, HTTP clients) rather than calling real services +- Use `CancellationTokenSource` with timeouts to prevent hanging tests +- Dispose resources properly (servers, clients, transports) using `IDisposable` or `await using` - Run tests with: `dotnet test --filter '(Execution!=Manual)'` -- Tests should be isolated and not depend on external services (except manual tests) ## Build and Development @@ -75,8 +98,8 @@ The SDK consists of three main packages: - **Clean**: `dotnet clean` or `make clean` ### SDK Requirements -- The project uses .NET SDK preview versions -- Target frameworks: .NET 8.0, .NET 9.0, .NET Standard 2.0 +- The project currently uses .NET SDK 10.0 RC (this is temporary while waiting for .NET 10 to go GA) +- Target frameworks: .NET 10.0, .NET 9.0, .NET 8.0, .NET Standard 2.0 - Support Native AOT compilation ### Project Structure @@ -86,10 +109,40 @@ The SDK consists of three main packages: - Documentation: `docs/` - Build artifacts: `artifacts/` (not committed) -## Common Patterns - -### MCP Server Tools -Tools are exposed using attributes: +## Architecture and Design Patterns + +### Server Implementation Architecture +- **McpServer** is the core server implementation in `ModelContextProtocol.Core/Server/` +- **IMcpServerBuilder** pattern provides fluent API for configuring servers via DI +- Server primitives (tools, prompts, resources) are discovered via reflection using attributes +- Support both attribute-based registration (`WithTools()`) and instance-based (`WithTools(target)`) +- Use `McpServerFactory` to create server instances with configured options + +### Tool/Prompt/Resource Discovery +- Tools, prompts, and resources use attribute-based discovery: `[McpServerTool]`, `[McpServerPrompt]`, `[McpServerResource]` +- Type-level attributes (`[McpServerToolType]`, etc.) mark classes containing server primitives +- Discovery supports both static and instance methods (public and non-public) +- For Native AOT compatibility, use generic `WithTools()` methods instead of reflection-based variants +- `AIFunctionMcpServerTool`, `AIFunctionMcpServerPrompt`, and `AIFunctionMcpServerResource` wrap `AIFunction` for integration with Microsoft.Extensions.AI + +### Request Processing Pipeline +- Requests flow through `McpServer.Methods.cs` which handles JSON-RPC message routing +- Use `McpRequestFilter` for cross-cutting concerns (logging, auth, validation) +- `RequestContext` provides access to current request state and services +- `RequestServiceProvider` enables scoped dependency injection per request +- Filters can short-circuit request processing or transform requests/responses + +### Transport Layer Abstraction +- Transport implementations handle message serialization and connection management +- Core transports: `StdioServerTransport`, `StreamServerTransport`, `SseResponseStreamTransport`, `StreamableHttpServerTransport` +- Transports must implement bidirectional JSON-RPC message exchange +- SSE (Server-Sent Events) transport for unidirectional server→client streaming +- Streamable HTTP for request/response with streamed progress updates + +## Implementation Patterns + +### Tool Implementation +Tools are methods marked with `[McpServerTool]`: ```csharp [McpServerToolType] public class MyTools @@ -99,13 +152,18 @@ public class MyTools [Description("Parameter description")] string param, CancellationToken cancellationToken) { - // Implementation + // Implementation - use Description attributes for parameter documentation + // Return string, TextContent, ImageContent, EmbeddedResource, or arrays of these } } ``` +- Tools support dependency injection in constructors for instance methods +- Parameters are automatically deserialized from JSON using `System.Text.Json` +- Use `[Description]` attributes on parameters to generate tool schemas +- Return types: `string`, `TextContent`, `ImageContent`, `EmbeddedResource`, or collections of content types -### MCP Server Prompts -Prompts are exposed similarly: +### Prompt Implementation +Prompts return `ChatMessage` or arrays thereof: ```csharp [McpServerPromptType] public static class MyPrompts @@ -115,17 +173,45 @@ public static class MyPrompts new(ChatRole.User, $"Prompt template: {content}"); } ``` +- Prompts can accept arguments to customize generated messages +- Return single `ChatMessage` or `ChatMessage[]` for multi-turn prompts +- Use `ChatRole.User`, `ChatRole.Assistant`, or `ChatRole.System` appropriately -### Client Usage +### Resource Implementation +Resources provide access to data with URI templates: ```csharp -var client = await McpClient.CreateAsync( - new StdioClientTransport(new() { Command = "...", Arguments = [...] }), - clientOptions: new() { /* ... */ }, - loggerFactory: loggerFactory); +[McpServerResourceType] +public class MyResources +{ + [McpServerResource("file:///{path}"), Description("Reads file content")] + public static async Task ReadFile(string path, CancellationToken cancellationToken) + { + // Resource URI matching uses UriTemplate syntax + // Extract parameters from URI and return content + } +} +``` +- Use URI templates to define resource paths with parameters +- Resources support subscription for dynamic content updates +- Return content types similar to tools -var tools = await client.ListToolsAsync(); -var result = await client.CallToolAsync("tool-name", arguments, cancellationToken); +### Filters and Middleware +Implement `McpRequestFilter` for request/response interception: +```csharp +public class LoggingFilter : McpRequestFilter +{ + public override async ValueTask InvokeAsync(RequestContext context, Func next) + { + // Pre-processing + await next(); // Call next filter or handler + // Post-processing + } +} ``` +- Filters execute in registration order +- Can short-circuit by not calling `next()` +- Access request context, services, and can modify responses +- Use for cross-cutting concerns: logging, auth, validation, caching ## OpenTelemetry Integration From a54c6c2a319918f34c8a6951f182ca7eae1da5f8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 13 Oct 2025 19:39:33 +0000 Subject: [PATCH 5/8] Add key types and architectural layers documentation Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com> --- .github/copilot-instructions.md | 82 ++++++++++++++++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8eaa382d9..fd5b688db 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -98,7 +98,7 @@ The SDK consists of three main packages: - **Clean**: `dotnet clean` or `make clean` ### SDK Requirements -- The project currently uses .NET SDK 10.0 RC (this is temporary while waiting for .NET 10 to go GA) +- The repo currently requires the .NET SDK 10.0 to build and run tests. - Target frameworks: .NET 10.0, .NET 9.0, .NET 8.0, .NET Standard 2.0 - Support Native AOT compilation @@ -109,6 +109,86 @@ The SDK consists of three main packages: - Documentation: `docs/` - Build artifacts: `artifacts/` (not committed) +## Key Types and Architectural Layers + +The SDK is organized into distinct architectural layers, each with specific responsibilities: + +### Protocol Layer (DTO Types) +- Located in `ModelContextProtocol.Core/Protocol/` +- Contains Data Transfer Objects (DTOs) for the MCP specification +- All protocol types follow JSON-RPC 2.0 conventions +- Key types: + - **JsonRpcMessage** (abstract base): Represents any JSON-RPC message (request, response, notification, error) + - **JsonRpcRequest**, **JsonRpcResponse**, **JsonRpcNotification**: Concrete message types + - **Tool**, **Prompt**, **Resource**: MCP primitive definitions + - **CallToolRequestParams**, **GetPromptRequestParams**, **ReadResourceRequestParams**: Request parameter types + - **ClientCapabilities**, **ServerCapabilities**: Capability negotiation types + - **Implementation**: Server/client identification metadata + +### JSON-RPC Implementation +- Built-in JSON-RPC 2.0 implementation for MCP communication +- **JsonRpcMessage.Converter**: Polymorphic converter that deserializes messages into correct types based on structure +- **JsonRpcMessageContext**: Transport-specific metadata (transport reference, execution context, authenticated user) +- Message routing handled automatically by session implementations +- Error responses generated via **McpException** with **McpErrorCode** enumeration + +### Transport Abstraction +- **ITransport**: Core abstraction for bidirectional communication + - Provides `MessageReader` (ChannelReader) for incoming messages + - `SendMessageAsync()` for outgoing messages + - `SessionId` property for multi-session scenarios +- **IClientTransport**: Client-side abstraction that establishes connections and returns ITransport +- **TransportBase**: Base class for transport implementations with common functionality + +### Transport Implementations +Two primary transport implementations with different invariants: + +1. **Stdio-based transports** (`StdioServerTransport`, `StdioClientTransport`): + - Single-session, process-bound communication + - Uses standard input/output streams + - No session IDs (returns null) + - Automatic lifecycle tied to process + +2. **HTTP-based transports**: + - **SseResponseStreamTransport**: Server-Sent Events for server-to-client streaming + - Unidirectional (server → client) event stream + - Client posts messages to separate endpoint (e.g., `/message`) + - Supports multiple concurrent sessions via SessionId + - **StreamableHttpServerTransport**: Bidirectional HTTP with streaming + - Request/response model with streamed progress updates + - Session management for concurrent connections + +### Session Layer +- **McpSession** (abstract base): Core bidirectional communication for clients and servers + - Manages JSON-RPC request/response correlation + - Handles notification routing + - Provides `SendRequestAsync()`, `SendNotificationAsync()`, `RegisterNotificationHandler()` + - Properties: `SessionId`, `NegotiatedProtocolVersion` + +- **McpClient** (extends McpSession): Client-side MCP implementation + - Connects to servers via `CreateAsync(IClientTransport)` + - Exposes `ServerCapabilities`, `ServerInfo`, `ServerInstructions` + - Methods: `ListToolsAsync()`, `CallToolAsync()`, `ListPromptsAsync()`, `GetPromptAsync()`, etc. + +- **McpServer** (extends McpSession): Server-side MCP implementation + - Configured via `McpServerOptions` and `IMcpServerBuilder` + - Primitives registered as services: `McpServerTool`, `McpServerPrompt`, `McpServerResource` + - Handles incoming requests through `McpServer.Methods.cs` + - Supports filters via `McpRequestFilter` for cross-cutting concerns + +### Serialization Architecture +- **McpJsonUtilities.DefaultOptions**: Singleton JsonSerializerOptions for all MCP types + - Hardcoded to use source-generated serialization for JSON-RPC messages (Native AOT compatible) + - Source generation defined in `McpJsonUtilities` via `[JsonSerializable]` attributes + - Includes Microsoft.Extensions.AI types via chained TypeInfoResolver + +- **User-defined types** (tool parameters, return values): + - Accept custom `JsonSerializerOptions` via `McpServerToolCreateOptions.SerializerOptions` + - Default to `McpJsonUtilities.DefaultOptions` if not specified + - Can use reflection-based serialization or custom source generators + +- **Enum handling**: `CustomizableJsonStringEnumConverter` for flexible enum serialization + ## Architecture and Design Patterns ### Server Implementation Architecture From e86dd9a0033a97b9e86bc4915febbf4f4824bb92 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 13 Oct 2025 21:22:17 +0000 Subject: [PATCH 6/8] Fix markdown link formatting for link checker Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index fd5b688db..63d73ed23 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -51,7 +51,7 @@ The SDK consists of three main packages: - Name parameters consistently: `cancellationToken` ### MCP Protocol -- Follow the MCP specification at https://spec.modelcontextprotocol.io/ (https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs/specification) +- Follow the MCP specification at https://spec.modelcontextprotocol.io/ ([specification docs](https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs/specification)) - Use JSON-RPC 2.0 for message transport - Support all standard MCP capabilities (e.g. tools, prompts, resources, sampling) - Implement proper error handling with `McpException` and `McpErrorCode` From 7ba4a5ffe5850c7a5801667c0b4181d477f3872b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 13 Oct 2025 22:24:48 +0000 Subject: [PATCH 7/8] Add explicit build and test requirements to instructions Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com> --- .github/copilot-instructions.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 63d73ed23..19b7878b2 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,6 +2,19 @@ This repository contains the official C# SDK for the Model Context Protocol (MCP), enabling .NET applications to implement and interact with MCP clients and servers. +## Critical: Always Build and Test + +**ALWAYS build and run tests before declaring any task complete or making a pull request.** + +When making code changes: +1. **Build first**: Run `dotnet build` or `make build` to ensure the code compiles without errors +2. **Run tests**: Execute `dotnet test --filter '(Execution!=Manual)'` or `make test` to verify all tests pass +3. **Fix issues**: Address any build errors or test failures before proceeding +4. **Verify iteratively**: Build and test frequently during development, not just at the end +5. **Check warnings**: Treat warnings as errors - the build is configured with `TreatWarningsAsErrors=true` + +**Never skip these steps.** Even small changes can have unexpected impacts. A passing build and test suite is the minimum bar for any code change. + ## Project Overview The SDK consists of three main packages: @@ -97,6 +110,16 @@ The SDK consists of three main packages: - **Test**: `dotnet test` or `make test` - **Clean**: `dotnet clean` or `make clean` +### Development Workflow +**Critical**: Always follow this workflow when making changes: +1. Make code changes +2. Build immediately: `dotnet build` - fix any compilation errors +3. Run tests: `dotnet test --filter '(Execution!=Manual)'` - fix any test failures +4. Repeat steps 1-3 iteratively as you develop +5. Only after successful build and tests should you consider the change complete + +Do not skip or defer building and testing. These are mandatory steps for every code change, no matter how small. + ### SDK Requirements - The repo currently requires the .NET SDK 10.0 to build and run tests. - Target frameworks: .NET 10.0, .NET 9.0, .NET 8.0, .NET Standard 2.0 From 3d464f857d778f876d789cf51f7bd38197f74615 Mon Sep 17 00:00:00 2001 From: Stephen Toub Date: Mon, 13 Oct 2025 21:48:03 -0400 Subject: [PATCH 8/8] Apply suggestions from code review --- .github/copilot-instructions.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 19b7878b2..dc8f0ca6d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,8 +7,8 @@ This repository contains the official C# SDK for the Model Context Protocol (MCP **ALWAYS build and run tests before declaring any task complete or making a pull request.** When making code changes: -1. **Build first**: Run `dotnet build` or `make build` to ensure the code compiles without errors -2. **Run tests**: Execute `dotnet test --filter '(Execution!=Manual)'` or `make test` to verify all tests pass +1. **Build first**: Run `dotnet build` to ensure the code compiles without errors +2. **Run tests**: Execute `dotnet test` to verify all tests pass 3. **Fix issues**: Address any build errors or test failures before proceeding 4. **Verify iteratively**: Build and test frequently during development, not just at the end 5. **Check warnings**: Treat warnings as errors - the build is configured with `TreatWarningsAsErrors=true` @@ -105,16 +105,16 @@ The SDK consists of three main packages: ## Build and Development ### Build Commands -- **Restore**: `dotnet restore` or `make restore` -- **Build**: `dotnet build` or `make build` -- **Test**: `dotnet test` or `make test` -- **Clean**: `dotnet clean` or `make clean` +- **Restore**: `dotnet restore` +- **Build**: `dotnet build` +- **Test**: `dotnet test` +- **Clean**: `dotnet clean` ### Development Workflow **Critical**: Always follow this workflow when making changes: 1. Make code changes 2. Build immediately: `dotnet build` - fix any compilation errors -3. Run tests: `dotnet test --filter '(Execution!=Manual)'` - fix any test failures +3. Run tests: `dotnet test` - fix any test failures 4. Repeat steps 1-3 iteratively as you develop 5. Only after successful build and tests should you consider the change complete