mirror of
https://github.com/FuzzingLabs/fuzzforge_ai.git
synced 2026-08-30 07:40:44 +02:00
feat: FuzzForge AI - complete rewrite for OSS release
This commit is contained in:
AFredefon
@@ -0,0 +1,223 @@
|
||||
# FuzzForge MCP
|
||||
|
||||
Model Context Protocol (MCP) server that enables AI agents to orchestrate FuzzForge security research modules.
|
||||
|
||||
## Overview
|
||||
|
||||
FuzzForge MCP provides a standardized interface for AI agents (Claude Code, GitHub Copilot, Claude Desktop) to:
|
||||
|
||||
- List and discover available security modules
|
||||
- Execute modules in isolated containers
|
||||
- Chain modules together in workflows
|
||||
- Manage project assets and results
|
||||
|
||||
The server communicates with AI agents using the [Model Context Protocol](https://modelcontextprotocol.io/) over stdio.
|
||||
|
||||
## Installation
|
||||
|
||||
### Automatic Installation (Recommended)
|
||||
|
||||
Use the FuzzForge CLI to automatically configure MCP for your AI agent:
|
||||
|
||||
```bash
|
||||
# For GitHub Copilot
|
||||
uv run fuzzforge mcp install copilot
|
||||
|
||||
# For Claude Code (VS Code extension)
|
||||
uv run fuzzforge mcp install claude-code
|
||||
|
||||
# For Claude Desktop (standalone app)
|
||||
uv run fuzzforge mcp install claude-desktop
|
||||
|
||||
# Verify installation
|
||||
uv run fuzzforge mcp status
|
||||
```
|
||||
|
||||
After installation, restart your AI agent to activate the connection.
|
||||
|
||||
### Manual Installation
|
||||
|
||||
For custom setups, you can manually configure the MCP server.
|
||||
|
||||
#### Claude Code (`.mcp.json` in project root)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"fuzzforge": {
|
||||
"command": "/path/to/fuzzforge-oss/.venv/bin/python",
|
||||
"args": ["-m", "fuzzforge_mcp"],
|
||||
"cwd": "/path/to/fuzzforge-oss",
|
||||
"env": {
|
||||
"FUZZFORGE_MODULES_PATH": "/path/to/fuzzforge-oss/fuzzforge-modules",
|
||||
"FUZZFORGE_ENGINE__TYPE": "podman",
|
||||
"FUZZFORGE_ENGINE__GRAPHROOT": "~/.fuzzforge/containers/storage",
|
||||
"FUZZFORGE_ENGINE__RUNROOT": "~/.fuzzforge/containers/run"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### GitHub Copilot (`~/.config/Code/User/mcp.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"fuzzforge": {
|
||||
"type": "stdio",
|
||||
"command": "/path/to/fuzzforge-oss/.venv/bin/python",
|
||||
"args": ["-m", "fuzzforge_mcp"],
|
||||
"cwd": "/path/to/fuzzforge-oss",
|
||||
"env": {
|
||||
"FUZZFORGE_MODULES_PATH": "/path/to/fuzzforge-oss/fuzzforge-modules",
|
||||
"FUZZFORGE_ENGINE__TYPE": "podman",
|
||||
"FUZZFORGE_ENGINE__GRAPHROOT": "~/.fuzzforge/containers/storage",
|
||||
"FUZZFORGE_ENGINE__RUNROOT": "~/.fuzzforge/containers/run"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Claude Desktop (`~/.config/Claude/claude_desktop_config.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"fuzzforge": {
|
||||
"type": "stdio",
|
||||
"command": "/path/to/fuzzforge-oss/.venv/bin/python",
|
||||
"args": ["-m", "fuzzforge_mcp"],
|
||||
"cwd": "/path/to/fuzzforge-oss",
|
||||
"env": {
|
||||
"FUZZFORGE_MODULES_PATH": "/path/to/fuzzforge-oss/fuzzforge-modules",
|
||||
"FUZZFORGE_ENGINE__TYPE": "podman",
|
||||
"FUZZFORGE_ENGINE__GRAPHROOT": "~/.fuzzforge/containers/storage",
|
||||
"FUZZFORGE_ENGINE__RUNROOT": "~/.fuzzforge/containers/run"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
| -------- | -------- | ------- | ----------- |
|
||||
| `FUZZFORGE_MODULES_PATH` | Yes | - | Path to the modules directory |
|
||||
| `FUZZFORGE_ENGINE__TYPE` | No | `podman` | Container engine (`podman` or `docker`) |
|
||||
| `FUZZFORGE_ENGINE__GRAPHROOT` | No | `~/.fuzzforge/containers/storage` | Container image storage path |
|
||||
| `FUZZFORGE_ENGINE__RUNROOT` | No | `~/.fuzzforge/containers/run` | Container runtime state path |
|
||||
|
||||
## Available Tools
|
||||
|
||||
The MCP server exposes the following tools to AI agents:
|
||||
|
||||
### Project Management
|
||||
|
||||
- **`init_project`** - Initialize a new FuzzForge project
|
||||
- **`set_project_assets`** - Set initial assets (source code, contracts, etc.) for the project
|
||||
|
||||
### Module Management
|
||||
|
||||
- **`list_modules`** - List all available security research modules
|
||||
- **`execute_module`** - Execute a single module in an isolated container
|
||||
|
||||
### Workflow Management
|
||||
|
||||
- **`execute_workflow`** - Execute a workflow consisting of multiple chained modules
|
||||
|
||||
### Resources
|
||||
|
||||
The server also provides resources for accessing:
|
||||
|
||||
- Project information and configuration
|
||||
- Module metadata and schemas
|
||||
- Execution results and artifacts
|
||||
- Workflow definitions and status
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### From AI Agent (e.g., Claude Code)
|
||||
|
||||
Once configured, AI agents can interact with FuzzForge naturally:
|
||||
|
||||
```text
|
||||
User: List the available security modules
|
||||
|
||||
AI Agent: [Calls list_modules tool]
|
||||
```
|
||||
|
||||
```text
|
||||
User: Run echidna fuzzer on my Solidity contracts
|
||||
|
||||
AI Agent: [Calls init_project, set_project_assets, then execute_module]
|
||||
```
|
||||
|
||||
```text
|
||||
User: Create a workflow that compiles contracts, runs slither, then echidna
|
||||
|
||||
AI Agent: [Calls execute_workflow with appropriate steps]
|
||||
```
|
||||
|
||||
### Direct Testing (Development)
|
||||
|
||||
For testing during development, you can run the MCP server directly:
|
||||
|
||||
```bash
|
||||
# Run MCP server in stdio mode (for AI agents)
|
||||
uv run python -m fuzzforge_mcp
|
||||
|
||||
# Run HTTP server for testing (not for production)
|
||||
uv run uvicorn fuzzforge_mcp.application:app --reload
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────┐
|
||||
│ AI Agent (Claude/Copilot) │
|
||||
│ via MCP Protocol │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
│ stdio/JSON-RPC
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ FuzzForge MCP Server │
|
||||
│ Tools: init_project, list_modules, │
|
||||
│ execute_module, execute_workflow│
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ FuzzForge Runner │
|
||||
│ Podman/Docker Orchestration │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────┼─────────┐
|
||||
▼ ▼ ▼
|
||||
[Module 1] [Module 2] [Module 3]
|
||||
Container Container Container
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Building the Package
|
||||
|
||||
```bash
|
||||
# Install development dependencies
|
||||
uv sync
|
||||
|
||||
# Run type checking
|
||||
uv run mypy src/
|
||||
|
||||
# Run tests
|
||||
uv run pytest
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [FuzzForge Main README](../README.md) - Overall project documentation
|
||||
- [Module SDK](../fuzzforge-modules/fuzzforge-modules-sdk/README.md) - Creating custom modules
|
||||
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
|
||||
Reference in New Issue
Block a user