feat(distribution): Claude Desktop .mcpb bundle + one-click MCP install badges

.github/workflows/release.yml

@@ -154,6 +154,39 @@ jobs:
             "spec-kit-docguard-v${VERSION}.zip" \
             --clobber
 
+  # ── Step 4b: Build and attach Claude Desktop extension (.mcpb) ─────────
+  # One-click local install for Claude Desktop (Settings → Extensions).
+  # Stages the exact npm-pack payload + the one production dep, stamps the
+  # manifest template, and packs with the official @anthropic-ai/mcpb tool
+  # (its schema is strict — the template must contain no unknown keys).
+  build-mcpb:
+    needs: [detect-version, create-release]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+
+      - name: Stage and pack .mcpb
+        run: |
+          VERSION="${{ needs.detect-version.outputs.version }}"
+          npm pack --pack-destination /tmp
+          mkdir -p /tmp/mcpb && tar xzf /tmp/docguard-cli-*.tgz -C /tmp/mcpb
+          cd /tmp/mcpb/package
+          npm install --omit=dev --no-audit --no-fund
+          sed "s/__VERSION__/${VERSION}/" "$GITHUB_WORKSPACE/mcpb/manifest.template.json" > manifest.json
+          npx -y @anthropic-ai/mcpb pack . "/tmp/docguard-v${VERSION}.mcpb"
+
+      - name: Upload to release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ needs.detect-version.outputs.version }}"
+          gh release upload "v${VERSION}" \
+            "/tmp/docguard-v${VERSION}.mcpb" \
+            --clobber
+
   # ── Step 5: Publish to npm ─────────────────────────────────────────────
   publish-npm:
     needs: [detect-version, test, create-release]

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Claude Desktop one-click extension (`.mcpb`).** Each release now attaches `docguard-v<version>.mcpb` — the official MCP Bundle format: drag into Claude Desktop → Settings → Extensions, pick the project folder, done. No npm, no JSON editing. Built by the new `build-mcpb` release job from the exact npm-pack payload (manifest template in `mcpb/`, packed with `@anthropic-ai/mcpb`). README gained one-click install badges for Cursor and VS Code (MCP deeplinks) alongside the Claude Code and registry paths.
+
 - **npm provenance attestation.** Releases now publish with `npm publish --provenance` (OIDC + Sigstore): every tarball carries a signed statement that it was built by this repo's GitHub Actions from a specific commit. This is what "unknown package" legitimacy checks (Claude Code, socket.dev, npm's Provenance badge) verify — DocGuard installs are now cryptographically attributable.
 - **PRIVACY.md** — the short, honest policy: DocGuard collects nothing, all analysis is local, no telemetry; the three explicit user-initiated outbound paths (`feedback` URL, `gh`-backed PR commands, opt-in HTTP transport) are enumerated. Ships in the npm package and unblocks Anthropic Connectors Directory submission (a missing privacy policy is an instant rejection there).
 - **FAQ**: why AI agents flag DocGuard as "unknown" on first install, and how to pre-trust it (project `.mcp.json`, Always allow, managed-settings allowlist).

README.md

@@ -454,6 +454,15 @@ DocGuard ships **18 professional templates** with metadata, badges, and revision
 
 ## 🤖 AI Agent Support
 
+### One-click MCP install
+
+[![Add to Cursor](https://img.shields.io/badge/Cursor-Add_MCP_Server-000000?logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=docguard&config=eyJjb21tYW5kIjogIm5weCIsICJhcmdzIjogWyIteSIsICJkb2NndWFyZC1jbGkiLCAibWNwIl19)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?logo=githubcopilot)](vscode:mcp/install?%7B%22name%22%3A%22docguard%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22docguard-cli%22%2C%22mcp%22%5D%7D)
+
+- **Claude Code**: `claude mcp add docguard -- npx docguard-cli mcp`
+- **Claude Desktop**: download `docguard-v<version>.mcpb` from the [latest release](https://github.com/raccioly/docguard/releases/latest) and drag it into Settings → Extensions — you'll be asked which project folder to analyze. No npm, no JSON editing.
+- **Anything MCP**: DocGuard is a verified namespace on the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=docguard) (`io.github.raccioly/docguard`).
+
 DocGuard works with **every major AI coding agent**. All canonical docs are plain markdown — no vendor lock-in.
 
 | Agent | Compatibility | Auto-Generate Config |

mcpb/README.md

@@ -0,0 +1,14 @@
+# MCPB bundle (Claude Desktop one-click extension)
+
+`manifest.template.json` is the source for the `.mcpb` Desktop Extension —
+`__VERSION__` is substituted by the release workflow's `build-mcpb` job, which
+stages the npm package (plus its one production dependency), packs it with
+`@anthropic-ai/mcpb`, and attaches `docguard.mcpb` to the GitHub Release.
+
+The mcpb schema is strict: no `$comment`/unknown keys in the manifest.
+Spec: <https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md>
+
+Users install by dragging `docguard.mcpb` into Claude Desktop →
+Settings → Extensions (they'll be asked to pick the project folder DocGuard
+analyzes). Directory listing is curated by Anthropic — submission interest
+form is linked from <https://claude.com/docs/connectors/building/mcpb>.

mcpb/manifest.template.json

@@ -0,0 +1,57 @@
+{
+  "manifest_version": "0.3",
+  "name": "docguard",
+  "display_name": "DocGuard",
+  "version": "__VERSION__",
+  "description": "Deterministic doc-drift detection: guard, score, explain, verify-claims, report and diagnose as read-only MCP tools.",
+  "long_description": "DocGuard validates your project's documentation against its code — 27 deterministic validators, CDD maturity score, compliance-evidence reports, requirements traceability — with a zero-LLM core. Every tool is read-only: it inspects the project folder you choose and never writes, mutates, or reaches the network. Local-first: no telemetry, no data collection (see PRIVACY.md in the repository).",
+  "author": {
+    "name": "Ricardo Accioly",
+    "url": "https://github.com/raccioly"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raccioly/docguard.git"
+  },
+  "homepage": "https://github.com/raccioly/docguard#readme",
+  "documentation": "https://github.com/raccioly/docguard/blob/main/docs/ai-integration.md",
+  "support": "https://github.com/raccioly/docguard/issues",
+  "keywords": ["documentation", "validation", "drift-detection", "cdd", "traceability", "code-quality"],
+  "server": {
+    "type": "node",
+    "entry_point": "cli/docguard.mjs",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/cli/docguard.mjs",
+        "mcp",
+        "--dir",
+        "${user_config.project_dir}"
+      ],
+      "env": {}
+    }
+  },
+  "user_config": {
+    "project_dir": {
+      "type": "directory",
+      "title": "Project folder",
+      "description": "The repository DocGuard analyzes by default. Every tool also accepts a per-call projectDir override.",
+      "required": true
+    }
+  },
+  "tools": [
+    { "name": "docguard_guard", "description": "Run every enabled validator against the project's canonical docs" },
+    { "name": "docguard_score", "description": "CDD maturity score (0-100) with per-category breakdown" },
+    { "name": "docguard_explain", "description": "Explain a stable finding code (STR001, ENV003, ...)" },
+    { "name": "docguard_verify_claims", "description": "Extract documented numbers/limits/enums as verification tasks" },
+    { "name": "docguard_report", "description": "Commit-stamped compliance-evidence bundle with integrity hash" },
+    { "name": "docguard_diagnose", "description": "Only what needs fixing, shaped for an agent to act on" }
+  ],
+  "compatibility": {
+    "platforms": ["darwin", "win32", "linux"],
+    "runtimes": {
+      "node": ">=18.0.0"
+    }
+  }
+}