Repository navigation
Graduate MCP endpoint declaration to stable - #22158
Maddy Montaquila (maddymontaquila) merged 4 commits into
Conversation
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 22158Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 22158" |
There was a problem hiding this comment.
🟢 Approval recommended
There are no active review issues blocking the WithMcpServer API graduation.
No open issues 🎉
What changed in this PR
Graduates Aspire’s WithMcpServer endpoint declaration helper to stable while preserving its API, export, and runtime behavior. MCP transport implementations and the separate PostgreSQL MCP integration remain outside this graduation.
Changes:
- Removes the experimental marker and related suppressions, and records
ASPIREMCP001as retired. - Clarifies endpoint selection, path handling, deferred resolution, and declaration-only behavior.
- Expands endpoint/path tests and updates TypeScript and Go snapshots to reflect the stable API documentation.
| File | Description |
|---|---|
tests/Aspire.Hosting.Tests/WithMcpServerTests.cs |
Removes suppression and expands endpoint selection, path, and failure coverage. |
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.ts |
Updates generated documentation and removes experimental notices. |
tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.go |
Updates generated documentation and removes experimental notices. |
src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs |
Removes the experimental attribute and documents the existing contract. |
src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs |
Removes the obsolete ASPIREMCP001 suppression. |
docs/list-of-diagnostics.md |
Records the retired diagnostic and its limited graduation scope. |
Review effort: Balanced
This comment has been minimized.
This comment has been minimized.
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
Retain existing endpoint selection and path resolution behavior, document the declaration-only contract, and remove ASPIREMCP001 suppressions. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
d810c2b to
b6b8fa5
Compare
This comment has been minimized.
This comment has been minimized.
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
|
Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt. |
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Tests selector52 / 101 PR test projects · 4 PR jobs, from 5 changed files. Selected PR test projects (52 / 101)
Selected PR jobs (4)
How these were chosen — grouped by what changed
🔧 show 39
🔧 🧪 📦 affected project 📦 affected project 🧪 🧪 Job reasons
Selection computed for commit |
| /// <param name="path">An optional path to append to the endpoint URL when forming the MCP server address. Defaults to <c>"/mcp"</c>.</param> | ||
| /// <param name="endpointName">An optional name of the endpoint that hosts the MCP server. If not specified, defaults to the first HTTPS or HTTP endpoint.</param> | ||
| /// <param name="path">An optional path to append to the endpoint URL when forming the MCP server address. Defaults to <c>"/mcp"</c>. | ||
| /// A leading slash is added if missing. A null or empty value uses the endpoint URL without an additional path.</param> |
6a7a7c4
into
release/17.0
|
Pull request created: #2171
|
|
📝 Documentation has been drafted in microsoft/aspire.dev#2171 targeting Documents that Note This draft PR needs human review before merging. |

Description
AppHosts can declare an existing MCP server with
WithMcpServerwithout suppressingASPIREMCP001. This graduates the endpoint declaration helper only; it retains the API, its[AspireExport], and all runtime behavior. It does not graduate a transport implementation or the separate PostgreSQL MCP integration.Removes the experimental attribute and the two directly related suppressions, documents the precise contract, records the retired diagnostic, and strengthens endpoint/path tests. Generated TypeScript and Go test snapshots now reflect the stable API and updated documentation. Generated
api/*.csand ATS release baselines are untouched. No new dependencies.Original API contributor: David Fowler (@davidfowl) — introduced in #14618, with the initial Copilot-authored commit crediting him as co-author and his follow-up implementation commit establishing the current endpoint-selection shape. Mentioning for awareness, not assigning a review or asserting approval to graduate.
Fixes # (issue)
Contract review
Preserves the existing declaration contract rather than broadening it:
https, thenhttp, independent of declaration order. Arbitrary names requireendpointName, even when their scheme is HTTPS. Missing selections fail during resolver consumption, not registration./mcp; a missing leading slash is added. Null/empty uses the base endpoint URL, and trailing path slashes are retained.These boundaries are grounded in the current implementation, dedicated tests, original introducing PR, and backchannel consumers. No claim is made about upstream protocol GA or maintainer graduation approval. Open PR searches for
ASPIREMCP001,WithMcpServer, and MCP stabilization found no duplicate.User-facing usage
For an existing resource
apithat exposes an MCP server on itshttpendpoint:The existing generated TypeScript shape is retained, without
@experimental:Release branch replay and conflict resolution
Targets
release/17.0. Replayed only the three intended stabilization/snapshot commits after the verified original-main fork point793dfe6e254fe050af24cb7bcfba214066dcaab8onto release commit9a97ab889bfb731de74ead0280be279ffdd000bf; unrelated main history is excluded.Subsequently merged release commit
bcfa151cdca6d0a573f22d5d9c23f9c727cb3b2fand resolved conflicts in diagnostic documentation and the Go snapshot. Preserved the release connection-string diagnostic explanation and its now-current...WithMcpServerOptionfunctional-option signature, retaining the stable MCP documentation and removing only the applicable experimental notices. The earlier replay had retained the pointer-option signature used by release at that time. No runtime implementation adaptations or new features were needed. The PR remains scoped to six changed files.Validation on release/17.0
The following commands passed again on conflict-resolution head
a4095d31cc6a8149cf8c3d097fa48292feba9417:./restore.sh— passed; zero warnings and zero errors.dotnet test --project tests/Aspire.Hosting.Tests/Aspire.Hosting.Tests.csproj --no-launch-profile -- --filter-class '*.WithMcpServerTests' --filter-class '*.McpServerEndpointAnnotationTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'— passed, 31 tests.dotnet test --project tests/Aspire.Hosting.PostgreSQL.Tests/Aspire.Hosting.PostgreSQL.Tests.csproj --no-launch-profile -- --filter-class '*.PostgresMcpBuilderTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'— passed, 5 tests.dotnet test --project tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests.csproj --no-launch-profile -- --filter-method '*.TwoPassScanning_GeneratesWithEnvironmentOnTestRedisBuilder' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'— passed, 1 test.dotnet test --project tests/Aspire.Hosting.CodeGeneration.Go.Tests/Aspire.Hosting.CodeGeneration.Go.Tests.csproj --no-launch-profile -- --filter-method '*.TwoPassScanning_GeneratesWithEnvironmentOnTestRedisBuilder' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'— passed, 1 test.dotnet test --project tests/Aspire.Hosting.CodeGeneration.Java.Tests/Aspire.Hosting.CodeGeneration.Java.Tests.csproj --no-launch-profile -- --filter-method '*.TwoPassScanning_GeneratesWithEnvironmentOnTestRedisBuilder' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'— passed, 1 test.dotnet test --project tests/Aspire.Hosting.CodeGeneration.Python.Tests/Aspire.Hosting.CodeGeneration.Python.Tests.csproj --no-launch-profile -- --filter-method '*.TwoPassScanning_GeneratesWithEnvironmentOnTestRedisBuilder' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'— passed, 1 test.dotnet test --project tests/Aspire.Hosting.CodeGeneration.Rust.Tests/Aspire.Hosting.CodeGeneration.Rust.Tests.csproj --no-launch-profile -- --filter-method '*.TwoPassScanning_GeneratesWithEnvironmentOnTestRedisBuilder' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true'— passed, 1 test.git diff --check origin/release/17.0...HEAD— passed.Total current release passing tests: 41. All snapshot tests passed on their first run, without further snapshot changes. The previous release replay at
b6b8fa54bedbdbb450b33e4d104b150d729efe77also passed the same 41 tests; its restore had 13 existing dependency vulnerability warnings and zero errors. No live MCP transport/authentication or deployment behavior was changed or tested.Previous main-branch validation
Before replaying onto release, the same test commands passed 41 tests on main-based head
d810c2bd15c412aa31d22e21a419864f394b16c3. The initial main-based TypeScript and Go runs intentionally failed while Verify refreshed the expected MCP-only snapshot changes; identical reruns passed after review. Those historical results are separate from the release validation above.Checklist
<remarks />and<code />elements on your triple slash comments?