# llamacpp-mcp

An MCP (Model Context Protocol) wrapper for running local LLMs using `llama-cpp-python`. This project provides a framework for integrating local language models as MCP tools with built-in support for specialized models like SmileyLlama.

### SmileyLlama Integration
Generate SMILES strings (chemical notation) for drug-like molecules with fine-grained constraints:
- Lipinski's Rule of Five validation
- Hydrogen bond donor/acceptor limits
- Molecular weight and LogP constraints
- Warhead SMARTS pattern matching
- Macrocycle detection and filtering
- And more...

## Installation

### Prerequisites

- Python ≥ 3.13
- `uv` (recommended) or pip

### Setup

Clone the repository and install dependencies:

```sh
git clone <repository-url>
cd llamacpp-mcp
uv sync
```

### Backend Configuration

The `llama-cpp-python` library requires compilation with hardware acceleration support. Choose the appropriate backend for your system:

**CUDA** (NVIDIA GPUs):
```sh
CMAKE_ARGS="-DGGML_CUDA=on" uv pip install llama-cpp-python --force-reinstall --no-cache-dir
```

**ROCm** (AMD GPUs):
```sh
CMAKE_ARGS="-DGGML_HIPBLAS=on" uv pip install llama-cpp-python --force-reinstall --no-cache-dir
```

**Metal** (Apple Silicon):
```sh
CMAKE_ARGS="-DGGML_METAL=on" uv pip install llama-cpp-python --force-reinstall --no-cache-dir
```

**CPU-only** (no GPU acceleration):
```sh
uv sync
```

## Usage

### Run the agent example

Setup your `example/fastagent.secrets.yaml`:

```yaml
anthropic:
  api_key: your-api-key-here
```

Then run the agent interface in the terminal:

```sh
cd example/
uv run --extra agent agent.py
```

### Running the MCP Server

Start the MCP server with a GGUF model:

```sh
uv run llamacpp-mcp -i /path/to/model.gguf
```

Additional parameters can be passed as command-line arguments:

```sh
uv run llamacpp-mcp --input model.gguf -n_gpu_layers -1 -n_threads 8
```

**Common parameters:**
- `-n_gpu_layers`: Number of model layers to offload to GPU (-1 for all)
- `-n_threads`: Number of CPU threads to use
- `-n_ctx`: Context window size
- `-verbose`: Verbosity level

### Available Tools

#### generate_smiles

Generate SMILES strings for drug-like molecules with optional constraints.

**Parameters:**
- `max_hbond_donors`: Maximum hydrogen bond donors
- `max_hbond_acceptors`: Maximum hydrogen bond acceptors
- `max_molecular_weight`: Maximum molecular weight
- `max_clogp`: Maximum calculated LogP
- `lipinski_rule_of_five`: Enforce Lipinski's Rule of Five
- `rule_of_three`: Enforce Rule-of-Three for fragment-like molecules
- And additional constraint options...

## Dependencies

**Core:**
- `fastmcp>=2.13.1` - MCP server framework
- `llama-cpp-python>=0.3.16` - LLM inference engine

**Optional:**
- `fast-agent-mcp>=0.2.25` - For agent-based integrations

## Development

### Project Setup

The project uses `uv` for dependency management. After installing uv, run:

```sh
uv sync
```

This installs all dependencies in a local virtual environment.

### Adding New Models

To add a new model type:

1. Create a subdirectory under `src/llamacpp_mcp/models/`
2. Implement `models.py` with Pydantic constraint definitions
3. Implement `tools.py` with tool registration function
4. Import and register tools in the main `__init__.py`

## Configuration

Model parameters can be configured via:

1. **Command-line arguments** - Pass directly to `llamacpp-mcp`
2. **Environment variables** - Set before running the server
3. **Agent Tool Configuration** - See `example/fastagent.config.yaml` for reference

## License

MIT License

## Author

Lukas Kim