✨ Set up Copilot instructions for repository

.github/copilot-instructions.md

@@ -0,0 +1,245 @@
+# 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.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
+
+### 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` 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
+- Use `ValueTask<T>` 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/ (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`
+
+### 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` 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)'`
+
+## 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 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
+- Source code: `src/`
+- Tests: `tests/`
+- Samples: `samples/`
+- Documentation: `docs/`
+- Build artifacts: `artifacts/` (not committed)
+
+## 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<T>()`) 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<T>()` 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
+{
+    [McpServerTool, Description("Tool description")]
+    public static async Task<string> MyTool(
+        [Description("Parameter description")] string param,
+        CancellationToken cancellationToken)
+    {
+        // 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
+
+### Prompt Implementation
+Prompts return `ChatMessage` or arrays thereof:
+```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}");
+}
+```
+- 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
+
+### Resource Implementation
+Resources provide access to data with URI templates:
+```csharp
+[McpServerResourceType]
+public class MyResources
+{
+    [McpServerResource("file:///{path}"), Description("Reads file content")]
+    public static async Task<string> 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
+
+### Filters and Middleware
+Implement `McpRequestFilter` for request/response interception:
+```csharp
+public class LoggingFilter : McpRequestFilter
+{
+    public override async ValueTask InvokeAsync(RequestContext context, Func<ValueTask> 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
+
+- 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 `<remarks>` 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