Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-02-20 02:15:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(aspire): flatten skill to references/, version-gate MCP tools, simplify integrations catalog

Browse Source 
- Move all reference docs from cli/, mcp/, framework/ subfolders into references/ per agentskills.io spec

- Update all cross-references in SKILL.md and reference files

- Version-gate MCP tools: 9 tools in 13.1+, docs tools (list_docs/search_docs/get_doc) in 13.2+

- Simplify integrations-catalog.md to lead with MCP tool discovery (list_integrations/get_integration_docs)

- Remove .vscode/mcp.json (test artifact from aspire mcp init)
This commit is contained in:
Chris McKee
2026-02-08 19:46:16 -06:00
parent 970cd25bef
commit e765718787
6 changed files with 534 additions and 684 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
skills/aspire/SKILL.md
View File

@@ -1,9 +1,6 @@
---
name: aspire
description: 'Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application.'
metadata:
author: chrismckee
version: "2.0"
---
# Aspire — Polyglot Distributed-App Orchestration
@@ -12,99 +9,84 @@ Aspire is a **code-first, polyglot toolchain** for building observable, producti
> **Mental model:** The AppHost is a *conductor* — it doesn't play the instruments, it tells every service when to start, how to find each other, and watches for problems.
## Deep-dive references
Detailed reference material lives in the `references/` folder — load on demand.
This skill follows progressive disclosure. The sections below cover essentials. For detailed reference, load these on demand:
---
## References
| Reference | When to load |
|---|---|
| [Polyglot APIs](references/polyglot-apis.md) | Need full method signatures, chaining options, or language-specific patterns |
| [Integrations Catalog](references/integrations-catalog.md) | Looking up specific integrations, NuGet packages, or wiring patterns |
| [CLI Reference](references/cli-reference.md) | Need command flags, options, or detailed usage examples |
| [Architecture](references/architecture.md) | Need DCP internals, resource model, service discovery, networking, or telemetry details |
| [Deployment](references/deployment.md) | Deploying to Docker, Kubernetes, Azure Container Apps, or App Service |
| [MCP Server](references/mcp-server.md) | Setting up the MCP server for AI assistants |
| [Dashboard](references/dashboard.md) | Dashboard features, standalone mode, or GenAI Visualizer |
| [Testing](references/testing.md) | Writing integration tests against the AppHost |
| [CLI Reference](references/cli-reference.md) | Command flags, options, or detailed usage |
| [MCP Server](references/mcp-server.md) | Setting up MCP for AI assistants, available tools |
| [Integrations Catalog](references/integrations-catalog.md) | Discovering integrations via MCP tools, wiring patterns |
| [Polyglot APIs](references/polyglot-apis.md) | Method signatures, chaining options, language-specific patterns |
| [Architecture](references/architecture.md) | DCP internals, resource model, service discovery, networking, telemetry |
| [Dashboard](references/dashboard.md) | Dashboard features, standalone mode, GenAI Visualizer |
| [Deployment](references/deployment.md) | Docker, Kubernetes, Azure Container Apps, App Service |
| [Testing](references/testing.md) | Integration tests against the AppHost |
| [Troubleshooting](references/troubleshooting.md) | Diagnostic codes, common errors, and fixes |
---
## 1. Researching Aspire Documentation (Agent Guidance)
## 1. Researching Aspire Documentation
When you need deeper or newer information than this skill provides, use **Context7** (`mcp_context7`) to query up-to-date documentation and code examples directly. This is the fastest approach — a single query returns code snippets, explanations, and source links without needing to search and then separately read files.
The Aspire team ships an **MCP server** that provides documentation tools directly inside your AI assistant. See [MCP Server](references/mcp-server.md) for setup details.
### Preferred: Context7 (single-step lookup)
### Aspire CLI 13.2+ (recommended — has built-in docs search)
If running Aspire CLI **13.2 or later** (`aspire --version`), the MCP server includes docs search tools:
| Tool | Description |
|---|---|
| `list_docs` | Lists all available documentation from aspire.dev |
| `search_docs` | Performs weighted lexical search across indexed documentation |
| `get_doc` | Retrieves a specific document by its slug |
These tools were added in [PR #14028](https://github.com/dotnet/aspire/pull/14028). To update: `aspire update --self --channel daily`.
For more on this approach, see David Pine's post: https://davidpine.dev/posts/aspire-docs-mcp-tools/
### Aspire CLI 13.1 (integration tools only)
On 13.1, the MCP server provides integration lookup but **not** docs search:
| Tool | Description |
|---|---|
| `list_integrations` | Lists available Aspire hosting integrations |
| `get_integration_docs` | Gets documentation for a specific integration package |
For general docs queries on 13.1, use **Context7** as your primary source (see below).
### Fallback: Context7
Use **Context7** (`mcp_context7`) when the Aspire MCP docs tools are unavailable (13.1) or the MCP server isn't running:
**Step 1 — Resolve the library ID** (one-time per session):
Call `mcp_context7_resolve-library-id` with `libraryName: ".NET Aspire"` to get the Context7-compatible library IDs. Context7 indexes both GitHub repos and websites — below is a quality-ranked breakdown based on testing:
Call `mcp_context7_resolve-library-id` with `libraryName: ".NET Aspire"`.
| Rank | Library ID | Source type | Snippets | Quality | Use when |
|---|---|---|---|---|---|
| 1 | `/microsoft/aspire.dev` | GitHub repo (MDX source) | 1865 | **Best** — most complete, highest detail, full Aspire 13+ coverage | Primary source. Guides, integrations, CLI reference, what's-new, deployment. |
| 2 | `/websites/learn_microsoft-en-us-dotnet-aspire` | Website crawl (learn.microsoft.com) | 2506 | **Good** — mirrors Learn content, occasionally has formatting artifacts | Rendered docs. Good alternative if repo source has gaps. |
| 3 | `/dotnet/aspire` | GitHub repo (runtime C#) | 1185 | **Good** — source code, READMEs, test scenarios, playground examples | API internals, source-level implementation details, playground demos. |
| 4 | `/communitytoolkit/aspire` | GitHub repo (community) | 311 | **Best for community** — Golang, Java, Node.js, Vite, Ollama | Non-Microsoft polyglot integrations, community-contributed hosting packages. |
| 5 | `/dotnet/docs-aspire` | GitHub repo (old docs) | 482 | **Superseded** — compatibility/breaking-change notes only, missing newer APIs | Avoid for tutorials. Only useful for migration/deprecation references. |
| Rank | Library ID | Use when |
|---|---|---|
| 1 | `/microsoft/aspire.dev` | Primary source. Guides, integrations, CLI reference, deployment. |
| 2 | `/dotnet/aspire` | API internals, source-level implementation details. |
| 3 | `/communitytoolkit/aspire` | Non-Microsoft polyglot integrations (Go, Java, Node.js, Ollama). |
> **Important:** `/dotnet/docs-aspire` is the **legacy** docs repo being superseded by `microsoft/aspire.dev`. It lacks newer APIs (e.g., `AddPythonExecutable`, `AddPythonModule`) and tutorials. Prefer `/microsoft/aspire.dev` for all general lookups.
**Step 2 — Query docs**:
Call `mcp_context7_query-docs` with the library ID and a descriptive query. Be specific — include method names, concepts, or language names for best results.
**Step 2 — Query docs:**
```
# Primary source — covers most needs:
libraryId: "/microsoft/aspire.dev", query: "Python integration AddPythonApp AddUvicornApp service discovery"
libraryId: "/microsoft/aspire.dev", query: "deployment Azure Container Apps Kubernetes publish manifest"
libraryId: "/microsoft/aspire.dev", query: "aspire CLI commands aspire run aspire publish aspire new"
libraryId: "/microsoft/aspire.dev", query: "Redis caching integration WithReference"
# Community integrations (Golang, Java, Node.js):
libraryId: "/microsoft/aspire.dev", query: "Python integration AddPythonApp service discovery"
libraryId: "/communitytoolkit/aspire", query: "Golang Java Node.js community integrations"
# Runtime source (when you need API internals or test patterns):
libraryId: "/dotnet/aspire", query: "PythonAppResource AddPythonApp implementation"
# Microsoft Learn website (alternative rendered view):
libraryId: "/websites/learn_microsoft-en-us-dotnet-aspire", query: "aspire starter template quickstart"
```
Each result includes the code snippet, source URL, and context — no second tool call needed.
### Fallback: GitHub search (when Context7 is unavailable)
If Context7 tools are not available, fall back to searching the official documentation repos on GitHub. The source-of-truth MDX files live here:
### Fallback: GitHub search (when Context7 is also unavailable)
Search the official docs repo on GitHub:
- **Docs repo:** `microsoft/aspire.dev` — path: `src/frontend/src/content/docs/`
- **Source repo:** `dotnet/aspire` — runtime (C#)
- **Source repo:** `dotnet/aspire`
- **Samples repo:** `dotnet/aspire-samples`
- **Community integrations:** `CommunityToolkit/Aspire`
Use `mcp_github_search_code` with patterns like:
```
path:src/frontend/src/content/docs/ extension:mdx repo:microsoft/aspire.dev <topic>
```
**Exclude** `path:src/frontend/src/content/docs/ja/` (Japanese translations). After finding file paths, use the GitHub file contents tool to read the full MDX.
### Documentation map
| Folder | Files | Coverage |
|---|---|---|
| `get-started/` | 16 | Install, quickstarts, templates, Dev Containers, Codespaces |
| `architecture/` | 7 | DCP, resource model, networking, service discovery |
| `app-host/` | 8 | Orchestration, resources, configuration, eventing |
| `fundamentals/` | 13 | Health checks, telemetry, configuration, security |
| `integrations/` | 90+ | Caching, databases, messaging, AI, cloud, frameworks |
| `dashboard/` | 11 | Monitoring, logs, traces, metrics, MCP server |
| `deployment/` | 5 | Docker, K8s, Azure Container Apps, App Service |
| `reference/cli/` | 13 | All CLI commands |
| `testing/` | 3 | Integration testing patterns |
| `diagnostics/` | 30 | Diagnostic codes ASPIRE001–008 + experimental |
| `whats-new/` | 9 | Release notes, breaking changes |
---
## 2. Prerequisites & Install
@@ -135,16 +117,16 @@ dotnet new install Aspire.ProjectTemplates
| Template | Command | Description |
|---|---|---|
| **aspire-starter** | `aspire new aspire-starter` | .NET API + web frontend + AppHost + tests |
| **aspire-ts-cs-starter** | `aspire new aspire-ts-cs-starter` | TypeScript frontend + C# API + AppHost |
| **aspire-py-starter** | `aspire new aspire-py-starter` | Python backend + AppHost |
| **aspire** | `aspire new aspire` | Empty AppHost only |
| **aspire-starter** | `aspire new aspire-starter` | ASP.NET Core/Blazor starter + AppHost + tests |
| **aspire-ts-cs-starter** | `aspire new aspire-ts-cs-starter` | ASP.NET Core/React starter + AppHost |
| **aspire-py-starter** | `aspire new aspire-py-starter` | FastAPI/React starter + AppHost |
| **aspire-apphost-singlefile** | `aspire new aspire-apphost-singlefile` | Empty single-file AppHost |
---
## 4. AppHost Quick Start (Polyglot)
The AppHost orchestrates all services. Non-.NET workloads run as containers or executables — they don't need the .NET SDK themselves.
The AppHost orchestrates all services. Non-.NET workloads run as containers or executables.
```csharp
var builder = DistributedApplication.CreateBuilder(args);
@@ -172,7 +154,7 @@ var worker = builder.AddGolangApp("worker", "../go-worker")
builder.Build().Run();
```
For complete API signatures and all chaining methods, see [Polyglot APIs](references/polyglot-apis.md).
For complete API signatures, see [Polyglot APIs](references/polyglot-apis.md).
---
@@ -186,25 +168,30 @@ For complete API signatures and all chaining methods, see [Polyglot APIs](refere
| **Resource types** | `ProjectResource`, `ContainerResource`, `ExecutableResource`, `ParameterResource` |
| **Integrations** | 144+ across 13 categories. Hosting package (AppHost) + Client package (service). |
| **Dashboard** | Real-time logs, traces, metrics, GenAI visualizer. Runs automatically with `aspire run`. |
| **MCP Server** | AI assistants can query running apps via CLI (STDIO) or Dashboard (HTTP/SSE). |
| **MCP Server** | AI assistants can query running apps and search docs via CLI (STDIO). |
| **Testing** | `Aspire.Hosting.Testing` — spin up full AppHost in xUnit/MSTest/NUnit. |
| **Deployment** | Docker, Kubernetes, Azure Container Apps, Azure App Service. |
For architecture details, see [Architecture](references/architecture.md).
---
## 6. CLI Quick Reference
| Command | Description |
|---|---|
| `aspire new <template>` | Create from template |
| `aspire init` | Initialize in existing project |
| `aspire run` | Start all resources locally |
| `aspire publish` | Generate deployment manifests |
| `aspire add` | Add an integration |
| `aspire mcp init` | Configure MCP for AI assistants |
| `aspire test` | Run integration tests |
Valid commands in Aspire CLI 13.1:
| Command | Description | Status |
|---|---|---|
| `aspire new <template>` | Create from template | Stable |
| `aspire init` | Initialize in existing project | Stable |
| `aspire run` | Start all resources locally | Stable |
| `aspire add <integration>` | Add an integration | Stable |
| `aspire publish` | Generate deployment manifests | Preview |
| `aspire config` | Manage configuration settings | Stable |
| `aspire cache` | Manage disk cache | Stable |
| `aspire deploy` | Deploy to defined targets | Preview |
| `aspire do <step>` | Execute a pipeline step | Preview |
| `aspire update` | Update integrations (or `--self` for CLI) | Preview |
| `aspire mcp init` | Configure MCP for AI assistants | Stable |
| `aspire mcp start` | Start the MCP server | Stable |
Full command reference with flags: [CLI Reference](references/cli-reference.md).
@@ -222,8 +209,8 @@ Full command reference with flags: [CLI Reference](references/cli-reference.md).
### Migrating from Docker Compose
1. `aspire new aspire` (empty AppHost)
2. Replace each `docker-compose` service → Aspire resource
1. `aspire new aspire-apphost-singlefile` (empty AppHost)
2. Replace each `docker-compose` service with an Aspire resource
3. `depends_on` → `.WithReference()` + `.WaitFor()`
4. `ports` → `.WithHttpEndpoint()`
5. `environment` → `.WithEnvironment()` or `.WithReference()`
@@ -241,3 +228,4 @@ Full command reference with flags: [CLI Reference](references/cli-reference.md).
| **Community Toolkit** | https://github.com/CommunityToolkit/Aspire |
| **Dashboard image** | `mcr.microsoft.com/dotnet/aspire-dashboard` |
| **Discord** | https://aka.ms/aspire/discord |
| **Reddit** | https://www.reddit.com/r/aspiredotdev/ |

310
skills/aspire/references/cli-reference.md
View File

@@ -2,6 +2,8 @@
The Aspire CLI (`aspire`) is the primary interface for creating, running, and publishing distributed applications. It is cross-platform and installed standalone (not coupled to the .NET CLI, though `dotnet` commands also work).
**Tested against:** Aspire CLI 13.1.0
---
## Installation
@@ -16,12 +18,26 @@ irm https://aspire.dev/install.ps1 | iex
# Verify
aspire --version
# Update to latest
aspire update
# Update the CLI itself
aspire update --self
```
---
## Global Options
All commands support these options:
| Option | Description |
| --------------------- | ---------------------------------------------- |
| `-d, --debug` | Enable debug logging to the console |
| `--non-interactive` | Disable all interactive prompts and spinners |
| `--wait-for-debugger` | Wait for a debugger to attach before executing |
| `-?, -h, --help` | Show help and usage information |
| `--version` | Show version information |
---
## Command Reference
### `aspire new`
@@ -29,26 +45,29 @@ aspire update
Create a new project from a template.
```bash
aspire new <template-name> [options]
aspire new [<template>] [options]
# Options:
# -o, --output <dir> Output directory
# -n, --name <name> Project name
# --force Overwrite existing files
# -o, --output <dir> Output directory
# -s, --source <source> NuGet source for templates
# -v, --version <version> Version of templates to use
# --channel <channel> Channel (stable, daily)
# Examples:
aspire new aspire-starter
aspire new aspire-starter -n MyApp -o ./my-app
aspire new aspire-ts-cs-starter
aspire new aspire-py-starter
aspire new aspire # empty AppHost only
aspire new aspire-apphost-singlefile
```
Available templates:
- `aspire-starter` — .NET API + web frontend + AppHost + ServiceDefaults + test project
- `aspire-ts-cs-starter` — TypeScript (Vite) frontend + C# API + AppHost
- `aspire-py-starter` — Python (FastAPI) backend + AppHost
- `aspire` — empty AppHost only
- `aspire-starter` — ASP.NET Core/Blazor starter + AppHost + tests
- `aspire-ts-cs-starter` — ASP.NET Core/React + AppHost
- `aspire-py-starter` — FastAPI/React + AppHost
- `aspire-apphost-singlefile` — Empty single-file AppHost
### `aspire init`
@@ -58,8 +77,9 @@ Initialize Aspire in an existing project or solution.
aspire init [options]
# Options:
# --apphost-project <path> Existing project to use as AppHost
# --enlist <projects> Projects to add to the AppHost
# -s, --source <source> NuGet source for templates
# -v, --version <version> Version of templates to use
# --channel <channel> Channel (stable, daily)
# Example:
cd my-existing-solution
@@ -73,22 +93,18 @@ Adds AppHost and ServiceDefaults projects to an existing solution. Interactive p
Start all resources locally using the DCP (Developer Control Plane).
```bash
aspire run [options]
aspire run [options] [-- <additional arguments>]
# Options:
# --project <path> Path to AppHost project (default: current dir)
# --no-dashboard Skip launching the dashboard
# --dashboard-port <n> Override dashboard port (default: auto-assigned)
# --watch Enable hot reload / file watching
# --project <path> Path to AppHost project file
# Examples:
aspire run
aspire run --project ./src/MyApp.AppHost
aspire run --no-dashboard
aspire run --watch
```
Behavior:
1. Builds the AppHost project
2. Starts the DCP engine
3. Creates resources in dependency order (DAG)
@@ -98,158 +114,194 @@ Behavior:
Press `Ctrl+C` to gracefully stop all resources.
### `aspire publish`
### `aspire add`
Add a hosting integration to the AppHost.
```bash
aspire add [<integration>] [options]
# Options:
# --project <path> Target project file
# -v, --version <version> Version of integration to add
# -s, --source <source> NuGet source for integration
# Examples:
aspire add redis
aspire add postgresql
aspire add mongodb
```
### `aspire publish` (Preview)
Generate deployment manifests from the AppHost resource model.
```bash
aspire publish [options]
aspire publish [options] [-- <additional arguments>]
# Options:
# -p, --publisher <name> Target publisher (docker, kubernetes, azure, appservice)
# --project <path> Path to AppHost project
# -o, --output <dir> Output directory for manifests
# --project <path> Path to AppHost project file
# -o, --output-path <path> Output directory (default: ./aspire-output)
# --log-level <level> Log level (trace, debug, information, warning, error, critical)
# -e, --environment <env> Environment (default: Production)
# --include-exception-details Include stack traces in pipeline logs
# Examples:
aspire publish -p docker
aspire publish -p kubernetes -o ./k8s-manifests
aspire publish -p azure
aspire publish -p appservice
aspire publish
aspire publish --output-path ./deploy
aspire publish -e Staging
```
Publishers:
- `docker` — Generates `docker-compose.yml` and Dockerfiles
- `kubernetes` — Generates Helm charts / K8s YAML manifests
- `azure` — Generates Bicep templates for Azure Container Apps
- `appservice` — Generates Bicep templates for Azure App Service
### `aspire add`
Add an integration to the AppHost or a service project.
```bash
aspire add <integration> [options]
# Options:
# --project <path> Target project (default: current dir)
# --hosting Add hosting package only (AppHost side)
# --client Add client package only (service side)
# Examples:
aspire add redis
aspire add postgresql --hosting
aspire add mongodb --client
```
### `aspire build`
Build the AppHost project.
```bash
aspire build [options]
# Options:
# --project <path> Path to AppHost project
# -c, --configuration <config> Build configuration (Debug/Release)
```
### `aspire test`
Run integration tests.
```bash
aspire test [options]
# Options:
# --project <path> Path to test project
# --filter <filter> Test filter expression
# Examples:
aspire test
aspire test --project ./tests/MyApp.Tests
aspire test --filter "Category=Integration"
```
### `aspire dev`
Start in dev mode with file watching and hot reload.
```bash
aspire dev [options]
# Options:
# --project <path> Path to AppHost project
```
### `aspire mcp init`
Configure the MCP (Model Context Protocol) server for AI assistants.
```bash
aspire mcp init [options]
# Interactive — prompts you to select your AI assistant:
# - Claude Code
# - OpenAI Codex CLI
# - GitHub Copilot (VS Code)
# - Cursor
# - VS Code Chat
```
Generates the appropriate configuration file for your selected AI tool (e.g., `.mcp.json`, `claude_desktop_config.json`). See [MCP Server](mcp-server.md) for details.
### `aspire config`
Manage Aspire configuration.
Manage Aspire configuration settings.
```bash
aspire config [options]
aspire config <subcommand>
# Subcommands:
# set <key> <value> Set a configuration value
# get <key> Get a configuration value
# list List all configuration
# set <key> <value> Set a configuration value
# list List all configuration values
# delete <key> Delete a configuration value
# Examples:
aspire config list
aspire config set telemetry.enabled false
aspire config get telemetry.enabled
aspire config delete telemetry.enabled
```
### `aspire list`
### `aspire cache`
List available resources.
Manage disk cache for CLI operations.
```bash
aspire list [options]
aspire cache <subcommand>
# Subcommands:
# templates List available project templates
# integrations List available integrations
# clear Clear all cache entries
# Example:
aspire cache clear
```
### `aspire update`
### `aspire deploy` (Preview)
Update the Aspire CLI to the latest version.
Deploy the contents of an Aspire apphost to its defined deployment targets.
```bash
aspire update
aspire deploy [options] [-- <additional arguments>]
# Options:
# --project <path> Path to AppHost project file
# -o, --output-path <path> Output path for deployment artifacts
# --log-level <level> Log level (trace, debug, information, warning, error, critical)
# -e, --environment <env> Environment (default: Production)
# --include-exception-details Include stack traces in pipeline logs
# --clear-cache Clear deployment cache for current environment
# Example:
aspire deploy --project ./src/MyApp.AppHost
```
### `aspire --version`
### `aspire do` (Preview)
Display the installed CLI version.
Execute a specific pipeline step and its dependencies.
```bash
aspire --version
aspire do <step> [options] [-- <additional arguments>]
# Options:
# --project <path> Path to AppHost project file
# -o, --output-path <path> Output path for artifacts
# --log-level <level> Log level (trace, debug, information, warning, error, critical)
# -e, --environment <env> Environment (default: Production)
# --include-exception-details Include stack traces in pipeline logs
# Example:
aspire do build-images --project ./src/MyApp.AppHost
```
### `aspire update` (Preview)
Update integrations in the Aspire project, or update the CLI itself.
```bash
aspire update [options]
# Options:
# --project <path> Path to AppHost project file
# --self Update the Aspire CLI itself to the latest version
# --channel <channel> Channel to update to (stable, daily)
# Examples:
aspire update # Update project integrations
aspire update --self # Update the CLI itself
aspire update --self --channel daily # Update CLI to daily build
```
### `aspire mcp`
Manage the MCP (Model Context Protocol) server.
```bash
aspire mcp <subcommand>
# Subcommands:
# init Initialize MCP server configuration for detected agent environments
# start Start the MCP server
```
#### `aspire mcp init`
```bash
aspire mcp init
# Interactive — detects your AI environment and creates config files.
# Supported environments:
# - VS Code (GitHub Copilot)
# - Copilot CLI
# - Claude Code
# - OpenCode
```
Generates the appropriate configuration file for your detected AI tool.
See [MCP Server](mcp-server.md) for details.
#### `aspire mcp start`
```bash
aspire mcp start
# Starts the MCP server using STDIO transport.
# This is typically invoked by your AI tool, not run manually.
```
---
## Commands That Do NOT Exist
The following commands are **not valid** in Aspire CLI 13.1. Use alternatives:
| Invalid Command | Alternative |
| --------------- | -------------------------------------------------------------------- |
| `aspire build` | Use `dotnet build ./AppHost` |
| `aspire test` | Use `dotnet test ./Tests` |
| `aspire dev` | Use `aspire run` (includes file watching) |
| `aspire list` | Use `aspire new --help` for templates, `aspire add` for integrations |
---
## .NET CLI equivalents
The `dotnet` CLI can also manage Aspire projects:
The `dotnet` CLI can perform some Aspire tasks:
| Aspire CLI | .NET CLI Equivalent |
|---|---|
| --------------------------- | -------------------------------- |
| `aspire new aspire-starter` | `dotnet new aspire-starter` |
| `aspire run` | `dotnet run --project ./AppHost` |
| `aspire build` | `dotnet build ./AppHost` |
| `aspire test` | `dotnet test ./Tests` |
| N/A | `dotnet build ./AppHost` |
| N/A | `dotnet test ./Tests` |
The Aspire CLI adds value with `publish`, `add`, `mcp init`, and `config` — commands that have no direct `dotnet` equivalent.
The Aspire CLI adds value with `publish`, `deploy`, `add`, `mcp`, `config`, `cache`, `do`, and `update` — commands that have no direct `dotnet` equivalent.

23
skills/aspire/references/dashboard.md
View File

@@ -9,6 +9,7 @@ The Aspire Dashboard provides real-time observability for all resources in your
### Resources view
Displays all resources (projects, containers, executables) with:
- **Name** and **type** (Project, Container, Executable)
- **State** (Starting, Running, Stopped, FailedToStart, etc.)
- **Start time** and **uptime**
@@ -19,6 +20,7 @@ Displays all resources (projects, containers, executables) with:
### Console logs
Aggregated raw stdout/stderr from all resources:
- Filter by resource name
- Search within logs
- Auto-scroll with pause
@@ -27,6 +29,7 @@ Aggregated raw stdout/stderr from all resources:
### Structured logs
Application-level structured logs (via ILogger, OpenTelemetry):
- **Filterable** by resource, log level, category, message content
- **Expandable** — click to see full log entry with all properties
- **Correlated** with traces — click to jump to the related trace
@@ -36,6 +39,7 @@ Application-level structured logs (via ILogger, OpenTelemetry):
### Distributed traces
End-to-end request traces across all services:
- **Waterfall view** — shows the full call chain with timing
- **Span details** — HTTP method, URL, status code, duration
- **Database spans** — SQL queries, connection details
@@ -46,6 +50,7 @@ End-to-end request traces across all services:
### Metrics
Real-time and historical metrics:
- **Runtime metrics** — CPU, memory, GC, thread pool
- **HTTP metrics** — request rate, error rate, latency percentiles
- **Custom metrics** — any metrics your services emit via OpenTelemetry
@@ -54,6 +59,7 @@ Real-time and historical metrics:
### GenAI Visualizer
For applications using AI/LLM integrations:
- **Token usage** — prompt tokens, completion tokens, total tokens per request
- **Prompt/completion pairs** — see the exact prompt sent and response received
- **Model metadata** — which model, temperature, max tokens
@@ -65,8 +71,9 @@ For applications using AI/LLM integrations:
## Dashboard URL
By default, the dashboard runs on an auto-assigned port. Find it:
- In the terminal output when `aspire run` starts
- Via MCP: `get_dashboard_url` tool
- Via MCP: `list_resources` tool
- Override with `--dashboard-port`:
```bash
@@ -80,15 +87,14 @@ aspire run --dashboard-port 18888
Run the dashboard without an AppHost — useful for existing applications that already emit OpenTelemetry:
```bash
docker run --rm -it \
docker run --rm -d \
-p 18888:18888 \
-p 4317:18889 \
-d aspire-dashboard \
mcr.microsoft.com/dotnet/aspire-dashboard:latest
```
| Port | Purpose |
|---|---|
| ---------------- | ------------------------------------------------------------ |
| `18888` | Dashboard web UI |
| `4317` → `18889` | OTLP gRPC receiver (standard OTel port → dashboard internal) |
@@ -134,7 +140,7 @@ services:
The standalone dashboard supports authentication via browser tokens:
```bash
docker run --rm -it \
docker run --rm -d \
-p 18888:18888 \
-p 4317:18889 \
-e DASHBOARD__FRONTEND__AUTHMODE=BrowserToken \
@@ -174,6 +180,7 @@ docker run --rm -it \
## Copilot integration
The dashboard integrates with GitHub Copilot in VS Code:
- Ask questions about resource status
- Query logs and traces in natural language
- The MCP server (see [MCP Server](mcp-server.md)) provides the bridge
@@ -204,14 +211,14 @@ trace.set_tracer_provider(provider)
### JavaScript (OpenTelemetry SDK)
```javascript
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-grpc");
const provider = new NodeTracerProvider();
provider.addSpanProcessor(
new BatchSpanProcessor(
new OTLPTraceExporter({
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317'
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4317",
})
)
);

298
skills/aspire/references/integrations-catalog.md
View File

@@ -1,14 +1,36 @@
# Integrations Catalog — Complete Reference
# Integrations Catalog
Aspire has **144+ integrations** across 13 categories, with **90+ NuGet packages**. Each integration typically provides two packages:
Aspire has **144+ integrations** across 13 categories. Rather than maintaining a static list, use the MCP tools to get live, up-to-date integration data.
- **Hosting package** (`Aspire.Hosting.*`) — adds the resource to the AppHost
- **Client package** (`Aspire.*`) — configures the client SDK in your service with health checks, telemetry, and retries
---
## Discovering integrations (MCP tools)
The Aspire MCP server provides two tools for integration discovery — these work on **all CLI versions** (13.1+) and do **not** require a running AppHost.
| Tool | What it does | When to use |
| ---------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `list_integrations` | Returns all available Aspire hosting integrations with their NuGet package IDs | "What integrations are available for databases?" / "Show me all Redis-related integrations" |
| `get_integration_docs` | Retrieves detailed documentation for a specific integration package (setup, configuration, code samples) | "How do I configure PostgreSQL?" / "Show me the docs for `Aspire.Hosting.Redis`" |
### Workflow
1. **Browse** — Call `list_integrations` to see what's available. Filter results by category or keyword.
2. **Deep dive** — Call `get_integration_docs` with the package ID (e.g., `Aspire.Hosting.Redis`) and version (e.g., `9.0.0`) to get full setup instructions.
3. **Add** — Run `aspire add <integration>` to install the hosting package into your AppHost.
> **Tip:** These tools return the same data as the [official integrations gallery](https://aspire.dev/integrations/gallery/). Prefer them over static docs — integrations are added frequently.
---
## Integration pattern
Every integration follows a two-package pattern:
- **Hosting package** (`Aspire.Hosting.*`) — adds the resource to the AppHost
- **Client package** (`Aspire.*`) — configures the client SDK in your service with health checks, telemetry, and retries
- **Community Toolkit** (`CommunityToolkit.Aspire.*`) — community-maintained integrations from [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire)
```csharp
// === AppHost (hosting side) ===
var redis = builder.AddRedis("cache"); // Aspire.Hosting.Redis
@@ -16,263 +38,31 @@ var api = builder.AddProject<Projects.Api>("api")
.WithReference(redis);
// === Service (client side) — in API's Program.cs ===
builder.AddRedisClient("cache"); // Aspire.Redis
builder.AddRedisClient("cache"); // Aspire.StackExchange.Redis
// Automatically configures: connection string, health checks, OpenTelemetry, retries
```
---
## AI
## Categories at a glance
| Integration | Hosting Package | Client Package |
|---|---|---|
| Azure OpenAI | `Aspire.Hosting.Azure.CognitiveServices` | `Aspire.Azure.AI.OpenAI` |
| OpenAI | — | `Aspire.OpenAI` |
| Ollama | `Aspire.Hosting.Ollama` | `Aspire.Ollama` |
| GitHub Models | — | `Aspire.GitHubModels` |
Use `list_integrations` for the full live list. This summary covers the major categories:
```csharp
// AppHost: Azure OpenAI
var openai = builder.AddAzureOpenAI("openai")
.AddDeployment(new("gpt-4o", "gpt-4o", "2024-08-06"));
| Category | Key integrations | Example hosting package |
| ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------- |
| **AI** | Azure OpenAI, OpenAI, GitHub Models, Ollama | `Aspire.Hosting.Azure.CognitiveServices` |
| **Caching** | Redis, Garnet, Valkey, Azure Cache for Redis | `Aspire.Hosting.Redis` |
| **Cloud / Azure** | Storage, Cosmos DB, Service Bus, Key Vault, Event Hubs, Functions, SQL, SignalR (25+) | `Aspire.Hosting.Azure.Storage` |
| **Cloud / AWS** | AWS SDK integration | `Aspire.Hosting.AWS` |
| **Databases** | PostgreSQL, SQL Server, MongoDB, MySQL, Oracle, Elasticsearch, Milvus, Qdrant, SQLite | `Aspire.Hosting.PostgreSQL` |
| **DevTools** | Data API Builder, Dev Tunnels, Mailpit, k6, Flagd, Ngrok, Stripe | `Aspire.Hosting.DevTunnels` |
| **Messaging** | RabbitMQ, Kafka, NATS, ActiveMQ, LavinMQ | `Aspire.Hosting.RabbitMQ` |
| **Observability** | OpenTelemetry (built-in), Seq, OTel Collector | `Aspire.Hosting.Seq` |
| **Compute** | Docker Compose, Kubernetes | `Aspire.Hosting.Docker` |
| **Reverse Proxies** | YARP | `Aspire.Hosting.Yarp` |
| **Security** | Keycloak | `Aspire.Hosting.Keycloak` |
| **Frameworks** | JavaScript, Python, Go, Java, Rust, Bun, Deno, Orleans, MAUI, Dapr, PowerShell | `Aspire.Hosting.Python` |
// AppHost: Ollama (local)
var ollama = builder.AddOllama("ollama")
.AddModel("llama3.2")
.WithDataVolume();
```
For polyglot framework method signatures, see [Polyglot APIs](polyglot-apis.md).
---
## Caching
| Integration | Hosting Package | Client Package |
|---|---|---|
| Redis | `Aspire.Hosting.Redis` | `Aspire.StackExchange.Redis` |
| Redis (output caching) | `Aspire.Hosting.Redis` | `Aspire.StackExchange.Redis.OutputCaching` |
| Redis (distributed cache) | `Aspire.Hosting.Redis` | `Aspire.StackExchange.Redis.DistributedCaching` |
| Garnet | `Aspire.Hosting.Garnet` | `Aspire.StackExchange.Redis` (wire-compatible) |
| Valkey | `Aspire.Hosting.Valkey` | `Aspire.StackExchange.Redis` (wire-compatible) |
```csharp
var redis = builder.AddRedis("cache")
.WithRedisCommander() // adds Redis Commander UI
.WithRedisInsight() // adds RedisInsight UI
.WithDataVolume() // persist data across restarts
.WithPersistence(); // enable RDB snapshots
```
---
## Cloud / Azure (25+ integrations)
| Integration | Hosting Package | Client Package |
|---|---|---|
| AI Foundry | `Aspire.Hosting.Azure.AIFoundry` | `Aspire.Azure.AI.Foundry` |
| App Configuration | `Aspire.Hosting.Azure.AppConfiguration` | `Aspire.Azure.AppConfiguration` |
| Blob Storage | `Aspire.Hosting.Azure.Storage` | `Aspire.Azure.Storage.Blobs` |
| Queue Storage | `Aspire.Hosting.Azure.Storage` | `Aspire.Azure.Storage.Queues` |
| Table Storage | `Aspire.Hosting.Azure.Storage` | `Aspire.Azure.Storage.Tables` |
| Cosmos DB | `Aspire.Hosting.Azure.CosmosDB` | `Aspire.Microsoft.Azure.Cosmos` |
| Cosmos DB (EF Core) | `Aspire.Hosting.Azure.CosmosDB` | `Aspire.Microsoft.EntityFrameworkCore.Cosmos` |
| Event Hubs | `Aspire.Hosting.Azure.EventHubs` | `Aspire.Azure.Messaging.EventHubs` |
| Key Vault | `Aspire.Hosting.Azure.KeyVault` | `Aspire.Azure.Security.KeyVault` |
| Search (AI Search) | `Aspire.Hosting.Azure.Search` | `Aspire.Azure.Search.Documents` |
| Service Bus | `Aspire.Hosting.Azure.ServiceBus` | `Aspire.Azure.Messaging.ServiceBus` |
| SignalR | `Aspire.Hosting.Azure.SignalR` | `Aspire.Azure.SignalR` |
| Web PubSub | `Aspire.Hosting.Azure.WebPubSub` | `Aspire.Azure.Messaging.WebPubSub` |
| Azure Functions | `Aspire.Hosting.Azure.Functions` | — |
| Azure SQL | `Aspire.Hosting.Azure.Sql` | `Aspire.Azure.Sql` |
| Azure PostgreSQL | `Aspire.Hosting.Azure.PostgreSQL` | Built on `Aspire.Npgsql` |
| Azure Redis | `Aspire.Hosting.Azure.Redis` | Built on `Aspire.StackExchange.Redis` |
```csharp
// Azure Storage (Blob + Queue + Table)
var storage = builder.AddAzureStorage("storage")
.RunAsEmulator(); // use Azurite locally
var blobs = storage.AddBlobs("blobs");
var queues = storage.AddQueues("queues");
// Cosmos DB with emulator for local dev
var cosmos = builder.AddAzureCosmosDB("cosmos")
.RunAsEmulator()
.AddDatabase("mydb");
// Service Bus
var sb = builder.AddAzureServiceBus("messaging")
.AddQueue("orders")
.AddTopic("events", topic => topic.AddSubscription("processor"));
```
---
## Databases
| Integration | Hosting Package | Client Package |
|---|---|---|
| PostgreSQL | `Aspire.Hosting.PostgreSQL` | `Aspire.Npgsql` |
| PostgreSQL (EF Core) | `Aspire.Hosting.PostgreSQL` | `Aspire.Npgsql.EntityFrameworkCore.PostgreSQL` |
| SQL Server | `Aspire.Hosting.SqlServer` | `Aspire.Microsoft.Data.SqlClient` |
| SQL Server (EF Core) | `Aspire.Hosting.SqlServer` | `Aspire.Microsoft.EntityFrameworkCore.SqlServer` |
| MongoDB | `Aspire.Hosting.MongoDB` | `Aspire.MongoDB.Driver` |
| MySQL / MariaDB | `Aspire.Hosting.MySql` | `Aspire.MySqlConnector` |
| MySQL (EF Core) | `Aspire.Hosting.MySql` | `Aspire.Pomelo.EntityFrameworkCore.MySql` |
| Oracle (EF Core) | `Aspire.Hosting.Oracle` | `Aspire.Oracle.EntityFrameworkCore` |
| Elasticsearch | `Aspire.Hosting.Elasticsearch` | `Aspire.Elastic.Clients.Elasticsearch` |
| Milvus (vector DB) | `Aspire.Hosting.Milvus` | `Aspire.Milvus.Client` |
| Qdrant (vector DB) | `Aspire.Hosting.Qdrant` | `Aspire.Qdrant.Client` |
| SurrealDB | `CommunityToolkit.Aspire.Hosting.SurrealDb` | Community |
| RavenDB | `CommunityToolkit.Aspire.Hosting.RavenDB` | Community |
| KurrentDB | `CommunityToolkit.Aspire.Hosting.KurrentDB` | Community |
| SQLite (EF Core) | — | `Aspire.Microsoft.EntityFrameworkCore.Sqlite` |
```csharp
// PostgreSQL with pgAdmin and pgWeb UIs
var postgres = builder.AddPostgres("pg")
.WithPgAdmin()
.WithPgWeb()
.WithDataVolume()
.AddDatabase("catalog");
// MongoDB with Mongo Express UI
var mongo = builder.AddMongoDB("mongo")
.WithMongoExpress()
.WithDataVolume()
.AddDatabase("analytics");
// SQL Server
var sql = builder.AddSqlServer("sql")
.WithDataVolume()
.AddDatabase("orders");
```
---
## DevTools
| Integration | Hosting Package | Purpose |
|---|---|---|
| Data API Builder (DAB) | `Aspire.Hosting.DataAPIBuilder` | REST/GraphQL over databases |
| Dev Tunnels | `Aspire.Hosting.DevTunnels` | Public URL tunnels for local dev |
| Flagd | `CommunityToolkit.Aspire.Hosting.Flagd` | Feature flags (OpenFeature) |
| k6 | `CommunityToolkit.Aspire.Hosting.k6` | Load testing |
| Mailpit | `CommunityToolkit.Aspire.Hosting.Mailpit` | Email testing |
| SQL Database Projects | `Aspire.Hosting.SqlDatabaseProjects` | SQL schema deployment |
---
## Messaging
| Integration | Hosting Package | Client Package |
|---|---|---|
| RabbitMQ | `Aspire.Hosting.RabbitMQ` | `Aspire.RabbitMQ.Client` |
| Kafka | `Aspire.Hosting.Kafka` | `Aspire.Confluent.Kafka` |
| NATS | `Aspire.Hosting.Nats` | `Aspire.NATS.Net` |
| LavinMQ | `CommunityToolkit.Aspire.Hosting.LavinMQ` | `Aspire.RabbitMQ.Client` (AMQP-compat) |
```csharp
var rabbit = builder.AddRabbitMQ("messaging")
.WithManagementPlugin() // adds management UI
.WithDataVolume();
var kafka = builder.AddKafka("kafka")
.WithKafkaUI(); // adds Kafka UI
```
---
## Observability
| Integration | Package | Purpose |
|---|---|---|
| OpenTelemetry | Built-in | Traces, metrics, logs (auto-configured) |
| Seq | `Aspire.Hosting.Seq` | Structured log aggregation |
| Grafana + Prometheus | Community | Metrics dashboards |
---
## Reverse Proxies
| Integration | Package |
|---|---|
| YARP | `Aspire.Hosting.Yarp` |
---
## Security
| Integration | Package |
|---|---|
| Keycloak | `CommunityToolkit.Aspire.Hosting.Keycloak` |
---
## Frameworks (Polyglot)
See [Polyglot APIs](polyglot-apis.md) for complete method signatures.
| Framework | Package | Type |
|---|---|---|
| JavaScript | `Aspire.Hosting.JavaScript` | Official |
| Python | `Aspire.Hosting.Python` | Official |
| Go | `CommunityToolkit.Aspire.Hosting.Golang` | Community |
| Java | `CommunityToolkit.Aspire.Hosting.Java` | Community |
| Rust | `CommunityToolkit.Aspire.Hosting.Rust` | Community |
| Bun | `CommunityToolkit.Aspire.Hosting.Bun` | Community |
| Deno | `CommunityToolkit.Aspire.Hosting.Deno` | Community |
| Dapr | `Aspire.Hosting.Dapr` | Official |
| Orleans | `Aspire.Hosting.Orleans` | Official |
| MAUI | `Aspire.Hosting.Maui` | Official |
---
## Custom integrations
### Custom hosting integration
```csharp
public static class MyServiceExtensions
{
public static IResourceBuilder<ContainerResource> AddMyService(
this IDistributedApplicationBuilder builder, string name)
{
return builder.AddContainer(name, "my-registry/my-service")
.WithHttpEndpoint(targetPort: 8080, name: "http")
.WithEnvironment("MODE", "production");
}
}
```
### Custom client integration
```csharp
public static class MyServiceClientExtensions
{
public static IHostApplicationBuilder AddMyServiceClient(
this IHostApplicationBuilder builder, string connectionName)
{
// Register client with DI
builder.Services.AddHttpClient<MyServiceClient>(client =>
{
var conn = builder.Configuration.GetConnectionString(connectionName);
client.BaseAddress = new Uri(conn!);
});
// Add health check
builder.Services.AddHealthChecks()
.AddUrlGroup(new Uri($"{connectionName}/health"), name: connectionName);
return builder;
}
}
```
### Secure communication between integrations
```csharp
// Enable TLS between services
var api = builder.AddProject<Projects.Api>("api")
.WithHttpsEndpoint()
.WithReference(redis)
.WithTransport("https");
```

234
skills/aspire/references/mcp-server.md
View File

@@ -1,134 +1,134 @@
# MCP Server — Complete Reference
Aspire exposes an **MCP (Model Context Protocol) server** that lets AI coding assistants query and control your running distributed application. This enables AI tools to inspect resource status, read logs, view traces, and restart services — all from within the AI assistant's context.
Aspire exposes an **MCP (Model Context Protocol) server** that lets AI coding assistants query and control your running distributed application, and search Aspire documentation. This enables AI tools to inspect resource status, read logs, view traces, restart services, and look up docs — all from within the AI assistant's context.
Reference: https://aspire.dev/get-started/configure-mcp/
---
## Two Entry Points
## Setup: `aspire mcp init`
| Mode | Transport | Protocol | Start Method |
|---|---|---|---|
| **CLI** | STDIO | MCP over stdin/stdout | `aspire mcp init` generates config |
| **Dashboard** | HTTP (SSE) | MCP over Server-Sent Events | Auto-started with dashboard |
### CLI MCP Server (STDIO)
The CLI-based MCP server runs as a subprocess of your AI tool. Your AI assistant spawns the Aspire process and communicates via stdin/stdout.
The easiest way to configure the MCP server is using the Aspire CLI:
```bash
# Initialize — interactive, selects your AI tool
# Open a terminal in your project directory
aspire mcp init
```
This generates the appropriate config file for your AI tool.
The command walks you through an interactive setup:
### Dashboard MCP Server (HTTP/SSE)
1. **Workspace root** — prompts for the path to your workspace root (defaults to current directory)
2. **Environment detection** — detects supported AI environments (VS Code, Copilot CLI, Claude Code, OpenCode) and asks which to configure
3. **Playwright MCP** — optionally offers to configure the Playwright MCP server alongside Aspire
4. **Config creation** — writes the appropriate configuration files (e.g., `.vscode/mcp.json`)
5. **AGENTS.md** — if one doesn't already exist, creates an `AGENTS.md` with Aspire-specific instructions for AI agents
The dashboard automatically exposes an MCP endpoint when running. AI tools connect via HTTP/SSE to the dashboard URL.
No additional setup needed — if the dashboard is running, the MCP endpoint is available.
> **Note:** `aspire mcp init` uses interactive prompts (Spectre.Console). It must be run in a real terminal — the VS Code integrated terminal may not handle the prompts correctly. Use an external terminal if needed.
---
## MCP Tools (10 available)
## Understanding the Configuration
| Tool | Description | Example use |
|---|---|---|
| `list_resources` | List all resources in the AppHost | "What services are running?" |
| `get_resource` | Get details of a specific resource | "Show me the API resource details" |
| `get_resource_logs` | Get console logs for a resource | "Show me the last 50 log lines from the API" |
| `get_resource_health` | Get health check status | "Is the database healthy?" |
| `start_resource` | Start a stopped resource | "Start the worker service" |
| `stop_resource` | Stop a running resource | "Stop the ML service" |
| `restart_resource` | Restart a resource | "Restart the API" |
| `get_dashboard_url` | Get the dashboard URL | "Open the Aspire dashboard" |
| `get_traces` | Get distributed traces | "Show me recent traces for the API" |
| `get_metrics` | Get metrics data | "What's the request rate for the API?" |
When you run `aspire mcp init`, the CLI creates configuration files appropriate for your detected environment.
---
### VS Code (GitHub Copilot)
## Setup by AI Assistant
### Claude Code
```bash
aspire mcp init
# Select: Claude Code
```
Generates `.mcp.json` in the project root:
```json
{
"mcpServers": {
"aspire": {
"command": "aspire",
"args": ["mcp", "serve"],
"cwd": "/path/to/your/apphost"
}
}
}
```
### GitHub Copilot (VS Code)
```bash
aspire mcp init
# Select: GitHub Copilot (VS Code)
```
Generates `.vscode/mcp.json`:
Creates or updates `.vscode/mcp.json`:
```json
{
"servers": {
"aspire": {
"type": "stdio",
"command": "aspire",
"args": ["mcp", "serve"],
"cwd": "${workspaceFolder}/src/AppHost"
"args": ["mcp", "start"]
}
}
}
```
### Cursor
## MCP Tools
```bash
aspire mcp init
# Select: Cursor
The tools available depend on your Aspire CLI version. Check with `aspire --version`.
### Tools available in 13.1+ (stable)
#### Resource management tools
These tools require a running AppHost (`aspire run`).
| Tool | Description |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| `list_resources` | Lists all resources, including state, health status, source, endpoints, and commands |
| `list_console_logs` | Lists console logs for a resource |
| `list_structured_logs` | Lists structured logs, optionally filtered by resource name |
| `list_traces` | Lists distributed traces. Traces can be filtered using an optional resource name parameter |
| `list_trace_structured_logs` | Lists structured logs for a specific trace |
| `execute_resource_command` | Executes a resource command (accepts resource name and command name) |
#### AppHost management tools
| Tool | Description |
| ---------------- | ------------------------------------------------------------------------------------------- |
| `list_apphosts` | Lists all detected AppHost connections, showing which are in/out of working directory scope |
| `select_apphost` | Selects which AppHost to use when multiple are running |
#### Integration tools
These work without a running AppHost.
| Tool | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `list_integrations` | Lists available Aspire hosting integrations (NuGet packages for databases, message brokers, cloud services, etc.) |
| `get_integration_docs` | Gets documentation for a specific Aspire hosting integration package |
### Tools added in 13.2+ (documentation search)
> **Version gate:** These tools were added in [PR #14028](https://github.com/dotnet/aspire/pull/14028) and ship in Aspire CLI **13.2**. If you are on 13.1, these tools will NOT appear. To get them early, update to the daily channel: `aspire update --self --channel daily`.
| Tool | Description |
| ------------- | ------------------------------------------------------------------------ |
| `list_docs` | Lists all available documentation from aspire.dev |
| `search_docs` | Performs weighted lexical search across indexed aspire.dev documentation |
| `get_doc` | Retrieves a specific document by its slug |
These tools index aspire.dev content using the `llms.txt` specification and provide weighted lexical search (titles 10x, summaries 8x, headings 6x, code 5x, body 1x). They work without a running AppHost.
### Fallback for documentation (13.1 users)
If you are on Aspire CLI 13.1 and don't have `list_docs`/`search_docs`/`get_doc`, use **Context7** as a fallback for documentation queries. See the [SKILL.md documentation research section](../SKILL.md#1-researching-aspire-documentation) for details.
---
## Excluding Resources from MCP
Resources and associated telemetry can be excluded from MCP results by annotating the resource:
```csharp
var builder = DistributedApplication.CreateBuilder(args);
var apiService = builder.AddProject<Projects.Api>("apiservice")
.ExcludeFromMcp(); // Hidden from MCP tools
builder.AddProject<Projects.Web>("webfrontend")
.WithExternalHttpEndpoints()
.WithReference(apiService);
builder.Build().Run();
```
Generates `.cursor/mcp.json`:
---
```json
{
"mcpServers": {
"aspire": {
"command": "aspire",
"args": ["mcp", "serve"],
"cwd": "/path/to/your/apphost"
}
}
}
```
## Supported AI Assistants
### OpenAI Codex CLI
The `aspire mcp init` command supports:
```bash
aspire mcp init
# Select: OpenAI Codex CLI
```
- [VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) (GitHub Copilot)
- [Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli#add-an-mcp-server)
- [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
- [OpenCode](https://opencode.ai/docs/mcp-servers/)
Generates appropriate configuration for the Codex CLI environment.
### VS Code Chat
```bash
aspire mcp init
# Select: VS Code Chat
```
Uses the same `.vscode/mcp.json` format as GitHub Copilot.
The MCP server uses the **STDIO transport protocol** and may work with other agentic coding environments that support this protocol.
---
@@ -139,38 +139,30 @@ Uses the same `.vscode/mcp.json` format as GitHub Copilot.
Once MCP is configured, your AI assistant can:
1. **Inspect running state:**
- "List all my Aspire resources and their status"
- "Is the database healthy?"
- "What port is the API running on?"
2. **Read logs:**
- "Show me the recent logs from the ML service"
- "Are there any errors in the worker logs?"
- "What was the last exception in the API?"
3. **View traces:**
- "Show me the trace for the last failed request"
- "What's the latency for API → Database calls?"
4. **Control resources:**
- "Restart the API service"
- "Stop the worker while I debug the queue"
- "Start the ML service back up"
### Example conversation flow
```
User: "My API is returning 500 errors"
AI Assistant (using MCP):
1. Calls list_resources → sees API is "Running"
2. Calls get_resource_logs("api") → finds NullReferenceException
3. Calls get_traces("api") → finds the failing endpoint
4. Reports: "The /orders endpoint is throwing a NullReferenceException
at OrderService.cs:42. The trace shows the database connection
string is null — the WithReference() for the database might be
missing in your AppHost."
```
5. **Search docs (13.2+):**
- "Search the Aspire docs for Redis caching"
- "How do I configure service discovery?"
- _(Requires CLI 13.2+. On 13.1, use Context7 or `list_integrations`/`get_integration_docs` for integration-specific docs.)_
---
@@ -179,5 +171,25 @@ AI Assistant (using MCP):
- The MCP server only exposes resources from the local AppHost
- No authentication is required (local development only)
- The STDIO transport only works for the AI tool that spawned the process
- The HTTP/SSE transport is bound to localhost by default
- **Do not expose the MCP endpoint to the network in production**
---
## Limitations
- AI models have limits on data processing. Large data fields (e.g., stack traces) may be truncated.
- Requests involving large collections of telemetry may be shortened by omitting older items.
---
## Troubleshooting
If you run into issues, check the [open MCP issues on GitHub](https://github.com/dotnet/aspire/issues?q=is%3Aissue+is%3Aopen+label%3Aarea-mcp).
## See Also
- [aspire mcp command](https://aspire.dev/reference/cli/commands/aspire-mcp/)
- [aspire mcp init command](https://aspire.dev/reference/cli/commands/aspire-mcp-init/)
- [aspire mcp start command](https://aspire.dev/reference/cli/commands/aspire-mcp-start/)
- [GitHub Copilot in the Dashboard](https://aspire.dev/dashboard/copilot/)
- [How I taught AI to read Aspire docs](https://davidpine.dev/posts/aspire-docs-mcp-tools/)

33
skills/aspire/references/troubleshooting.md
View File

@@ -9,7 +9,7 @@ Aspire emits diagnostic codes for common issues. These appear in build warnings/
### Standard diagnostics
| Code | Severity | Description |
|---|---|---|
| ------------- | -------- | ---------------------------------------------------------- |
| **ASPIRE001** | Warning | Resource name contains invalid characters |
| **ASPIRE002** | Warning | Duplicate resource name detected |
| **ASPIRE003** | Error | Missing required package reference |
@@ -19,12 +19,12 @@ Aspire emits diagnostic codes for common issues. These appear in build warnings/
| **ASPIRE007** | Warning | Container image tag not specified (using `latest`) |
| **ASPIRE008** | Error | Circular dependency detected in resource graph |
### Experimental diagnostics (ASPIREHOSTINGX*)
### Experimental diagnostics (ASPIREHOSTINGX\*)
These codes indicate usage of experimental/preview APIs. They may require `#pragma warning disable` or `<NoWarn>` if you intentionally use experimental features:
| Code | Area |
|---|---|
| ------------------------- | -------------------------------- |
| ASPIRE_HOSTINGX_0001–0005 | Experimental hosting APIs |
| ASPIRE_HOSTINGX_0006–0010 | Experimental integration APIs |
| ASPIRE_HOSTINGX_0011–0015 | Experimental deployment APIs |
@@ -54,7 +54,7 @@ var resource = builder.AddExperimentalResource("test");
### Container runtime
| Problem | Solution |
|---|---|
| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
| "Cannot connect to Docker daemon" | Start Docker Desktop / Podman / Rancher Desktop |
| Container fails to start | Check `docker ps -a` for exit codes; check dashboard console logs |
| Port already in use | Another process is using the port; Aspire auto-assigns, but `targetPort` must be free on the container |
@@ -64,7 +64,7 @@ var resource = builder.AddExperimentalResource("test");
### Service discovery
| Problem | Solution |
|---|---|
| ----------------------------- | ---------------------------------------------------------------------------- |
| Service can't find dependency | Verify `.WithReference()` in AppHost; check env vars in dashboard |
| Connection string is null | The reference resource name doesn't match; check `ConnectionStrings__<name>` |
| Wrong port in service URL | Check `targetPort` vs actual service listen port |
@@ -73,7 +73,7 @@ var resource = builder.AddExperimentalResource("test");
### Python workloads
| Problem | Solution |
|---|---|
| --------------------------------- | --------------------------------------------------------------- |
| "Python not found" | Ensure Python is on PATH; specify full path in `AddPythonApp()` |
| venv not found | Use `.WithVirtualEnvironment()` or create venv manually |
| pip packages fail to install | Use `.WithPipPackages()` or install in venv before `aspire run` |
@@ -83,7 +83,7 @@ var resource = builder.AddExperimentalResource("test");
### JavaScript / TypeScript workloads
| Problem | Solution |
|---|---|
| ----------------------------- | ---------------------------------------------------------------- |
| "node_modules not found" | Use `.WithNpmPackageInstallation()` to auto-install |
| npm install fails | Check `package.json` is valid; check npm registry connectivity |
| Vite dev server won't start | Verify `vite` is in devDependencies; check Vite config |
@@ -93,7 +93,7 @@ var resource = builder.AddExperimentalResource("test");
### Go workloads
| Problem | Solution |
|---|---|
| -------------------------- | ---------------------------------------------------------- |
| "go not found" | Ensure Go is installed and on PATH |
| Build fails | Check `go.mod` exists in working directory |
| "no Go files in directory" | Verify `workingDir` points to the directory with `main.go` |
@@ -101,7 +101,7 @@ var resource = builder.AddExperimentalResource("test");
### Java workloads
| Problem | Solution |
|---|---|
| ------------------------ | ------------------------------------------------------- |
| "java not found" | Ensure JDK is installed and `JAVA_HOME` is set |
| Maven/Gradle build fails | Verify build files exist; check build tool installation |
| Spring Boot won't start | Check `application.properties`; verify main class |
@@ -109,14 +109,14 @@ var resource = builder.AddExperimentalResource("test");
### Rust workloads
| Problem | Solution |
|---|---|
| -------------------- | -------------------------------------------------------------------- |
| "cargo not found" | Install Rust via rustup |
| Build takes too long | Rust compile times are normal; use `.WithCargoBuild()` for pre-build |
### Health checks & startup
| Problem | Solution |
|---|---|
| ---------------------------- | ------------------------------------------------------------------------------ |
| Resource stuck in "Starting" | Health check endpoint not responding; check service logs |
| `.WaitFor()` timeout | Increase timeout or fix health endpoint; default is 30 seconds |
| Health check always fails | Verify endpoint path (default: `/health`); check service binds to correct port |
@@ -125,7 +125,7 @@ var resource = builder.AddExperimentalResource("test");
### Dashboard
| Problem | Solution |
|---|---|
| ------------------------------------- | ------------------------------------------------------------------------- |
| Dashboard doesn't open | Check terminal for URL; use `--dashboard-port` for fixed port |
| No logs appearing | Service may not be writing to stdout/stderr; check console output |
| No traces for non-.NET services | Configure OpenTelemetry SDK in the service; see [Dashboard](dashboard.md) |
@@ -134,7 +134,7 @@ var resource = builder.AddExperimentalResource("test");
### Build & configuration
| Problem | Solution |
|---|---|
| ----------------------------------------- | ------------------------------------------------------------------- |
| "Project not found" for `AddProject<T>()` | Ensure `.csproj` is in the solution and referenced by AppHost |
| Package version conflicts | Pin all Aspire packages to the same version |
| AppHost won't build | Check `Aspire.AppHost.Sdk` is in the project; run `dotnet restore` |
@@ -143,7 +143,7 @@ var resource = builder.AddExperimentalResource("test");
### Deployment
| Problem | Solution |
|---|---|
| ---------------------------------------- | -------------------------------------------------------------------- |
| `aspire publish` fails | Check publisher package is installed (e.g., `Aspire.Hosting.Docker`) |
| Generated Bicep has errors | Check for unsupported resource configurations |
| Container image push fails | Verify registry credentials and permissions |
@@ -172,6 +172,7 @@ If services fail to start, check the dependency order. A failed dependency block
### 5. Use MCP for AI-assisted debugging
If MCP is configured (see [MCP Server](mcp-server.md)), ask your AI assistant:
- "What resources are failing?"
- "Show me the logs for [service]"
- "What traces show errors?"
@@ -185,9 +186,9 @@ Run just the failing resource by commenting out others in the AppHost. This narr
## Getting help
| Channel | URL |
|---|---|
| ----------------------- | ---------------------------------------------- |
| GitHub Issues (runtime) | https://github.com/dotnet/aspire/issues |
| GitHub Issues (docs) | https://github.com/microsoft/aspire.dev/issues |
| Discord | https://aka.ms/aspire/discord |
| Stack Overflow | Tag: `dotnet-aspire` |
| Reddit | r/dotnet |
| Reddit | https://www.reddit.com/r/aspiredotdev/ |