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

Navigate to the server directory:

cd Cariddi

Create and activate virtual environment:

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

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

Make sure your server is running (see above)
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

Navigate to the server directory:

cd Cariddi

Build the Docker image:

docker build -t cariddi-mcp-server .

Run the container:

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

Using Docker Compose

Navigate to the server directory:

cd Cariddi

Start the server:

docker-compose up -d

View logs:

docker-compose logs -f

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

Navigate to the client directory:

cd CariddiClient

Install Python dependencies:

pip install -r requirements.txt

Make sure Ollama is running:

ollama serve

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:

Exploration: Lists files in /tmp directory to identify relevant challenge files
Analysis: Identifies cryptographic schemes (RSA, AES, DES, XOR, etc.) and vulnerabilities
Execution: Writes and executes Python scripts to solve challenges
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:

Automatically loads available tools from the MCP server
Passes them to Ollama as usable tools
Executes tools when requested by the model
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:

Implement the tool function in modules/filesystem.py
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:

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

License

[Add your license information here]

Contributing

[Add contributing guidelines here]