CariddiCTF/README.md

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/
├── mcpServer/              # 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
├── mcpClient/        # 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:

cd Cariddi

2. Create and activate virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

Running the Server

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:

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:

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:

cd Cariddi

2. Build the Docker image:

docker build -t cariddi-mcp-server .

3. Run the container:

docker run -d -p 8000:8000 --name cariddi-mcp cariddi-mcp-server

Using Docker Compose

1. Navigate to the server directory:

cd Cariddi

2. Start the server:

docker-compose up -d

3. View logs:

docker-compose logs -f

4. Stop the server:

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:

cd CariddiClient

2. Install Python dependencies:

pip install -r requirements.txt

3. Make sure Ollama is running:

ollama serve

4. Pull a model (if you haven't already):

ollama pull ministral-3
# or
ollama pull llama3.2

Client Usage

List available models

python mcpClient.py --list-models

Send a single prompt

python mcpClient.py --prompt "What is the capital of France?"

Interactive mode

python mcpClient.py --interactive

Custom Ollama URL and model

python mcpClient.py --base-url http://localhost:11434 --model ministral-3 --prompt "Hello!"

Connect to MCP server (streamable HTTP)

# 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

# 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

# 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

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:

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]