-
Notifications
You must be signed in to change notification settings - Fork 4.1k
feat(skills): add dotnet-mcp-builder, deprecate csharp-mcp-server-gen… #1645
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
aaronpowell
merged 5 commits into
github:staged
from
AClerbois:skill/dotnet-mcp-builder
May 10, 2026
Merged
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
aaafd7f
feat(skills): add dotnet-mcp-builder, deprecate csharp-mcp-server-gen…
AClerbois 521542c
fix: address PR review from aaronpowell
AClerbois aa23f7e
Merge branch 'staged' into skill/dotnet-mcp-builder
AClerbois 71129af
chore: remove C# MCP development plugin files
AClerbois 35ab26a
chore: remove csharp-mcp-development plugin entry from marketplace
AClerbois File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,59 +1,24 @@ | ||
| --- | ||
| name: csharp-mcp-server-generator | ||
| description: 'Generate a complete MCP server project in C# with tools, prompts, and proper configuration' | ||
| description: 'Deprecated: superseded by dotnet-mcp-builder, which targets the current stable ModelContextProtocol 1.x packages and covers every MCP primitive (tools, prompts, resources, elicitation, sampling, roots, MCP Apps) plus both transports (STDIO and Streamable HTTP). Install dotnet-mcp-builder instead.' | ||
| --- | ||
|
|
||
| # Generate C# MCP Server | ||
| # csharp-mcp-server-generator (deprecated) | ||
|
|
||
| Create a complete Model Context Protocol (MCP) server in C# with the following specifications: | ||
| This skill has been superseded by **`dotnet-mcp-builder`**. | ||
|
|
||
| ## Requirements | ||
| `dotnet-mcp-builder` is a strict superset: it targets the current stable `ModelContextProtocol` 1.x NuGet packages (this skill predated 1.0 and referenced the prerelease line, which has breaking API differences), covers both transports (STDIO and Streamable HTTP — the legacy HTTP+SSE transport is deprecated upstream), and covers every primitive in the current MCP spec (2025-11-25): tools, prompts, resources, elicitation (form + URL mode), sampling, roots, completions, logging, and MCP Apps. It also includes a basic .NET MCP client and testing reference, and steers the model away from common pitfalls — STDIO stdout/stderr trap, stateless-vs-stateful HTTP wiring, OAuth and reverse-proxy specifics for remote deployments. | ||
|
|
||
| 1. **Project Structure**: Create a new C# console application with proper directory structure | ||
| 2. **NuGet Packages**: Include ModelContextProtocol (prerelease) and Microsoft.Extensions.Hosting | ||
| 3. **Logging Configuration**: Configure all logs to stderr to avoid interfering with stdio transport | ||
| 4. **Server Setup**: Use the Host builder pattern with proper DI configuration | ||
| 5. **Tools**: Create at least one useful tool with proper attributes and descriptions | ||
| 6. **Error Handling**: Include proper error handling and validation | ||
| ## Migration steps | ||
|
|
||
| ## Implementation Details | ||
| 1. Install the replacement skill: | ||
| ``` | ||
| gh skills install github/awesome-copilot dotnet-mcp-builder | ||
| ``` | ||
| 2. (Optional) Uninstall this skill so the deprecation notice no longer appears in your skill list: | ||
| ``` | ||
| gh skills uninstall github/awesome-copilot csharp-mcp-server-generator | ||
| ``` | ||
| 3. Re-run your existing prompts. The new skill triggers on the same .NET MCP server intents and on a broader set (HTTP transport, prompts/resources, elicitation, MCP Apps, debugging). | ||
|
|
||
| ### Basic Project Setup | ||
| - Use .NET 8.0 or later | ||
| - Create a console application | ||
| - Add necessary NuGet packages with --prerelease flag | ||
| - Configure logging to stderr | ||
|
|
||
| ### Server Configuration | ||
| - Use `Host.CreateApplicationBuilder` for DI and lifecycle management | ||
| - Configure `AddMcpServer()` with stdio transport | ||
| - Use `WithToolsFromAssembly()` for automatic tool discovery | ||
| - Ensure the server runs with `RunAsync()` | ||
|
|
||
| ### Tool Implementation | ||
| - Use `[McpServerToolType]` attribute on tool classes | ||
| - Use `[McpServerTool]` attribute on tool methods | ||
| - Add `[Description]` attributes to tools and parameters | ||
| - Support async operations where appropriate | ||
| - Include proper parameter validation | ||
|
|
||
| ### Code Quality | ||
| - Follow C# naming conventions | ||
| - Include XML documentation comments | ||
| - Use nullable reference types | ||
| - Implement proper error handling with McpProtocolException | ||
| - Use structured logging for debugging | ||
|
|
||
| ## Example Tool Types to Consider | ||
| - File operations (read, write, search) | ||
| - Data processing (transform, validate, analyze) | ||
| - External API integrations (HTTP requests) | ||
| - System operations (execute commands, check status) | ||
| - Database operations (query, update) | ||
|
|
||
| ## Testing Guidance | ||
| - Explain how to run the server | ||
| - Provide example commands to test with MCP clients | ||
| - Include troubleshooting tips | ||
|
|
||
| Generate a complete, production-ready MCP server with comprehensive documentation and error handling. | ||
| The replacement skill lives under `skills/dotnet-mcp-builder/` in this repository. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| --- | ||
| name: dotnet-mcp-builder | ||
| description: 'Build Model Context Protocol (MCP) servers in C#/.NET against the current ModelContextProtocol 1.x NuGet packages. Especially helps with cases the model often gets wrong without guidance — stale preview versions (it tends to pick 0.3 or 0.4 preview), MCP Apps (interactive UI rendered in the host), elicitation URL mode, per-session HTTP wiring, OAuth and reverse-proxy deploy specifics, and debugging concrete MapMcp / STDIO / Streamable-HTTP errors. Also covers the routine work — STDIO and Streamable HTTP transports (SSE is deprecated), tools, prompts, resources, sampling, roots, completions, logging — and a basic .NET MCP client. Trigger when the user says or implies any .NET MCP server work: ModelContextProtocol, McpServerTool, MapMcp, WithStdioServerTransport, "MCP server in C#", "MCP tool in dotnet", "expose this as MCP", or names a primitive (prompt/resource/elicitation/MCP App) in a .NET context. Skip for MCP work in other languages.' | ||
| --- | ||
|
|
||
| # Building MCP servers in .NET | ||
|
|
||
| This skill helps you write production-quality MCP servers and basic clients in C#/.NET against the **official** [`ModelContextProtocol`](https://www.nuget.org/profiles/ModelContextProtocol) NuGet packages, maintained by Microsoft and the MCP project. It targets the **stable 1.x** line and the current spec (2025-11-25). | ||
|
|
||
| ## When this skill earns its keep | ||
|
|
||
| The .NET MCP SDK had years of preview packages (`0.x-preview`) before reaching `1.0`. Without help, the model tends to: | ||
| - Pin a stale preview version that won't compile against current samples. | ||
| - Miss recent spec features (elicitation URL mode, MCP Apps, structured content blocks). | ||
| - Get HTTP transport details wrong (stateful/stateless, proxy buffering, OAuth wiring). | ||
| - Forget the STDIO stdout/stderr trap. | ||
|
|
||
| If the task is one of those, *load the matching reference* and follow it. If it's truly trivial (e.g. "rename this tool method"), you don't need to read everything — the cardinal rules below are the minimum. | ||
|
|
||
| ## Mental model in 30 seconds | ||
|
|
||
| A .NET MCP server is an ordinary `Microsoft.Extensions.Hosting` (or `WebApplication`) app that wires an MCP server through DI: | ||
|
|
||
| ```csharp | ||
| builder.Services | ||
| .AddMcpServer() | ||
| .WithStdioServerTransport() // OR .WithHttpTransport(...) | ||
| .WithToolsFromAssembly() // discover [McpServerToolType] classes | ||
| .WithPrompts<MyPrompts>() // optional | ||
| .WithResources<MyResources>(); // optional | ||
| ``` | ||
|
|
||
| Primitives are plain C# methods on classes marked with attributes (`[McpServerToolType]` + `[McpServerTool]`, `[McpServerPromptType]` + `[McpServerPrompt]`, `[McpServerResourceType]` + `[McpServerResource]`). Parameters bind from JSON-RPC; the SDK builds the JSON Schema from the signature plus `[Description]` attributes. | ||
|
|
||
| Server-to-client features (sampling, elicitation, roots, log/progress notifications) are methods on the injected `IMcpServer`. | ||
|
|
||
| ## Decision tree → which references to load | ||
|
|
||
| Always load `references/packages.md` if you're creating a new project or unsure of the current package version. | ||
|
|
||
| | Task | Load | | ||
| |---|---| | ||
| | New STDIO server | `references/transport-stdio.md` | | ||
| | New HTTP (Streamable) server | `references/transport-http.md` | | ||
| | Add/modify a tool | `references/tool-primitive.md` | | ||
| | Add/modify a prompt | `references/prompt-primitive.md` | | ||
| | Add/modify a resource | `references/resource-primitive.md` | | ||
| | Ask the user a question mid-tool | `references/elicitation.md` | | ||
| | Call the client's LLM from a tool | `references/sampling.md` | | ||
| | Read the user's project roots | `references/roots.md` | | ||
| | Return an interactive UI | `references/mcp-apps.md` | | ||
| | Argument completions, log/progress notifications, filters, server instructions | `references/server-features.md` | | ||
| | Write a .NET program that **consumes** an MCP server | `references/client.md` | | ||
| | MCP Inspector, in-memory tests, mocks, CI | `references/testing.md` | | ||
|
|
||
| For multi-primitive tasks, load several at once. For trivial edits in an existing file, you usually don't need any. | ||
|
|
||
| ## Cardinal rules (apply always; these prevent the highest-frequency breakages) | ||
|
|
||
| 1. **Pin the current stable package, not a preview.** Use `ModelContextProtocol` / `ModelContextProtocol.AspNetCore` / `ModelContextProtocol.Core` at the latest **1.x**. If you find yourself writing `0.3-preview` or `0.4-preview`, stop and check NuGet — preview APIs have breaking differences. | ||
| 2. **STDIO servers must not write to stdout.** Stdout is the JSON-RPC channel. Configure `LogToStandardErrorThreshold = LogLevel.Trace` before anything else and never `Console.WriteLine` from a tool. | ||
| 3. **HTTP defaults to stateful.** For horizontally-scaled deployments without server-initiated traffic, set `options.Stateless = true`. Server-to-client features (sampling, elicitation, roots, unsolicited notifications) require stateful HTTP **or** STDIO — `Stateless = true` will break them at runtime. | ||
| 4. **SSE-only is deprecated.** Use Streamable HTTP. Only enable legacy SSE (`EnableLegacySse = true`) for an old client you must support, and call it out. | ||
| 5. **Always `[Description]` tools and parameters.** This is what the LLM sees when picking and shaping calls. Vague descriptions are the #1 reason tools don't get used. | ||
| 6. **Show the registration line every time you add a primitive.** A new `[McpServerPromptType]` class without `.WithPrompts<...>()` (or `.WithPromptsFromAssembly()`) is invisible. | ||
| 7. **Don't invent APIs.** If you're unsure a method exists, say so and check the [API reference](https://csharp.sdk.modelcontextprotocol.io/api/ModelContextProtocol.html) — wrong method names cause silent failures. | ||
|
|
||
| ## Working style | ||
|
|
||
| - **Make minimal, additive changes.** Add a method to the existing tool class rather than restructuring the project. | ||
| - **For non-trivial setups, run `dotnet build`.** Catches missing usings, attribute typos, and TFM mismatches before the user sees them. | ||
| - **Confirm transport + .NET version + primitives before scaffolding** if context doesn't already make them obvious. Default to **.NET 10** for new projects. | ||
|
|
||
| ## When the user is stuck | ||
|
|
||
| Walk this checklist before guessing: | ||
| 1. **STDIO:** something is writing to stdout (logger sink, `Console.WriteLine`, library banner). | ||
| 2. **HTTP 404:** path mismatch — `app.MapMcp()` is root, `app.MapMcp("/mcp")` puts it under `/mcp`. | ||
| 3. **Tool not appearing:** missing `[McpServerToolType]` on the class, or no `.WithToolsFromAssembly()` / `.WithTools<T>()` registered. | ||
| 4. **Args not bound:** parameter names must match the JSON-RPC `arguments` keys; complex types bind via `System.Text.Json`. | ||
| 5. **Sampling/elicitation/roots failing:** transport is stateless HTTP, or the client doesn't advertise the capability. | ||
|
|
||
| Still stuck? Point the user at the [`EverythingServer`](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/EverythingServer) sample — it exercises every feature. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.