mcp2agy
by uziii2208
README.md
<div align="center">
### Model Context Protocol · Multi-Agent 0day Research & Audit Pipeline
[](https://antigravity.google)
[](#)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](LICENSE.md)
[](#)
</div>
<br/>
> **mcp2agy** is an MCP-native, multi-agent security audit engine engineered for the **Google Antigravity (AGY)** ecosystem. It coordinates specialized subagents across the complete 0day research lifecycle: static AST taint analysis, 7-class confounder elimination, deterministic Proof-of-Concept verification (≤60s triggers), multi-chain exploit synthesis, publication-ready security reporting, and atomic code remediation.
---
## Key Capabilities (v3.1.0 Resilient Architecture)
- **Strict Path Safety & Directory Containment**: Validates all paths through `assertSafePath()`, preventing root directory escapes, path traversal (`..`), and symlink attacks.
- **Direct Object Tool Interfaces**: MCP tools accept native JavaScript objects and arrays directly, eliminating JSON string escaping errors and handler parsing crashes.
- **Automated Run Artifacts & Compact Summaries**: Saves all heavy artifacts (`candidates.json`, `verified_findings.json`, `exploit_chains.json`, `report.md`, `fixes.diff`) to `mcp2agy_workspace/runs/<runId>/`, returning clean executive summaries to prevent LLM context explosion.
- **Confidence-Calibrated Scanning & Noise Reduction**: Categorizes candidate findings into `high`, `medium`, and `low` confidence while automatically ignoring build/test noise (`node_modules`, `dist`, `tests/`, `fixtures/`).
- **Strict Verifier Gating**: Enforces formal reachability checks and confounder clearance before confirming findings, preventing false positives from propagating downstream.
- **Resilient Phase Progression**: Tracks pipeline execution across 5 distinct phases with per-candidate error isolation and detailed `pipeline_state.json` logs.
- **Contextual Fix Generation**: Patches are generated directly from actual file code snippets and verified candidate line ranges, cross-checked with known call sites.
---
## Architecture & Agent Pipeline
```css
┌────────────────────────────────────────┐
│ Master Audit Orchestrator │
│ (/audit) │
└───────────────────┬────────────────────┘
│
┌──────────────────┬─────────────────┴──────────────┬──────────────────┐
│ Phase 1: SCAN │ Phase 2: VERIFY │ Phase 2.5: CHAIN │ Phase 3: REPORT & FIX
▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Scanner │──►│ Verifier │───────────────►│ Chainer │──►│ Reporter & │
│ Subagent │ │ (Parallel) │ │ Synthesis │ │ Fixer Agents │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
│ │ │ │
[Gate 1: AST] [Gate 2: PoC] [Compound CVSS] [Gate 4: Diff]
```
### [+] Core Subagents & Modules
| Subagent | Role Identifier | Primary Responsibility | Input | Output |
|:---|:---|:---|:---|:---|
| **Orchestrator** | `mcp2agy-audit` | Workflow management, gate checks, agent delegation | Target directory | `report.md`, `fixes.diff` |
| **Scanner** | `mcp2agy-scanner-agent` | Static AST triage, dangerous sink grep, candidate generation | Physical source files | `candidates.yaml` |
| **Verifier** | `mcp2agy-verifier-agent` | 7-class confounder clearance, reachability trace, MTS PoC | `candidates.yaml` | `verified_findings.yaml` |
| **Chainer** | `chain_findings` | Multi-primitive correlation, compound CVSS calibration | `verified_findings.yaml` | `exploit_chains.json` |
| **Reporter** | `mcp2agy-reporter-agent` | Publication-ready advisories (Mode A/B/C), root cause breakdown | `exploit_chains.json` | `report.md`, `advisories/` |
| **Fixer** | `mcp2agy-fixer-agent` | 16 CWE grounded patches, multi-site call site fixes, unit tests | `verified_findings.yaml` | `fixes.diff`, `tests/` |
---
## Slash Commands Matrix
| Command | Subsystem | Description | Example Usage |
|:---|:---|:---|:---|
| `/audit <path>` | `Full Pipeline` | Orchestrates Scanner → Verifier → Chainer → Reporter → Fixer | `/audit src/` |
| `/scan <path>` | `Scanner` | Static 0day AST analysis producing normalized candidate records | `/scan internal/` |
| `/verify <target>` | `Verifier` | Rigorous PoC verification (≤60s reproducer) & CVSS calibration | `/verify CAND-001` |
| `/report [mode]` | `Reporter` | Composes Mode A internal reports & Mode B GHSA advisories | `/report mode_b` |
| `/fix [finding]` | `Fixer` | Generates minimal atomic patches (`fixes.diff`) & unit test harnesses | `/fix CAND-001` |
| `/status` | `Monitor` | Inspects active subagents, host OS context, and workspace inventory | `/status` |
| `/docs` | `Documentation` | Interactive documentation hub and comprehensive tool guide | `/docs` |
| `/recon <target>` | `Recon Squad` | Concurrent OSINT, port scanning, and cloud asset mapping | `/recon target.com` |
| `/exploit <app>` | `Exploit Squad` | Pwntools ROP generation, web payload weaponization | `/exploit binary.elf` |
| `/reverse <bin>` | `Reverse Squad` | Static decompilation (Ghidra), dynamic Frida hooking | `/reverse app.bin` |
| `/forge <type>` | `Tool Forge` | AFL++/LibFuzzer harness generation, custom scanners, Sigma rules | `/forge fuzzer` |
| `/ctf <chal>` | `CTF Squad` | Autonomous multi-category challenge solving (pwn, rev, web, crypto) | `/ctf chal.zip` |
| `/swarm <target>` | `Swarm Mesh` | Launches synchronized multi-agent offensive mesh | `/swarm app/` |
---
## Native MCP Tools — 15 Tools
```
┌──────────────────────────────────────────────────────────────────────────────────┐
│ Native MCP Tools (15 Tools) │
├──────────────────────┬──────────────────────────┬────────────────────────────────┤
│ Target Profiling │ Static Analysis │ Verification & PoC │
│ • detect_platform │ • analyze_code │ • check_reachability │
│ • profile_target │ • scan_file │ • verify_finding │
│ │ • get_patterns │ • generate_poc │
│ │ │ • calculate_cvss │
├──────────────────────┼──────────────────────────┼────────────────────────────────┤
│ Exploit Chaining │ Remediation & Fix │ End-to-End Automation │
│ • chain_findings │ • generate_fix │ • audit_pipeline │
│ • generate_report │ • check_fix_completeness │ │
│ │ • list_fix_templates │ │
└──────────────────────┴──────────────────────────┴────────────────────────────────┘
```
| Category | MCP Tools | Primary Capability |
|:---|:---|:---|
| **Target Profiling** | `detect_platform`<br>`profile_target` | Detects OS environment, file hashing, and codebase topology |
| **Static Analysis** | `analyze_code`<br>`scan_file`<br>`get_patterns` | AST data-flow analysis, dangerous sink inspection & taxonomy matching |
| **Verification & PoC** | `check_reachability`<br>`verify_finding`<br>`generate_poc`<br>`calculate_cvss` | 7-class confounder clearance, deterministic PoCs (≤60s), empirical CVSS |
| **Exploit Chaining** | `chain_findings`<br>`generate_report` | Multi-primitive exploit correlation & publication-ready advisories |
| **Remediation & Fix** | `generate_fix`<br>`check_fix_completeness`<br>`list_fix_templates` | 16 CWE grounded patches, multi-site call site fixes, test generation |
| **End-to-End** | `audit_pipeline` | Automated orchestration across all pipeline phases with state persistence |
---
## Workspace Directory Structure
All persistent outputs, candidate records, evidence bundles, and patches reside in `mcp2agy_workspace/`:
```
mcp2agy_workspace/
├── runs/
│ └── <YYYYMMDD_HHMMSS>/ ← Dedicated per-run execution directory
│ ├── pipeline_state.json ← Orchestrator state & phase progression
│ ├── candidates.json ← Scanner normalized candidates
│ ├── verified_findings.json ← Verifier confirmed findings
│ ├── exploit_chains.json ← Synthesized multi-step exploit chains
│ ├── report.md ← Reporter publication-ready markdown report
│ ├── fixes.diff ← Fixer minimal unified diff
│ ├── evidence/ ← Verifier PoCs & reachability traces
│ │ └── <CAND_ID>/
│ │ ├── reachability.md
│ │ └── mts_poc/ (poc.py, Dockerfile, run.sh)
│ └── regression_tests/ ← Fixer unit test harnesses
├── auditor_zone/
│ └── results/
│ └── <YYYYMMDD_HHMMSS>/ ← Synchronized auditor zone artifacts
├── recon/results/ ← Attack surface maps & OSINT data
├── exploits/pocs/ ← Standalone weaponized exploit scripts
├── reverse/analysis/ ← Decompiled symbols & binary call graphs
├── tools/ ← Custom scanners & fuzzing harnesses
├── ctf/solves/ ← CTF solve scripts & writeups
└── loot/ ← Discovered credentials, keys & tokens
```
---
## Anti-Hallucination Invariants
All subagents operate under 10 strict invariants defined in [`.agents/plugins/mcp2agy/rules/AGENTS.md`](.agents/plugins/mcp2agy/rules/AGENTS.md):
| # | Invariant | Description |
|:---:|:---|:---|
| **01** | **Zero Invention** | Never report a finding that static code analysis did not physically produce. |
| **02** | **Line Count Ceiling** | Never cite line ranges exceeding the physical file's total line count. |
| **03** | **Physical Hash Echo** | Every candidate record must echo the physical SHA-256 hash of the target file. |
| **04** | **Deterministic PoC** | Never mark a finding `CONFIRMED` without an executable reproducer triggering in ≤60s. |
| **05** | **Dual-Leg Verification** | Both legs of multi-step exploit chains must be independently proven. |
| **06** | **7-Class Confounder Clearance** | Dead code, auto-escaping, auth gates, and strict types must be formally evaluated. |
| **07** | **Empirical CVSS** | Score deductions require reproducible technical evidence — no estimation. |
| **08** | **One-Way Information Valve** | Downstream agents strictly receive normalized facts to prevent confirmation bias. |
| **09** | **Clean Negative Results** | If 0 defects exist, output `NO_SECURITY_FINDINGS` / `NO_DEFECTS_FOUND`. |
| **10** | **Atomic Minimal Diff** | Remediation diffs must touch only vulnerable lines without introducing new TOCTOU races. |
---
## Cross-Platform Compatibility
<div align="center">
[](#)
[](#)
[](#)
</div>
- **Node.js Lifecycle Hooks (`hooks.json`)**: Eliminates shell script dependencies — `preToolCall` logging and `postFileWrite` permission hardening execute via cross-platform Node.js.
- **Permission Hardening**: Enforces `chmod 600` on POSIX systems and explicit `icacls` permission stripping on Windows (`icacls <file> /inheritance:r /grant:r "%USERNAME%:(R,W)"`).
- **Context-Aware Escaping**: Distinguishes single-quote (`_pse`) vs double-quote (`_pde`) shell string evaluation in PowerShell heredoc contexts.
---
## Documentation
Detailed technical documentation is available in the [`docs/`](docs/) directory:
| Document | Description |
|:---|:---|
| ↗ [**Global & Multi-Directory Usage**](docs/global-usage-guide.md) | How to setup and run `mcp2agy` against **any directory or repository** globally |
| ↗ [**Architecture & Coordination Protocol**](docs/architecture.md) | Multi-agent orchestrator lifecycle, integrity gates & one-way information valve |
| ↗ [**Slash Commands Guide**](docs/slash-commands.md) | Complete reference for all 13 slash commands and usage examples |
| ↗ [**Native MCP Tools Reference (15 Tools)**](docs/mcp-tools-reference.md) | Detailed input/output schemas and examples for all 15 native MCP tools |
| ↗ [**Multi-Chain Synthesis Engine**](docs/multi-chain-engine.md) | Cross-primitive exploit synthesis, gadget chaining & compound CVSS |
| ↗ [**Vulnerability Taxonomy & PAT-01..18 Matrix**](docs/taxonomy-patterns.md) | 2026+ 0day vulnerability patterns, AST grep signatures & root causes |
| ↗ [**Workspace Standards & Artifact Schemas**](docs/workspace-and-artifacts.md) | Directory layout, candidate schemas, verified findings & advisory formats |
| ↗ [**Cross-Platform Setup & OS Nuances**](docs/cross-platform-guide.md) | Windows NTFS ACLs, POSIX permissions, lifecycle hooks & shell differentials |
---
<div align="center">
**mcp2agy** · *Hyperdope AI* · `mcp2agy_workspace/`
[](LICENSE.md)
</div>
TDQS
A3.7/5.0
Scored across 15 tools
Disambiguation4/5
Most tools have distinct purposes (e.g., calculate_cvss vs generate_poc), but scan_file and analyze_code both scan for vulnerabilities with overlapping output structures, and check_reachability is a subset of verify_finding's workflow. Descriptions help differentiate, but some confusion is possible.
Naming Consistency5/5
All tool names follow a consistent snake_case verb_noun pattern (generate_fix, scan_file, verify_finding, audit_pipeline). No mixed conventions or vague verbs; naming is highly predictable.
Tool Count5/5
With 15 tools, the server is well-scoped for a comprehensive security audit pipeline. Each tool addresses a distinct stage (profiling, scanning, verification, fixing, reporting, chaining), and none feel redundant or excessive.
Completeness5/5
The tool surface covers the full audit lifecycle: profile_target (discovery), scan_file/analyze_code (detection), verify_finding/check_reachability (validation), calculate_cvss (scoring), generate_poc (exploitation), generate_fix/check_fix_completeness (remediation), chain_findings (synthesis), and generate_report (output). The audit_pipeline orchestrates everything, leaving no major dead ends.
Maintenance
ActivityMaintained
ResponsivenessSyncing