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.
Files changed (39) hide show
  1. mcpguard_adk-0.3.1/LICENSE +89 -0
  2. mcpguard_adk-0.3.1/PKG-INFO +324 -0
  3. mcpguard_adk-0.3.1/README.md +289 -0
  4. mcpguard_adk-0.3.1/mcpguard_adk/__init__.py +24 -0
  5. mcpguard_adk-0.3.1/mcpguard_adk/a2a/__init__.py +27 -0
  6. mcpguard_adk-0.3.1/mcpguard_adk/a2a/protocol.py +619 -0
  7. mcpguard_adk-0.3.1/mcpguard_adk/a2a/server.py +184 -0
  8. mcpguard_adk-0.3.1/mcpguard_adk/agent.py +303 -0
  9. mcpguard_adk-0.3.1/mcpguard_adk/agents/__init__.py +11 -0
  10. mcpguard_adk-0.3.1/mcpguard_adk/agents/cost_optimizer.py +78 -0
  11. mcpguard_adk-0.3.1/mcpguard_adk/agents/security_auditor.py +80 -0
  12. mcpguard_adk-0.3.1/mcpguard_adk/agents/voice_debrief.py +106 -0
  13. mcpguard_adk-0.3.1/mcpguard_adk/cli.py +271 -0
  14. mcpguard_adk-0.3.1/mcpguard_adk/cost_engine.py +278 -0
  15. mcpguard_adk-0.3.1/mcpguard_adk/github_pr_bot.py +279 -0
  16. mcpguard_adk-0.3.1/mcpguard_adk/llm_client.py +165 -0
  17. mcpguard_adk-0.3.1/mcpguard_adk/mcp_server.py +256 -0
  18. mcpguard_adk-0.3.1/mcpguard_adk/nodes/__init__.py +11 -0
  19. mcpguard_adk-0.3.1/mcpguard_adk/nodes/hitl_patch_emitter.py +267 -0
  20. mcpguard_adk-0.3.1/mcpguard_adk/nodes/prefilter.py +957 -0
  21. mcpguard_adk-0.3.1/mcpguard_adk/nodes/triage_router.py +103 -0
  22. mcpguard_adk-0.3.1/mcpguard_adk/sarif.py +80 -0
  23. mcpguard_adk-0.3.1/mcpguard_adk/schemas.py +107 -0
  24. mcpguard_adk-0.3.1/mcpguard_adk/telemetry/__init__.py +13 -0
  25. mcpguard_adk-0.3.1/mcpguard_adk/telemetry/otel.py +215 -0
  26. mcpguard_adk-0.3.1/mcpguard_adk/tui.py +763 -0
  27. mcpguard_adk-0.3.1/mcpguard_adk/web_studio.py +511 -0
  28. mcpguard_adk-0.3.1/mcpguard_adk.egg-info/PKG-INFO +324 -0
  29. mcpguard_adk-0.3.1/mcpguard_adk.egg-info/SOURCES.txt +37 -0
  30. mcpguard_adk-0.3.1/mcpguard_adk.egg-info/dependency_links.txt +1 -0
  31. mcpguard_adk-0.3.1/mcpguard_adk.egg-info/entry_points.txt +3 -0
  32. mcpguard_adk-0.3.1/mcpguard_adk.egg-info/requires.txt +13 -0
  33. mcpguard_adk-0.3.1/mcpguard_adk.egg-info/top_level.txt +1 -0
  34. mcpguard_adk-0.3.1/pyproject.toml +71 -0
  35. mcpguard_adk-0.3.1/setup.cfg +4 -0
  36. mcpguard_adk-0.3.1/tests/test_a2a_v1_protocol.py +125 -0
  37. mcpguard_adk-0.3.1/tests/test_cost_engineering.py +88 -0
  38. mcpguard_adk-0.3.1/tests/test_otel_and_eval_conformance.py +239 -0
  39. 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
+ [![CI & Conformance](https://github.com/Chitresh-Bhatia-264/MCPGuard-ADK/actions/workflows/ci.yml/badge.svg)](https://github.com/Chitresh-Bhatia-264/MCPGuard-ADK/actions)
41
+ ![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)
42
+ ![Python: 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg)
43
+ ![Google ADK: v2.0](https://img.shields.io/badge/Google_ADK-v2.0-4285F4.svg)
44
+ ![A2A Protocol: v1.0 Ed25519](https://img.shields.io/badge/A2A_Protocol-v1.0_Ed25519-EA4335.svg)
45
+ ![OpenTelemetry: OTLP v1/traces](https://img.shields.io/badge/OpenTelemetry-OTLP_v1%2Ftraces-34A853.svg)
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
+ ![MCPGuard-ADK PR Bot Inline Suggestion](https://raw.githubusercontent.com/Chitresh-Bhatia-264/MCPGuard-ADK/main/docs/assets/pr_bot_inline_suggestion.jpg)
238
+
239
+ **B. Failing Check (`exit 2`) Flagging a Vulnerable MCP PR:**
240
+ ![MCPGuard-ADK Failing Check on Vulnerable PR](https://raw.githubusercontent.com/Chitresh-Bhatia-264/MCPGuard-ADK/main/docs/assets/pr_bot_failing_check.png)
241
+
242
+ **C. Clean PR Passing All Checks (`0` Billed LLM Tokens, `$0.00`):**
243
+ ![MCPGuard-ADK Clean PR Passing Checks](https://raw.githubusercontent.com/Chitresh-Bhatia-264/MCPGuard-ADK/main/docs/assets/pr_bot_clean_pass.jpg)
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.*