I maded this Projects because I wanted to learn more about Model Context Protocols
and to learn how to create better README's. I have added simple tools just to have my LLM
complete simple task, I plan to add more tool in the future.

# Ollama MCP Server

A small [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that
gives a local Ollama model a set of safe, sandboxed tools — most importantly the
ability to read, write, list, and remove files inside a workspace directory you
control.

Everything runs locally. The model, the tools, and your files never leave your machine.

## How it works

```
┌─────────────┐   chat + tool calls   ┌────────────────────┐   MCP (stdio)   ┌──────────────────┐
│   You (CLI) │ ───────────────────▶ │  Ollama client     │ ──────────────▶ │  MCP server      │
│             │ ◀─────────────────── │  (ollama_clients)  │ ◀────────────── │  (server.py)     │
└─────────────┘      responses        └────────────────────┘   tool results   └──────────────────┘
                                              │                                        │
                                              ▼                                        ▼
                                       local Ollama model                     sandboxed workspace
                                       (e.g. qwen2.5:14b)                      (~/Projects/…)
```

1. You type a message in the client.
2. The client sends it to your local Ollama model along with the list of tools the
   MCP server exposes.
3. If the model decides to call a tool, the client forwards that call to the MCP
   server over stdio, gets the result, and feeds it back to the model.
4. The model produces a final answer.

## Features

- **Sandboxed file tools** — the model can only touch files inside the active
  workspace. Absolute paths, `../` escapes, and protected directories (`.git`,
  `.venv`, `.trash`, `__pycache__`) are all rejected.
- **Recoverable deletes** — `remove_project_file` and overwrites don't hard-delete.
  The previous version is moved into `<workspace>/.trash/`, preserving its layout.
- **Atomic writes** — files are written to a temp file and `os.replace`'d into place,
  so a crash mid-write can't corrupt an existing file.
- **Named workspace profiles** — switch between project directories via config or an
  environment variable.
- **Size limits** — configurable maximum file size for reads and writes.

### Available tools

| Tool | Description |
|------|-------------|
| `read_project_file` | Read a UTF-8 text file from the workspace. |
| `write_project_file` | Create or overwrite a file (overwrite makes a `.trash` backup). |
| `list_project_items` | List files/directories in the workspace (recursive optional). |
| `remove_project_file` | Move a file into `.trash` (recoverable). |
| `ping` | Health check — returns `pong`. |
| `add_numbers` | Trivial demo tool that adds two numbers. |

## Requirements

- **Python 3.12+**
- **[Ollama](https://ollama.com)** installed and running, with a model pulled
  (default: `qwen2.5:14b`).
- Python packages: `mcp[cli]==2.0.0`, `ollama`

## Installation

```bash
# 1. Clone
git clone <your-repo-url> mcp-server
cd mcp-server

# 2. Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies
pip install "mcp[cli]==2.0.0" ollama

# 4. Pull the model (if you haven't already)
ollama pull qwen2.5:14b
```

## Configuration

All settings live in [`config.toml`](./config.toml):

```toml
[ollama]
model = "qwen2.5:14b"     # any model available to your local Ollama
max_tool_rounds = 8       # max tool round-trips per user message

[mcp]
default_workspace = "ollama-workspace" # replace with desired workplace profile
max_list_results = 500
MAX_FILE_SIZE_BYTES = 1000000   # 1 MB read/write cap

[mcp.workspaces]
ollama-workspace = "~/Projects/ollama-workspace" # replace these for your workspace's path
custom-workspace = "~/Projects/Scripts"          # replace these for your workspace's path
```

Each entry under `[mcp.workspaces]` is a **named profile** pointing at a directory the
tools are allowed to operate in. The directory is created automatically if it doesn't
exist.

### Environment variables

| Variable | Purpose |
|----------|---------|
| `OLLAMA_MODEL` | Override the model from `config.toml`. |
| `MCP_WORKSPACE_NAME` | Select a named profile from `[mcp.workspaces]`. |
| `MCP_WORKSPACE` | Point at a directory directly (bypasses named profiles — handy for testing). |
| `MCP_CONFIG` | Use a config file other than `./config.toml`. |

## Getting started

### Run the assistant (normal use)

```bash
source .venv/bin/activate
python3 clients/ollama_clients.py
```

You'll see the connected tools and a prompt. Try:

```
You: create a file called notes.txt that says "hello from ollama"
You: list the files in the workspace
You: read notes.txt
```

Type `exit` or `quit` to stop.

To use a different workspace or model for a session:

```bash
MCP_WORKSPACE_NAME="custom-workspace" \
OLLAMA_MODEL="qwen2.5:14b" \
python3 clients/ollama_clients.py
```

### Inspect the server on its own

The MCP CLI inspector lets you call the server's tools directly, without a model:

```bash
uv run --with "mcp[cli]==2.0.0" mcp dev ./server/server.py
```

## Maintenance: clearing old trash

Because deletes are recoverable, `.trash` grows over time. The included script purges
trash entries older than a week:

```bash
scripts/clean_trash.sh              # clean the configured workspaces
RETENTION_DAYS=14 scripts/clean_trash.sh   # keep two weeks instead
```

To run it automatically, add a cron entry (daily at 3 AM):

```cron
0 3 * * * /path/to/mcp-server/scripts/clean_trash.sh >> $HOME/.mcp-trash-clean.log 2>&1
```

## Project layout

```
mcp-server/
├── server/
│   └── server.py            # MCP server + tool definitions
├── clients/
│   └── ollama_clients.py    # Ollama <-> MCP bridge (the chat loop)
├── scripts/
│   └── clean_trash.sh       # purges .trash entries older than a week
├── config.toml              # model + workspace configuration
├── tests/                   # (add tests here)
└── README.md
```