Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,9 @@ Use the **binlog MCP server** (`Microsoft.AITools.BinlogMcp`, exposed under the

### Alternate flow — text-log replay (when MCP is unavailable)

Use `troubleshoot-binlog-mcp` if the user wants to repair the connection. If repair
is blocked, declined, or unnecessary, continue performance analysis with replay.

1. Replay to diagnostic log: `dotnet msbuild perf-baseline.binlog -noconlog -fl -flp:v=diag;logfile=full.log;performancesummary`
2. `grep 'Target Performance Summary' -A 50 full.log` → find dominant targets and their cumulative time
3. `grep 'Task Performance Summary' -A 50 full.log` → find dominant tasks
Expand Down
3 changes: 3 additions & 0 deletions catalog/Tools/Official-DotNet-MSBuild/agents/msbuild/AGENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ Classify the user's request and route to the appropriate specialist:

| User Intent | Route To |
|------------|----------|
| Binlog MCP won't connect, `CONNECTION_CLOSED`, or binlog tools are missing | This agent + `troubleshoot-binlog-mcp` skill |
| Build failed, errors to diagnose | This agent + `binlog-failure-analysis` skill |
| Build is slow, optimize performance | `build-perf` agent + `build-perf-baseline` skill (start with baseline) |
| Review/clean up project files | `msbuild-code-review` agent (specialized code review) |
Expand Down Expand Up @@ -70,6 +71,8 @@ When answering questions about MSBuild syntax, properties, or behavior, use `#to
This agent has access to a comprehensive set of troubleshooting and optimization skills:

### Build Failure Skills

- `troubleshoot-binlog-mcp` — Binlog MCP startup/connection diagnosis, without requiring a binlog
- `binlog-failure-analysis` — Binary log analysis for failure diagnosis
- `binlog-generation` — Binary log generation conventions

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: binlog-failure-analysis
description: "Analyze MSBuild binary logs to diagnose build failures. USE FOR: build errors that are unclear from console output, diagnosing cascading failures across multi-project builds, tracing MSBuild target execution order, and generally any MSBuild build issues. Requires an existing .binlog file. DO NOT USE FOR: generating binlogs (use binlog-generation), non-MSBuild build systems."
description: "Analyze MSBuild binary logs to diagnose build failures. USE FOR: build errors that are unclear from console output, diagnosing cascading failures across multi-project builds, tracing MSBuild target execution order, and generally any MSBuild build issues. Requires an existing .binlog file. DO NOT USE FOR: generating binlogs (use binlog-generation), binlog MCP startup or connection failures (use troubleshoot-binlog-mcp), non-MSBuild build systems."
license: MIT
---

Expand All @@ -9,7 +9,9 @@ license: MIT
This skill diagnoses MSBuild build failures from a `.binlog` file. The preferred
path uses the **binlog MCP server** (`Microsoft.AITools.BinlogMcp`, exposed under the
`binlog` MCP namespace) which is bundled with this plugin. If the MCP server is
not available, fall back to the **binlog replay** workflow at the bottom.
not available, use `troubleshoot-binlog-mcp` to diagnose startup when repair is wanted.
If repair is blocked, declined, or unnecessary for this task, continue with the
**binlog replay** workflow at the bottom.

## Primary workflow — binlog MCP

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: binlog-generation
description: "Generate MSBuild binary logs (binlogs) for build diagnostics and analysis. USE FOR: adding /bl:{} to any dotnet build, test, pack, publish, or restore command to capture a full build execution trace, prerequisite for binlog-failure-analysis and build-perf-diagnostics skills, enabling post-build investigation of errors or performance. Requires MSBuild 17.8+ / .NET 8 SDK+ for {} placeholder; PowerShell must quote the complete switch as '-bl:{}'. DO NOT USE FOR: non-MSBuild build systems (npm, Maven, CMake), analyzing an existing binlog (use binlog-failure-analysis instead)."
description: "Generate MSBuild binary logs (binlogs) for build diagnostics and analysis. USE FOR: adding /bl:{} to any dotnet build, test, pack, publish, or restore command to capture a full build execution trace, prerequisite for binlog-failure-analysis and build-perf-diagnostics skills, enabling post-build investigation of errors or performance. Requires MSBuild 17.8+ / .NET 8 SDK+ for {} placeholder; PowerShell must quote the complete switch as '-bl:{}'. DO NOT USE FOR: non-MSBuild build systems (npm, Maven, CMake), analyzing an existing binlog (use binlog-failure-analysis instead), binlog MCP startup failures (use troubleshoot-binlog-mcp)."
license: MIT
---

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ license: MIT
1. **Generate a binlog**: `dotnet build /bl:{} -m`
2. Use the **binlog MCP server** (`Microsoft.AITools.BinlogMcp`, exposed under the `binlog` MCP namespace) which is bundled with this plugin

If the server cannot connect, use `troubleshoot-binlog-mcp` when startup repair is
wanted. If repair is blocked, declined, or unnecessary, use the replay flow below.

### Alternate flow when MCP is unavailable: binlog replay to text logs

1. **Generate a binlog**: `dotnet build /bl:{} -m`
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
name: troubleshoot-binlog-mcp
description: "Diagnose dotnet-msbuild binlog MCP startup failures. USE FOR: CONNECTION_CLOSED, binlog server won't connect, missing binlog tools, Microsoft.AITools.BinlogMcp not found, dnx launch errors. Checks workspace SDK, feeds, and source mapping without bypassing policy. DO NOT USE FOR: errors inside a binlog (use binlog-failure-analysis), capturing binlogs (use binlog-generation), unrelated MCP servers."
license: MIT
---

# Troubleshoot Binlog MCP Startup

Explain why the plugin's binlog MCP server cannot connect and give an evidence-based,
policy-safe recovery. This diagnoses the **server launch**, not failures recorded in a build.
No binlog file or project build is needed.

This skill runs on demand. It cannot see a host error that was never exposed to the agent,
inject session-start context, or guarantee activation merely because a plugin was installed.

## 1. Establish what failed

Use the user's error and any host MCP status or startup logs already available.
`CONNECTION_CLOSED` alone says that the transport closed, not why. Do not translate it
directly into "package missing."

- If the binlog server is connected and its tools are discoverable, stop startup troubleshooting.
Continue the original binlog analysis; do not change a working setup.
- If the plugin's skills loaded but its binlog server did not, continue below.
- If the plugin itself is not installed/enabled or no server is registered, address that host
configuration first. Do not diagnose NuGet package resolution without a launch attempt.
- If execution or host logs are unavailable, explain that limit and give the next command for
the user to run. Never claim to have inspected logs or repaired a connection.

## 2. Match the host's workspace and SDK

Discover the affected workspace directory and the host's actual MCP command, arguments, and
environment from available configuration. The shipped command is:

```text
dotnet dnx Microsoft.AITools.BinlogMcp --yes --prerelease
```

Run diagnostics from that workspace with the host's environment, not from the plugin directory
or a temporary directory with different NuGet settings. Inspect:

```text
dotnet --info
dotnet --version
dotnet nuget list source
```

Check the applicable `global.json` and inherited NuGet configuration, including parent/user
configuration, `clear`, disabled sources, and `packageSourceMapping`. A workspace `clear`
can replace the default nuget.org source with a private mirror that lacks this package.
An installed SDK is not necessarily the SDK selected in this directory. The shipped
`dotnet dnx` command requires a .NET 10+ SDK.

Do not dump credential settings, private feed URLs, tokens, or credential-provider output into
the answer. Inspect locally as needed and report a redacted source label and relevant error.

## 3. Capture the real launch error

Prefer an existing startup log from the failing host. Otherwise reproduce its **unchanged**
launch command once, from the affected workspace, capturing both stdout and stderr plus the
exit code. Do not initially add `--source`, replace the configuration, remove `global.json`,
clear caches, or install another copy: those change the conditions being diagnosed.

A stdio MCP server may remain running waiting for protocol input. Keep stdin open while
observing startup and use a bounded execution (for example, 30 seconds) with cleanup of only
the diagnostic process tree, including credential-provider children. Use the host's supported
timeout/cancellation facility; if it cannot safely clean up, ask the user to run the command
locally instead. Do not leave a background server running or kill unrelated `dotnet` processes.
A timeout, silence, or an open process is **not** proof that MCP initialized.

Only if package availability remains unclear, run this supporting probe under the same
workspace settings with a bounded execution:

```text
dotnet package search Microsoft.AITools.BinlogMcp --exact-match --prerelease --format json
```

Inspect the exact package ID and version in `searchResult[].packages`, and check both top-level
and per-source `problems`. Exit code zero alone does not establish a successful search.

| Observed evidence | Diagnosis and next action |
|-------------------|---------------------------|
| `dnx` reports no matching version in the configured feeds | Those settings did not resolve the package. Check whether the approved mirror provides prerelease versions of this exact package. |
| Search returns no packages and no source problems | Only the searched feeds lack a listed match. This is not proof that `dnx` must fail: a cached tool or unlisted version may still work. |
| Search has top-level/per-source problems, HTTP 401/403, TLS, network, or credential-provider errors | Availability is unverified, not "package missing." Address the specific feed/access failure first, even if search exited zero. |
| Search finds the package but `dnx` fails | Follow the launch error. Search does not apply package source mapping; check mapping, restore/download access, and runtime requirements. Do not declare the connection healthy. |
| Missing `dotnet`, unrecognized `dnx`, or SDK selection error | Fix the host's PATH/SDK selection. Account for `global.json`; do not silently upgrade the repository or remove its SDK pin. |
| Timeout, unsupported search command, or malformed/non-JSON output | Report an inconclusive probe. Use launch logs or a user-run diagnostic; do not infer absence or success. |
| Launch succeeds but host connection still fails | Investigate the host's actual command/environment and MCP initialization logs; package discovery is no longer the demonstrated failure. |

Do not repeat expensive probes once the evidence establishes the next action.

## 4. Choose a policy-safe recovery

Recommend the smallest change supported by the observed failure:

- Have the feed owner mirror `Microsoft.AITools.BinlogMcp` and its required versions/dependencies
into an approved feed, or correct an approved mapping that excludes it.
- Repair the approved feed's authentication, connectivity, or certificate configuration when
that is the observed problem. Never suggest disabling certificate validation.
- Add nuget.org only if organizational policy permits and the user approves the change.
Do not remove `clear`, disable source mapping, or override sources to bypass enterprise policy.
- If appropriate and approved, install the tool from an approved feed and register its
`binlog-mcp` executable with the host as an alternative MCP server. Confirm the executable's
path and avoid registering a duplicate server. Installation alone is not connection recovery.
- For SDK/PATH issues, make the required SDK available to the host or use a deliberately
configured alternative launch. Ask before changing repository SDK selection.

Do not edit NuGet settings, host registration, or SDK pins without the user's approval.
If policy prevents recovery, say so. For an existing binlog, offer the text-log replay fallback
in `binlog-failure-analysis` rather than blocking build diagnosis on MCP repair.

## 5. Verify and report

After an approved change, reconnect/restart the server using the host's supported controls.
Confirm MCP initialization and a tool listing that contains binlog tools such as
`binlog_overview`. If a binlog is available, resume the original analysis.

Report the observed cause (or what remains unknown), the relevant redacted evidence, the
smallest recovery, and what was actually verified. End with one status line:

```text
MCP status: connected
```

Use `connected` only after the host discovers the server's tools, `failed` for an observed
launch/connection failure, and `unverified` when only probes or advice are available.
Never substitute "package found" or "tool installed" for a verified MCP connection.
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"version": "0.1.11",
"category": "Core",
"compatibility": "Requires a .NET repository with MSBuild project or solution files."
}
4 changes: 2 additions & 2 deletions external-sources/upstreams/astro/packages/astro/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@
],
"scripts": {
"prebuild": "astro-scripts prebuild --to-string \"src/runtime/server/astro-island.ts\" \"src/runtime/client/{idle,load,media,only,visible}.ts\"",
"build": "pnpm run prebuild && astro-scripts build \"src/**/*.{ts,js}\" --copy-wasm && tsc -b && astro-check -- -- --tsconfig ./tsconfig.components.json",
"build": "pnpm run prebuild && astro-scripts build \"src/**/*.{ts,js}\" --copy-wasm && tsc -b && astro-check --tsconfig ./tsconfig.components.json",
"build:ci": "pnpm run prebuild && astro-scripts build \"src/**/*.{ts,js}\" --copy-wasm",
"dev": "astro-scripts dev --copy-wasm --prebuild \"src/runtime/server/astro-island.ts\" --prebuild \"src/runtime/client/{idle,load,media,only,visible}.ts\" \"src/**/*.{ts,js}\"",
"test": "pnpm run test:unit && pnpm run test:integration && pnpm run test:types",
Expand Down Expand Up @@ -214,7 +214,7 @@
"sass": "^1.105.1",
"typescript": "^6.0.3",
"undici": "7.30.0",
"vitest": "^4.1.11"
"vitest": "^5.0.5"
},
"engines": {
"node": ">=22.22.0",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,25 @@ The plugin also exposes the `binlog` MCP server to supported hosts.
Files under `agents/` are GitHub Copilot custom-agent definitions. Codex plugin installs expose the
skills and the Codex-compatible `binlog` MCP declaration, but do not install those `.agent.md` files
as native Codex agents.

## Binlog startup diagnostics

The [troubleshoot-binlog-mcp](skills/troubleshoot-binlog-mcp/SKILL.md) skill diagnoses
`CONNECTION_CLOSED`, missing binlog tools, and failures to start `Microsoft.AITools.BinlogMcp`.
Ask, for example, "The dotnet-msbuild binlog MCP won't connect; help me diagnose it."
It captures the launch error in the affected workspace, checks SDK and NuGet settings,
and suggests recovery without bypassing organizational feed policy.

This is an **on-demand skill**, not a session-start hook. It adds no executable hook code,
startup probe, or host-specific diagnostic payload. The MCP launch command is unchanged.
An agent can select the skill when the user reports a problem or a binlog workflow encounters
an unavailable server, provided the host has loaded the plugin's skills. A connection error
hidden from the agent cannot trigger the skill, so an automatic warning at session start is
not guaranteed.

The skill distinguishes package absence from feed/authentication problems, SDK mismatches,
and timeouts. Package search alone is not a startup test: `dnx` also applies source mapping
and can use cached tools or unlisted versions. Recovery is verified by reconnecting the
host and discovering the binlog MCP tools, not just by finding the package.

Focused evaluation scenarios live in `tests/dotnet-msbuild/troubleshoot-binlog-mcp/`.
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,9 @@ Use the **binlog MCP server** (`Microsoft.AITools.BinlogMcp`, exposed under the

### Alternate flow — text-log replay (when MCP is unavailable)

Use `troubleshoot-binlog-mcp` if the user wants to repair the connection. If repair
is blocked, declined, or unnecessary, continue performance analysis with replay.

1. Replay to diagnostic log: `dotnet msbuild perf-baseline.binlog -noconlog -fl -flp:v=diag;logfile=full.log;performancesummary`
2. `grep 'Target Performance Summary' -A 50 full.log` → find dominant targets and their cumulative time
3. `grep 'Task Performance Summary' -A 50 full.log` → find dominant tasks
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ Classify the user's request and route to the appropriate specialist:

| User Intent | Route To |
|------------|----------|
| Binlog MCP won't connect, `CONNECTION_CLOSED`, or binlog tools are missing | This agent + `troubleshoot-binlog-mcp` skill |
| Build failed, errors to diagnose | This agent + `binlog-failure-analysis` skill |
| Build is slow, optimize performance | `build-perf` agent + `build-perf-baseline` skill (start with baseline) |
| Review/clean up project files | `msbuild-code-review` agent (specialized code review) |
Expand Down Expand Up @@ -70,6 +71,8 @@ When answering questions about MSBuild syntax, properties, or behavior, use `#to
This agent has access to a comprehensive set of troubleshooting and optimization skills:

### Build Failure Skills

- `troubleshoot-binlog-mcp` — Binlog MCP startup/connection diagnosis, without requiring a binlog
- `binlog-failure-analysis` — Binary log analysis for failure diagnosis
- `binlog-generation` — Binary log generation conventions

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: binlog-failure-analysis
description: "Analyze MSBuild binary logs to diagnose build failures. USE FOR: build errors that are unclear from console output, diagnosing cascading failures across multi-project builds, tracing MSBuild target execution order, and generally any MSBuild build issues. Requires an existing .binlog file. DO NOT USE FOR: generating binlogs (use binlog-generation), non-MSBuild build systems."
description: "Analyze MSBuild binary logs to diagnose build failures. USE FOR: build errors that are unclear from console output, diagnosing cascading failures across multi-project builds, tracing MSBuild target execution order, and generally any MSBuild build issues. Requires an existing .binlog file. DO NOT USE FOR: generating binlogs (use binlog-generation), binlog MCP startup or connection failures (use troubleshoot-binlog-mcp), non-MSBuild build systems."
license: MIT
---

Expand All @@ -9,7 +9,9 @@ license: MIT
This skill diagnoses MSBuild build failures from a `.binlog` file. The preferred
path uses the **binlog MCP server** (`Microsoft.AITools.BinlogMcp`, exposed under the
`binlog` MCP namespace) which is bundled with this plugin. If the MCP server is
not available, fall back to the **binlog replay** workflow at the bottom.
not available, use `troubleshoot-binlog-mcp` to diagnose startup when repair is wanted.
If repair is blocked, declined, or unnecessary for this task, continue with the
**binlog replay** workflow at the bottom.

## Primary workflow — binlog MCP

Expand Down
Loading
Loading