agent-mcp-guard 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +68 -50
  2. package/SECURITY.md +40 -0
  3. package/docs/business-playbook.md +64 -0
  4. package/docs/roadmap.md +35 -0
  5. package/package.json +13 -2
  6. package/site/assets/brand-mark.svg +6 -0
  7. package/site/assets/readme-hero.svg +42 -0
  8. package/src/cli.js +1 -1
package/README.md CHANGED
@@ -1,39 +1,26 @@
1
+ <p align="center">
2
+ <img src="site/assets/readme-hero.svg" alt="mcp-guard scan report hero" width="100%">
3
+ </p>
4
+
1
5
  # mcp-guard
2
6
 
3
- Open-source CLI scanner for risky MCP server and AI agent tool configuration.
7
+ Local-first security scanning for MCP and AI agent tool configs.
4
8
 
5
- `mcp-guard` helps developers review MCP configs before giving AI agents access to files, shells, credentials, SaaS tools, or production systems.
9
+ `mcp-guard` helps teams review what their AI agents can execute before those agents touch local files, shells, credentials, SaaS accounts, or production systems.
6
10
 
7
- ## What It Detects
11
+ Website: [chaoyue0307.github.io/mcp-guard](https://chaoyue0307.github.io/mcp-guard/)
8
12
 
9
- - Shell wrappers and inline scripts.
10
- - `node -e`, `python -c`, and other interpreter eval modes.
11
- - Remote package runners such as `npx`, `uvx`, `bunx`, and `pnpm dlx`.
12
- - Unpinned MCP server package versions.
13
- - Secret-like environment variables and headers.
14
- - Broad filesystem access such as `/`, home, Desktop, Documents, or Downloads.
15
- - Remote MCP server URLs.
16
- - Dangerous command patterns such as `rm -rf`, `sudo`, `chmod 777`, and curl pipe to shell.
13
+ <p>
14
+ <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>
15
+ <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>
16
+ <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-111827"></a>
17
+ <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>
18
+ </p>
17
19
 
18
20
  ## Install
19
21
 
20
- For local development from this repo:
21
-
22
- ```bash
23
- npm install -g .
24
- ```
25
-
26
- After npm publication:
27
-
28
22
  ```bash
29
23
  npm install -g agent-mcp-guard
30
- ```
31
-
32
- ## Usage
33
-
34
- Scan common Claude Desktop, Cursor, and project MCP config locations:
35
-
36
- ```bash
37
24
  mcp-guard scan
38
25
  ```
39
26
 
@@ -49,15 +36,43 @@ Generate a Markdown report:
49
36
  mcp-guard scan --format markdown --output mcp-guard-report.md
50
37
  ```
51
38
 
52
- Use in CI and fail when high-risk findings are present:
39
+ Use in CI:
53
40
 
54
41
  ```bash
55
42
  mcp-guard scan --config .mcp.json --fail-on high
56
43
  ```
57
44
 
58
- ## Supported Config Shape
45
+ ## What It Finds
46
+
47
+ | Risk | Why it matters |
48
+ | --- | --- |
49
+ | Shell wrappers and inline scripts | Agent startup can become arbitrary code execution. |
50
+ | `npx`, `uvx`, `bunx`, `pnpm dlx` | Remote package execution expands supply-chain risk. |
51
+ | Unpinned packages | A trusted MCP server can change underneath you. |
52
+ | Secret-like env vars and headers | Long-lived tokens leak into tool runtimes and reports. |
53
+ | Broad filesystem access | Home, root, Desktop, Documents, and Downloads are high-blast-radius paths. |
54
+ | Remote MCP URLs | Data may leave the local trust boundary. |
55
+ | Dangerous command patterns | `rm -rf`, `sudo`, `chmod 777`, and curl-pipe-shell should block review. |
56
+
57
+ ## Example Output
58
+
59
+ ```text
60
+ mcp-guard scan report
61
+ Scanned files: 1
62
+ MCP servers: 3
63
+ Findings: 9
64
+ Risk score: 98
65
+ Critical: 2 High: 5 Medium: 2 Low: 0
66
+
67
+ - [CRITICAL] MCP010 Shell command executes inline script
68
+ - [HIGH] MCP021 Remote MCP package is not version pinned
69
+ - [HIGH] MCP030 Secret-like environment variable is exposed to MCP server
70
+ - [HIGH] MCP041 MCP server argument grants broad filesystem access
71
+ ```
72
+
73
+ See the full sample report: [examples/sample-report.md](examples/sample-report.md)
59
74
 
60
- `mcp-guard` supports the common MCP config shape used by Claude Desktop, Cursor, and many project configs:
75
+ ## Supported Config Shape
61
76
 
62
77
  ```json
63
78
  {
@@ -74,45 +89,48 @@ mcp-guard scan --config .mcp.json --fail-on high
74
89
  }
75
90
  ```
76
91
 
77
- It also accepts `servers` as an alternative top-level key.
92
+ `mcp-guard` supports the common `mcpServers` shape used by Claude Desktop, Cursor, and project-level MCP configs. It also accepts `servers` as an alternative top-level key.
78
93
 
79
- ## Example
94
+ ## Why Local-First
80
95
 
81
- ```bash
82
- npm run scan:example
83
- ```
84
-
85
- This scans `examples/unsafe-claude_desktop_config.json` and writes `examples/sample-report.md`.
96
+ MCP configs often contain sensitive local paths, internal hostnames, tokens, and workflow details. `mcp-guard` runs locally by default:
86
97
 
87
- ## Exit Codes
98
+ - no config upload;
99
+ - no external API call;
100
+ - secret-like values redacted in reports;
101
+ - text, Markdown, and JSON output for local review and CI.
88
102
 
89
- - `0`: scan completed and did not hit the fail threshold.
90
- - `1`: CLI usage or runtime error.
91
- - `2`: finding severity met `--fail-on` threshold.
103
+ ## Commercial Support
92
104
 
93
- ## Privacy
105
+ Need help reviewing a real AI agent or MCP setup?
94
106
 
95
- `mcp-guard` is local-first:
107
+ I offer private **AI Agent/MCP Security Audits** covering server inventory, risky startup commands, secret exposure, filesystem scope, remote MCP endpoints, and remediation planning.
96
108
 
97
- - It does not upload configs.
98
- - It does not call external APIs.
99
- - It redacts secret-like values in reports by default.
109
+ Contact: [hechaoyue0307@gmail.com](mailto:hechaoyue0307@gmail.com)
100
110
 
101
- MCP configs and reports can still contain sensitive paths, hostnames, and configuration details. Review before sharing.
111
+ Service details: [docs/paid-audit.md](docs/paid-audit.md)
102
112
 
103
113
  ## Documentation
104
114
 
105
115
  - [Rule reference](docs/rules.md)
106
116
  - [Privacy and security](docs/privacy-and-security.md)
107
- - [Paid audit service](docs/paid-audit.md)
117
+ - [Roadmap](docs/roadmap.md)
118
+ - [Business playbook](docs/business-playbook.md)
108
119
  - [Launch checklist](docs/launch-checklist.md)
109
120
  - [Operator runbook](docs/operator-runbook.md)
110
121
 
111
- ## Commercial Support
122
+ ## Exit Codes
112
123
 
113
- Need a private AI Agent/MCP security audit?
124
+ - `0`: scan completed and did not hit the fail threshold.
125
+ - `1`: CLI usage or runtime error.
126
+ - `2`: finding severity met `--fail-on` threshold.
114
127
 
115
- The first paid service is a focused review of your MCP and agent tool setup: inventory, risk report, remediation checklist, and a hardening call. See [docs/paid-audit.md](docs/paid-audit.md).
128
+ ## Development
129
+
130
+ ```bash
131
+ npm test
132
+ npm run release:check
133
+ ```
116
134
 
117
135
  ## License
118
136
 
package/SECURITY.md ADDED
@@ -0,0 +1,40 @@
1
+ # Security Policy
2
+
3
+ ## Supported Versions
4
+
5
+ `mcp-guard` is early-stage software. Security fixes target the latest npm version.
6
+
7
+ ## Reporting A Vulnerability
8
+
9
+ Please do not open a public issue for a vulnerability that could expose users.
10
+
11
+ Email: [hechaoyue0307@gmail.com](mailto:hechaoyue0307@gmail.com)
12
+
13
+ Include:
14
+
15
+ - affected version;
16
+ - operating system;
17
+ - config sample with secrets removed;
18
+ - reproduction steps;
19
+ - expected and actual behavior;
20
+ - potential impact.
21
+
22
+ I will acknowledge valid reports as quickly as practical and coordinate disclosure before publishing details.
23
+
24
+ ## Scope
25
+
26
+ In scope:
27
+
28
+ - secret redaction failures;
29
+ - unexpected config upload or network access;
30
+ - incorrect handling of local files;
31
+ - CLI behavior that hides high-risk findings;
32
+ - supply-chain or package publishing issues.
33
+
34
+ Out of scope:
35
+
36
+ - generic MCP server vulnerabilities unrelated to `mcp-guard`;
37
+ - findings that require already-compromised local admin access;
38
+ - social engineering against maintainers;
39
+ - spam or automated low-signal reports.
40
+
package/docs/business-playbook.md ADDED
@@ -0,0 +1,64 @@
1
+ # Business Playbook
2
+
3
+ ## Positioning
4
+
5
+ `mcp-guard` is the local-first security scanner for teams adopting AI agents and MCP servers.
6
+
7
+ 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.
8
+
9
+ ## First Paid Offer
10
+
11
+ AI Agent/MCP Security Audit.
12
+
13
+ Deliverables:
14
+
15
+ - MCP server inventory;
16
+ - `mcp-guard` scan report;
17
+ - manual review of high-risk findings;
18
+ - prioritized remediation plan;
19
+ - 60-minute hardening call;
20
+ - optional PR with safer config changes.
21
+
22
+ ## Pricing
23
+
24
+ | Customer | Price |
25
+ | --- | ---: |
26
+ | Solo founder / indie team | USD 300-800 |
27
+ | Small startup | USD 1,000-3,000 |
28
+ | Funded team / private deployment pilot | USD 3,000-8,000 |
29
+
30
+ ## Outreach Copy
31
+
32
+ ```text
33
+ I built mcp-guard, an open-source local scanner for MCP and AI agent tool configs.
34
+
35
+ It checks for risky shell access, unpinned npx packages, broad filesystem permissions, exposed secrets, and remote MCP servers.
36
+
37
+ 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.
38
+ ```
39
+
40
+ ## First 20 Targets
41
+
42
+ - MCP server authors.
43
+ - AI automation agencies.
44
+ - Devtool startups using MCP.
45
+ - Teams publishing agent demos with real tool access.
46
+ - Founders discussing Cursor, Claude Code, Codex, or MCP on GitHub, X, LinkedIn, Hacker News, or Discord.
47
+
48
+ ## Validation Signals
49
+
50
+ Strong:
51
+
52
+ - user shares real redacted config;
53
+ - user asks for CI integration;
54
+ - user asks whether a finding is exploitable;
55
+ - user pays for remediation;
56
+ - team asks for monthly scanning.
57
+
58
+ Weak:
59
+
60
+ - stars without config samples;
61
+ - vague security interest;
62
+ - requests for a full dashboard before any audit;
63
+ - only free users with toy configs.
64
+
package/docs/roadmap.md ADDED
@@ -0,0 +1,35 @@
1
+ # Product Roadmap
2
+
3
+ `mcp-guard` should stay narrow: local-first MCP and AI agent tool security that produces actionable reports.
4
+
5
+ ## Now
6
+
7
+ - CLI config scanning.
8
+ - Text, Markdown, and redacted JSON output.
9
+ - Rules for shell wrappers, remote package runners, unpinned packages, broad filesystem access, secret-like env vars/headers, and remote MCP URLs.
10
+ - CI usage with `--fail-on`.
11
+
12
+ ## Next
13
+
14
+ 1. GitHub Action wrapper.
15
+ 2. HTML audit report.
16
+ 3. More MCP client discovery paths.
17
+ 4. Rule packs mapped to MCP security best practices.
18
+ 5. `mcp-guard audit` mode for client-ready reports.
19
+
20
+ ## Later
21
+
22
+ 1. Policy file: approved commands, packages, directories, and remote URLs.
23
+ 2. Baseline mode: accept known findings and fail only on new risks.
24
+ 3. SBOM/package metadata checks for MCP server packages.
25
+ 4. Local web report viewer.
26
+ 5. Hosted team dashboard only after repeated paid audit demand.
27
+
28
+ ## Product Principles
29
+
30
+ - Local-first by default.
31
+ - Findings must include a fix.
32
+ - Avoid noisy rules that do not change behavior.
33
+ - Prefer workflow integration over dashboards.
34
+ - Services first, SaaS later.
35
+
package/package.json CHANGED
@@ -1,8 +1,16 @@
1
1
  {
2
2
  "name": "agent-mcp-guard",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Open-source CLI scanner for risky MCP server and AI agent tool configuration.",
5
5
  "type": "module",
6
+ "homepage": "https://chaoyue0307.github.io/mcp-guard/",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/ChaoYue0307/mcp-guard.git"
10
+ },
11
+ "bugs": {
12
+ "url": "https://github.com/ChaoYue0307/mcp-guard/issues"
13
+ },
6
14
  "bin": {
7
15
  "mcp-guard": "bin/mcp-guard.js"
8
16
  },
@@ -33,7 +41,10 @@
33
41
  "src",
34
42
  "README.md",
35
43
  "LICENSE",
44
+ "SECURITY.md",
36
45
  "docs",
37
- "examples"
46
+ "examples",
47
+ "site/assets/readme-hero.svg",
48
+ "site/assets/brand-mark.svg"
38
49
  ]
39
50
  }
package/site/assets/brand-mark.svg ADDED
@@ -0,0 +1,6 @@
1
+ <svg width="96" height="96" viewBox="0 0 96 96" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="mcp-guard mark">
2
+ <rect width="96" height="96" rx="22" fill="#101312"/>
3
+ <path d="M29 48l19-24 19 24-19 24-19-24z" fill="#2dd4bf"/>
4
+ <path d="M52 23l28 25-28 25" stroke="#f8fafc" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
5
+ </svg>
6
+
package/site/assets/readme-hero.svg ADDED
@@ -0,0 +1,42 @@
1
+ <svg width="1200" height="420" viewBox="0 0 1200 420" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
2
+ <title id="title">mcp-guard scan report</title>
3
+ <desc id="desc">A dark product hero showing an MCP security scan report with critical, high, medium, and low findings.</desc>
4
+ <rect width="1200" height="420" rx="28" fill="#101312"/>
5
+ <path d="M0 0h1200v420H0z" fill="url(#grid)" opacity=".22"/>
6
+ <path d="M925 0h275v150L1015 94 925 132V0z" fill="#0f766e" opacity=".2"/>
7
+ <path d="M0 282l202 64 144-42v116H0V282z" fill="#7c2d12" opacity=".18"/>
8
+ <rect x="70" y="66" width="440" height="288" rx="22" fill="#f8fafc"/>
9
+ <rect x="96" y="94" width="78" height="78" rx="18" fill="#101312"/>
10
+ <path d="M121 133l15-19 15 19-15 19-15-19z" fill="#2dd4bf"/>
11
+ <path d="M139 112l23 21-23 21" stroke="#f8fafc" stroke-width="8" stroke-linecap="round" stroke-linejoin="round"/>
12
+ <text x="198" y="122" fill="#101312" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="800">mcp-guard</text>
13
+ <text x="198" y="154" fill="#475569" font-family="Inter, Arial, sans-serif" font-size="18">Local-first MCP config security scanner</text>
14
+ <rect x="96" y="196" width="360" height="16" rx="8" fill="#dbeafe"/>
15
+ <rect x="96" y="226" width="270" height="16" rx="8" fill="#ccfbf1"/>
16
+ <rect x="96" y="256" width="322" height="16" rx="8" fill="#ffedd5"/>
17
+ <rect x="96" y="296" width="152" height="40" rx="20" fill="#0f766e"/>
18
+ <text x="125" y="322" fill="#fff" font-family="Inter, Arial, sans-serif" font-size="16" font-weight="700">npm install</text>
19
+ <rect x="546" y="44" width="584" height="332" rx="24" fill="#0b0f0e" stroke="#33413d"/>
20
+ <rect x="546" y="44" width="584" height="54" rx="24" fill="#161d1b"/>
21
+ <circle cx="576" cy="71" r="6" fill="#ef4444"/>
22
+ <circle cx="598" cy="71" r="6" fill="#f59e0b"/>
23
+ <circle cx="620" cy="71" r="6" fill="#10b981"/>
24
+ <text x="652" y="77" fill="#94a3b8" font-family="Menlo, Consolas, monospace" font-size="14">mcp-guard scan --fail-on high</text>
25
+ <text x="586" y="134" fill="#e2e8f0" font-family="Menlo, Consolas, monospace" font-size="20" font-weight="700">scan report</text>
26
+ <text x="586" y="172" fill="#94a3b8" font-family="Menlo, Consolas, monospace" font-size="15">MCP servers: 3 Findings: 9 Risk score: 98</text>
27
+ <rect x="586" y="204" width="138" height="38" rx="12" fill="#7f1d1d"/>
28
+ <text x="610" y="229" fill="#fecaca" font-family="Inter, Arial, sans-serif" font-size="14" font-weight="800">2 critical</text>
29
+ <rect x="742" y="204" width="112" height="38" rx="12" fill="#7c2d12"/>
30
+ <text x="767" y="229" fill="#fed7aa" font-family="Inter, Arial, sans-serif" font-size="14" font-weight="800">5 high</text>
31
+ <rect x="872" y="204" width="124" height="38" rx="12" fill="#713f12"/>
32
+ <text x="897" y="229" fill="#fde68a" font-family="Inter, Arial, sans-serif" font-size="14" font-weight="800">2 medium</text>
33
+ <rect x="586" y="272" width="482" height="1" fill="#33413d"/>
34
+ <text x="586" y="306" fill="#fca5a5" font-family="Menlo, Consolas, monospace" font-size="15">MCP010 shell command executes inline script</text>
35
+ <text x="586" y="334" fill="#fdba74" font-family="Menlo, Consolas, monospace" font-size="15">MCP030 secret-like env var exposed</text>
36
+ <text x="586" y="362" fill="#fef3c7" font-family="Menlo, Consolas, monospace" font-size="15">MCP041 broad filesystem access</text>
37
+ <defs>
38
+ <pattern id="grid" width="38" height="38" patternUnits="userSpaceOnUse">
39
+ <path d="M38 0H0v38" stroke="#f8fafc" stroke-width="1"/>
40
+ </pattern>
41
+ </defs>
42
+ </svg>
package/src/cli.js CHANGED
@@ -4,7 +4,7 @@ import { scan } from "./scan.js";
4
4
  import { generateJsonReport, generateMarkdownReport, generateTextReport } from "./report.js";
5
5
  import { compareSeverity, severityRank } from "./severity.js";
6
6
 
7
- const VERSION = "0.1.0";
7
+ const VERSION = "0.1.1";
8
8
 
9
9
  export async function runCli(argv, io) {
10
10
  const args = argv.slice(2);