agent-mcp-guard 0.3.0 → 0.4.0

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.0"><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.0"><img alt="Release" src="https://img.shields.io/github/v/release/ChaoYue0307/mcp-guard?color=7c2d12"></a>
 </p>
 
 ## Install
@@ -54,15 +59,41 @@ 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@v0.3.0
+- uses: ChaoYue0307/mcp-guard-action@v0.4.0
   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:
+
+- input config: [site/e2e/claude_desktop_config.json](site/e2e/claude_desktop_config.json)
+- generated Markdown report: [site/e2e/report.md](site/e2e/report.md)
+- generated HTML report: [site/e2e/report.html](site/e2e/report.html)
+- 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 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
 
 | Risk | Why it matters |
@@ -75,13 +106,24 @@ Use the GitHub Action:
 | 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
 
@@ -121,24 +163,22 @@ MCP configs often contain sensitive local paths, internal hostnames, tokens, and
 - secret-like values redacted in reports;
 - text, Markdown, HTML, JSON, and SARIF output for local review, CI artifacts, and GitHub code scanning.
 
-## Commercial Support
+## Early Access and Feedback
 
-Need help reviewing a real AI agent or MCP setup?
+Want to try `mcp-guard` on a real AI agent or MCP setup?
 
-I offer private **AI Agent/MCP Security Audits** covering server inventory, risky startup commands, secret exposure, filesystem scope, remote MCP endpoints, and remediation planning.
+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)
 
-Service details: [docs/paid-audit.md](docs/paid-audit.md)
-
 ## 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)
 - [Roadmap](docs/roadmap.md)
-- [Business playbook](docs/business-playbook.md)
-- [Launch checklist](docs/launch-checklist.md)
 - [Operator runbook](docs/operator-runbook.md)
 
 ## Exit Codes

package/action.yml

@@ -1,4 +1,4 @@
-name: mcp-guard
+name: mcp-guard MCP Security Scanner
 description: Scan MCP and AI agent tool configuration for risky commands, secrets, and broad permissions.
 author: mcp-guard
 
@@ -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,6 +56,9 @@ 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
@@ -62,6 +73,7 @@ runs:
       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,6 +134,43 @@ 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@v7
+      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

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.0
+  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.0",
+  "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,29 +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. Revenue comes from private audits, remediation, and eventually team workflows.
+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.
 
-## First Paid Offer
+## Near-Term Paid Offer
 
-AI Agent/MCP Security Audit.
+MCP Guard CI Setup Sprint.
+
+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
 
@@ -35,7 +36,7 @@ I built mcp-guard, an open-source local scanner for MCP and AI agent tool config
 
 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.
+I am collecting real-world MCP and AI agent config patterns from teams using Claude, Cursor, Codex, or MCP in production-like workflows. If you can share a redacted config or run the CLI locally, your feedback can help improve the scanner's rules and reports.
 ```
 
 ## First 20 Targets

package/docs/examples/e2e-example.md

@@ -0,0 +1,60 @@
+# End-to-End Example
+
+This example is designed for transparent product evaluation. It uses a synthetic MCP config committed to the repository, then runs the real `mcp-guard` CLI to generate Markdown, HTML, JSON, and SARIF outputs.
+
+The input is intentionally unsafe so users can see whether the scanner catches concrete risks.
+
+## Input
+
+Config file:
+
+- [`site/e2e/claude_desktop_config.json`](../../site/e2e/claude_desktop_config.json)
+
+It contains three MCP server entries:
+
+- `filesystem-all-home`: launches an unpinned remote package with broad filesystem access and a secret-like environment variable.
+- `shell-installer`: runs `bash -c` with a curl-pipe-shell installer pattern.
+- `remote-prod`: points at a remote MCP endpoint with a secret-like authorization header.
+
+## Reproduce the Reports
+
+```bash
+node ./bin/mcp-guard.js scan --config site/e2e/claude_desktop_config.json --format markdown --output site/e2e/report.md
+node ./bin/mcp-guard.js scan --config site/e2e/claude_desktop_config.json --format html --output site/e2e/report.html
+node ./bin/mcp-guard.js scan --config site/e2e/claude_desktop_config.json --format json --output site/e2e/report.json
+node ./bin/mcp-guard.js scan --config site/e2e/claude_desktop_config.json --format sarif --output site/e2e/report.sarif
+```
+
+## Expected Result
+
+The current scanner reports:
+
+- Risk score: `98`
+- Findings: `9`
+- Critical: `2`
+- High: `5`
+- Medium: `2`
+- Low: `0`
+
+Important findings include:
+
+- `MCP010`: shell command executes inline script.
+- `MCP050`: curl-pipe-shell startup command.
+- `MCP021`: unpinned remote MCP package.
+- `MCP030`: secret-like environment variable.
+- `MCP040` and `MCP041`: broad working directory and filesystem argument.
+- `MCP061`: secret-like remote header.
+
+## Generated Artifacts
+
+- [Markdown report](../../site/e2e/report.md)
+- [HTML report](../../site/e2e/report.html)
+- [JSON report](../../site/e2e/report.json)
+- [SARIF report](../../site/e2e/report.sarif)
+
+## What This Proves
+
+- The scanner does not need the config to leave the machine.
+- Secret-like values are redacted in reports.
+- Findings include rule IDs, severity, evidence, and remediation guidance.
+- The same scan can feed a human-readable HTML report, automation JSON, and GitHub code scanning SARIF.

package/docs/github-action.md

@@ -4,6 +4,10 @@ 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
 
 ```yaml
@@ -16,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@v0.3.0
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.0
         with:
+          config: .mcp.json
           fail-on: high
+          comment-pr: "true"
 ```
 
 ## Upload SARIF to GitHub Security
@@ -48,7 +55,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ChaoYue0307/mcp-guard@v0.3.0
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.0
         with:
           config: .mcp.json
           fail-on: high
@@ -60,17 +67,39 @@ jobs:
 Use `fail-on: none` when you want artifacts and summaries without blocking a pull request.
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard@v0.3.0
+- uses: ChaoYue0307/mcp-guard-action@v0.4.0
   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.0
+  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`. |
@@ -84,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

@@ -10,8 +10,9 @@
 - [ ] Publish with `npm publish --access public`.
 - [ ] Generate fresh sample report with `npm run scan:example`.
 - [ ] Add screenshots or paste report excerpt into README.
+- [ ] Finish the GitHub Marketplace web publishing step for `mcp-guard-action`.
 - [ ] Post a short technical article or launch note.
-- [ ] Contact 20 early users for free scans or paid hardening.
+- [ ] Contact 20 early users for scan feedback, missing rules, and CI setup needs.
 - [ ] Follow the detailed steps in `docs/operator-runbook.md`.
 
 ## User Setup
@@ -27,6 +28,18 @@ mcp-guard scan
 mcp-guard scan --config .mcp.json --fail-on high
 ```
 
+## GitHub Action Setup
+
+```yaml
+- uses: ChaoYue0307/mcp-guard-action@v0.4.0
+  with:
+    config: .mcp.json
+    baseline: .mcp-guard-baseline.json
+    fail-on: high
+    comment-pr: "true"
+    upload-sarif: "true"
+```
+
 Exit codes:
 
 - `0`: scan completed and did not hit the fail threshold.

package/docs/marketplace-action-readme.md

@@ -0,0 +1,121 @@
+# mcp-guard MCP Security Scanner
+
+Scan MCP and AI agent tool configuration in GitHub Actions before risky tools merge.
+
+`mcp-guard` finds risky shell startup commands, leaked secret-like values, broad filesystem access, remote MCP endpoints, dangerous command patterns, and unpinned remote package runners.
+
+## Usage
+
+```yaml
+name: mcp-guard
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.0
+        with:
+          config: .mcp.json
+          fail-on: high
+          comment-pr: "true"
+```
+
+## Upload SARIF to GitHub Security
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.0
+        with:
+          config: .mcp.json
+          fail-on: high
+          upload-sarif: "true"
+```
+
+## 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`. |
+| `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. |
+| `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
+
+The action generates:
+
+- Markdown for pull request review.
+- HTML for review-ready artifacts.
+- JSON for automation.
+- SARIF 2.1.0 for GitHub code scanning.
+
+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.0
+  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