# italoag/farofino-mcp architecture

> Architecture diagram of the GitHub repository italoag/farofino-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/italoag/farofino-mcp
- Repository: https://github.com/italoag/farofino-mcp

## Overview

Faro Fino is an MCP smart-contract auditing server with a CLI fallback. An MCP client calls a registered tool, or a CLI user starts a scan; each entry point delegates to the shared engine. The engine reads contract sources, runs selected static analyzers and heuristic checks, and returns normalized findings and tool-status information. The README also documents source reading and tool discovery as standalone capabilities. Engine internals are only partially sampled, so analyzer and reporting connections reflect the documented behavior; uncertain implementation details are omitted.

Main entry points: [`farofino_mcp/engine.py`](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py) (Audit engine), [`farofino_mcp/scan.py`](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/scan.py) (Scan CLI), [`farofino_mcp/schema.py`](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/schema.py) (Finding schema), [`farofino_mcp/__main__.py`](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/__main__.py) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_mcp_server["MCP server<br/>[__main__.py]"]
  node_scan_cli["Scan CLI<br/>[scan.py]"]
end

subgraph group_analysis["Analysis engine"]
  node_engine["Audit engine<br/>[engine.py]"]
  node_slither["Slither runner<br/>[engine.py]"]
  node_aderyn["Aderyn runner<br/>[engine.py]"]
  node_patterns["Pattern checks<br/>[engine.py]"]
  node_contract_reader["Contract reader<br/>[engine.py]"]
  node_tool_status["Tool discovery<br/>[engine.py]"]
end

subgraph group_integrations["Audit integrations"]
  node_slither_tool["Slither"]
  node_aderyn_tool["Aderyn"]
  node_solc_tools["Compiler tools"]
end

subgraph group_results["Results"]
  node_normalized["Finding schema<br/>[schema.py]"]
  node_report["Scan report<br/>[schema.py]"]
end

node_mcp_client(("MCP client"))
node_cli_user(("CLI user"))
node_contract["Contract source"]

node_mcp_client -->|"calls tools"| node_mcp_server
node_mcp_server -->|"dispatches"| node_engine
node_engine -->|"returns results"| node_mcp_server
node_cli_user -->|"starts scan"| node_scan_cli
node_scan_cli -->|"runs audit"| node_engine
node_engine -->|"returns report data"| node_scan_cli
node_engine -->|"runs when selected"| node_slither
node_engine -->|"runs when selected"| node_aderyn
node_engine -->|"runs checks"| node_patterns
node_engine -->|"reads source"| node_contract_reader
node_engine -->|"checks availability"| node_tool_status
node_slither -->|"executes"| node_slither_tool
node_aderyn -->|"executes"| node_aderyn_tool
node_slither -.->|"selects compiler"| node_solc_tools
node_contract -->|"provides target"| node_engine
node_slither -->|"normalizes findings"| node_normalized
node_aderyn -->|"normalizes findings"| node_normalized
node_patterns -->|"creates findings"| node_normalized
node_engine -->|"aggregates findings"| node_report
node_normalized -->|"supplies findings"| node_report
node_report -->|"renders output"| node_scan_cli

click node_mcp_server "https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/__main__.py"
click node_scan_cli "https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/scan.py"
click node_engine "https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py"
click node_slither "https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py"
click node_aderyn "https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py"
click node_patterns "https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py"
click node_contract_reader "https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py"
click node_tool_status "https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py"
click node_normalized "https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/schema.py"
click node_report "https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/schema.py"

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_mcp_server,node_scan_cli,node_mcp_client,node_cli_user toneBlue
class node_engine,node_slither,node_aderyn,node_patterns,node_contract_reader,node_tool_status toneAmber
class node_slither_tool,node_aderyn_tool,node_solc_tools toneMint
class node_normalized,node_report toneRose
class node_contract toneIndigo
```

## Components

### Entry points

- [MCP server](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/__main__.py): `farofino_mcp/__main__.py`
- [Scan CLI](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/scan.py): `farofino_mcp/scan.py`

### Analysis engine

- [Audit engine](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py): `farofino_mcp/engine.py`
- [Slither runner](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py): `farofino_mcp/engine.py`
- [Aderyn runner](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py): `farofino_mcp/engine.py`
- [Pattern checks](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py): `farofino_mcp/engine.py`
- [Contract reader](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py): `farofino_mcp/engine.py`
- [Tool discovery](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/engine.py): `farofino_mcp/engine.py`

### Audit integrations

- **Slither**
- **Aderyn**
- **Compiler tools**

### Results

- [Finding schema](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/schema.py): `farofino_mcp/schema.py`
- [Scan report](https://github.com/italoag/farofino-mcp/blob/main/farofino_mcp/schema.py): `farofino_mcp/schema.py`

### Other components

- **MCP client**
- **CLI user**
- **Contract source**

## Connections

- MCP client → MCP server: calls tools
- MCP server → Audit engine: dispatches
- Audit engine → MCP server: returns results
- CLI user → Scan CLI: starts scan
- Scan CLI → Audit engine: runs audit
- Audit engine → Scan CLI: returns report data
- Audit engine → Slither runner: runs when selected
- Audit engine → Aderyn runner: runs when selected
- Audit engine → Pattern checks: runs checks
- Audit engine → Contract reader: reads source
- Audit engine → Tool discovery: checks availability
- Slither runner → Slither: executes
- Aderyn runner → Aderyn: executes
- Slither runner → Compiler tools: selects compiler
- Contract source → Audit engine: provides target
- Slither runner → Finding schema: normalizes findings
- Aderyn runner → Finding schema: normalizes findings
- Pattern checks → Finding schema: creates findings
- Audit engine → Scan report: aggregates findings
- Finding schema → Scan report: supplies findings
- Scan report → Scan CLI: renders output