MAF Doctor — a toolkit for Microsoft Agent Framework

Diagnose, explain, prescribe, verify — for MAF agents and workflows.

MAF Doctor is a .NET global tool (installed from NuGet) that does three things in one install:

1. An MCP server — exposes 26 executable tools, 6 resources, and 9 prompts to GitHub Copilot / Claude Code / Cursor.
2. A CLI — doctor for an A–F health letter, autofix-all for deterministic rewriters, new agent to scaffold, init to wire up your repo, and more.
3. A plugin — init drops steering snippets and wires the MCP server into both VS Code and Claude Code, so Copilot's and Claude's agentic loops gain MAF-specific knowledge (13 bundled skills + 7 specialist agents).

Plus a separate maf-doctor.Analyzers NuGet package with 3 Roslyn analyzers (MAF001 / MAF002 / MAF003) for IDE write-time enforcement, and a curated, version-keyed obsolete-API registry that maps every known CS0618 warning to its exact replacement.

📦 Latest release on NuGet → — and the toolkit keeps its own MAF knowledge current automatically. See It updates itself.

Install, then run maf-doctor doctor on any MAF codebase — an A–F health letter + the top fixes, in seconds.

🆕 New in 1.3.0 — findings you can act on in one read

Every finding now tells you Why it matters, the Fix, and whether it's auto-fixable:

• doctor surfaces each finding's Why + Fix + the offending source line — --all groups every finding by rule, --json is machine-readable for CI.
• doctor --plan emits an ordered, checkboxed remediation plan, ready to paste into a GitHub issue.
• MafExplainFinding (in an MCP client) deep-dives any single finding by file:line — grounded explanation + fix using your host model (Copilot / Claude / Cursor), at no extra LLM cost.
• The deterministic auto-fixer is now compile-verified — a CI guard compiles every rewriter's output, so a fix can never emit uncompilable code. (full notes →)

What makes it worth trying

• 🔍 Catches the bugs that compile clean — detects fan-out/fan-in silent failures where a workflow exits successfully but produces no output. Runtime-only, zero build signal, invisible without this tool.
• 🩺 Compiler ground-truth for CS0618 — surfaces obsolete-API usage the build would hit, including transitive obsoletions and overload-resolution surprises, and maps each to its canonical fix.
• ✅ Best-practice auditing, not just migration — reviews your agents and workflows against current MAF patterns, catching drift and anti-patterns before they become production bugs.
• 🤖 Fully agentic loop — Copilot audits your codebase, generates a tracked migration plan, and executes it task-by-task, building after every step.
• 🧰 Deterministic fixes, not guesses — the obsolete-API registry maps every known CS0618 warning to its exact replacement pattern. No hallucinated fixes.
• 📖 It updates itself — as new MAF versions ship, the toolkit refreshes its own migration knowledge automatically. How →
• 🔐 Hardened against the named MCP attack lattice — a comprehensive security pass closes the critical- and high-tier MCP attack classes (path-escape, annotation drift, scaffold code-injection, prompt-injection via release notes, workflow-dispatch input injection), with defense-in-depth helpers and CI-enforced invariants. Cisco mcp-scanner: all tools SAFE, 0 findings. See SECURITY.md and docs/security.md.

It updates itself

Migration tooling is only useful if it knows about the MAF version you're on. MAF Doctor keeps its own knowledge base current instead of asking you to wait for a maintainer release:

How — a GitHub Actions watcher checks NuGet for a new Microsoft.Agents.AI release, diffs the API surface against the last known version, and updates the per-version migration guide, the compatibility matrix, and the obsolete-API registry:

• Minor / patch bumps are committed straight to the main branch — the guide, matrix, and tracked version move forward on their own.
• Major bumps don't auto-merge; they open a human-gated issue so a breaking release gets eyes before anything lands.
• New registry entries are drafted by an AI-fill loop and PR-verified — a registry-verification check runs on the fill PR (and can gate the merge when required-status-checks is enabled), so the deterministic fix data stays trustworthy.

When — every Thursday 06:00 UTC (~08:00 Europe/Zurich), aligned with MAF's .NET Thursday-morning ship cadence. Off-cadence releases are covered by a manual dispatch trigger.

The practical upshot: you don't pin to a MAF version in these docs, and you don't wait on us. Re-run the doctor after any MAF bump and it cross-references the freshest guide automatically.

How It Works

MAF Doctor is a Model Context Protocol (MCP) server packaged as a .NET global tool. With no subcommand it runs in MCP mode and exposes:

• 26 executable tools, each annotated with MCP behavior hints (read-only / destructive / idempotent / open-world) so clients can auto-classify them — registry lookup, code scanning, build-verified CS0618 hunts, NuGet diffing, workflow simulation, scaffolding, PR-scoped audits, version planning, and a single-command health letter. The anti-pattern and fan-out scanners emit SARIF for GitHub Advanced Security; the two destructive tools (auto-fix and auto-fix-all) support a dry-run.
• 6 resources — the migration guide, constraints, registry, rules, help, and per-name skills — readable on demand.
• 9 prompts — audit, migrate, remediate, cs0618-hunt, review, debug, explain-finding, scaffold, and help.
• 3 Roslyn analyzers (in the separate maf-doctor.Analyzers package) — MAF001 (fan-out), MAF002 (DefaultAzureCredential), MAF003 (EnableSensitiveData). Write-time enforcement.

With a subcommand, the same binary runs as a CLI tool — see Quick Start below.

Quick Start

🎬 New here? The 3-minute quickstart walks install → init → analyze → auto-fix → upgrade-to-latest-MAF end-to-end (the demo-video script).

⭐ Mode 1: MCP Server (recommended — full agentic power)

# 1. Install the MCP server as a .NET global tool
dotnet tool install --global maf-doctor

# 2. In your MAF project — wires MCP + steering for VS Code, Copilot & Claude Code
cd your-maf-project
maf-doctor init

init is non-destructive — it attaches and updates only, never overwriting your files. It adds its own MCP server entry to both VS Code (.vscode/mcp.json) and Claude Code (.mcp.json), and drops auto-loaded steering as self-contained sidecars in each tool's convention dir — .github/instructions/ for Copilot, .claude/ plus a one-line CLAUDE.md import for Claude Code, and an AGENTS.md managed block. These sidecars are refreshed on every re-run and never merged into your hand-authored files, so re-running init after an upgrade is always safe. Your assistant picks the server up automatically and gains live tool calls, resource reads, and structured prompts.

Keeping it up to date

dotnet tool update --global maf-doctor   # upgrade to the latest release
maf-doctor --version                      # confirm
cd your-maf-project && maf-doctor init    # re-run init to refresh the steering sidecars

⚠️ "The file is locked by another process" on update? Your editor keeps the MCP server (maf-doctor) running, which locks the tool binary — so dotnet tool update can't replace it. Stop the running server first, then update:

# Windows: kill the running MCP server, then update
Get-Process maf-doctor -ErrorAction SilentlyContinue | Stop-Process -Force
dotnet tool update --global maf-doctor

# macOS / Linux
pkill -f maf-doctor; dotnet tool update --global maf-doctor

Or just close the editor (or disable the maf-doctor MCP server) → update → reopen. The editor relaunches the server automatically.

📖 Going deeper: what init installs (and why) · using MAF Doctor — prompts, tools, agents & natural-language steering · hands-on workshop.

First three commands to try:

maf-doctor doctor .            # instant A/B/C/F health grade + top fixes
maf-doctor autofix-all .       # apply every deterministic Roslyn rewriter
maf-doctor new agent ChatBot   # scaffold an anti-pattern-clean MAF agent + smoke test

Then, in Copilot Chat:

@maf-auditor                   # full pre-migration audit + plan
@maf-best-practice-reviewer    # steady-state best-practice review

⭐ Mode 1b: Docker container (no .NET SDK on the host)

docker pull ghcr.io/joslat/maf-doctor:latest

{
  "servers": {
    "maf-doctor": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/joslat/maf-doctor:latest"]
    }
  }
}

Same tools, skills, and resources — isolated in a container. Multi-arch (amd64 + arm64).

Mode 2: Skills + Agents only (no MCP server)

Copy this repo's .github folder into your .NET repository root for the agents and skills via VS Code's instruction/agent system — no live tool calls, but no install either.

git clone https://github.com/joslat/maf-doctor tmp-maf
Copy-Item tmp-maf/.github -Destination .github -Recurse
Remove-Item tmp-maf -Recurse

Then use the @maf-migration or @maf-auditor agents in Copilot Chat.

Recommended companion MCP

MAF Doctor is laser-focused on diagnose + fix for Microsoft Agent Framework. For documentation lookup, pair it with the Microsoft Learn MCP — live, version-aware MAF docs and code samples, no auth required. Docs lookup stays in Learn's lane; audit + fix + migration stays in ours.

Why This Exists

The .NET upgrade-assistant handles package version bumps. MAF Doctor handles everything else:

• MAF-specific executor pattern migration (ReflectingExecutor → partial class : Executor + [MessageHandler])
• Session API changes (AgentThread → AgentSession)
• Fan-out/fan-in silent failure detection — a class of bug that builds green but runs wrong
• Compiler ground-truth CS0618 detection (transitive obsoletions, overload-resolution surprises, project-local Obsolete attributes)
• Build-verified, task-by-task execution with a full tracking table
• A machine-readable obsolete-API registry so fixes are deterministic, not guessed

Typical Migration Workflow

1. Audit — open Copilot Chat → use the audit prompt (or the @maf-auditor agent) to scan your codebase and generate a tracked migration plan.
2. Migrate — use the migrate prompt (or the @maf-migration agent) to execute the plan task-by-task, building after each step.
3. Hunt stragglers — use the cs0618-hunt prompt to catch any remaining CS0618 warnings the build surfaces.

The MCP tools are called automatically by Copilot during these steps — you don't invoke them directly.

Distribution

Distribution: NuGet (maf-doctor + maf-doctor.Analyzers), Docker GHCR (multi-arch amd64 + arm64, semver tags), and the self-updating knowledge base described above. Security model: docs/security.md.

Acknowledgements

This toolkit relies on dotnet-inspect by Rich Lander — a CLI for querying .NET API surfaces across NuGet packages and assemblies. The release watcher uses it (via dnx) to diff MAF package versions and surface breaking API changes. Pin to v0.7.8 or later — it surfaces Obsolete members at the overload level (PR #318); the compiler-based cs0618-hunter path stays complementary for transitive and project-local obsoletions.

Contributing

When a migration surfaces a new surprise (unexpected breaking change, silent runtime failure, wrong pattern in the docs), update:

1. The matching per-version guide in the guides folder (the cumulative guide auto-regenerates from those).
2. The obsolete-API registry at .github/skills/maf-obsolete-api-registry/registry.yaml — add the CS0618 entry.
3. The MAF constraints instructions — update the breaking-changes table if needed.

See CONTRIBUTING.md for contribution shapes + PR conventions.