# mariano-aguero/solidity-audit-mcp architecture

> Architecture diagram of the GitHub repository mariano-aguero/solidity-audit-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mariano-aguero/solidity-audit-mcp
- Repository: https://github.com/mariano-aguero/solidity-audit-mcp

## Overview

Solidity Audit MCP exposes contract auditing through MCP, HTTP, and CLI entry points. Users submit source or a project for analysis; the service coordinates analyzers, consolidates findings, and returns reports or CI review results. The README documents static, AST/pattern, gas, test, fuzzing, and GitHub PR capabilities. Sampled source confirms orchestration, HTTP analysis and CI-review calls, but does not show every tool’s internal wiring; uncertain connections are omitted.

Main entry points: [`src/server/handlers/toolHandlers.ts`](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/server/handlers/toolHandlers.ts) (Tool dispatch), [`src/analyzers/AnalyzerOrchestrator.ts`](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/analyzers/AnalyzerOrchestrator.ts) (Analyzer orchestrator), [`src/server/handlers/httpHandlers.ts`](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/server/handlers/httpHandlers.ts) (REST handlers), [`src/tools/auditProject.ts`](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/tools/auditProject.ts) (Project audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access surfaces"]
  node_mcpentry["MCP stdio entry<br/>[index.ts]"]
  node_httpentry["HTTP/SSE entry<br/>[server.ts]"]
  node_cli["Audit CLI<br/>[cli.ts]"]
  node_mcpserver["MCP server<br/>[McpServer.ts]"]
  node_toolhandlers["Tool dispatch<br/>[toolHandlers.ts]"]
  node_httphandlers["REST handlers<br/>[httpHandlers.ts]"]
end

subgraph group_audit["Audit workflows"]
  node_auditproject["Project audit<br/>[auditProject.ts]"]
  node_analyzecontract["Contract analysis<br/>[analyzeContract.ts]"]
  node_vulncheck["Vulnerability check"]
  node_diffaudit["Diff audit<br/>[diffAudit.ts]"]
  node_otherfeatures["Audit utilities"]
end

subgraph group_analysis["Analysis engine"]
  node_scanner["Project scanner<br/>[projectScanner.ts]"]
  node_orchestrator["Analyzer orchestrator"]
  node_registry["Analyzer registry"]
  node_adapters["Analyzer adapters"]
  node_customdetectors["Custom detectors"]
end

subgraph group_results["Results and integrations"]
  node_findings[("Findings history<br/>[findingsDb.ts]")]
  node_reports["Reports and templates<br/>[generateReport.ts]"]
  node_githubci["GitHub review<br/>[githubComment.ts]"]
  node_sarif["SARIF output<br/>[sarif.ts]"]
end

node_assistant(("AI assistant"))
node_cliuser(("CLI user"))
node_github(("GitHub"))
node_analyzers["Analyzer tools"]

node_assistant -->|"sends MCP requests"| node_mcpentry
node_mcpentry -->|"connects transport"| node_mcpserver
node_mcpserver -->|"dispatches tools"| node_toolhandlers
node_httpentry -->|"routes REST requests"| node_httphandlers
node_cliuser -->|"starts audit"| node_cli
node_cli -->|"runs audit"| node_auditproject
node_toolhandlers -->|"executes tool"| node_auditproject
node_toolhandlers -->|"executes tool"| node_analyzecontract
node_toolhandlers -->|"executes tool"| node_vulncheck
node_toolhandlers -->|"executes tool"| node_diffaudit
node_toolhandlers -->|"executes tools"| node_otherfeatures
node_httphandlers -->|"analyzes source"| node_analyzecontract
node_httphandlers -->|"checks source"| node_vulncheck
node_httphandlers -->|"analyzes CI files"| node_orchestrator
node_httphandlers -->|"posts review"| node_githubci
node_auditproject -->|"scans project"| node_scanner
node_analyzecontract -->|"runs analysis"| node_orchestrator
node_vulncheck -->|"runs detectors"| node_orchestrator
node_orchestrator -->|"resolves analyzers"| node_registry
node_orchestrator -->|"runs analyzers"| node_adapters
node_adapters -->|"invokes tools"| node_analyzers
node_orchestrator -.->|"runs custom checks"| node_customdetectors
node_auditproject -.->|"records audit history"| node_findings
node_otherfeatures -->|"generates reports"| node_reports
node_reports -->|"formats findings"| node_sarif
node_githubci -->|"posts PR comments"| node_github

click node_mcpentry "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/index.ts"
click node_httpentry "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/server.ts"
click node_cli "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/cli.ts"
click node_mcpserver "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/server/McpServer.ts"
click node_toolhandlers "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/server/handlers/toolHandlers.ts"
click node_httphandlers "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/server/handlers/httpHandlers.ts"
click node_auditproject "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/tools/auditProject.ts"
click node_analyzecontract "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/tools/analyzeContract.ts"
click node_vulncheck "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/tools/checkVulnerabilities.ts"
click node_diffaudit "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/tools/diffAudit.ts"
click node_otherfeatures "https://github.com/mariano-aguero/solidity-audit-mcp/tree/main/src/tools"
click node_scanner "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/analyzers/projectScanner.ts"
click node_orchestrator "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/analyzers/AnalyzerOrchestrator.ts"
click node_registry "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/analyzers/AnalyzerRegistry.ts"
click node_adapters "https://github.com/mariano-aguero/solidity-audit-mcp/tree/main/src/analyzers/adapters"
click node_customdetectors "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/detectors/customDetectorEngine.ts"
click node_findings "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/storage/findingsDb.ts"
click node_reports "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/tools/generateReport.ts"
click node_githubci "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/ci/githubComment.ts"
click node_sarif "https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/utils/sarif.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcpentry,node_httpentry,node_cli,node_mcpserver,node_toolhandlers,node_httphandlers,node_cliuser toneBlue
class node_auditproject,node_analyzecontract,node_vulncheck,node_diffaudit,node_otherfeatures toneAmber
class node_scanner,node_orchestrator,node_registry,node_adapters,node_customdetectors toneMint
class node_findings,node_reports,node_githubci,node_sarif toneRose
class node_assistant,node_github,node_analyzers toneIndigo
```

## Components

### Access surfaces

- [MCP stdio entry](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/index.ts): `src/index.ts`
- [HTTP/SSE entry](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/server.ts): `src/server.ts`
- [Audit CLI](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/cli.ts): `src/cli.ts`
- [MCP server](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/server/McpServer.ts): `src/server/McpServer.ts`
- [Tool dispatch](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/server/handlers/toolHandlers.ts): `src/server/handlers/toolHandlers.ts`
- [REST handlers](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/server/handlers/httpHandlers.ts): `src/server/handlers/httpHandlers.ts`

### Audit workflows

- [Project audit](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/tools/auditProject.ts): `src/tools/auditProject.ts`
- [Contract analysis](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/tools/analyzeContract.ts): `src/tools/analyzeContract.ts`
- [Vulnerability check](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/tools/checkVulnerabilities.ts): `src/tools/checkVulnerabilities.ts`
- [Diff audit](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/tools/diffAudit.ts): `src/tools/diffAudit.ts`
- [Audit utilities](https://github.com/mariano-aguero/solidity-audit-mcp/tree/main/src/tools): `src/tools`

### Analysis engine

- [Project scanner](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/analyzers/projectScanner.ts): `src/analyzers/projectScanner.ts`
- [Analyzer orchestrator](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/analyzers/AnalyzerOrchestrator.ts): `src/analyzers/AnalyzerOrchestrator.ts`
- [Analyzer registry](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/analyzers/AnalyzerRegistry.ts): `src/analyzers/AnalyzerRegistry.ts`
- [Analyzer adapters](https://github.com/mariano-aguero/solidity-audit-mcp/tree/main/src/analyzers/adapters): `src/analyzers/adapters`
- [Custom detectors](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/detectors/customDetectorEngine.ts): `src/detectors/customDetectorEngine.ts`

### Results and integrations

- [Findings history](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/storage/findingsDb.ts): `src/storage/findingsDb.ts`
- [Reports and templates](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/tools/generateReport.ts): `src/tools/generateReport.ts`
- [GitHub review](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/ci/githubComment.ts): `src/ci/githubComment.ts`
- [SARIF output](https://github.com/mariano-aguero/solidity-audit-mcp/blob/main/src/utils/sarif.ts): `src/utils/sarif.ts`

### Other components

- **AI assistant**
- **CLI user**
- **GitHub**
- **Analyzer tools**

## Connections

- AI assistant → MCP stdio entry: sends MCP requests
- MCP stdio entry → MCP server: connects transport
- MCP server → Tool dispatch: dispatches tools
- HTTP/SSE entry → REST handlers: routes REST requests
- CLI user → Audit CLI: starts audit
- Audit CLI → Project audit: runs audit
- Tool dispatch → Project audit: executes tool
- Tool dispatch → Contract analysis: executes tool
- Tool dispatch → Vulnerability check: executes tool
- Tool dispatch → Diff audit: executes tool
- Tool dispatch → Audit utilities: executes tools
- REST handlers → Contract analysis: analyzes source
- REST handlers → Vulnerability check: checks source
- REST handlers → Analyzer orchestrator: analyzes CI files
- REST handlers → GitHub review: posts review
- Project audit → Project scanner: scans project
- Contract analysis → Analyzer orchestrator: runs analysis
- Vulnerability check → Analyzer orchestrator: runs detectors
- Analyzer orchestrator → Analyzer registry: resolves analyzers
- Analyzer orchestrator → Analyzer adapters: runs analyzers
- Analyzer adapters → Analyzer tools: invokes tools
- Analyzer orchestrator → Custom detectors: runs custom checks
- Project audit → Findings history: records audit history
- Audit utilities → Reports and templates: generates reports
- Reports and templates → SARIF output: formats findings
- GitHub review → GitHub: posts PR comments