docs(sdk): add MCP server phase, CI config health to roadmap, ADR-015

- Phase 5: MCP server for AI assistant integration (ADR-015)
  Documents why MCP over skill files: staleness, vendor neutrality,
  structured data, single source of truth
- CI preflight and living issue (Renovate-style config health tracking)
- Runtime network dependency notes for --check-tools

Author: eFAILution

.ai/decisions.yaml

@@ -652,3 +652,82 @@ decisions:
       argus/containers.py: Central image manifest for version tracking
       docker/: Dockerfiles for custom images (bandit, opengrep, supply-chain, cli)
       .github/dependabot.yml: docker ecosystem for Dockerfile base images
+
+  - id: ADR-015
+    title: "MCP server for AI assistant integration instead of skill files"
+    date: "2026-04-12"
+    status: proposed
+
+    context: |
+      AI coding assistants (Claude Code, Cursor, Windsurf, VS Code Copilot) are
+      increasingly used to drive developer workflows. Argus has a curated skill
+      file at .agents/skills/argus-scanner-selection/ that teaches AI assistants
+      how to select and run scanners. However, distributing this skill to users
+      has unsolved problems:
+
+      1. No universal skill format — each AI tool has its own convention
+         (.claude/commands/, .cursorrules, .github/copilot-instructions.md).
+         Picking one means favoring a vendor; supporting all means maintaining
+         duplicates.
+      2. No versioning or update mechanism — copying a skill into a project
+         creates a stale snapshot. AI tools have no skill registries or update
+         notifications. There is no "pip install" for skills.
+      3. Lossy interface — the AI shells out to the CLI and parses unstructured
+         terminal output (including ANSI colors, tables, progress indicators),
+         losing structured information.
+      4. Duplicated intelligence — the skill file re-describes logic that already
+         exists in argus init (project detection) and the engine (scanner
+         selection). Two sources of truth drift over time.
+
+    decision: |
+      Expose Argus as an MCP (Model Context Protocol) server via `argus mcp`.
+      The server provides typed tools (argus_scan, argus_detect, argus_validate,
+      argus_list_scanners, argus_init) that return structured JSON, and resources
+      (argus://config, argus://results/latest) for reading project state.
+
+      MCP is the emerging standard supported by Claude Code, Cursor, Windsurf,
+      and VS Code Copilot. A single implementation works across all tools.
+
+    alternatives_considered:
+      - name: "Skill file installed by argus init"
+        rejected_because: |
+          Creates stale snapshots with no update path. Must choose a tool-specific
+          location or maintain duplicates. AI still parses terminal output.
+
+      - name: "Inform-only (print URL at init)"
+        rejected_because: |
+          Avoids staleness but puts full integration burden on the user. Still
+          has the terminal-parsing problem. No structured data exchange.
+
+      - name: "Publish to AI tool skill registries"
+        rejected_because: |
+          No such registries exist with versioning or update notifications.
+          cursor.directory is community-shared with no version control.
+          Would still require tool-specific formats.
+
+      - name: "Generate tool-specific files for each AI tool"
+        rejected_because: |
+          As OSS, Argus should not favor one tool vendor over another.
+          Maintaining N tool-specific formats is unsustainable.
+
+    consequences:
+      positive:
+        - "Tool-agnostic — one implementation, all MCP-compatible AI tools"
+        - "Structured data — AI receives typed JSON, not terminal output"
+        - "Auto-updating — upgrades ship with pip install --upgrade"
+        - "No vendor favoritism — MCP is an open protocol"
+        - "Single source of truth — MCP tools call the same engine as the CLI"
+        - "Discoverable — AI tools auto-detect available tools from the server"
+      negative:
+        - "Adds MCP Python SDK as optional dependency"
+        - "Users must configure MCP server in their AI tool (one-time setup)"
+        - "MCP adoption is still early — not all tools support it yet"
+        - "Scanner dependency story unchanged — tools still need local bins or Docker"
+
+    implementation: |
+      Phase 5 in SDK-ROADMAP.md. Key files:
+        argus/mcp.py — MCP server module (stdio transport)
+        argus mcp — CLI subcommand to start the server
+      Optional dependency: pip install argus-security[mcp]
+      Existing skill at .agents/skills/ remains as fallback reference.
+      Depends on Phase 3 (portability) for maximum scanner coverage without Docker.

docs/developer/SDK-ROADMAP.md

@@ -147,13 +147,103 @@ Refactor `.github/actions/scanner-*` to call `argus scan` internally. Actions sh
 - [ ] Progress indicators during scanning and container pulls
 - [ ] `argus report github` — post results as PR comment via GitHub API
 
+### CI Preflight and Config Health
+
+- [ ] CI workflow step: `argus validate --strict --check-tools` as a gate before scan jobs
+- [ ] Living issue (Renovate-style): a single "Argus Config Health" GitHub issue that gets updated (not recreated) when config validation fails on the default branch. Scheduled workflow runs `argus validate --strict --check-tools`, updates the issue body with current status, and auto-closes when healthy. Avoids issue spam — one issue, always current.
+- [ ] `argus validate --check-tools` notes for scanners with runtime network dependencies (e.g., OSV API, ClamAV freshclam, Trivy DB updates) — informational, not blocking
+
 ### CI Templates
 - [ ] GitLab CI template
 - [ ] Jenkins pipeline template
 - [ ] Azure DevOps template
 
 ---
 
+## Remaining: Phase 5 — MCP Server (AI Assistant Integration)
+
+Expose Argus as an MCP (Model Context Protocol) server so AI coding assistants can drive scanning natively. Replaces the need for tool-specific skill files with a single, tool-agnostic integration that stays current with the installed Argus version.
+
+### Why MCP over skill files
+
+We explored three approaches for AI assistant integration:
+
+1. **Skill file installed by `argus init`** — A markdown file copied into the user's project that teaches AI assistants how to shell out to the Argus CLI. Problems:
+   - Immediately becomes a stale snapshot with no update mechanism
+   - AI tools have no skill registries or update notifications
+   - Must be duplicated per tool (`.claude/commands/`, `.cursorrules`, `.github/copilot-instructions.md`) or the project picks favorites
+   - The AI parses unstructured terminal output, losing information
+
+2. **"Inform, don't install"** — `argus init` prints a URL to the skill. Avoids staleness but puts the integration burden entirely on the user, and still has the terminal-parsing problem.
+
+3. **MCP server** — Argus exposes structured tools that any MCP-compatible AI assistant discovers automatically. The assistant calls typed functions and receives structured JSON instead of parsing CLI output. Updates ship with `pip install --upgrade argus`. Tool-agnostic by design (Claude Code, Cursor, Windsurf, VS Code Copilot all support MCP).
+
+### What the MCP server provides
+
+**Tools:**
+
+| Tool | Parameters | Returns |
+|------|-----------|---------|
+| `argus_detect` | `path` | Detected project signals (languages, frameworks, IaC, containers) |
+| `argus_scan` | `scanners`, `path`, `severity_threshold` | Structured findings with severity, file, line, rule, message |
+| `argus_validate` | `config_path` | Validation errors and warnings for argus.yml |
+| `argus_list_scanners` | — | Available scanners with install status and descriptions |
+| `argus_init` | `path`, `platform` | Generated config content and file paths |
+
+**Resources:**
+
+| Resource URI | Description |
+|-------------|-------------|
+| `argus://config` | Current argus.yml parsed as structured data |
+| `argus://results/latest` | Most recent scan results from the last run |
+
+### User setup
+
+```json
+{
+  "mcpServers": {
+    "argus": {
+      "command": "argus",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+One line of config in any MCP-compatible tool. The AI assistant then has full Argus capabilities without needing to know CLI syntax, parse terminal output, or have a skill file installed.
+
+### Dependencies and portability considerations
+
+The MCP server is a new interface to the existing engine — it does not change the scanner dependency story. Scanners still require either local binaries or Docker. Key considerations:
+
+- Pure Python scanners (bandit, checkov, osv) work without Docker
+- Binary scanners (gitleaks, trivy, opengrep) need Docker or local install
+- `argus_list_scanners` should clearly report what's available and what's missing
+- Graceful degradation: scans return partial results with clear "unavailable" status per scanner rather than failing entirely
+- Phase 3 (portability) should land first to maximize the set of scanners that work out of the box
+
+### Implementation tasks
+
+- [ ] `argus/mcp.py` — MCP server module using the MCP Python SDK
+- [ ] `argus mcp` CLI subcommand to start the server (stdio transport)
+- [ ] `argus_detect` tool — wraps `detect_project()` from init module
+- [ ] `argus_scan` tool — wraps engine scan, returns structured `ScanResult.to_dict()`
+- [ ] `argus_validate` tool — wraps config validation
+- [ ] `argus_list_scanners` tool — wraps scanner registry with availability status
+- [ ] `argus_init` tool — wraps init workflow, returns generated content
+- [ ] `argus://config` resource — reads and parses argus.yml
+- [ ] `argus://results/latest` resource — reads most recent results from output dir
+- [ ] Add `mcp` extra to pyproject.toml (`pip install argus-security[mcp]`)
+- [ ] Tests for all MCP tools with mock engine
+- [ ] Documentation: setup instructions per AI tool, example interactions
+- [ ] `argus init` prints MCP setup hint in summary output
+
+### Existing skill file
+
+The skill at `.agents/skills/argus-scanner-selection/` remains as a reference document and works for AI tools that don't support MCP. It is not versioned or synced to releases. Once the MCP server ships, the skill can reference it as the preferred integration path.
+
+---
+
 ## Known Issues
 
 ### Engine