agent-mcp-guard 0.1.1 → 0.2.0

package/README.md

@@ -14,7 +14,7 @@ Website: [chaoyue0307.github.io/mcp-guard](https://chaoyue0307.github.io/mcp-gua
   <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.1.1"><img alt="Release" src="https://img.shields.io/github/v/release/ChaoYue0307/mcp-guard?color=7c2d12"></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
@@ -36,12 +36,26 @@ Generate a Markdown report:
 mcp-guard scan --format markdown --output mcp-guard-report.md
 ```
 
+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
 ```
 
+Use the GitHub Action:
+
+```yaml
+- uses: ChaoYue0307/mcp-guard@v0.2.0
+  with:
+    fail-on: high
+```
+
 ## What It Finds
 
 | Risk | Why it matters |
@@ -98,7 +112,7 @@ MCP configs often contain sensitive local paths, internal hostnames, tokens, and
 - no config upload;
 - no external API call;
 - secret-like values redacted in reports;
-- text, Markdown, and JSON output for local review and CI.
+- text, Markdown, HTML, and JSON output for local review and CI.
 
 ## Commercial Support
 
@@ -113,6 +127,7 @@ 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)
 - [Roadmap](docs/roadmap.md)
 - [Business playbook](docs/business-playbook.md)

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

@@ -13,9 +13,10 @@ AI Agent/MCP Security Audit.
 Deliverables:
 
 - MCP server inventory;
-- `mcp-guard` scan report;
+- `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.
 
@@ -61,4 +62,3 @@ Weak:
 - 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

@@ -5,25 +5,24 @@
 ## Now
 
 - CLI config scanning.
-- Text, Markdown, and redacted JSON output.
+- 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. GitHub Action wrapper.
-2. HTML audit report.
-3. More MCP client discovery paths.
-4. Rule packs mapped to MCP security best practices.
-5. `mcp-guard audit` mode for client-ready reports.
+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. Policy file: approved commands, packages, directories, and remote URLs.
-2. Baseline mode: accept known findings and fail only on new risks.
-3. SBOM/package metadata checks for MCP server packages.
-4. Local web report viewer.
-5. Hosted team dashboard only after repeated paid audit demand.
+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
 
@@ -32,4 +31,3 @@
 - Avoid noisy rules that do not change behavior.
 - Prefer workflow integration over dashboards.
 - Services first, SaaS later.
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mcp-guard",
-  "version": "0.1.1",
+  "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/",
@@ -40,6 +40,7 @@
     "bin",
     "src",
     "README.md",
+    "action.yml",
     "LICENSE",
     "SECURITY.md",
     "docs",

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.1";
+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;");
+}