From e76571878704705c6170e35e3f0662f2dde3c529 Mon Sep 17 00:00:00 2001 From: Chris McKee Date: Sun, 8 Feb 2026 19:46:16 -0600 Subject: [PATCH] refactor(aspire): flatten skill to references/, version-gate MCP tools, simplify integrations catalog - 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) --- skills/aspire/SKILL.md | 170 +++++----- skills/aspire/references/cli-reference.md | 318 ++++++++++-------- skills/aspire/references/dashboard.md | 27 +- .../aspire/references/integrations-catalog.md | 298 +++------------- skills/aspire/references/mcp-server.md | 234 +++++++------ skills/aspire/references/troubleshooting.md | 171 +++++----- 6 files changed, 534 insertions(+), 684 deletions(-) diff --git a/skills/aspire/SKILL.md b/skills/aspire/SKILL.md index f96adf2b..937dffae 100644 --- a/skills/aspire/SKILL.md +++ b/skills/aspire/SKILL.md @@ -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 -``` - -**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