agent-mcp-guard 0.1.0 → 0.2.0

package/README.md

@@ -1,39 +1,26 @@
+<p align="center">
+  <img src="site/assets/readme-hero.svg" alt="mcp-guard scan report hero" width="100%">
+</p>
+
 # mcp-guard
 
-Open-source CLI scanner for risky MCP server and AI agent tool configuration.
+Local-first security scanning for MCP and AI agent tool configs.
 
-`mcp-guard` helps developers review MCP configs before giving AI agents access to files, shells, credentials, SaaS tools, or production systems.
+`mcp-guard` helps teams review what their AI agents can execute before those agents touch local files, shells, credentials, SaaS accounts, or production systems.
 
-## What It Detects
+Website: [chaoyue0307.github.io/mcp-guard](https://chaoyue0307.github.io/mcp-guard/)
 
-- Shell wrappers and inline scripts.
-- `node -e`, `python -c`, and other interpreter eval modes.
-- Remote package runners such as `npx`, `uvx`, `bunx`, and `pnpm dlx`.
-- Unpinned MCP server package versions.
-- Secret-like environment variables and headers.
-- Broad filesystem access such as `/`, home, Desktop, Documents, or Downloads.
-- Remote MCP server URLs.
-- Dangerous command patterns such as `rm -rf`, `sudo`, `chmod 777`, and curl pipe to shell.
+<p>
+  <a href="https://www.npmjs.com/package/agent-mcp-guard"><img alt="npm version" src="https://img.shields.io/npm/v/agent-mcp-guard?color=0f766e"></a>
+  <a href="https://github.com/ChaoYue0307/mcp-guard/actions"><img alt="CI" src="https://github.com/ChaoYue0307/mcp-guard/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-111827"></a>
+  <a href="https://github.com/ChaoYue0307/mcp-guard/releases/tag/v0.2.0"><img alt="Release" src="https://img.shields.io/github/v/release/ChaoYue0307/mcp-guard?color=7c2d12"></a>
+</p>
 
 ## Install
 
-For local development from this repo:
-
-```bash
-npm install -g .
-```
-
-After npm publication:
-
 ```bash
 npm install -g agent-mcp-guard
-```
-
-## Usage
-
-Scan common Claude Desktop, Cursor, and project MCP config locations:
-
-```bash
 mcp-guard scan
 ```
 
@@ -49,15 +36,57 @@ Generate a Markdown report:
 mcp-guard scan --format markdown --output mcp-guard-report.md
 ```
 
-Use in CI and fail when high-risk findings are present:
+Generate an HTML report:
+
+```bash
+mcp-guard scan --format html --output mcp-guard-report.html
+```
+
+Use in CI:
 
 ```bash
 mcp-guard scan --config .mcp.json --fail-on high
 ```
 
-## Supported Config Shape
+Use the GitHub Action:
+
+```yaml
+- uses: ChaoYue0307/mcp-guard@v0.2.0
+  with:
+    fail-on: high
+```
+
+## What It Finds
+
+| Risk | Why it matters |
+| --- | --- |
+| Shell wrappers and inline scripts | Agent startup can become arbitrary code execution. |
+| `npx`, `uvx`, `bunx`, `pnpm dlx` | Remote package execution expands supply-chain risk. |
+| Unpinned packages | A trusted MCP server can change underneath you. |
+| Secret-like env vars and headers | Long-lived tokens leak into tool runtimes and reports. |
+| Broad filesystem access | Home, root, Desktop, Documents, and Downloads are high-blast-radius paths. |
+| Remote MCP URLs | Data may leave the local trust boundary. |
+| Dangerous command patterns | `rm -rf`, `sudo`, `chmod 777`, and curl-pipe-shell should block review. |
+
+## Example Output
+
+```text
+mcp-guard scan report
+Scanned files: 1
+MCP servers: 3
+Findings: 9
+Risk score: 98
+Critical: 2  High: 5  Medium: 2  Low: 0
+
+- [CRITICAL] MCP010 Shell command executes inline script
+- [HIGH] MCP021 Remote MCP package is not version pinned
+- [HIGH] MCP030 Secret-like environment variable is exposed to MCP server
+- [HIGH] MCP041 MCP server argument grants broad filesystem access
+```
+
+See the full sample report: [examples/sample-report.md](examples/sample-report.md)
 
-`mcp-guard` supports the common MCP config shape used by Claude Desktop, Cursor, and many project configs:
+## Supported Config Shape
 
 ```json
 {
@@ -74,45 +103,49 @@ mcp-guard scan --config .mcp.json --fail-on high
 }
 ```
 
-It also accepts `servers` as an alternative top-level key.
+`mcp-guard` supports the common `mcpServers` shape used by Claude Desktop, Cursor, and project-level MCP configs. It also accepts `servers` as an alternative top-level key.
 
-## Example
-
-```bash
-npm run scan:example
-```
+## Why Local-First
 
-This scans `examples/unsafe-claude_desktop_config.json` and writes `examples/sample-report.md`.
+MCP configs often contain sensitive local paths, internal hostnames, tokens, and workflow details. `mcp-guard` runs locally by default:
 
-## Exit Codes
+- no config upload;
+- no external API call;
+- secret-like values redacted in reports;
+- text, Markdown, HTML, and JSON output for local review and CI.
 
-- `0`: scan completed and did not hit the fail threshold.
-- `1`: CLI usage or runtime error.
-- `2`: finding severity met `--fail-on` threshold.
+## Commercial Support
 
-## Privacy
+Need help reviewing a real AI agent or MCP setup?
 
-`mcp-guard` is local-first:
+I offer private **AI Agent/MCP Security Audits** covering server inventory, risky startup commands, secret exposure, filesystem scope, remote MCP endpoints, and remediation planning.
 
-- It does not upload configs.
-- It does not call external APIs.
-- It redacts secret-like values in reports by default.
+Contact: [hechaoyue0307@gmail.com](mailto:hechaoyue0307@gmail.com)
 
-MCP configs and reports can still contain sensitive paths, hostnames, and configuration details. Review before sharing.
+Service details: [docs/paid-audit.md](docs/paid-audit.md)
 
 ## Documentation
 
 - [Rule reference](docs/rules.md)
+- [GitHub Action](docs/github-action.md)
 - [Privacy and security](docs/privacy-and-security.md)
-- [Paid audit service](docs/paid-audit.md)
+- [Roadmap](docs/roadmap.md)
+- [Business playbook](docs/business-playbook.md)
 - [Launch checklist](docs/launch-checklist.md)
 - [Operator runbook](docs/operator-runbook.md)
 
-## Commercial Support
+## Exit Codes
 
-Need a private AI Agent/MCP security audit?
+- `0`: scan completed and did not hit the fail threshold.
+- `1`: CLI usage or runtime error.
+- `2`: finding severity met `--fail-on` threshold.
+
+## Development
 
-The first paid service is a focused review of your MCP and agent tool setup: inventory, risk report, remediation checklist, and a hardening call. See [docs/paid-audit.md](docs/paid-audit.md).
+```bash
+npm test
+npm run release:check
+```
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy
+
+## Supported Versions
+
+`mcp-guard` is early-stage software. Security fixes target the latest npm version.
+
+## Reporting A Vulnerability
+
+Please do not open a public issue for a vulnerability that could expose users.
+
+Email: [hechaoyue0307@gmail.com](mailto:hechaoyue0307@gmail.com)
+
+Include:
+
+- affected version;
+- operating system;
+- config sample with secrets removed;
+- reproduction steps;
+- expected and actual behavior;
+- potential impact.
+
+I will acknowledge valid reports as quickly as practical and coordinate disclosure before publishing details.
+
+## Scope
+
+In scope:
+
+- secret redaction failures;
+- unexpected config upload or network access;
+- incorrect handling of local files;
+- CLI behavior that hides high-risk findings;
+- supply-chain or package publishing issues.
+
+Out of scope:
+
+- generic MCP server vulnerabilities unrelated to `mcp-guard`;
+- findings that require already-compromised local admin access;
+- social engineering against maintainers;
+- spam or automated low-signal reports.
+

package/action.yml

@@ -0,0 +1,111 @@
+name: mcp-guard
+description: Scan MCP and AI agent tool configuration for risky commands, secrets, and broad permissions.
+author: mcp-guard
+
+branding:
+  icon: shield
+  color: green
+
+inputs:
+  config:
+    description: Optional MCP config path to scan. Leave empty to scan default project and user config locations.
+    required: false
+    default: ""
+  fail-on:
+    description: Fail the workflow when a finding is at least this severity. Use critical, high, medium, low, or none.
+    required: false
+    default: high
+  output-dir:
+    description: Directory where reports will be written.
+    required: false
+    default: mcp-guard-report
+  package-version:
+    description: npm package version to install.
+    required: false
+    default: latest
+  upload-artifact:
+    description: Upload generated reports as a workflow artifact.
+    required: false
+    default: "true"
+  artifact-name:
+    description: Artifact name for generated reports.
+    required: false
+    default: mcp-guard-report
+
+outputs:
+  markdown-report:
+    description: Path to the generated Markdown report.
+    value: ${{ steps.reports.outputs.markdown-report }}
+  html-report:
+    description: Path to the generated HTML report.
+    value: ${{ steps.reports.outputs.html-report }}
+  json-report:
+    description: Path to the generated JSON report.
+    value: ${{ steps.reports.outputs.json-report }}
+  exit-code:
+    description: mcp-guard threshold exit code.
+    value: ${{ steps.reports.outputs.exit-code }}
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: "20"
+
+    - name: Install mcp-guard
+      shell: bash
+      env:
+        MCP_GUARD_PACKAGE_VERSION: ${{ inputs.package-version }}
+      run: npm install --global "agent-mcp-guard@${MCP_GUARD_PACKAGE_VERSION}"
+
+    - name: Generate reports
+      id: reports
+      shell: bash
+      env:
+        MCP_GUARD_CONFIG: ${{ inputs.config }}
+        MCP_GUARD_FAIL_ON: ${{ inputs.fail-on }}
+        MCP_GUARD_OUTPUT_DIR: ${{ inputs.output-dir }}
+      run: |
+        set -euo pipefail
+
+        mkdir -p "${MCP_GUARD_OUTPUT_DIR}"
+
+        scan_args=()
+        if [ -n "${MCP_GUARD_CONFIG}" ]; then
+          scan_args+=(--config "${MCP_GUARD_CONFIG}")
+        fi
+
+        markdown_report="${MCP_GUARD_OUTPUT_DIR}/mcp-guard-report.md"
+        html_report="${MCP_GUARD_OUTPUT_DIR}/mcp-guard-report.html"
+        json_report="${MCP_GUARD_OUTPUT_DIR}/mcp-guard-report.json"
+
+        mcp-guard scan "${scan_args[@]}" --format markdown --output "${markdown_report}" --fail-on none
+        mcp-guard scan "${scan_args[@]}" --format html --output "${html_report}" --fail-on none
+        mcp-guard scan "${scan_args[@]}" --format json --output "${json_report}" --fail-on none
+
+        set +e
+        mcp-guard scan "${scan_args[@]}" --fail-on "${MCP_GUARD_FAIL_ON}"
+        status="$?"
+        set -e
+
+        {
+          echo "markdown-report=${markdown_report}"
+          echo "html-report=${html_report}"
+          echo "json-report=${json_report}"
+          echo "exit-code=${status}"
+        } >> "${GITHUB_OUTPUT}"
+
+    - name: Upload report artifact
+      if: ${{ always() && inputs.upload-artifact == 'true' }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ inputs.artifact-name }}
+        path: ${{ inputs.output-dir }}
+
+    - name: Enforce severity threshold
+      shell: bash
+      env:
+        MCP_GUARD_EXIT_CODE: ${{ steps.reports.outputs.exit-code }}
+      run: exit "${MCP_GUARD_EXIT_CODE}"

package/docs/business-playbook.md

@@ -0,0 +1,64 @@
+# Business Playbook
+
+## Positioning
+
+`mcp-guard` is the local-first security scanner for teams adopting AI agents and MCP servers.
+
+The business is not the open-source CLI alone. The CLI creates trust and distribution. Revenue comes from private audits, remediation, and eventually team workflows.
+
+## First Paid Offer
+
+AI Agent/MCP Security Audit.
+
+Deliverables:
+
+- MCP server inventory;
+- `mcp-guard` Markdown, HTML, and JSON scan reports;
+- manual review of high-risk findings;
+- prioritized remediation plan;
+- optional GitHub Action setup for continuous scans;
+- 60-minute hardening call;
+- optional PR with safer config changes.
+
+## Pricing
+
+| Customer | Price |
+| --- | ---: |
+| Solo founder / indie team | USD 300-800 |
+| Small startup | USD 1,000-3,000 |
+| Funded team / private deployment pilot | USD 3,000-8,000 |
+
+## Outreach Copy
+
+```text
+I built mcp-guard, an open-source local scanner for MCP and AI agent tool configs.
+
+It checks for risky shell access, unpinned npx packages, broad filesystem permissions, exposed secrets, and remote MCP servers.
+
+I am doing a few early MCP security audits for teams using Claude, Cursor, Codex, or MCP in real workflows. If you send a redacted config or run the CLI locally, I can help interpret the report and suggest hardening steps.
+```
+
+## First 20 Targets
+
+- MCP server authors.
+- AI automation agencies.
+- Devtool startups using MCP.
+- Teams publishing agent demos with real tool access.
+- Founders discussing Cursor, Claude Code, Codex, or MCP on GitHub, X, LinkedIn, Hacker News, or Discord.
+
+## Validation Signals
+
+Strong:
+
+- user shares real redacted config;
+- user asks for CI integration;
+- user asks whether a finding is exploitable;
+- user pays for remediation;
+- team asks for monthly scanning.
+
+Weak:
+
+- stars without config samples;
+- vague security interest;
+- requests for a full dashboard before any audit;
+- only free users with toy configs.

package/docs/github-action.md

@@ -0,0 +1,68 @@
+# GitHub Action
+
+Use the `mcp-guard` action to scan MCP and AI agent tool configuration in pull requests and CI.
+
+The action installs the published npm package, generates Markdown, HTML, and JSON reports, uploads them as a workflow artifact, then fails the job when findings meet your selected severity threshold.
+
+## Basic Workflow
+
+```yaml
+name: mcp-guard
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ChaoYue0307/mcp-guard@v0.2.0
+        with:
+          fail-on: high
+```
+
+## Scan a Specific Config
+
+```yaml
+- uses: ChaoYue0307/mcp-guard@v0.2.0
+  with:
+    config: .mcp.json
+    fail-on: medium
+```
+
+## Pin the npm Package
+
+The action defaults to `agent-mcp-guard@latest`. Pin it when you want deterministic CI behavior:
+
+```yaml
+- uses: ChaoYue0307/mcp-guard@v0.2.0
+  with:
+    package-version: 0.2.0
+    fail-on: high
+```
+
+## Inputs
+
+| Input | Default | Description |
+| --- | --- | --- |
+| `config` | empty | Optional MCP config path. Empty scans default project and user config locations. |
+| `fail-on` | `high` | Fails the job for `critical`, `high`, `medium`, or `low` findings. Use `none` for report-only mode. |
+| `output-dir` | `mcp-guard-report` | Directory for generated reports. |
+| `package-version` | `latest` | npm package version to install. |
+| `upload-artifact` | `true` | Uploads generated reports as a workflow artifact. |
+| `artifact-name` | `mcp-guard-report` | Name of the uploaded artifact. |
+
+## Outputs
+
+| Output | Description |
+| --- | --- |
+| `markdown-report` | Path to the generated Markdown report. |
+| `html-report` | Path to the generated HTML report. |
+| `json-report` | Path to the generated JSON report. |
+| `exit-code` | `0` when below threshold, `2` when findings met the threshold. |

package/docs/roadmap.md

@@ -0,0 +1,33 @@
+# Product Roadmap
+
+`mcp-guard` should stay narrow: local-first MCP and AI agent tool security that produces actionable reports.
+
+## Now
+
+- CLI config scanning.
+- Text, Markdown, HTML, and redacted JSON output.
+- Rules for shell wrappers, remote package runners, unpinned packages, broad filesystem access, secret-like env vars/headers, and remote MCP URLs.
+- CI usage with `--fail-on`.
+- GitHub Action wrapper that uploads Markdown, HTML, and JSON reports as artifacts.
+
+## Next
+
+1. More MCP client discovery paths.
+2. Rule packs mapped to MCP security best practices.
+3. `mcp-guard audit` mode for client-ready reports.
+4. Policy file for approved commands, packages, directories, and remote URLs.
+5. Baseline mode: accept known findings and fail only on new risks.
+
+## Later
+
+1. SBOM/package metadata checks for MCP server packages.
+2. Local web report viewer.
+3. Hosted team dashboard only after repeated paid audit demand.
+
+## Product Principles
+
+- Local-first by default.
+- Findings must include a fix.
+- Avoid noisy rules that do not change behavior.
+- Prefer workflow integration over dashboards.
+- Services first, SaaS later.

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "agent-mcp-guard",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Open-source CLI scanner for risky MCP server and AI agent tool configuration.",
   "type": "module",
+  "homepage": "https://chaoyue0307.github.io/mcp-guard/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChaoYue0307/mcp-guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ChaoYue0307/mcp-guard/issues"
+  },
   "bin": {
     "mcp-guard": "bin/mcp-guard.js"
   },
@@ -32,8 +40,12 @@
     "bin",
     "src",
     "README.md",
+    "action.yml",
     "LICENSE",
+    "SECURITY.md",
     "docs",
-    "examples"
+    "examples",
+    "site/assets/readme-hero.svg",
+    "site/assets/brand-mark.svg"
   ]
 }

package/site/assets/brand-mark.svg

@@ -0,0 +1,6 @@
+<svg width="96" height="96" viewBox="0 0 96 96" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="mcp-guard mark">
+  <rect width="96" height="96" rx="22" fill="#101312"/>
+  <path d="M29 48l19-24 19 24-19 24-19-24z" fill="#2dd4bf"/>
+  <path d="M52 23l28 25-28 25" stroke="#f8fafc" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+

package/site/assets/readme-hero.svg

@@ -0,0 +1,42 @@
+<svg width="1200" height="420" viewBox="0 0 1200 420" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">mcp-guard scan report</title>
+  <desc id="desc">A dark product hero showing an MCP security scan report with critical, high, medium, and low findings.</desc>
+  <rect width="1200" height="420" rx="28" fill="#101312"/>
+  <path d="M0 0h1200v420H0z" fill="url(#grid)" opacity=".22"/>
+  <path d="M925 0h275v150L1015 94 925 132V0z" fill="#0f766e" opacity=".2"/>
+  <path d="M0 282l202 64 144-42v116H0V282z" fill="#7c2d12" opacity=".18"/>
+  <rect x="70" y="66" width="440" height="288" rx="22" fill="#f8fafc"/>
+  <rect x="96" y="94" width="78" height="78" rx="18" fill="#101312"/>
+  <path d="M121 133l15-19 15 19-15 19-15-19z" fill="#2dd4bf"/>
+  <path d="M139 112l23 21-23 21" stroke="#f8fafc" stroke-width="8" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="198" y="122" fill="#101312" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="800">mcp-guard</text>
+  <text x="198" y="154" fill="#475569" font-family="Inter, Arial, sans-serif" font-size="18">Local-first MCP config security scanner</text>
+  <rect x="96" y="196" width="360" height="16" rx="8" fill="#dbeafe"/>
+  <rect x="96" y="226" width="270" height="16" rx="8" fill="#ccfbf1"/>
+  <rect x="96" y="256" width="322" height="16" rx="8" fill="#ffedd5"/>
+  <rect x="96" y="296" width="152" height="40" rx="20" fill="#0f766e"/>
+  <text x="125" y="322" fill="#fff" font-family="Inter, Arial, sans-serif" font-size="16" font-weight="700">npm install</text>
+  <rect x="546" y="44" width="584" height="332" rx="24" fill="#0b0f0e" stroke="#33413d"/>
+  <rect x="546" y="44" width="584" height="54" rx="24" fill="#161d1b"/>
+  <circle cx="576" cy="71" r="6" fill="#ef4444"/>
+  <circle cx="598" cy="71" r="6" fill="#f59e0b"/>
+  <circle cx="620" cy="71" r="6" fill="#10b981"/>
+  <text x="652" y="77" fill="#94a3b8" font-family="Menlo, Consolas, monospace" font-size="14">mcp-guard scan --fail-on high</text>
+  <text x="586" y="134" fill="#e2e8f0" font-family="Menlo, Consolas, monospace" font-size="20" font-weight="700">scan report</text>
+  <text x="586" y="172" fill="#94a3b8" font-family="Menlo, Consolas, monospace" font-size="15">MCP servers: 3    Findings: 9    Risk score: 98</text>
+  <rect x="586" y="204" width="138" height="38" rx="12" fill="#7f1d1d"/>
+  <text x="610" y="229" fill="#fecaca" font-family="Inter, Arial, sans-serif" font-size="14" font-weight="800">2 critical</text>
+  <rect x="742" y="204" width="112" height="38" rx="12" fill="#7c2d12"/>
+  <text x="767" y="229" fill="#fed7aa" font-family="Inter, Arial, sans-serif" font-size="14" font-weight="800">5 high</text>
+  <rect x="872" y="204" width="124" height="38" rx="12" fill="#713f12"/>
+  <text x="897" y="229" fill="#fde68a" font-family="Inter, Arial, sans-serif" font-size="14" font-weight="800">2 medium</text>
+  <rect x="586" y="272" width="482" height="1" fill="#33413d"/>
+  <text x="586" y="306" fill="#fca5a5" font-family="Menlo, Consolas, monospace" font-size="15">MCP010 shell command executes inline script</text>
+  <text x="586" y="334" fill="#fdba74" font-family="Menlo, Consolas, monospace" font-size="15">MCP030 secret-like env var exposed</text>
+  <text x="586" y="362" fill="#fef3c7" font-family="Menlo, Consolas, monospace" font-size="15">MCP041 broad filesystem access</text>
+  <defs>
+    <pattern id="grid" width="38" height="38" patternUnits="userSpaceOnUse">
+      <path d="M38 0H0v38" stroke="#f8fafc" stroke-width="1"/>
+    </pattern>
+  </defs>
+</svg>

package/src/cli.js

@@ -1,10 +1,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { scan } from "./scan.js";
-import { generateJsonReport, generateMarkdownReport, generateTextReport } from "./report.js";
+import { generateHtmlReport, generateJsonReport, generateMarkdownReport, generateTextReport } from "./report.js";
 import { compareSeverity, severityRank } from "./severity.js";
 
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 
 export async function runCli(argv, io) {
   const args = argv.slice(2);
@@ -80,8 +80,8 @@ function parseScanArgs(args, defaultCwd) {
     } else if (arg === "--format" || arg === "-f") {
       options.format = readValue(args, index, arg);
       index += 1;
-      if (!["text", "markdown", "json"].includes(options.format)) {
-        throw new Error("--format must be one of: text, markdown, json");
+      if (!["text", "markdown", "json", "html"].includes(options.format)) {
+        throw new Error("--format must be one of: text, markdown, json, html");
       }
     } else if (arg === "--fail-on") {
       options.failOn = readValue(args, index, arg);
@@ -121,6 +121,9 @@ function renderReport(result, format) {
   if (format === "markdown") {
     return generateMarkdownReport(result);
   }
+  if (format === "html") {
+    return generateHtmlReport(result);
+  }
   return generateTextReport(result);
 }
 
@@ -142,7 +145,7 @@ Usage:
 Scan options:
   -c, --config <path>       Scan a specific MCP config file. Can be repeated.
   -o, --output <path>       Write report to a file.
-  -f, --format <format>     text, markdown, or json. Default: text.
+  -f, --format <format>     text, markdown, json, or html. Default: text.
       --fail-on <severity>  Exit 2 when finding severity is at least threshold.
                             critical, high, medium, low, none. Default: none.
       --cwd <path>          Working directory for project config discovery.
@@ -151,6 +154,7 @@ Scan options:
 Examples:
   mcp-guard scan
   mcp-guard scan --format markdown --output mcp-guard-report.md
+  mcp-guard scan --format html --output mcp-guard-report.html
   mcp-guard scan --config .mcp.json --fail-on high
 `;
 }

package/src/report.js

@@ -105,6 +105,362 @@ export function generateJsonReport(result) {
   return JSON.stringify(sanitizeResult(result), null, 2);
 }
 
+export function generateHtmlReport(result) {
+  const safeResult = sanitizeResult(result);
+  const riskTone = riskToneForScore(safeResult.summary.riskScore);
+  const findings = safeResult.findings;
+  const servers = safeResult.servers;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>mcp-guard Scan Report</title>
+  <style>
+    :root {
+      color-scheme: light;
+      --bg: #f8fafc;
+      --panel: #ffffff;
+      --ink: #111827;
+      --muted: #5b6575;
+      --line: #d9e2ec;
+      --soft: #eef4f7;
+      --critical: #b91c1c;
+      --high: #c2410c;
+      --medium: #a16207;
+      --low: #0f766e;
+      --info: #1d4ed8;
+      --shadow: 0 20px 55px rgba(15, 23, 42, 0.08);
+    }
+
+    * { box-sizing: border-box; }
+
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--ink);
+      font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      line-height: 1.5;
+    }
+
+    main {
+      width: min(1120px, calc(100% - 32px));
+      margin: 0 auto;
+      padding: 28px 0 48px;
+    }
+
+    .hero {
+      background: #ffffff;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      box-shadow: var(--shadow);
+      padding: 28px;
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) 240px;
+      gap: 24px;
+      align-items: stretch;
+    }
+
+    .eyebrow {
+      margin: 0 0 8px;
+      color: var(--info);
+      font-size: 13px;
+      font-weight: 700;
+      letter-spacing: 0;
+      text-transform: uppercase;
+    }
+
+    h1, h2 {
+      letter-spacing: 0;
+      line-height: 1.08;
+    }
+
+    h1 {
+      margin: 0;
+      font-size: 34px;
+    }
+
+    h2 {
+      margin: 0 0 14px;
+      font-size: 21px;
+    }
+
+    .lead {
+      max-width: 720px;
+      margin: 12px 0 0;
+      color: var(--muted);
+      font-size: 16px;
+    }
+
+    .scorecard {
+      border-radius: 8px;
+      border: 1px solid var(--line);
+      background: var(--soft);
+      padding: 18px;
+      min-height: 176px;
+      display: flex;
+      flex-direction: column;
+      justify-content: space-between;
+    }
+
+    .score-label {
+      margin: 0;
+      color: var(--muted);
+      font-size: 13px;
+      font-weight: 700;
+      text-transform: uppercase;
+    }
+
+    .score-value {
+      margin: 8px 0;
+      font-size: 58px;
+      font-weight: 800;
+      line-height: 1;
+      color: var(--${riskTone});
+    }
+
+    .score-caption {
+      margin: 0;
+      color: var(--muted);
+      font-size: 14px;
+    }
+
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+      gap: 12px;
+      margin: 18px 0 0;
+    }
+
+    .metric {
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      padding: 14px;
+    }
+
+    .metric strong {
+      display: block;
+      font-size: 24px;
+      line-height: 1.1;
+    }
+
+    .metric span {
+      display: block;
+      margin-top: 6px;
+      color: var(--muted);
+      font-size: 13px;
+    }
+
+    section {
+      margin-top: 22px;
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      box-shadow: 0 10px 30px rgba(15, 23, 42, 0.04);
+      padding: 22px;
+    }
+
+    .severity-row {
+      display: grid;
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+      gap: 10px;
+    }
+
+    .severity {
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      padding: 12px;
+      min-height: 78px;
+    }
+
+    .severity b {
+      display: block;
+      font-size: 22px;
+      line-height: 1.1;
+    }
+
+    .severity span {
+      display: block;
+      margin-top: 6px;
+      color: var(--muted);
+      font-size: 13px;
+      text-transform: capitalize;
+    }
+
+    .critical { color: var(--critical); }
+    .high { color: var(--high); }
+    .medium { color: var(--medium); }
+    .low { color: var(--low); }
+
+    .table-wrap {
+      width: 100%;
+      overflow-x: auto;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+    }
+
+    table {
+      width: 100%;
+      min-width: 760px;
+      border-collapse: collapse;
+      background: var(--panel);
+    }
+
+    th, td {
+      padding: 12px 14px;
+      border-bottom: 1px solid var(--line);
+      text-align: left;
+      vertical-align: top;
+      font-size: 14px;
+    }
+
+    th {
+      color: #374151;
+      background: #f1f5f9;
+      font-size: 12px;
+      text-transform: uppercase;
+    }
+
+    tr:last-child td { border-bottom: 0; }
+
+    code {
+      padding: 2px 5px;
+      border-radius: 5px;
+      background: #eef2f7;
+      color: #111827;
+      font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+      font-size: 0.92em;
+      white-space: normal;
+      overflow-wrap: anywhere;
+    }
+
+    .pill {
+      display: inline-flex;
+      align-items: center;
+      min-height: 24px;
+      padding: 3px 8px;
+      border-radius: 999px;
+      background: #f1f5f9;
+      font-size: 12px;
+      font-weight: 700;
+      text-transform: uppercase;
+    }
+
+    .pill.critical { background: #fee2e2; }
+    .pill.high { background: #ffedd5; }
+    .pill.medium { background: #fef3c7; }
+    .pill.low { background: #ccfbf1; }
+
+    .empty {
+      margin: 0;
+      color: var(--muted);
+      border: 1px dashed var(--line);
+      border-radius: 8px;
+      padding: 16px;
+      background: #fbfdff;
+    }
+
+    .notes {
+      color: var(--muted);
+      font-size: 14px;
+    }
+
+    .notes ul {
+      margin: 10px 0 0;
+      padding-left: 18px;
+    }
+
+    @media (max-width: 780px) {
+      main {
+        width: min(100% - 20px, 1120px);
+        padding-top: 10px;
+      }
+
+      .hero {
+        grid-template-columns: 1fr;
+        padding: 20px;
+      }
+
+      h1 { font-size: 28px; }
+
+      .grid,
+      .severity-row {
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+      }
+    }
+
+    @media (max-width: 460px) {
+      .grid,
+      .severity-row {
+        grid-template-columns: 1fr;
+      }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <header class="hero">
+      <div>
+        <p class="eyebrow">mcp-guard scan report</p>
+        <h1>AI agent tool risk review</h1>
+        <p class="lead">Local-first review of MCP server configuration, startup commands, remote endpoints, filesystem scope, and secret-like values.</p>
+        <div class="grid">
+          ${metric("Scanned files", safeResult.summary.scannedFileCount)}
+          ${metric("MCP servers", safeResult.summary.serverCount)}
+          ${metric("Findings", safeResult.summary.findingCount)}
+          ${metric("Generated", formatDate(safeResult.metadata.generatedAt))}
+        </div>
+      </div>
+      <aside class="scorecard" aria-label="Risk score">
+        <div>
+          <p class="score-label">Risk score</p>
+          <p class="score-value">${escapeHtml(safeResult.summary.riskScore)}</p>
+        </div>
+        <p class="score-caption">${escapeHtml(riskCaption(safeResult.summary.riskScore))}</p>
+      </aside>
+    </header>
+
+    <section>
+      <h2>Severity Summary</h2>
+      <div class="severity-row">
+        ${severityCard("critical", safeResult.summary.counts.critical)}
+        ${severityCard("high", safeResult.summary.counts.high)}
+        ${severityCard("medium", safeResult.summary.counts.medium)}
+        ${severityCard("low", safeResult.summary.counts.low)}
+      </div>
+    </section>
+
+    <section>
+      <h2>Scanned Files</h2>
+      ${renderScannedFiles(safeResult)}
+    </section>
+
+    <section>
+      <h2>MCP Server Inventory</h2>
+      ${renderServerTable(servers, safeResult.metadata.cwd)}
+    </section>
+
+    <section>
+      <h2>Findings</h2>
+      ${renderFindingsTable(findings)}
+    </section>
+
+    <section class="notes">
+      <h2>Review Notes</h2>
+      <ul>
+        <li>Secret-like values are redacted before rendering this report.</li>
+        <li>Review each server before granting access to files, shells, SaaS accounts, or production systems.</li>
+        <li>This report assists security review and does not guarantee that every issue was found.</li>
+      </ul>
+    </section>
+  </main>
+</body>
+</html>
+`;
+}
+
 function cell(value) {
   return String(value).replaceAll("|", "\\|").replaceAll("\n", "<br>");
 }
@@ -134,3 +490,108 @@ function sanitizeResult(result) {
     summary: result.summary
   };
 }
+
+function metric(label, value) {
+  return `<div class="metric"><strong>${escapeHtml(value)}</strong><span>${escapeHtml(label)}</span></div>`;
+}
+
+function severityCard(severity, count) {
+  return `<div class="severity ${severity}"><b>${escapeHtml(count)}</b><span>${escapeHtml(severity)}</span></div>`;
+}
+
+function renderScannedFiles(result) {
+  if (result.scannedFiles.length === 0) {
+    return `<p class="empty">No MCP config files were found.</p>`;
+  }
+
+  const items = result.scannedFiles
+    .map((file) => `<tr><td><code>${escapeHtml(displayPath(file, result.metadata.cwd))}</code></td></tr>`)
+    .join("");
+
+  return `<div class="table-wrap"><table><thead><tr><th>Path</th></tr></thead><tbody>${items}</tbody></table></div>`;
+}
+
+function renderServerTable(servers, cwd) {
+  if (servers.length === 0) {
+    return `<p class="empty">No MCP servers were found.</p>`;
+  }
+
+  const rows = servers.map((server) => {
+    const env = kvList(server.env);
+    const headers = kvList(server.headers);
+    return `<tr>
+      <td><strong>${escapeHtml(server.name)}</strong><br><code>${escapeHtml(displayPath(server.configPath, cwd))}</code></td>
+      <td>${codeOrDash(server.command)}</td>
+      <td>${codeOrDash(server.args.join(" "))}</td>
+      <td>${codeOrDash(server.cwd)}</td>
+      <td>${codeOrDash(server.url)}</td>
+      <td>${env || "-"}</td>
+      <td>${headers || "-"}</td>
+    </tr>`;
+  }).join("");
+
+  return `<div class="table-wrap"><table>
+    <thead><tr><th>Server</th><th>Command</th><th>Args</th><th>CWD</th><th>URL</th><th>Env</th><th>Headers</th></tr></thead>
+    <tbody>${rows}</tbody>
+  </table></div>`;
+}
+
+function renderFindingsTable(findings) {
+  if (findings.length === 0) {
+    return `<p class="empty">No findings. Keep reviewing new MCP servers and agent tools before adding them.</p>`;
+  }
+
+  const rows = findings.map((finding) => `<tr>
+    <td><span class="pill ${escapeHtml(finding.severity)}">${escapeHtml(finding.severity)}</span></td>
+    <td><code>${escapeHtml(finding.id)}</code></td>
+    <td>${escapeHtml(finding.serverName)}</td>
+    <td>${escapeHtml(finding.title)}</td>
+    <td>${codeOrDash(finding.evidence)}</td>
+    <td>${escapeHtml(finding.recommendation)}</td>
+  </tr>`).join("");
+
+  return `<div class="table-wrap"><table>
+    <thead><tr><th>Severity</th><th>Rule</th><th>Server</th><th>Finding</th><th>Evidence</th><th>Recommendation</th></tr></thead>
+    <tbody>${rows}</tbody>
+  </table></div>`;
+}
+
+function kvList(record) {
+  return Object.entries(record || {})
+    .map(([key, value]) => `<code>${escapeHtml(key)}=${escapeHtml(value)}</code>`)
+    .join("<br>");
+}
+
+function codeOrDash(value) {
+  if (!value) return "-";
+  return `<code>${escapeHtml(value)}</code>`;
+}
+
+function formatDate(value) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return `${date.toISOString().slice(0, 16).replace("T", " ")} UTC`;
+}
+
+function riskToneForScore(score) {
+  if (score >= 80) return "critical";
+  if (score >= 50) return "high";
+  if (score >= 20) return "medium";
+  return "low";
+}
+
+function riskCaption(score) {
+  if (score >= 80) return "Critical review recommended before enabling these tools.";
+  if (score >= 50) return "High risk configuration; review before team use.";
+  if (score >= 20) return "Moderate risk; confirm the intended permission scope.";
+  return "Low risk based on the current rule set.";
+}
+
+function escapeHtml(value) {
+  return String(value ?? "")
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}