# Cariddi - MCP Client and Server

A complete MCP (Model Context Protocol) solution consisting of:
- **Cariddi Server**: A FastMCP server with filesystem tools for file operations and command execution
- **Cariddi Client**: A Python client that uses Ollama models for inference and connects to MCP servers, specialized as a Crypto Solver Agent for CTF challenges

## Project Structure

```
Cariddi/
├── Cariddi/              # MCP Server implementation
│   ├── main.py          # FastMCP server entry point
│   ├── modules/
│   │   └── filesystem.py # Filesystem operation implementations
│   ├── requirements.txt
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── mcp.json         # MCP server configuration
├── CariddiClient/        # MCP Client with Ollama
│   ├── mcpClient.py     # Main client implementation
│   └── requirements.txt
└── challs/              # CTF challenges
    └── cryptoEasy/
        ├── challenge.py
        └── cryptoeasy.txt
```

---

## Cariddi Server

A FastMCP server that provides filesystem tools for file operations, command execution, and Python file writing with proper handling of escape characters.

### Server Setup

1. Navigate to the server directory:
```bash
cd Cariddi
```

2. Create and activate virtual environment:
```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -r requirements.txt
```

### Running the Server

```bash
source venv/bin/activate  # On Windows: venv\Scripts\activate
python main.py
```

The server will start on `http://0.0.0.0:8000/mcp` with streamable-http transport.

### Environment Variables

- `FASTMCP_HOST` or `MCP_HOST`: Server host (default: `0.0.0.0`)
- `FASTMCP_PORT` or `MCP_PORT`: Server port (default: `8000`)

### Using MCP Inspector

The MCP Inspector is a visual tool for testing and debugging MCP servers.

#### Install and Run Inspector

1. Make sure your server is running (see above)

2. Run the inspector to connect to your server:
```bash
npx @modelcontextprotocol/inspector --url http://localhost:8000/mcp
```

The inspector will open in your browser (typically at `http://localhost:5173`).

#### Alternative: Run Inspector with Server

You can also run the inspector and server together:
```bash
npx @modelcontextprotocol/inspector python main.py
```

#### Setup MCP Inspector

Use "Streamable HTTP"

URL: `http://localhost:8000/mcp`

and press connect.

### Docker Deployment

#### Build and Run with Docker

1. Navigate to the server directory:
```bash
cd Cariddi
```

2. Build the Docker image:
```bash
docker build -t cariddi-mcp-server .
```

3. Run the container:
```bash
docker run -d -p 8000:8000 --name cariddi-mcp cariddi-mcp-server
```

#### Using Docker Compose

1. Navigate to the server directory:
```bash
cd Cariddi
```

2. Start the server:
```bash
docker-compose up -d
```

3. View logs:
```bash
docker-compose logs -f
```

4. Stop the server:
```bash
docker-compose down
```

The server will be accessible at `http://localhost:8000/mcp` from your host machine.

### Server Tools

The server provides the following tools:

- **`listFiles(path: str)`** - List all files in the given path
- **`readFile(path: str)`** - Read the contents of a file
- **`writeFile(path: str, content: str)`** - Write contents to a file
- **`executeCommand(command: str)`** - Execute a shell command and return stdout, stderr, and return code
- **`writePythonFile(path: str, content: str)`** - Write a Python file handling streaming and escape characters correctly (handles code blocks and unicode escapes)

---

## Cariddi Client

A Python MCP client that uses Ollama models for inference. The client is specialized as a **Crypto Solver Agent** for CTF (Capture The Flag) challenges, capable of identifying, analyzing, and solving cryptographic challenges.

### Client Requirements

- Python 3.7+
- Ollama installed and running (see https://ollama.ai/)

### Client Installation

1. Navigate to the client directory:
```bash
cd CariddiClient
```

2. Install Python dependencies:
```bash
pip install -r requirements.txt
```

3. Make sure Ollama is running:
```bash
ollama serve
```

4. Pull a model (if you haven't already):
```bash
ollama pull ministral-3
# or
ollama pull llama3.2
```

### Client Usage

#### List available models
```bash
python mcpClient.py --list-models
```

#### Send a single prompt
```bash
python mcpClient.py --prompt "What is the capital of France?"
```

#### Interactive mode
```bash
python mcpClient.py --interactive
```

#### Custom Ollama URL and model
```bash
python mcpClient.py --base-url http://localhost:11434 --model ministral-3 --prompt "Hello!"
```

#### Connect to MCP server (streamable HTTP)
```bash
# Connect to MCP server via streamable HTTP
python mcpClient.py --mcp-server "http://localhost:8000/mcp" --prompt "Use tools to help me"

# With authentication headers
python mcpClient.py --mcp-server "http://localhost:8000/mcp" --mcp-headers '{"Authorization": "Bearer token"}' --interactive
```

### Client Examples

```bash
# Simple question
python mcpClient.py --prompt "Explain quantum computing in simple terms"

# Interactive chat
python mcpClient.py -i

# Use a different model
python mcpClient.py --model mistral --prompt "Write a haiku about coding"
```

### Client Features

- Connects to local or remote Ollama instances
- Supports chat and generation modes
- **Connect to MCP servers** and use their tools automatically
- Tool registration for extensibility
- Interactive and non-interactive modes
- Health checking for Ollama server
- Automatic tool calling from MCP server tools
- **Specialized Crypto Solver Agent** with built-in knowledge for CTF challenges

### Crypto Solver Agent

The client is configured as a specialized Crypto Solver Agent that:

1. **Exploration**: Lists files in `/tmp` directory to identify relevant challenge files
2. **Analysis**: Identifies cryptographic schemes (RSA, AES, DES, XOR, etc.) and vulnerabilities
3. **Execution**: Writes and executes Python scripts to solve challenges
4. **Validation**: Searches for flags in the format `flag{...}`

The agent can handle:
- **RSA**: Small modulus factorization, low public exponent attacks, Wiener attack, Hastad attack, common modulus attacks
- **Symmetric Encryption**: AES/DES with various modes (ECB, CBC), IV vulnerabilities, key reuse
- **Classical Ciphers**: Frequency analysis, fixed-key attacks
- **Encoding**: Base64, Hex, Big-Endian/Little-Endian conversions

### Connecting to an MCP Server

The client uses **FastMCP** to connect to an existing MCP server via **streamable HTTP**. Once connected, the client:

1. Automatically loads available tools from the MCP server
2. Passes them to Ollama as usable tools
3. Executes tools when requested by the model
4. Returns results to the model to continue the conversation

#### Example with MCP Server

```bash
# Connect to an MCP server via streamable HTTP
python mcpClient.py --mcp-server "http://localhost:8000/mcp" --interactive

# With authentication headers
python mcpClient.py --mcp-server "http://localhost:8000/mcp" --mcp-headers '{"Authorization": "Bearer your-token"}' --prompt "Use your tools"
```

### Default Configuration

- **Default Ollama URL**: `http://localhost:11434`
- **Default Model**: `ministral-3`
- **Default MCP Server**: `http://localhost:8000/mcp`

---

## Complete Workflow Example

### 1. Start the MCP Server

```bash
cd Cariddi
python main.py
```

The server will start on `http://localhost:8000/mcp`.

### 2. Run the Client and Connect to the Server

In another terminal:

```bash
cd CariddiClient
python mcpClient.py --mcp-server "http://localhost:8000/mcp" --interactive
```

### 3. Use the Crypto Solver Agent

The client will automatically discover and use the server's tools (like `listFiles`, `readFile`, `writeFile`, `executeCommand`, `writePythonFile`) through Ollama. You can ask it to solve CTF challenges:

```
You: Analyze the files in /tmp and solve the crypto challenge
```

The agent will:
- List files in `/tmp`
- Read relevant files
- Analyze the cryptographic scheme
- Write and execute Python scripts to solve the challenge
- Return the flag

---

## CTF Challenges

The `challs/` directory contains CTF challenges for testing the Crypto Solver Agent:

- **cryptoEasy**: A Diffie-Hellman based challenge with AES encryption

---

## Development

### Server Development

The server is built using FastMCP and provides filesystem operations. To add new tools:

1. Implement the tool function in `modules/filesystem.py`
2. Register it as an MCP tool in `main.py` using `@mcpServer.tool()`

### Client Development

The client uses FastMCP for server communication and Ollama for inference. To modify the agent's behavior:

1. Edit the system prompt in `mcpClient.py` (line 248)
2. Add custom tools using `registerTool()` method
3. Modify the tool execution logic in `_executeTool()` method

---

## License

[Add your license information here]

---

## Contributing

[Add contributing guidelines here]