mcpguard-adk 0.3.1__tar.gz
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.
- mcpguard_adk-0.3.1/LICENSE +89 -0
- mcpguard_adk-0.3.1/PKG-INFO +324 -0
- mcpguard_adk-0.3.1/README.md +289 -0
- mcpguard_adk-0.3.1/mcpguard_adk/__init__.py +24 -0
- mcpguard_adk-0.3.1/mcpguard_adk/a2a/__init__.py +27 -0
- mcpguard_adk-0.3.1/mcpguard_adk/a2a/protocol.py +619 -0
- mcpguard_adk-0.3.1/mcpguard_adk/a2a/server.py +184 -0
- mcpguard_adk-0.3.1/mcpguard_adk/agent.py +303 -0
- mcpguard_adk-0.3.1/mcpguard_adk/agents/__init__.py +11 -0
- mcpguard_adk-0.3.1/mcpguard_adk/agents/cost_optimizer.py +78 -0
- mcpguard_adk-0.3.1/mcpguard_adk/agents/security_auditor.py +80 -0
- mcpguard_adk-0.3.1/mcpguard_adk/agents/voice_debrief.py +106 -0
- mcpguard_adk-0.3.1/mcpguard_adk/cli.py +271 -0
- mcpguard_adk-0.3.1/mcpguard_adk/cost_engine.py +278 -0
- mcpguard_adk-0.3.1/mcpguard_adk/github_pr_bot.py +279 -0
- mcpguard_adk-0.3.1/mcpguard_adk/llm_client.py +165 -0
- mcpguard_adk-0.3.1/mcpguard_adk/mcp_server.py +256 -0
- mcpguard_adk-0.3.1/mcpguard_adk/nodes/__init__.py +11 -0
- mcpguard_adk-0.3.1/mcpguard_adk/nodes/hitl_patch_emitter.py +267 -0
- mcpguard_adk-0.3.1/mcpguard_adk/nodes/prefilter.py +957 -0
- mcpguard_adk-0.3.1/mcpguard_adk/nodes/triage_router.py +103 -0
- mcpguard_adk-0.3.1/mcpguard_adk/sarif.py +80 -0
- mcpguard_adk-0.3.1/mcpguard_adk/schemas.py +107 -0
- mcpguard_adk-0.3.1/mcpguard_adk/telemetry/__init__.py +13 -0
- mcpguard_adk-0.3.1/mcpguard_adk/telemetry/otel.py +215 -0
- mcpguard_adk-0.3.1/mcpguard_adk/tui.py +763 -0
- mcpguard_adk-0.3.1/mcpguard_adk/web_studio.py +511 -0
- mcpguard_adk-0.3.1/mcpguard_adk.egg-info/PKG-INFO +324 -0
- mcpguard_adk-0.3.1/mcpguard_adk.egg-info/SOURCES.txt +37 -0
- mcpguard_adk-0.3.1/mcpguard_adk.egg-info/dependency_links.txt +1 -0
- mcpguard_adk-0.3.1/mcpguard_adk.egg-info/entry_points.txt +3 -0
- mcpguard_adk-0.3.1/mcpguard_adk.egg-info/requires.txt +13 -0
- mcpguard_adk-0.3.1/mcpguard_adk.egg-info/top_level.txt +1 -0
- mcpguard_adk-0.3.1/pyproject.toml +71 -0
- mcpguard_adk-0.3.1/setup.cfg +4 -0
- mcpguard_adk-0.3.1/tests/test_a2a_v1_protocol.py +125 -0
- mcpguard_adk-0.3.1/tests/test_cost_engineering.py +88 -0
- mcpguard_adk-0.3.1/tests/test_otel_and_eval_conformance.py +239 -0
- mcpguard_adk-0.3.1/tests/test_prefilter_and_workflow.py +111 -0
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity.
|
|
18
|
+
|
|
19
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
20
|
+
exercising permissions granted by this License.
|
|
21
|
+
|
|
22
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
23
|
+
including but not limited to software source code, documentation
|
|
24
|
+
source, and configuration files.
|
|
25
|
+
|
|
26
|
+
"Object" form shall mean any form resulting from mechanical
|
|
27
|
+
transformation or translation of a Source form, including but
|
|
28
|
+
not limited to compiled object code, generated documentation,
|
|
29
|
+
and conversions to other media types.
|
|
30
|
+
|
|
31
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
32
|
+
Object form, made available under the License, as indicated by a
|
|
33
|
+
copyright notice that is included in or attached to the work
|
|
34
|
+
(an example is provided in the Appendix below).
|
|
35
|
+
|
|
36
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
37
|
+
form, that is based on (or derived from) the Work and for which the
|
|
38
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
39
|
+
represent, as a whole, an original work of authorship.
|
|
40
|
+
|
|
41
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
42
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
43
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
44
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
45
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
46
|
+
Work and such Derivative Works in Source or Object form.
|
|
47
|
+
|
|
48
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
49
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
50
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
51
|
+
(except as stated in this section) patent license to make, have made,
|
|
52
|
+
use, offer to sell, sell, import, and otherwise transfer the Work.
|
|
53
|
+
|
|
54
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
55
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
56
|
+
modifications, and in Source or Object form, provided that You
|
|
57
|
+
meet the following conditions:
|
|
58
|
+
|
|
59
|
+
(a) You must give any other recipients of the Work or
|
|
60
|
+
Derivative Works a copy of this License; and
|
|
61
|
+
|
|
62
|
+
(b) You must cause any modified files to carry prominent notices
|
|
63
|
+
stating that You changed the files; and
|
|
64
|
+
|
|
65
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
66
|
+
that You distribute, all copyright, patent, trademark, and
|
|
67
|
+
attribution notices from the Source form of the Work.
|
|
68
|
+
|
|
69
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
70
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
71
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
72
|
+
this License, without any additional terms or conditions.
|
|
73
|
+
|
|
74
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
75
|
+
names, trademarks, service marks, or product names of the Licensor.
|
|
76
|
+
|
|
77
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
78
|
+
agreed to in writing, Licensor provides the Work on an "AS IS"
|
|
79
|
+
BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
|
|
80
|
+
|
|
81
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
82
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
83
|
+
shall any Contributor be liable to You for damages.
|
|
84
|
+
|
|
85
|
+
END OF TERMS AND CONDITIONS
|
|
86
|
+
|
|
87
|
+
Copyright 2026 MCPGuard-ADK Contributors
|
|
88
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
89
|
+
you may not use this file except in compliance with the License.
|
|
@@ -0,0 +1,324 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mcpguard-adk
|
|
3
|
+
Version: 0.3.1
|
|
4
|
+
Summary: Multi-agent MCP supply-chain, >200K token cost-cliff, and tool-trajectory auditor built on Google ADK 2.0, A2A Protocol v1.0, and OpenTelemetry.
|
|
5
|
+
Author: MCPGuard-ADK Contributors
|
|
6
|
+
License: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://github.com/Chitresh-Bhatia-264/MCPGuard-ADK
|
|
8
|
+
Project-URL: Repository, https://github.com/Chitresh-Bhatia-264/MCPGuard-ADK
|
|
9
|
+
Project-URL: Issues, https://github.com/Chitresh-Bhatia-264/MCPGuard-ADK/issues
|
|
10
|
+
Project-URL: CI, https://github.com/Chitresh-Bhatia-264/MCPGuard-ADK/actions
|
|
11
|
+
Keywords: google-adk,a2a-protocol,mcp-security,multi-agent-systems,opentelemetry,gemini,python,ai-agents
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Topic :: Security
|
|
19
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: pydantic>=2.7.0
|
|
24
|
+
Requires-Dist: cryptography>=42.0.0
|
|
25
|
+
Requires-Dist: opentelemetry-api>=1.25.0
|
|
26
|
+
Requires-Dist: opentelemetry-sdk>=1.25.0
|
|
27
|
+
Requires-Dist: google-genai>=1.0.0
|
|
28
|
+
Provides-Extra: adk
|
|
29
|
+
Requires-Dist: google-adk>=1.0.0; extra == "adk"
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: pytest>=8.0.0; extra == "dev"
|
|
32
|
+
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
|
|
33
|
+
Requires-Dist: ruff>=0.6.0; extra == "dev"
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
|
|
36
|
+
# MCPGuard-ADK
|
|
37
|
+
|
|
38
|
+
**Open-source multi-agent Model Context Protocol (MCP) supply-chain, secret-leak, >200K token cost-cliff, and tool-trajectory auditor engineered on Google Agent Development Kit (ADK) 2.0, Agent2Agent (A2A) Protocol v1.0, and OpenTelemetry.**
|
|
39
|
+
|
|
40
|
+
[](https://github.com/Chitresh-Bhatia-264/MCPGuard-ADK/actions)
|
|
41
|
+

|
|
42
|
+

|
|
43
|
+

|
|
44
|
+

|
|
45
|
+

|
|
46
|
+
|
|
47
|
+
```text
|
|
48
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
49
|
+
▄████▄ ███╗ ███╗ ██████╗██████╗ ██████╗ ██╗ ██╗ █████╗ ██████╗ ██████╗
|
|
50
|
+
██╔═══╝ ████╗ ████║██╔════╝██╔══██╗██╔════╝ ██║ ██║██╔══██╗██╔══██╗██╔══██╗
|
|
51
|
+
██║ ███╗ ██╔████╔██║██║ ██████╔╝██║ ███╗██║ ██║███████║██████╔╝██║ ██║
|
|
52
|
+
██║ ██║ ██║╚██╔╝██║██║ ██╔═══╝ ██║ ██║██║ ██║██╔══██║██╔══██╗██║ ██║
|
|
53
|
+
╚██████╔╝ ██║ ╚═╝ ██║╚██████╗██║ ╚██████╔╝╚██████╔╝██║ ██║██║ ██║██████╔╝
|
|
54
|
+
✦ ADK 2 ╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝
|
|
55
|
+
Google ADK 2.0 Hybrid Graph • A2A v1.0 Ed25519/JCS • Gemini FinOps • Cloud Trace OTLP v0.3.1
|
|
56
|
+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
57
|
+
|
|
58
|
+
╭─ ✦ 0-TOK AST ──────╮ ╭─ ◆ RISK ALERTS ────╮ ╭─ ● SCAN SPEND ─────╮ ╭─ ▸ A2A v1.0 JWS ───╮
|
|
59
|
+
│ 0/4 Clean │ │ 8 Findings │ │ $0.0000 Actual │ │ Ed25519 OK │
|
|
60
|
+
│ $0.00 (0 Tokens) │ │ 3 Crit • 4 High │ │ 0 Billed Tokens │ │ ID 853af5cf368 │
|
|
61
|
+
╰────────────────────╯ ╰────────────────────╯ ╰────────────────────╯ ╰────────────────────╯
|
|
62
|
+
|
|
63
|
+
╭── ◆ Security & >200K Cost-Cliff Alerts (Auto-Redacted Pinpoint View) ───── ACTION REQUIRED ──╮
|
|
64
|
+
│ 3. CRITICAL MCPG-SEC-003 ▸ vulnerable_mcp_config.json:11:41 │
|
|
65
|
+
│ WHAT LEAKED : GitHub Personal Access Token: GITHUB_PERSONAL_ACCESS_TOKEN = ghp_1234•••• │
|
|
66
|
+
│ WHERE (FILE): examples/vulnerable_mcp_config.json (Line 11, Col 41) │
|
|
67
|
+
│ ┌── Source Pinpoint ────────────────────────────────────────────────────────────────── │
|
|
68
|
+
│ │ 10 │ "env": { │
|
|
69
|
+
│ │ 11 │ "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_1234••••••••••••••••••••••••••••1 │
|
|
70
|
+
│ │ │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ │
|
|
71
|
+
│ │ 12 │ }, │
|
|
72
|
+
│ └───────────────────────────────────────────────────────────────────────────────────── │
|
|
73
|
+
│ ✔ FIX: Replace literal value with `${GITHUB_PERSONAL_ACCESS_TOKEN}` and load from `.env` │
|
|
74
|
+
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
75
|
+
|
|
76
|
+
╭── ✦ Google Cloud & ADK 2.0 Runtime Conformance Scorecard (5/5) ────────────── 5/5 PASSED ──╮
|
|
77
|
+
│ ✔ [VERIFIED] ADK 2.0 Hybrid Graph │ Stage 1 0-token AST ran (0/4 clean skipped); 6 spans │
|
|
78
|
+
│ ✔ [VERIFIED] Zero Context Bloat │ Sync McpToolset ['list_directory', 'read_file'] RO │
|
|
79
|
+
│ ✔ [VERIFIED] A2A v1.0 Ed25519 + JCS │ EdDSA valid + negative tamper test rejected │
|
|
80
|
+
│ ✔ [VERIFIED] Cloud Trace OTLP SDK │ EVENT_ONLY active; 6 W3C spans exported │
|
|
81
|
+
│ ✔ [VERIFIED] MCP Stdio & SARIF Gate │ Live JSON-RPC tools/list (3 tools) + SARIF 2.1.0 │
|
|
82
|
+
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## 30-Second Quickstart (`$0` Offline Scan — No API Key Required)
|
|
88
|
+
|
|
89
|
+
Run directly with **`uvx`** / **`pip`** on **Python 3.11+**, or install from source:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
# Option A: Zero-install one-liner via uvx / pip (once published on PyPI, or directly from GitHub)
|
|
93
|
+
uvx --from git+https://github.com/Chitresh-Bhatia-264/MCPGuard-ADK mcpguard scan .
|
|
94
|
+
# (After PyPI release: `pip install mcpguard-adk` or `uvx mcpguard-adk scan .`)
|
|
95
|
+
|
|
96
|
+
# Option B: Clone & run the built-in vulnerable examples + interactive shell
|
|
97
|
+
git clone https://github.com/Chitresh-Bhatia-264/MCPGuard-ADK.git
|
|
98
|
+
cd MCPGuard-ADK
|
|
99
|
+
pip install -e ".[dev]"
|
|
100
|
+
python -m mcpguard_adk.cli scan ./examples --live
|
|
101
|
+
python -m mcpguard_adk.cli shell
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Why MCPGuard-ADK?
|
|
107
|
+
|
|
108
|
+
Enterprise AI agent deployments hit two walls before production:
|
|
109
|
+
1. **Security / AppSec**: Over-broad MCP servers (`"/"` host mounts, unpinned `npx -y` execution, plaintext API keys in `mcp.json` or `.env`, prompt-injection payloads in tool metadata, and client-side XSS sinks).
|
|
110
|
+
2. **FinOps / Token Cost Cliffs**: Connecting `McpToolset` directly to a root orchestrator dumps 20+ tool schemas and raw file reads into global context—pushing uncompacted loops across **Gemini 3.1 Pro's 200,000-token pricing cliff** (`$2.00` $\rightarrow$ `$4.00`/1M input, `$12.00` $\rightarrow$ `$18.00`/1M output).
|
|
111
|
+
|
|
112
|
+
**MCPGuard-ADK** solves both in a single CI/CD gate using a **6-stage Google ADK 2.0 Hybrid Graph**:
|
|
113
|
+
|
|
114
|
+
```mermaid
|
|
115
|
+
flowchart TD
|
|
116
|
+
A["Stage 1: Polyglot AST, TOML, .env & Manifest Pre-Filter<br/>(Deterministic Code Node • 0 LLM Tokens • <200ms / 1K files)"] -->|Clean / Unchanged| Z["Short-Circuit ($0.00)"]
|
|
117
|
+
A -->|Anomalies Detected| B["Stage 2: Diff & Risk Triage Router<br/>(Gemini 3.1 Flash-Lite • $0.25/$1.50 per 1M)"]
|
|
118
|
+
B -->|SECURITY| C["Stage 3: Security & MCP Auditor<br/>(AgentTool + Sync McpToolset [RO] • Gemini 3.8 Flash / 3.1 Pro)"]
|
|
119
|
+
B -->|COST_CLIFF / TRAJECTORY_DRIFT| D["Stage 4: Cost & Trajectory Optimizer<br/>(AgentTool Isolated Context • Gemini 3.8 Flash)"]
|
|
120
|
+
C --> E["Stage 5: HITL Gate & Hardened Patch Emitter<br/>(Workspace-Relative difflib Patch + SARIF v2.1.0 + .test.json)"]
|
|
121
|
+
D --> E
|
|
122
|
+
E -.->|--live flag| F["Stage 6: Live Voice Incident Debrief<br/>(runner.run_live() + LiveRequestQueue Mid-Sentence Barge-In)"]
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## Built-In Detection Rules (Stage 1 Zero-Token Engine)
|
|
128
|
+
|
|
129
|
+
| Rule ID | Severity | Target Files | Vulnerability / Anti-Pattern Detected |
|
|
130
|
+
| :--- | :--- | :--- | :--- |
|
|
131
|
+
| `MCPG-SEC-001` | `CRITICAL` | `mcp.json`, `claude_desktop_config.json` | Over-broad host filesystem scope (`"/"`, `"~"`, `"C:\"`, `".."`, `"/etc"`). |
|
|
132
|
+
| `MCPG-SEC-002` | `HIGH` | `mcp.json`, `*mcp*.json` | Unpinned `npx -y` / `uvx` / `bunx` remote package execution without version lock. |
|
|
133
|
+
| `MCPG-SEC-003` | `CRITICAL` | `mcp.json`, `.env*`, `.py`, `.ts`, `.tsx`, `.js` | Leaked credentials (`AIza...` Gemini/GCP, `ghp_...` GitHub, `sk-...` OpenAI/Anthropic, `AKIA...` AWS, `sk_live_...` Stripe, DB URIs) with screen-safe masking. |
|
|
134
|
+
| `MCPG-SEC-004` | `CRITICAL` / `HIGH` | `mcp.json`, `.tsx`, `.jsx`, `.ts`, `.js` | Indirect prompt-injection payloads in MCP metadata & unescaped `dangerouslySetInnerHTML` / `eval()` sinks. |
|
|
135
|
+
| `MCPG-SEC-005` | `MEDIUM` | `mcp.json` | Missing read-only `tool_filter` on filesystem/shell MCP servers. |
|
|
136
|
+
| `MCPG-ADK-001` | `HIGH` | `.py` (Python AST) | Asynchronous runtime initialization of `McpToolset` inside `async def` (violates ADK session recovery rule). |
|
|
137
|
+
| `MCPG-ADK-002` | `HIGH` | `.py` (Python AST) | `McpToolset` instantiated without explicit least-privilege `tool_filter`. |
|
|
138
|
+
| `MCPG-ADK-003` | `MEDIUM` | `.py` (Python AST) | `McpToolset` bound directly to root agent instead of isolated `AgentTool` sub-agent. |
|
|
139
|
+
| `MCPG-ADK-004` | `HIGH` | `.py` (Python AST) | `LlmAgent` binding `>20` tools directly (schema bloat & tool-selection degradation). |
|
|
140
|
+
| `MCPG-COST-001` | `HIGH` | `.py` (Python AST) | Uncompacted `for`/`while` loops on Pro-tier models liable to cross the `>200K` token 2x pricing cliff. |
|
|
141
|
+
| `MCPG-PKG-001..003` | `HIGH` / `MEDIUM` | `package.json`, `pyproject.toml`, `go.mod` | Wildcard (`*`, `latest`), insecure `http://`, or local `replace => ../` supply-chain overrides. |
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Late-2026 Gemini Rate-Card & Cost-Cliff Benchmark
|
|
146
|
+
|
|
147
|
+
| Architecture Pattern | Assumed Workload per PR Audit | Published Rate Card Applied (per 1M Tokens) | Transparent Per-PR Math | Cost per 1,000 PR Audits |
|
|
148
|
+
| :--- | :--- | :--- | :--- | :--- |
|
|
149
|
+
| **Naive Single-Agent Loop (>200K Cliff)** | Uncompacted context reaches 250K in, 8K out on Gemini 3.1 Pro Preview | `$4.00` input / `$18.00` output (>200K tier) | `(0.25 * $4.00) + (0.008 * $18.00) = $1.144` | **`$1,144.00`** |
|
|
150
|
+
| **Naive Single-Agent Loop (<=200K)** | Compaction holds context at 120K in, 8K out on Gemini 3.1 Pro Preview | `$2.00` input / `$12.00` output (<=200K tier) | `(0.12 * $2.00) + (0.008 * $12.00) = $0.336` | **`$336.00`** |
|
|
151
|
+
| **MCPGuard-ADK Tiered Hybrid (2026 Promo)** | Stage 1 skips clean files (0 tokens); 3.1 Flash-Lite triage (40K in / 2K out); 3.8 Flash audit (25K in / 4K out); 3.1 Pro escalation on 10% of PRs | 3.1 Flash-Lite: `$0.25`/`$1.50`; 3.8 Flash: `$0.75`/`$3.75`; 3.1 Pro: `$2.00`/`$12.00` | `$0.013 + $0.03375 + $0.0054 = $0.05215` | **`$52.15`** *(95.4% lower)* |
|
|
152
|
+
| **MCPGuard-ADK Async Batch (2027 Post-Promo)** | Overnight Batch API (50% off Standard; 3.8 Flash at `$1.50`/`$7.50` list rate) | Batch: 3.1 Flash-Lite `$0.125`/`$0.75`; 3.8 Flash `$0.75`/`$3.75`; 3.1 Pro `$1.00`/`$6.00` | `$0.0065 + $0.03375 + $0.0027 = $0.04295` | **`$42.95`** |
|
|
153
|
+
|
|
154
|
+
Reproduce these calculations via CLI:
|
|
155
|
+
```bash
|
|
156
|
+
python -m mcpguard_adk.cli cost-sim --prs 1000
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
> **Measured vs. Simulated Spend:** Offline Stage 1 AST/manifest scans consume **`0` billed LLM tokens (`$0.0000` actual)**—including across all `12,372` files in the 10-repository public benchmark below. When `GEMINI_API_KEY` (or `GOOGLE_API_KEY`) is set, Stages 2–4 record exact live `prompt_token_count`, `candidates_token_count`, and `thoughts_token_count` from `google-genai` `usage_metadata` and compute actual USD spend right beside the `SIMULATED` 1,000-PR rate-card model.
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Empirical Benchmark: 10 Public MCP & Google ADK Repositories vs. Gitleaks
|
|
164
|
+
|
|
165
|
+
We ran **MCPGuard-ADK v0.3.1** (`Stage 1` deterministic engine) side-by-side with **Gitleaks v8.30.1** (`gitleaks detect --no-git`) across **10 public MCP and Google ADK repositories (`12,372` non-test source & config files)**:
|
|
166
|
+
|
|
167
|
+
**Summary:** **`10` repos scanned (`12,372` files) • `23` findings reported • `18` real issues (`78.3%` precision) • `5` false positives**
|
|
168
|
+
|
|
169
|
+
| Public Repository | Commit | Files Scanned | MCPGuard Reported | Real Issues (TP) | False Alarms (FP) | Gitleaks v8.30.1 Alerts | What MCPGuard Caught (Manual Audit Notes) |
|
|
170
|
+
| :--- | :--- | ---: | ---: | ---: | ---: | ---: | :--- |
|
|
171
|
+
| [`google/adk-python`](https://github.com/google/adk-python) | `90c3a29` | 2,034 | **16** | **15** | **1** | 13 *(test/mock keys)* | **15 TP**: `9` sample agents instantiate `McpToolset` without `tool_filter` (`MCPG-ADK-002`); `6` attach `McpToolset` directly to root `LlmAgent` without `AgentTool` isolation (`MCPG-ADK-003`). **1 FP**: `api_registry.py:193` helper factory returning `McpToolset`. |
|
|
172
|
+
| [`mcp-use/mcp-use`](https://github.com/mcp-use/mcp-use) | `362b898` | 1,994 | **1** | **1** | **0** | 16 *(public PostHog/test keys)* | **1 TP**: `airbnb_mcp.json:5` runs unpinned `npx -y @openbnb/mcp-server-airbnb` (`MCPG-SEC-002`). |
|
|
173
|
+
| [`idosal/git-mcp`](https://github.com/idosal/git-mcp) | `c487a29` | 165 | **2** | **2** | **0** | 0 | **2 TP**: `app/routes/_index.tsx:618,624` pass unescaped string `.replace()` HTML into `dangerouslySetInnerHTML` (`MCPG-SEC-004`, low exploitability with static props). |
|
|
174
|
+
| [`jlowin/fastmcp`](https://github.com/jlowin/fastmcp) | `10083f7` | 1,402 | **2** | **0** | **2** | 0 | **2 FP**: `examples/memory.py:40,300` hardcoded `postgresql://postgres:postgres@localhost:54320` local Docker dev DSNs (`MCPG-SEC-003`). |
|
|
175
|
+
| [`modelcontextprotocol/python-sdk`](https://github.com/modelcontextprotocol/python-sdk) | `77001c9` | 1,441 | **2** | **0** | **2** | 4 *(example/test keys)* | **2 FP**: `examples/mcpserver/memory.py:41,285` local `postgres:postgres@localhost:54320` Docker dev DSNs (`MCPG-SEC-003`). |
|
|
176
|
+
| [`modelcontextprotocol/servers`](https://github.com/modelcontextprotocol/servers) | `e1dc4b1` | 283 | **0** | **0** | **0** | 3 *(unit test tokens)* | Clean (`monorepo` workspace `"*"` sibling links accurately ignored). |
|
|
177
|
+
| [`modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector) | `488c30d` | 1,682 | **0** | **0** | **0** | 11 *(Storybook/test tokens)* | Clean. |
|
|
178
|
+
| [`evalstate/fast-agent`](https://github.com/evalstate/fast-agent) | `fed14e0` | 1,883 | **0** | **0** | **0** | 34 *(benchmark JSON blobs)* | Clean. |
|
|
179
|
+
| [`lastmile-ai/mcp-agent`](https://github.com/lastmile-ai/mcp-agent) | `f62d849` | 1,021 | **0** | **0** | **0** | 15 *(README/comment examples)* | Clean. |
|
|
180
|
+
| [`cloudflare/mcp-server-cloudflare`](https://github.com/cloudflare/mcp-server-cloudflare) | `a21972e` | 467 | **0** | **0** | **0** | 0 | Clean. |
|
|
181
|
+
| **Total (10 Public Repos)** | — | **12,372** | **23** | **18** | **5** | **96** | **Reproduce:** `python scripts/benchmark_public_repos.py` |
|
|
182
|
+
|
|
183
|
+
### Why Use MCPGuard-ADK Alongside Gitleaks?
|
|
184
|
+
|
|
185
|
+
| Risk Class | `gitleaks` (Secret Scanner) | `MCPGuard-ADK` (MCP + ADK + FinOps Auditor) |
|
|
186
|
+
| :--- | :---: | :---: |
|
|
187
|
+
| Git commit history & generic high-entropy secrets | ✅ Primary strength | Provider-targeted (`AIza`, `ghp_`, `sk-`, `AKIA`, `sk_live_`, DB URIs) |
|
|
188
|
+
| Over-broad MCP host mounts (`"/"`, `"~"`, `"C:\"`, `"/etc"`) | ❌ Misses | ✅ `MCPG-SEC-001` (`1-click` `./workspace` PR suggestion) |
|
|
189
|
+
| Unpinned `npx -y` / `uvx` / `bunx` remote MCP servers | ❌ Misses | ✅ `MCPG-SEC-002` (caught in `mcp-use/mcp-use`) |
|
|
190
|
+
| Prompt-injection in MCP metadata & `dangerouslySetInnerHTML` | ❌ Misses | ✅ `MCPG-SEC-004` (caught in `idosal/git-mcp`) |
|
|
191
|
+
| Async `McpToolset` init & missing `tool_filter` / `AgentTool` isolation | ❌ Misses | ✅ `MCPG-ADK-001..004` (caught `15` in `google/adk-python`) |
|
|
192
|
+
| Uncompacted Gemini Pro loops crossing the `>200K` 2x token cliff | ❌ Misses | ✅ `MCPG-COST-001` + live/simulated rate-card FinOps gate |
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## IDE Integration (MCP Stdio Server) & A2A Protocol v1.0
|
|
197
|
+
|
|
198
|
+
### 1. Mount Inside Cursor, Claude Desktop, VS Code, or Gemini CLI (`mcp.json`)
|
|
199
|
+
```json
|
|
200
|
+
{
|
|
201
|
+
"mcpServers": {
|
|
202
|
+
"mcpguard-adk": {
|
|
203
|
+
"command": "python",
|
|
204
|
+
"args": ["-m", "mcpguard_adk.cli", "serve-mcp"]
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
Exposes `mcpguard_audit_repository`, `mcpguard_simulate_cost_cliff`, and `mcpguard_verify_agent_card` over JSON-RPC 2.0 stdio (supporting both newline-delimited and `Content-Length` framing).
|
|
210
|
+
|
|
211
|
+
### 2. 1-Click GitHub Pull Request Bot (Composite GitHub Action)
|
|
212
|
+
Add `.github/workflows/mcpguard.yml` to any repository—whenever a teammate modifies `mcp.json`, `.env`, React/TS, or an ADK agent, **MCPGuard-ADK** posts **1-click inline `suggestion` commits** and blocks critical leaks:
|
|
213
|
+
|
|
214
|
+
```yaml
|
|
215
|
+
name: MCPGuard-ADK PR Bot
|
|
216
|
+
on: [pull_request]
|
|
217
|
+
permissions:
|
|
218
|
+
contents: read
|
|
219
|
+
pull-requests: write
|
|
220
|
+
issues: write
|
|
221
|
+
jobs:
|
|
222
|
+
audit:
|
|
223
|
+
runs-on: ubuntu-latest
|
|
224
|
+
steps:
|
|
225
|
+
- uses: actions/checkout@v4
|
|
226
|
+
with:
|
|
227
|
+
fetch-depth: 0
|
|
228
|
+
- uses: Chitresh-Bhatia-264/MCPGuard-ADK@v0.3.1
|
|
229
|
+
with:
|
|
230
|
+
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
231
|
+
fail-on: "critical"
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
#### Live GitHub Actions PR Verification Proof
|
|
235
|
+
|
|
236
|
+
**A. Inline PR Review Table + Suggested Fix (`"/"` $\rightarrow$ `"./workspace"`):**
|
|
237
|
+

|
|
238
|
+
|
|
239
|
+
**B. Failing Check (`exit 2`) Flagging a Vulnerable MCP PR:**
|
|
240
|
+

|
|
241
|
+
|
|
242
|
+
**C. Clean PR Passing All Checks (`0` Billed LLM Tokens, `$0.00`):**
|
|
243
|
+

|
|
244
|
+
|
|
245
|
+
### 3. Cross-Framework A2A Protocol v1.0 Server (`Ed25519` + `RFC 8785 JCS`)
|
|
246
|
+
```bash
|
|
247
|
+
# Start HTTP+JSON and Server-Sent Events (SSE) A2A v1.0 endpoint
|
|
248
|
+
python -m mcpguard_adk.cli serve-a2a --host 127.0.0.1 --port 8080
|
|
249
|
+
|
|
250
|
+
# Inspect & cryptographically verify the EdDSA-signed AgentCard + RFC 8037 OKP JWKS
|
|
251
|
+
python -m mcpguard_adk.cli agent-card --jwks
|
|
252
|
+
```
|
|
253
|
+
- Publishes `GET /.well-known/agent-card.json` signed with asymmetric **Ed25519 (`EdDSA`, RFC 8037)** over **RFC 8785 JSON Canonicalization Scheme (JCS)** and public keys at `GET /.well-known/jwks.json`.
|
|
254
|
+
- Streams `TaskStatusUpdateEvent` and chunked `TaskArtifactUpdateEvent` (`append` & `lastChunk`) using unified A2A v1.0 `Part` member `oneof` payloads.
|
|
255
|
+
- Protects `TaskPushNotificationConfig` webhooks against private-IP/cloud-metadata SSRF (`169.254.169.254`, `metadata.google.internal`) and JWT `jti` replay attacks.
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## CLI Command Reference & CI/CD Gating
|
|
260
|
+
|
|
261
|
+
```bash
|
|
262
|
+
# Interactive slash-command shell (/scan, /react, /voice, /patch, /a2a, /quit)
|
|
263
|
+
python -m mcpguard_adk.cli shell
|
|
264
|
+
|
|
265
|
+
# Full scan + simulated 1,000-PR FinOps model + approve HITL gate + SARIF v2.1.0 + OTLP traces
|
|
266
|
+
python -m mcpguard_adk.cli scan ./examples --live --finops-sim --approve-patches \
|
|
267
|
+
--emit-sarif reports/mcpguard.sarif.json \
|
|
268
|
+
--export-otel reports/otel_traces.json
|
|
269
|
+
|
|
270
|
+
# Pull-Request CI Gate (scan only git-modified files; exit code 2 on CRITICAL/HIGH)
|
|
271
|
+
python -m mcpguard_adk.cli scan . --git-diff --fail-on high
|
|
272
|
+
|
|
273
|
+
# Generate or post 1-Click GitHub PR Inline Review Suggestions (fork-PR HTTP 403 safe)
|
|
274
|
+
python -m mcpguard_adk.cli pr-review . --git-diff --fail-on critical
|
|
275
|
+
|
|
276
|
+
# Launch interactive browser visualizer (ADK 2.0 Graph + >200K Cliff Sliders)
|
|
277
|
+
python -m mcpguard_adk.cli ui ./examples
|
|
278
|
+
|
|
279
|
+
# Run the 24-test verification suite (AST, FinOps, fork-PR 403, PR git-diff, Ed25519, MCP, OTel)
|
|
280
|
+
python -m pytest tests -v
|
|
281
|
+
|
|
282
|
+
# Reproduce the 10-repository public MCP & Google ADK benchmark (+ optional Gitleaks comparison)
|
|
283
|
+
python scripts/benchmark_public_repos.py
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
## Repository Structure
|
|
289
|
+
|
|
290
|
+
```text
|
|
291
|
+
MCPGuard-ADK/
|
|
292
|
+
├── mcpguard_adk/
|
|
293
|
+
│ ├── agent.py # ADK 2.0 Hybrid Graph, sync McpToolset, AgentTool & native ADK bridge
|
|
294
|
+
│ ├── cli.py # CLI entrypoints (scan, shell, serve-mcp, serve-a2a, ui, agent-card, cost-sim)
|
|
295
|
+
│ ├── cost_engine.py # Late-2026 Gemini rate-card, >200K Pro cliff & cache storage ROI math
|
|
296
|
+
│ ├── llm_client.py # Official google-genai SDK client with 0-cost offline fallback
|
|
297
|
+
│ ├── mcp_server.py # Spec-compliant JSON-RPC 2.0 MCP stdio server
|
|
298
|
+
│ ├── sarif.py # SARIF v2.1.0 exporter for GitHub Advanced Security
|
|
299
|
+
│ ├── tui.py # 24-bit TrueColor terminal dashboard, secret redaction & REPL shell
|
|
300
|
+
│ ├── web_studio.py # Interactive browser graph & FinOps studio
|
|
301
|
+
│ ├── a2a/ # A2A v1.0 Ed25519/JCS signer, JWKS verifier, SSE & SSRF/jti guards
|
|
302
|
+
│ ├── agents/ # Security auditor, FinOps optimizer & Live Voice barge-in debrief
|
|
303
|
+
│ ├── nodes/ # Stage 1 AST/TOML/.env pre-filter, Stage 2 router & Stage 5 difflib patcher
|
|
304
|
+
│ └── telemetry/ # Official OpenTelemetry SDK W3C tracer & OTLP/JSON exporter (EVENT_ONLY)
|
|
305
|
+
├── examples/ # Deliberately vulnerable MCP config & uncompacted Pro loop for testing
|
|
306
|
+
├── scripts/ # Reproducible 10-repo public MCP & ADK benchmark runner
|
|
307
|
+
├── evals/ # ADK .test.json and multi-turn .evalset.json conformance suites
|
|
308
|
+
├── tests/ # 24 automated pytest suites
|
|
309
|
+
├── Dockerfile # Production container for Google Cloud Run
|
|
310
|
+
└── cloudbuild.yaml # Automated Google Cloud Build CI/CD pipeline
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
---
|
|
314
|
+
|
|
315
|
+
<img width="1266" height="256" alt="image" src="https://github.com/user-attachments/assets/a4a1a686-225c-49a9-8d8e-cb2633d88409" />
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
## License & Contributing
|
|
319
|
+
|
|
320
|
+
- **License**: [Apache License 2.0](LICENSE)
|
|
321
|
+
- **Contributing & Good First Issues**: [`CONTRIBUTING.md`](CONTRIBUTING.md) • [`.github/ISSUE_TEMPLATE/good_first_issue.md`](.github/ISSUE_TEMPLATE/good_first_issue.md)
|
|
322
|
+
- **AI Code Editor Index**: [`llms.txt`](llms.txt)
|
|
323
|
+
|
|
324
|
+
*If MCPGuard-ADK caught a misconfiguration or saved token spend, a star helps others discover it.*
|