agent-mcp-guard 0.3.1 → 0.4.1

package/README.md

@@ -10,11 +10,16 @@ Local-first security scanning for MCP and AI agent tool configs.
 
 Website: [chaoyue0307.github.io/mcp-guard](https://chaoyue0307.github.io/mcp-guard/)
 
+Marketplace: [mcp-guard MCP Security Scanner](https://github.com/marketplace/actions/mcp-guard-mcp-security-scanner)
+
+Live demo PR: [mcp-guard-demo#1](https://github.com/ChaoYue0307/mcp-guard-demo/pull/1)
+
 <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/marketplace/actions/mcp-guard-mcp-security-scanner"><img alt="GitHub Marketplace" src="https://img.shields.io/badge/Marketplace-mcp--guard-0f766e?logo=github"></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.3.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.4.1"><img alt="Release" src="https://img.shields.io/github/v/release/ChaoYue0307/mcp-guard?color=7c2d12"></a>
 </p>
 
 ## Install
@@ -54,15 +59,27 @@ Use in CI:
 mcp-guard scan --config .mcp.json --fail-on high
 ```
 
+Accept known findings and fail only on new risk:
+
+```bash
+mcp-guard scan --config .mcp.json --write-baseline .mcp-guard-baseline.json
+mcp-guard scan --config .mcp.json --baseline .mcp-guard-baseline.json --fail-on high
+```
+
 Use the GitHub Action:
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.3.1
+- uses: ChaoYue0307/mcp-guard-action@v0.4.1
   with:
+    config: .mcp.json
+    baseline: .mcp-guard-baseline.json
     fail-on: high
+    comment-pr: "true"
     upload-sarif: "true"
 ```
 
+Inspect the live demo pull request: [ChaoYue0307/mcp-guard-demo#1](https://github.com/ChaoYue0307/mcp-guard-demo/pull/1). It intentionally introduces risky MCP config so the Action fails, uploads reports, and sends SARIF to GitHub code scanning.
+
 ## End-to-End Example
 
 Use the transparent example to evaluate what the scanner actually does:
@@ -73,7 +90,9 @@ Use the transparent example to evaluate what the scanner actually does:
 - generated JSON report: [site/e2e/report.json](site/e2e/report.json)
 - generated SARIF report: [site/e2e/report.sarif](site/e2e/report.sarif)
 
-The example scans 3 MCP servers and reports 9 findings with a risk score of 98. It is synthetic, but fully reproducible from committed files.
+The example scans 3 MCP servers and reports 9 active findings with a risk score of 98. It is synthetic, but fully reproducible from committed files.
+
+For the GitHub Action workflow, inspect the public demo repository: [ChaoYue0307/mcp-guard-demo](https://github.com/ChaoYue0307/mcp-guard-demo).
 
 ## What It Finds
 
@@ -87,13 +106,24 @@ The example scans 3 MCP servers and reports 9 findings with a risk score of 98.
 | 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. |
 
+## Team Workflow
+
+`mcp-guard` now supports a baseline/allowlist workflow for real teams:
+
+1. Generate a baseline from already-known findings.
+2. Commit the baseline file after review.
+3. Run CI with `--baseline` so accepted findings are visible but do not fail the build.
+4. Fail pull requests only when new high-risk MCP changes appear.
+
+The GitHub Action can also post an optional pull request comment with the active finding summary.
+
 ## Example Output
 
 ```text
 mcp-guard scan report
 Scanned files: 1
 MCP servers: 3
-Findings: 9
+Active findings: 9
 Risk score: 98
 Critical: 2  High: 5  Medium: 2  Low: 0
 
@@ -137,13 +167,14 @@ MCP configs often contain sensitive local paths, internal hostnames, tokens, and
 
 Want to try `mcp-guard` on a real AI agent or MCP setup?
 
-The project is currently an automated local scanner. I am collecting early users, real-world config examples, CI setup feedback, and rule requests to improve coverage.
+The project is currently an automated local scanner. I am collecting early users, real-world config examples, CI setup feedback, baseline workflow feedback, and rule requests to improve coverage.
 
 Contact: [hechaoyue0307@gmail.com](mailto:hechaoyue0307@gmail.com)
 
 ## Documentation
 
 - [Rule reference](docs/rules.md)
+- [Baseline and allowlist](docs/baseline.md)
 - [GitHub Action](docs/github-action.md)
 - [Marketplace publishing plan](docs/marketplace.md)
 - [Privacy and security](docs/privacy-and-security.md)

package/action.yml

@@ -15,6 +15,14 @@ inputs:
     description: Fail the workflow when a finding is at least this severity. Use critical, high, medium, low, or none.
     required: false
     default: high
+  baseline:
+    description: Optional mcp-guard baseline/allowlist JSON path. Matching findings are accepted and do not fail the workflow.
+    required: false
+    default: ""
+  comment-pr:
+    description: "Post or update a pull request comment with the scan summary. Requires pull-requests: write permission."
+    required: false
+    default: "false"
   output-dir:
     description: Directory where reports will be written.
     required: false
@@ -48,20 +56,24 @@ outputs:
   exit-code:
     description: mcp-guard threshold exit code.
     value: ${{ steps.reports.outputs.exit-code }}
+  comment-report:
+    description: Path to the generated pull request comment body.
+    value: ${{ steps.reports.outputs.comment-report }}
 
 runs:
   using: composite
   steps:
     - name: Set up Node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v6
       with:
-        node-version: "20"
+        node-version: "24"
 
     - name: Generate reports
       id: reports
       shell: bash
       env:
         MCP_GUARD_CONFIG: ${{ inputs.config }}
+        MCP_GUARD_BASELINE: ${{ inputs.baseline }}
         MCP_GUARD_FAIL_ON: ${{ inputs.fail-on }}
         MCP_GUARD_OUTPUT_DIR: ${{ inputs.output-dir }}
       run: |
@@ -74,16 +86,26 @@ runs:
         if [ -n "${MCP_GUARD_CONFIG}" ]; then
           scan_args+=(--config "${MCP_GUARD_CONFIG}")
         fi
+        if [ -n "${MCP_GUARD_BASELINE}" ]; then
+          scan_args+=(--baseline "${MCP_GUARD_BASELINE}")
+        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"
         sarif_report="${MCP_GUARD_OUTPUT_DIR}/mcp-guard.sarif"
+        comment_report="${MCP_GUARD_OUTPUT_DIR}/mcp-guard-pr-comment.md"
 
         node "${guard_bin}" scan "${scan_args[@]}" --format markdown --output "${markdown_report}" --fail-on none
         node "${guard_bin}" scan "${scan_args[@]}" --format html --output "${html_report}" --fail-on none
         node "${guard_bin}" scan "${scan_args[@]}" --format json --output "${json_report}" --fail-on none
         node "${guard_bin}" scan "${scan_args[@]}" --format sarif --output "${sarif_report}" --fail-on none
+        node "${GITHUB_ACTION_PATH}/scripts/action-comment.js" \
+          "${json_report}" \
+          "${markdown_report}" \
+          "${html_report}" \
+          "${sarif_report}" \
+          "${MCP_GUARD_FAIL_ON}" > "${comment_report}"
 
         set +e
         node "${guard_bin}" scan "${scan_args[@]}" --fail-on "${MCP_GUARD_FAIL_ON}"
@@ -95,6 +117,7 @@ runs:
           echo "html-report=${html_report}"
           echo "json-report=${json_report}"
           echo "sarif-report=${sarif_report}"
+          echo "comment-report=${comment_report}"
           echo "exit-code=${status}"
         } >> "${GITHUB_OUTPUT}"
 
@@ -111,16 +134,53 @@ runs:
           "${{ steps.reports.outputs.sarif-report }}" \
           "${MCP_GUARD_FAIL_ON}" >> "${GITHUB_STEP_SUMMARY}"
 
+    - name: Comment on pull request
+      if: ${{ always() && inputs.comment-pr == 'true' && github.event_name == 'pull_request' && steps.reports.outputs.comment-report != '' }}
+      uses: actions/github-script@v9
+      env:
+        MCP_GUARD_COMMENT_PATH: ${{ steps.reports.outputs.comment-report }}
+      with:
+        script: |
+          const fs = require('fs');
+          const marker = '<!-- mcp-guard-comment -->';
+          const body = fs.readFileSync(process.env.MCP_GUARD_COMMENT_PATH, 'utf8');
+          const issue_number = context.payload.pull_request.number;
+          const { owner, repo } = context.repo;
+          const comments = await github.rest.issues.listComments({
+            owner,
+            repo,
+            issue_number,
+            per_page: 100
+          });
+          const previous = comments.data.find((comment) =>
+            comment.user?.type === 'Bot' && comment.body?.includes(marker)
+          );
+          if (previous) {
+            await github.rest.issues.updateComment({
+              owner,
+              repo,
+              comment_id: previous.id,
+              body
+            });
+          } else {
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number,
+              body
+            });
+          }
+
     - name: Upload report artifact
       if: ${{ always() && inputs.upload-artifact == 'true' }}
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
         name: ${{ inputs.artifact-name }}
         path: ${{ inputs.output-dir }}
 
     - name: Upload SARIF to code scanning
       if: ${{ always() && inputs.upload-sarif == 'true' && steps.reports.outputs.sarif-report != '' }}
-      uses: github/codeql-action/upload-sarif@v3
+      uses: github/codeql-action/upload-sarif@v4
       with:
         sarif_file: ${{ steps.reports.outputs.sarif-report }}
 

package/docs/baseline.md

@@ -0,0 +1,70 @@
+# Baseline and Allowlist
+
+Use a baseline when a team already has known MCP findings but wants CI to block only new risk.
+
+The baseline is local JSON. It stores stable finding fingerprints plus enough context for review. Matching findings are marked as accepted and are excluded from `--fail-on`.
+
+## Create a Baseline
+
+```bash
+mcp-guard scan \
+  --config .mcp.json \
+  --write-baseline .mcp-guard-baseline.json
+```
+
+Commit the baseline with the MCP config if the accepted findings are intentional.
+
+## Enforce Only New Findings
+
+```bash
+mcp-guard scan \
+  --config .mcp.json \
+  --baseline .mcp-guard-baseline.json \
+  --fail-on high
+```
+
+If the scan finds only baseline-accepted findings, the exit code is `0`. If a new high or critical finding appears, the exit code is `2`.
+
+`--allowlist` and `--write-allowlist` are aliases for teams that prefer that wording.
+
+## GitHub Action
+
+```yaml
+- uses: ChaoYue0307/mcp-guard-action@v0.4.1
+  with:
+    config: .mcp.json
+    baseline: .mcp-guard-baseline.json
+    fail-on: high
+```
+
+The generated Markdown, HTML, JSON, and PR comment separate active findings from accepted baseline findings.
+
+## Baseline Format
+
+```json
+{
+  "version": 1,
+  "generatedAt": "2026-05-10T00:00:00.000Z",
+  "toolVersion": "0.4.1",
+  "findings": [
+    {
+      "fingerprint": "mcpg_a009b2c2",
+      "id": "MCP010",
+      "severity": "critical",
+      "serverName": "shell-installer",
+      "configPath": ".mcp.json",
+      "title": "Shell command executes inline script",
+      "evidence": "command=bash args=-c curl https://example.com/install.sh | bash",
+      "acceptedAt": "2026-05-10T00:00:00.000Z",
+      "reason": "Accepted current MCP findings"
+    }
+  ]
+}
+```
+
+## Review Guidance
+
+- Treat the baseline like code. Review changes in pull requests.
+- Keep the reason field specific when accepting high or critical findings.
+- Regenerate the baseline only after reviewing why findings changed.
+- Do not use a baseline to hide unknown third-party tools or broad filesystem access from reviewers.

package/docs/business-playbook.md

@@ -4,31 +4,30 @@
 
 `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. Near-term validation comes from early users running the scanner on real setups. Revenue can later come from private audits, remediation, and team workflows once those services are actually offered.
+The business is not the open-source CLI alone. The CLI creates trust and distribution. Near-term validation comes from early users running the scanner on real setups. Revenue can start with setup help and team workflow integration before offering broader manual audits.
 
-## Future Paid Offer
+## Near-Term Paid Offer
 
-AI Agent/MCP Security Audit.
+MCP Guard CI Setup Sprint.
 
-Do not advertise this as active until there is a clear delivery process, pricing, and availability.
+This is setup and product onboarding, not a manual security audit.
 
 Deliverables:
 
-- MCP server inventory;
-- `mcp-guard` Markdown, HTML, JSON, and SARIF 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.
+- install the CLI and GitHub Action;
+- generate Markdown, HTML, JSON, and SARIF reports;
+- create an initial baseline for accepted known findings;
+- enable PR comments and optional SARIF upload;
+- document missing rule requests for future product work;
+- provide a short setup handoff note.
 
 ## 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 |
+| Solo founder / indie team | USD 199-500 |
+| Small startup | USD 750-2,000 |
+| Funded team / private deployment pilot | USD 2,000-5,000 |
 
 ## Outreach Copy
 

package/docs/github-action.md

@@ -4,6 +4,8 @@ Use the `mcp-guard` action to scan MCP and AI agent tool configuration in pull r
 
 The action runs the CLI from the pinned GitHub Action tag, generates Markdown, HTML, JSON, and SARIF reports, writes a job summary, uploads reports as an artifact, and fails the job when findings meet your selected severity threshold.
 
+It can also use a committed baseline to accept known findings and optionally post a pull request comment with only the active findings.
+
 Marketplace/action repository: <https://github.com/ChaoYue0307/mcp-guard-action>
 
 ## Basic Workflow
@@ -18,15 +20,18 @@ on:
 
 permissions:
   contents: read
+  pull-requests: write
 
 jobs:
   scan:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ChaoYue0307/mcp-guard-action@v0.3.1
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.1
         with:
+          config: .mcp.json
           fail-on: high
+          comment-pr: "true"
 ```
 
 ## Upload SARIF to GitHub Security
@@ -50,7 +55,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ChaoYue0307/mcp-guard-action@v0.3.1
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.1
         with:
           config: .mcp.json
           fail-on: high
@@ -62,17 +67,39 @@ jobs:
 Use `fail-on: none` when you want artifacts and summaries without blocking a pull request.
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.3.1
+- uses: ChaoYue0307/mcp-guard-action@v0.4.1
   with:
     fail-on: none
 ```
 
+## Baseline Mode
+
+Use a baseline when you want to accept known findings and fail only on new risk.
+
+```bash
+mcp-guard scan --config .mcp.json --write-baseline .mcp-guard-baseline.json
+```
+
+Commit `.mcp-guard-baseline.json`, then reference it from the action:
+
+```yaml
+- uses: ChaoYue0307/mcp-guard-action@v0.4.1
+  with:
+    config: .mcp.json
+    baseline: .mcp-guard-baseline.json
+    fail-on: high
+```
+
+Reports will show active findings separately from findings accepted by the baseline.
+
 ## 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. |
+| `baseline` | empty | Optional baseline/allowlist JSON path. Matching findings are accepted and do not fail the workflow. |
+| `comment-pr` | `false` | Posts or updates a pull request comment with the scan summary. Requires `pull-requests: write`. |
 | `output-dir` | `mcp-guard-report` | Directory for generated reports. |
 | `upload-artifact` | `true` | Uploads generated reports as a workflow artifact. |
 | `upload-sarif` | `false` | Uploads SARIF to GitHub code scanning. Requires `security-events: write`. |
@@ -86,4 +113,5 @@ Use `fail-on: none` when you want artifacts and summaries without blocking a pul
 | `html-report` | Path to the generated HTML report. |
 | `json-report` | Path to the generated JSON report. |
 | `sarif-report` | Path to the generated SARIF report. |
+| `comment-report` | Path to the generated pull request comment body. |
 | `exit-code` | `0` when below threshold, `2` when findings met the threshold. |

package/docs/launch-checklist.md

@@ -31,9 +31,12 @@ mcp-guard scan --config .mcp.json --fail-on high
 ## GitHub Action Setup
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.3.1
+- uses: ChaoYue0307/mcp-guard-action@v0.4.1
   with:
+    config: .mcp.json
+    baseline: .mcp-guard-baseline.json
     fail-on: high
+    comment-pr: "true"
     upload-sarif: "true"
 ```
 

package/docs/marketplace-action-readme.md

@@ -16,15 +16,18 @@ on:
 
 permissions:
   contents: read
+  pull-requests: write
 
 jobs:
   scan:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ChaoYue0307/mcp-guard-action@v0.3.1
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.1
         with:
+          config: .mcp.json
           fail-on: high
+          comment-pr: "true"
 ```
 
 ## Upload SARIF to GitHub Security
@@ -39,7 +42,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ChaoYue0307/mcp-guard-action@v0.3.1
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.1
         with:
           config: .mcp.json
           fail-on: high
@@ -52,6 +55,8 @@ jobs:
 | --- | --- | --- |
 | `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. |
+| `baseline` | empty | Optional baseline/allowlist JSON path. Matching findings are accepted and do not fail the workflow. |
+| `comment-pr` | `false` | Posts or updates a pull request comment with the scan summary. Requires `pull-requests: write`. |
 | `output-dir` | `mcp-guard-report` | Directory for generated reports. |
 | `upload-artifact` | `true` | Uploads generated reports as a workflow artifact. |
 | `upload-sarif` | `false` | Uploads SARIF to GitHub code scanning. Requires `security-events: write`. |
@@ -65,6 +70,7 @@ jobs:
 | `html-report` | Path to the generated HTML report. |
 | `json-report` | Path to the generated JSON report. |
 | `sarif-report` | Path to the generated SARIF report. |
+| `comment-report` | Path to the generated pull request comment body. |
 | `exit-code` | `0` when below threshold, `2` when findings met the threshold. |
 
 ## Reports
@@ -78,14 +84,38 @@ The action generates:
 
 Secret-like values are redacted before reports are written.
 
+## Baseline Mode
+
+Generate and commit a baseline when existing MCP risk is known and accepted:
+
+```bash
+mcp-guard scan --config .mcp.json --write-baseline .mcp-guard-baseline.json
+```
+
+Then enforce only new findings:
+
+```yaml
+- uses: ChaoYue0307/mcp-guard-action@v0.4.1
+  with:
+    config: .mcp.json
+    baseline: .mcp-guard-baseline.json
+    fail-on: high
+```
+
 ## Transparent Example
 
 Inspect a committed input config, reproduction commands, and generated Markdown, HTML, JSON, and SARIF artifacts:
 
 https://chaoyue0307.github.io/mcp-guard/e2e/
 
+Inspect a live GitHub Action demo pull request that intentionally fails on risky MCP config:
+
+https://github.com/ChaoYue0307/mcp-guard-demo/pull/1
+
 ## Links
 
 - Product site: https://chaoyue0307.github.io/mcp-guard/
+- Marketplace listing: https://github.com/marketplace/actions/mcp-guard-mcp-security-scanner
+- Live demo repository: https://github.com/ChaoYue0307/mcp-guard-demo
 - Main repository: https://github.com/ChaoYue0307/mcp-guard
 - npm package: https://www.npmjs.com/package/agent-mcp-guard

package/docs/marketplace.md

@@ -82,19 +82,18 @@ Code quality
 Release title:
 
 ```text
-v0.3.1
+v0.4.1
 ```
 
 Release notes:
 
 ```text
-Initial Marketplace-ready release.
+Node 24 compatibility release.
 
-- Runs mcp-guard from the pinned action tag.
-- Generates Markdown, HTML, JSON, and SARIF reports.
-- Writes a GitHub Step Summary for pull request review.
-- Can upload SARIF to GitHub code scanning with `upload-sarif: "true"`.
-- Fails workflows by configurable severity threshold.
+- Keeps the v0.4 baseline and pull request comment workflow.
+- Uses Node.js 24 for the scanner runtime.
+- Updates first-party GitHub Actions dependencies to current major versions.
+- Uses CodeQL SARIF upload v4.
 ```
 
 ## Manual Publishing Steps
@@ -103,11 +102,11 @@ Completed:
 
 - Public repository created: <https://github.com/ChaoYue0307/mcp-guard-action>
 - `dist/mcp-guard-action/` exported, committed, and pushed.
-- Release created: <https://github.com/ChaoYue0307/mcp-guard-action/releases/tag/v0.3.1>
+- Release created: <https://github.com/ChaoYue0307/mcp-guard-action/releases/tag/v0.4.1>
 - README, docs, and website examples now use:
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.3.1
+- uses: ChaoYue0307/mcp-guard-action@v0.4.1
 ```
 
 Remaining Marketplace web step:

package/docs/roadmap.md

@@ -9,14 +9,16 @@
 - 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 writes a job summary, uploads Markdown/HTML/JSON/SARIF artifacts, and can upload SARIF to GitHub code scanning.
+- Baseline/allowlist mode for accepting known findings and failing only on new risks.
+- Optional GitHub pull request comments from the Marketplace Action.
 
 ## Next
 
 1. More MCP client discovery paths.
 2. Rule packs mapped to MCP security best practices.
 3. Policy file for approved commands, packages, directories, and remote URLs.
-4. Baseline mode: accept known findings and fail only on new risks.
-5. `mcp-guard audit` mode for review-ready reports.
+4. `mcp-guard audit` mode for review-ready reports.
+5. Safer default remediation snippets for common MCP servers.
 
 ## Later
 

package/examples/sample-report.md

@@ -1,12 +1,12 @@
 # mcp-guard Scan Report
 
-Generated: 2026-05-10T06:56:59.977Z
+Generated: 2026-05-10T13:15:24.269Z
 
 ## Summary
 
 - Scanned files: 1
 - MCP servers: 3
-- Findings: 9
+- Active findings: 9
 - Risk score: 98
 - Critical: 2
 - High: 5
@@ -25,19 +25,19 @@ Generated: 2026-05-10T06:56:59.977Z
 | shell-installer | bash | -c curl https://example.com/install.sh \| bash | - | - | - |
 | remote-prod | - | - | - | https://mcp.example.com/sse | - |
 
-## Findings
-
-| Severity | Rule | Server | Finding | Evidence | Recommendation |
-| --- | --- | --- | --- | --- | --- |
-| critical | MCP010 | shell-installer | Shell command executes inline script | command=bash args=-c curl https://example.com/install.sh \| bash | Use a direct, pinned executable instead of a shell wrapper. If a shell is required, place the script in source control and review it. |
-| critical | MCP050 | shell-installer | MCP server command includes a dangerous operation | curl pipe to shell | Remove the dangerous operation from MCP startup. Run destructive setup steps manually and review them separately. |
-| high | MCP021 | filesystem-all-home | Remote MCP package is not version pinned | package=@modelcontextprotocol/server-filesystem | Pin the package to an exact version such as package@1.2.3 and review updates before changing it. |
-| high | MCP030 | filesystem-all-home | Secret-like environment variable is exposed to MCP server | GITHUB_TOKEN=ghp...890 (32 chars) | Pass the least privileged token possible. Prefer scoped tokens, short-lived credentials, and a dedicated service account. |
-| high | MCP040 | filesystem-all-home | MCP server has a broad working directory | cwd=/ | Run the server in a narrow project directory or sandbox with only the files it needs. |
-| high | MCP041 | filesystem-all-home | MCP server argument grants broad filesystem access | arg=/ | Replace broad filesystem paths with a dedicated project folder or read-only sandbox path. |
-| high | MCP061 | remote-prod | Secret-like header is configured for remote MCP server | Authorization=Bea...ken (27 chars) | Use scoped, short-lived credentials and avoid placing long-lived secrets directly in MCP config files. |
-| medium | MCP020 | filesystem-all-home | MCP server is launched through a remote package runner | command=npx package=@modelcontextprotocol/server-filesystem | Pin the package version, review the package source, and prefer a local lockfile or vendored executable for sensitive tools. |
-| medium | MCP060 | remote-prod | Remote MCP server URL is configured | url=https://mcp.example.com/sse | Verify the provider, use HTTPS, document the data sent to this server, and keep an allowlist of approved remote endpoints. |
+## Active Findings
+
+| Severity | Rule | Server | Finding | Evidence | Fingerprint | Recommendation |
+| --- | --- | --- | --- | --- | --- | --- |
+| critical | MCP010 | shell-installer | Shell command executes inline script | command=bash args=-c curl https://example.com/install.sh \| bash | mcpg_a009b2c2 | Use a direct, pinned executable instead of a shell wrapper. If a shell is required, place the script in source control and review it. |
+| critical | MCP050 | shell-installer | MCP server command includes a dangerous operation | curl pipe to shell | mcpg_6bd13204 | Remove the dangerous operation from MCP startup. Run destructive setup steps manually and review them separately. |
+| high | MCP021 | filesystem-all-home | Remote MCP package is not version pinned | package=@modelcontextprotocol/server-filesystem | mcpg_d0af49fa | Pin the package to an exact version such as package@1.2.3 and review updates before changing it. |
+| high | MCP030 | filesystem-all-home | Secret-like environment variable is exposed to MCP server | GITHUB_TOKEN=ghp...890 (32 chars) | mcpg_a5f382b0 | Pass the least privileged token possible. Prefer scoped tokens, short-lived credentials, and a dedicated service account. |
+| high | MCP040 | filesystem-all-home | MCP server has a broad working directory | cwd=/ | mcpg_31aaa689 | Run the server in a narrow project directory or sandbox with only the files it needs. |
+| high | MCP041 | filesystem-all-home | MCP server argument grants broad filesystem access | arg=/ | mcpg_dbc08d76 | Replace broad filesystem paths with a dedicated project folder or read-only sandbox path. |
+| high | MCP061 | remote-prod | Secret-like header is configured for remote MCP server | Authorization=Bea...ken (27 chars) | mcpg_5abd4cbd | Use scoped, short-lived credentials and avoid placing long-lived secrets directly in MCP config files. |
+| medium | MCP020 | filesystem-all-home | MCP server is launched through a remote package runner | command=npx package=@modelcontextprotocol/server-filesystem | mcpg_a3493a53 | Pin the package version, review the package source, and prefer a local lockfile or vendored executable for sensitive tools. |
+| medium | MCP060 | remote-prod | Remote MCP server URL is configured | url=https://mcp.example.com/sse | mcpg_cf1296e4 | Verify the provider, use HTTPS, document the data sent to this server, and keep an allowlist of approved remote endpoints. |
 
 ## Notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mcp-guard",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Open-source CLI scanner for risky MCP server and AI agent tool configuration.",
   "type": "module",
   "homepage": "https://chaoyue0307.github.io/mcp-guard/",
@@ -45,6 +45,7 @@
     "README.md",
     "action.yml",
     "scripts/action-summary.js",
+    "scripts/action-comment.js",
     "scripts/prepare-marketplace-action.js",
     "LICENSE",
     "SECURITY.md",