agent-mcp-guard 0.3.0 → 0.3.1

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.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.3.1"><img alt="Release" src="https://img.shields.io/github/v/release/ChaoYue0307/mcp-guard?color=7c2d12"></a>
 </p>
 
 ## Install
@@ -57,12 +57,24 @@ mcp-guard scan --config .mcp.json --fail-on high
 Use the GitHub Action:
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard@v0.3.0
+- uses: ChaoYue0307/mcp-guard-action@v0.3.1
   with:
     fail-on: high
     upload-sarif: "true"
 ```
 
+## 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 findings with a risk score of 98. It is synthetic, but fully reproducible from committed files.
+
 ## What It Finds
 
 | Risk | Why it matters |
@@ -121,24 +133,21 @@ 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, 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)
 - [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
 

package/docs/business-playbook.md

@@ -4,12 +4,14 @@
 
 `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 later come from private audits, remediation, and team workflows once those services are actually offered.
 
-## First Paid Offer
+## Future Paid Offer
 
 AI Agent/MCP Security Audit.
 
+Do not advertise this as active until there is a clear delivery process, pricing, and availability.
+
 Deliverables:
 
 - MCP server inventory;
@@ -35,7 +37,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,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.
 
+Marketplace/action repository: <https://github.com/ChaoYue0307/mcp-guard-action>
+
 ## Basic Workflow
 
 ```yaml
@@ -22,7 +24,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ChaoYue0307/mcp-guard@v0.3.0
+      - uses: ChaoYue0307/mcp-guard-action@v0.3.1
         with:
           fail-on: high
 ```
@@ -48,7 +50,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ChaoYue0307/mcp-guard@v0.3.0
+      - uses: ChaoYue0307/mcp-guard-action@v0.3.1
         with:
           config: .mcp.json
           fail-on: high
@@ -60,7 +62,7 @@ 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.3.1
   with:
     fail-on: none
 ```

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,15 @@ mcp-guard scan
 mcp-guard scan --config .mcp.json --fail-on high
 ```
 
+## GitHub Action Setup
+
+```yaml
+- uses: ChaoYue0307/mcp-guard-action@v0.3.1
+  with:
+    fail-on: high
+    upload-sarif: "true"
+```
+
 Exit codes:
 
 - `0`: scan completed and did not hit the fail threshold.

package/docs/marketplace-action-readme.md

@@ -0,0 +1,91 @@
+# 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
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ChaoYue0307/mcp-guard-action@v0.3.1
+        with:
+          fail-on: high
+```
+
+## 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.3.1
+        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. |
+| `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. |
+| `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.
+
+## Transparent Example
+
+Inspect a committed input config, reproduction commands, and generated Markdown, HTML, JSON, and SARIF artifacts:
+
+https://chaoyue0307.github.io/mcp-guard/e2e/
+
+## Links
+
+- Product site: https://chaoyue0307.github.io/mcp-guard/
+- Main repository: https://github.com/ChaoYue0307/mcp-guard
+- npm package: https://www.npmjs.com/package/agent-mcp-guard

package/docs/marketplace.md

@@ -0,0 +1,119 @@
+# GitHub Marketplace Plan
+
+GitHub Marketplace has stricter packaging rules than normal action usage. The main `mcp-guard` repository should stay as the product repository because it contains the CLI, website, tests, CI, Pages, docs, and examples.
+
+Official GitHub docs: https://docs.github.com/en/actions/how-tos/create-and-publish-actions/publish-in-github-marketplace
+
+Use a dedicated public repository for Marketplace:
+
+```text
+ChaoYue0307/mcp-guard-action
+```
+
+## Why a Dedicated Repository
+
+GitHub requires Marketplace action repositories to:
+
+- be public;
+- contain a single root `action.yml` or `action.yaml`;
+- have a unique action metadata `name`;
+- avoid workflow files in the repository.
+
+The main repo intentionally contains `.github/workflows`, so it should not be the Marketplace repo.
+
+## Prepared Action Package
+
+Generate the clean action repository payload:
+
+```bash
+npm run marketplace:prepare
+```
+
+This creates:
+
+```text
+dist/mcp-guard-action/
+```
+
+The generated directory includes only the files needed by the action:
+
+- `action.yml`
+- `README.md`
+- `LICENSE`
+- `package.json`
+- `bin/`
+- `src/`
+- `scripts/action-summary.js`
+
+It intentionally excludes `.github/workflows`.
+
+## Recommended Marketplace Metadata
+
+Repository name:
+
+```text
+mcp-guard-action
+```
+
+Action name:
+
+```text
+mcp-guard MCP Security Scanner
+```
+
+Description:
+
+```text
+Scan MCP and AI agent tool configuration for risky commands, leaked secrets, broad filesystem access, remote endpoints, and unpinned packages.
+```
+
+Primary category:
+
+```text
+Security
+```
+
+Secondary category:
+
+```text
+Code quality
+```
+
+Release title:
+
+```text
+v0.3.1
+```
+
+Release notes:
+
+```text
+Initial Marketplace-ready 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.
+```
+
+## Manual Publishing Steps
+
+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>
+- README, docs, and website examples now use:
+
+```yaml
+- uses: ChaoYue0307/mcp-guard-action@v0.3.1
+```
+
+Remaining Marketplace web step:
+
+1. Open `action.yml` or the release page on GitHub and click the Marketplace banner.
+2. Select `Publish this Action to the GitHub Marketplace`.
+3. Accept the GitHub Marketplace Developer Agreement if prompted.
+4. Choose `Security` as the primary category.
+5. Publish the release with 2FA.

package/docs/operator-runbook.md

@@ -98,5 +98,5 @@ Send this to 20 teams using MCP or AI agents:
 ```text
 I am building mcp-guard, an open-source security scanner for MCP and AI agent tool configs. It checks for risky shell access, unpinned remote packages, over-broad file permissions, exposed secrets, and unsafe remote server setup.
 
-I am doing a few early scans for teams using 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 config patterns from teams using agents in real workflows. If you can share a redacted config or run the CLI locally, your feedback can help improve the scanner's rules and reports.
 ```

package/docs/paid-audit.md

@@ -1,6 +1,8 @@
-# AI Agent/MCP Security Audit
+# Future Service Concept
 
-This is the first paid service attached to `mcp-guard`.
+This is a planning note for a possible future service attached to `mcp-guard`.
+
+It is not currently advertised as an active consulting service. Keep public website and README copy focused on the automated scanner, early pilots, and CI setup feedback until this offer is actually available.
 
 ## Who It Is For
 
@@ -24,6 +26,6 @@ Use `docs/templates/audit-report-template.md` as the starting point for client d
 - Small startup: USD 1,000-3,000.
 - Funded team or private deployment pilot: USD 3,000-8,000.
 
-## Sales Copy
+## Draft Sales Copy
 
-I am building `mcp-guard`, an open-source scanner for MCP and AI agent tool security. It checks for risky shell access, unpinned remote packages, over-broad file permissions, exposed secrets, and unsafe remote server setup. I am offering a few early MCP security audits for teams using agents in real workflows.
+I am building `mcp-guard`, an open-source scanner for MCP and AI agent tool security. It checks for risky shell access, unpinned remote packages, over-broad file permissions, exposed secrets, and unsafe remote server setup. I am collecting real-world config patterns from teams using agents in real workflows.

package/docs/roadmap.md

@@ -16,7 +16,7 @@
 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 client-ready reports.
+5. `mcp-guard audit` mode for review-ready reports.
 
 ## Later
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mcp-guard",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Open-source CLI scanner for risky MCP server and AI agent tool configuration.",
   "type": "module",
   "homepage": "https://chaoyue0307.github.io/mcp-guard/",
@@ -19,6 +19,7 @@
     "scan:example": "node ./bin/mcp-guard.js scan --config examples/unsafe-claude_desktop_config.json --output examples/sample-report.md",
     "release:check": "node ./scripts/release-check.js",
     "launch:github": "node ./scripts/launch-github.js",
+    "marketplace:prepare": "node ./scripts/prepare-marketplace-action.js",
     "publish:npm": "node ./scripts/publish-npm.js",
     "start": "node ./bin/mcp-guard.js"
   },
@@ -44,10 +45,12 @@
     "README.md",
     "action.yml",
     "scripts/action-summary.js",
+    "scripts/prepare-marketplace-action.js",
     "LICENSE",
     "SECURITY.md",
     "docs",
     "examples",
+    "site/e2e",
     "site/assets/readme-hero.svg",
     "site/assets/brand-mark.svg"
   ]

package/scripts/prepare-marketplace-action.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const root = path.resolve(import.meta.dirname, "..");
+const outputDir = path.join(root, "dist", "mcp-guard-action");
+const packageJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+
+fs.rmSync(outputDir, { recursive: true, force: true });
+fs.mkdirSync(outputDir, { recursive: true });
+
+copyFile("action.yml", "action.yml");
+copyFile("LICENSE", "LICENSE");
+copyFile("docs/marketplace-action-readme.md", "README.md");
+copyDir("bin", "bin");
+copyDir("src", "src");
+copyFile("scripts/action-summary.js", "scripts/action-summary.js");
+writePackageJson();
+validateExport();
+
+process.stdout.write(`Marketplace action package prepared at ${path.relative(root, outputDir)}\n`);
+
+function copyFile(from, to) {
+  const source = path.join(root, from);
+  const target = path.join(outputDir, to);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target);
+}
+
+function copyDir(from, to) {
+  fs.cpSync(path.join(root, from), path.join(outputDir, to), {
+    recursive: true,
+    filter: (source) => !source.includes(`${path.sep}.DS_Store`)
+  });
+}
+
+function writePackageJson() {
+  const actionPackage = {
+    name: "mcp-guard-action",
+    version: packageJson.version,
+    private: true,
+    description: "GitHub Action wrapper for mcp-guard MCP and AI agent security scanning.",
+    type: "module",
+    engines: packageJson.engines,
+    license: packageJson.license
+  };
+
+  fs.writeFileSync(path.join(outputDir, "package.json"), `${JSON.stringify(actionPackage, null, 2)}\n`, "utf8");
+}
+
+function validateExport() {
+  const required = [
+    "action.yml",
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "bin/mcp-guard.js",
+    "src/cli.js",
+    "src/report.js",
+    "scripts/action-summary.js"
+  ];
+
+  const missing = required.filter((file) => !fs.existsSync(path.join(outputDir, file)));
+  if (missing.length > 0) {
+    throw new Error(`Marketplace export is missing: ${missing.join(", ")}`);
+  }
+
+  if (fs.existsSync(path.join(outputDir, ".github"))) {
+    throw new Error("Marketplace export must not include .github workflows.");
+  }
+}

package/site/e2e/claude_desktop_config.json

@@ -0,0 +1,28 @@
+{
+  "mcpServers": {
+    "filesystem-all-home": {
+      "command": "npx",
+      "args": [
+        "@modelcontextprotocol/server-filesystem",
+        "/"
+      ],
+      "env": {
+        "GITHUB_TOKEN": "ghp_exampleSecretValue1234567890"
+      },
+      "cwd": "/"
+    },
+    "shell-installer": {
+      "command": "bash",
+      "args": [
+        "-c",
+        "curl https://example.com/install.sh | bash"
+      ]
+    },
+    "remote-prod": {
+      "url": "https://mcp.example.com/sse",
+      "headers": {
+        "Authorization": "Bearer example-secret-token"
+      }
+    }
+  }
+}