Update skill to CLI commands, rework agent init, add aspire mcp tools/call by davidfowl · Pull Request #14837 · microsoft/aspire

davidfowl · 2026-03-02T07:29:40Z

Description

Three related changes that shift the Aspire agent story from MCP-server-dependent to CLI-first:

1. Skill file: MCP tools → CLI commands

Updates the Aspire skill (SKILL.md generated by aspire agent init) to use CLI commands instead of MCP server tools. The skill no longer requires the MCP server to be configured — it works in any environment where the aspire CLI is installed.

Key changes:

aspire start instead of aspire run — agents should always use aspire start (detached), with --isolated in worktrees
aspire wait <resource> — block until a resource is healthy before interacting
aspire mcp tools / aspire mcp call — discover and invoke resource MCP tools via CLI
aspire docs search for finding integration docs
Explicit rules: never use aspire run, restart by re-running aspire start
Compact ~650 tokens (within optimal 500–2500 range per SkillsBench)

2. Agent init rework

Replaces the 3-group sequential prompt flow with a single flat prompt:

What would you like to configure? (Enter to skip, Ctrl+C to cancel)
  ✅ Install Aspire skill file (Recommended)
  ☐  Install Playwright CLI (Recommended for browser automation)
  ☐  Install Aspire MCP server

Skill file pre-selected, MCP server opt-in (last)
Deprecated config migrations applied silently
Categorization via McpInitPromptGroup (SkillFiles, Tools, AgentEnvironments) instead of string matching
Shows which environments were configured after applying
preSelected parameter added to PromptForSelectionsAsync

3. New CLI commands: `aspire mcp tools` / `aspire mcp call`

CLI-native MCP tool discovery and invocation for resources that expose MCP tools (e.g. WithPostgresMcp()):

aspire mcp tools                                              # list tools (table)
aspire mcp tools --format Json                                # includes input schemas
aspire mcp call <resource> <tool> --input '{"sql":"SELECT 1"}'  # invoke a tool

Uses the existing backchannel connection (same as aspire describe, aspire logs, etc.) — no MCP server needed. Pattern matches prior art (mcptools, mcp-cli).

Fixes #14619
Fixes #14856

Checklist

Is this feature complete?
- Yes. Ready to ship.
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
- No
Did you add public API?
- Yes
- No
Does the change make any security assumptions or guarantees?
- Yes
- No
Does the change require an update in our Aspire docs?
- Yes
  - Link to aspire.dev issue:
    - New issue
- No

github-actions · 2026-03-02T07:29:50Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 14837

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 14837"

github-actions · 2026-03-02T08:25:42Z

🎬 CLI E2E Test Recordings

The following terminal recordings are available for commit 13d0faa:

Test	Recording
AddPackageInteractiveWhileAppHostRunningDetached	▶️ View Recording
AddPackageWhileAppHostRunningDetached	▶️ View Recording
AgentCommands_AllHelpOutputs_AreCorrect	▶️ View Recording
AgentInitCommand_DefaultSelection_InstallsSkillOnly	▶️ View Recording
AgentInitCommand_MigratesDeprecatedConfig	▶️ View Recording
AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	▶️ View Recording
Banner_DisplayedOnFirstRun	▶️ View Recording
Banner_DisplayedWithExplicitFlag	▶️ View Recording
CreateAndDeployToDockerCompose	▶️ View Recording
CreateAndDeployToDockerComposeInteractive	▶️ View Recording
CreateAndPublishToKubernetes	▶️ View Recording
CreateAndRunAspireStarterProject	▶️ View Recording
CreateAndRunAspireStarterProjectWithBundle	▶️ View Recording
CreateAndRunJsReactProject	▶️ View Recording
CreateAndRunPythonReactProject	▶️ View Recording
CreateAndRunTypeScriptStarterProject	▶️ View Recording
CreateEmptyAppHostProject	▶️ View Recording
CreateStartAndStopAspireProject	▶️ View Recording
CreateStartWaitAndStopAspireProject	▶️ View Recording
CreateTypeScriptAppHostWithViteApp	▶️ View Recording
DescribeCommandResolvesReplicaNames	▶️ View Recording
DescribeCommandShowsRunningResources	▶️ View Recording
DetachFormatJsonProducesValidJson	▶️ View Recording
DoctorCommand_DetectsDeprecatedAgentConfig	▶️ View Recording
DoctorCommand_WithSslCertDir_ShowsTrusted	▶️ View Recording
DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	▶️ View Recording
LogsCommandShowsResourceLogs	❌ Upload failed
PsCommandListsRunningAppHost	▶️ View Recording
PsFormatJsonOutputsOnlyJsonToStdout	▶️ View Recording
SecretCrudOnDotNetAppHost	▶️ View Recording
SecretCrudOnTypeScriptAppHost	❌ Upload failed
StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	▶️ View Recording
StopAllAppHostsFromAppHostDirectory	▶️ View Recording
StopAllAppHostsFromUnrelatedDirectory	▶️ View Recording
StopNonInteractiveMultipleAppHostsShowsError	❌ Upload failed
StopNonInteractiveSingleAppHost	❌ Upload failed
StopWithNoRunningAppHostExitsSuccessfully	▶️ View Recording
TypeScriptAppHostWithProjectReferenceIntegration	▶️ View Recording

_{📹 Recordings uploaded automatically from CI run #22749871815}

Copilot

Pull request overview

Updates the Aspire agent skill content generated by aspire agent init to rely on Aspire CLI commands (rather than Aspire MCP server tools), so agents can manage/run/debug Aspire apps in environments that only have the CLI installed.

Changes:

Rewrites the generated SKILL.md content to reference CLI equivalents (e.g., aspire start, aspire wait, aspire docs search, aspire otel ..., --apphost).
Adds a compact CLI command reference table and updated “key workflows / rules” guidance around detached + isolated execution.
Updates the unit test assertion to validate the new skill content.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/Aspire.Cli/Agents/CommonAgentApplicators.cs	Replaces embedded `SkillFileContent` to use CLI commands and updated guidance/rules.
tests/Aspire.Cli.Tests/Agents/CommonAgentApplicatorsTests.cs	Updates test to assert for new skill content (`aspire start --isolated`).

src/Aspire.Cli/Agents/CommonAgentApplicators.cs

JamesNK · 2026-03-05T03:49:36Z

I have some concerns about replacing the logs and telemetry MCP tools.

For example, list_traces gives a better view of data by resolving the outbound address to a known resource.
And the logs and telemetry MCP tools have some limits to truncate very long data and remove duplication.

JamesNK · 2026-03-05T04:47:35Z

Actually, I forgot I added the resource destination to output JSON. There is a "aspire.destination" value added to span attributes. The Aspire skill should mention that can be used to match a span to the resource it calls.

I still worry about the size of telemetry JSON (it's verbose) but hopefully agents put some effort into client analysis rather than putting everything in the context window.

davidfowl · 2026-03-05T05:31:00Z

I still worry about the size of telemetry JSON (it's verbose) but hopefully agents put some effort into client analysis rather than putting everything in the context window.

All of the agents worth their salt have large context optimization by putting the result on disk and grepping 😄. That said I still think we should enable more complex filtering with the cli that what we have right now.

mitchdenny

Code Review — 3 Issues Found

1. 🔴 High — `preSelected` not forwarded via extension backchannel

File: src/Aspire.Cli/Interaction/ExtensionInteractionService.cs:276

When the extension prompt path is active, Backchannel.PromptForSelectionsAsync(...) is called without the new preSelected parameter. The console fallback path (line 293) correctly passes it through. This means extensions will never see pre-selected items.

// Extension path (line 276) — missing preSelected:
var result = await Backchannel.PromptForSelectionsAsync(promptText.RemoveSpectreFormatting(), choices, choiceFormatter, _cancellationToken);

// Console fallback path (line 293) — correctly passes preSelected:
return await _consoleInteractionService.PromptForSelectionsAsync(promptText, choices, choiceFormatter, preSelected, optional, cancellationToken);

2. 🟡 Medium — Unhandled `InvalidOperationException` in `McpCallCommand`

File: src/Aspire.Cli/Commands/McpCallCommand.cs:93-104

If --input is a JSON array or primitive (not an object), EnumerateObject() throws InvalidOperationException, which isn't caught by the catch (JsonException) block. Users would see a raw stack trace instead of a friendly error.

Fix: check doc.RootElement.ValueKind == JsonValueKind.Object before calling EnumerateObject(), or widen the catch to include InvalidOperationException.

3. 🟡 Medium — `TestInteractionService` drops `TryDequeue` call

File: tests/Aspire.Cli.Tests/TestServices/TestInteractionService.cs:127

The _responses.TryDequeue(out _) line was removed entirely. Any existing test that enqueues a response expecting it to be consumed by PromptForSelectionsAsync will now have a stale queue, potentially affecting subsequent prompt assertions in the same test.

I don't use request changes ... it stops flow

…e mcp tools/call ## Skill updates - Replace all MCP server tool references with CLI command equivalents - Use aspire start (not aspire run) for agents, --isolated for worktrees - Add aspire wait, aspire mcp tools, aspire mcp call to command table - Restore USE FOR/DO NOT USE FOR routing tags in frontmatter - Explicit rules: never use aspire run, restart via aspire start ## Agent init rework - Single flat prompt instead of 3 grouped prompts - Skill file pre-selected (Recommended), MCP server opt-in (last) - Playwright CLI shown as separate option - Deprecated config migrations applied silently - Categorization via McpInitPromptGroup (SkillFiles, Tools, AgentEnvironments) - Shows which environments were configured after applying - preSelected parameter added to PromptForSelectionsAsync ## New CLI commands - aspire mcp tools: list MCP tools from running resources via backchannel - aspire mcp call <resource> <tool> --input <json>: invoke resource MCP tools Fixes #14619 Fixes #14856 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…nt, restore TryDequeue - McpCallCommand: Validate JSON input is an object before calling EnumerateObject() to avoid unhandled InvalidOperationException for array/primitive inputs. - ExtensionInteractionService: Add comment documenting that the extension backchannel protocol does not yet support preSelected. - TestInteractionService: Restore _responses.TryDequeue call to maintain queue consumption behavior for existing tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…/call (microsoft#14837) * Update Aspire skill to use CLI commands, rework agent init, add aspire mcp tools/call ## Skill updates - Replace all MCP server tool references with CLI command equivalents - Use aspire start (not aspire run) for agents, --isolated for worktrees - Add aspire wait, aspire mcp tools, aspire mcp call to command table - Restore USE FOR/DO NOT USE FOR routing tags in frontmatter - Explicit rules: never use aspire run, restart via aspire start ## Agent init rework - Single flat prompt instead of 3 grouped prompts - Skill file pre-selected (Recommended), MCP server opt-in (last) - Playwright CLI shown as separate option - Deprecated config migrations applied silently - Categorization via McpInitPromptGroup (SkillFiles, Tools, AgentEnvironments) - Shows which environments were configured after applying - preSelected parameter added to PromptForSelectionsAsync ## New CLI commands - aspire mcp tools: list MCP tools from running resources via backchannel - aspire mcp call <resource> <tool> --input <json>: invoke resource MCP tools Fixes microsoft#14619 Fixes microsoft#14856 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix review issues: JSON input validation, extension backchannel comment, restore TryDequeue - McpCallCommand: Validate JSON input is an object before calling EnumerateObject() to avoid unhandled InvalidOperationException for array/primitive inputs. - ExtensionInteractionService: Add comment documenting that the extension backchannel protocol does not yet support preSelected. - TestInteractionService: Restore _responses.TryDequeue call to maintain queue consumption behavior for existing tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Mitch Denny <mitch@mitchdeny.com>

…/call (#14837) * Update Aspire skill to use CLI commands, rework agent init, add aspire mcp tools/call ## Skill updates - Replace all MCP server tool references with CLI command equivalents - Use aspire start (not aspire run) for agents, --isolated for worktrees - Add aspire wait, aspire mcp tools, aspire mcp call to command table - Restore USE FOR/DO NOT USE FOR routing tags in frontmatter - Explicit rules: never use aspire run, restart via aspire start ## Agent init rework - Single flat prompt instead of 3 grouped prompts - Skill file pre-selected (Recommended), MCP server opt-in (last) - Playwright CLI shown as separate option - Deprecated config migrations applied silently - Categorization via McpInitPromptGroup (SkillFiles, Tools, AgentEnvironments) - Shows which environments were configured after applying - preSelected parameter added to PromptForSelectionsAsync ## New CLI commands - aspire mcp tools: list MCP tools from running resources via backchannel - aspire mcp call <resource> <tool> --input <json>: invoke resource MCP tools Fixes #14619 Fixes #14856 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix review issues: JSON input validation, extension backchannel comment, restore TryDequeue - McpCallCommand: Validate JSON input is an object before calling EnumerateObject() to avoid unhandled InvalidOperationException for array/primitive inputs. - ExtensionInteractionService: Add comment documenting that the extension backchannel protocol does not yet support preSelected. - TestInteractionService: Restore _responses.TryDequeue call to maintain queue consumption behavior for existing tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Mitch Denny <mitch@mitchdeny.com>

davidfowl added the area-cli label Mar 2, 2026

mitchdenny approved these changes Mar 3, 2026

View reviewed changes

davidfowl marked this pull request as ready for review March 3, 2026 06:33

Copilot AI review requested due to automatic review settings March 3, 2026 06:33

Copilot started reviewing on behalf of davidfowl March 3, 2026 06:34 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

src/Aspire.Cli/Agents/CommonAgentApplicators.cs Outdated Show resolved Hide resolved

github-actions bot mentioned this pull request Mar 3, 2026

[13.2-burndown] Daily Burndown Report - March 3, 2026 #14879

Closed

davidfowl force-pushed the davidfowl/skill-use-cli branch 4 times, most recently from 427053b to 05a9e79 Compare March 4, 2026 07:13

davidfowl mentioned this pull request Mar 4, 2026

Allow registering Aspire MCP server in VS Code extension #14917

Merged

10 tasks

davidfowl force-pushed the davidfowl/skill-use-cli branch from 416d040 to fd14fb8 Compare March 4, 2026 07:54

github-actions bot mentioned this pull request Mar 4, 2026

[13.2-burndown] Daily Burndown Report - March 4, 2026 #14940

Closed

davidfowl force-pushed the davidfowl/skill-use-cli branch from f066eb1 to ed3b1b0 Compare March 5, 2026 07:54

davidfowl requested a review from eerhardt as a code owner March 5, 2026 07:54

davidfowl force-pushed the davidfowl/skill-use-cli branch 4 times, most recently from 6db004c to 28d8723 Compare March 5, 2026 08:35

davidfowl changed the title ~~Update Aspire skill to use CLI commands instead of MCP tools~~ Update skill to CLI commands, rework agent init, add aspire mcp tools/call Mar 5, 2026

davidfowl force-pushed the davidfowl/skill-use-cli branch 4 times, most recently from 83058d0 to 3153a99 Compare March 6, 2026 01:21

davidfowl force-pushed the davidfowl/skill-use-cli branch from 3153a99 to e4adcba Compare March 6, 2026 01:52

mitchdenny previously requested changes Mar 6, 2026

View reviewed changes

dotnet-policy-service bot added the needs-author-action An issue or pull request that requires more info or actions from the author. label Mar 6, 2026

davidfowl and others added 2 commits March 6, 2026 16:00

mitchdenny force-pushed the davidfowl/skill-use-cli branch from cd667e4 to 13d0faa Compare March 6, 2026 05:02

mitchdenny approved these changes Mar 6, 2026

View reviewed changes

mitchdenny merged commit 43dced3 into release/13.2 Mar 6, 2026
759 of 763 checks passed

mitchdenny deleted the davidfowl/skill-use-cli branch March 6, 2026 05:56

dotnet-policy-service bot added this to the 13.2 milestone Mar 6, 2026

davidfowl mentioned this pull request Mar 6, 2026

Update the aspire skill to use the CLI instead of the MCP server #14619

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update skill to CLI commands, rework agent init, add aspire mcp tools/call#14837

Update skill to CLI commands, rework agent init, add aspire mcp tools/call#14837
mitchdenny merged 2 commits intorelease/13.2from
davidfowl/skill-use-cli

davidfowl commented Mar 2, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 2, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

JamesNK commented Mar 5, 2026

Uh oh!

JamesNK commented Mar 5, 2026 •

edited

Loading

Uh oh!

davidfowl commented Mar 5, 2026

Uh oh!

mitchdenny left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

davidfowl commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

1. Skill file: MCP tools → CLI commands

2. Agent init rework

3. New CLI commands: aspire mcp tools / aspire mcp call

Checklist

Uh oh!

github-actions bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎬 CLI E2E Test Recordings

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

JamesNK commented Mar 5, 2026

Uh oh!

JamesNK commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidfowl commented Mar 5, 2026

Uh oh!

mitchdenny left a comment

Choose a reason for hiding this comment

Code Review — 3 Issues Found

1. 🔴 High — preSelected not forwarded via extension backchannel

2. 🟡 Medium — Unhandled InvalidOperationException in McpCallCommand

3. 🟡 Medium — TestInteractionService drops TryDequeue call

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

davidfowl commented Mar 2, 2026 •

edited

Loading

3. New CLI commands: `aspire mcp tools` / `aspire mcp call`

github-actions bot commented Mar 2, 2026 •

edited

Loading

github-actions bot commented Mar 2, 2026 •

edited

Loading

JamesNK commented Mar 5, 2026 •

edited

Loading

1. 🔴 High — `preSelected` not forwarded via extension backchannel

2. 🟡 Medium — Unhandled `InvalidOperationException` in `McpCallCommand`

3. 🟡 Medium — `TestInteractionService` drops `TryDequeue` call