# Helix MCP Server

A modern, local-first Model Context Protocol (MCP) server built with Python and managed by `uv`. 

This server is designed to work fully offline (e.g. alongside `llama-server` running local models like Gemma 2) while providing secure workspace operations, offline searching, and modular web capabilities without requiring paid API keys.

## Features

* 🔌 **Standard stdio Transport**: Connects seamlessly to standard MCP clients like Claude Desktop.
* 🛡️ **Secure Filesystem Boundary**: All file operations (read, write, delete, list, move) are strictly confined to the workspace root directory.
* 🔎 **Offline Search & Indexer**: Built-in SQLite FTS5 (Full-Text Search) engine that indices all text and code files in the workspace locally.
* 👁️ **File Change Watcher**: Background thread utilizing `watchdog` to monitor workspace additions, deletions, modifications, and moves.
* 🌐 **Zero-Cost Web Search**: Multi-adapter web search using **DuckDuckGo** (via Python SDK) and **Mojeek** (via HTML parsing) with automatic fallback. No API keys required.
* 📄 **Clean Web Fetcher**: Downloads pages and converts them to readable Markdown, stripping script, style, navigation, and image tags to conserve context window tokens.

## Tech Stack
* **Python 3.10+**
* **uv**: Blazing-fast dependency resolver & package manager.
* **FastMCP**: Declarative MCP framework wrapper.
* **SQLite FTS5**: Fully offline search indexing.
* **Watchdog**: Multi-threaded file systems events catcher.
* **Httpx & BeautifulSoup4**: Scraping & page cleanup.

---

## MCP Tools Provided

| Tool Name | Arguments | Description |
| :--- | :--- | :--- |
| `web_search` | `query: str`, `engine: str = "auto"`, `limit: int = 5` | Search the web using DuckDuckGo/Mojeek. |
| `web_fetch` | `url: str` | Downloads a webpage and cleans it to Markdown. |
| `workspace_index` | None | Indexes all workspace text/code files locally. |
| `workspace_search` | `query: str`, `limit: int = 10` | Instantly queries the local index using FTS5 keywords. |
| `file_read` | `path: str` | Reads a text/code file (workspace relative). |
| `file_write` | `path: str`, `content: str` | Writes content to a file (workspace relative). |
| `file_delete` | `path: str` | Deletes a file or empty directory. |
| `file_move` | `source: str`, `destination: str` | Moves or renames files or directories. |
| `directory_list` | `path: str = "."` | Lists contents inside a workspace folder. |
| `file_changes_get` | None | Returns a log of recent workspace file changes. |

---

## Getting Started

### Prerequisites

Install `uv` if you haven't already:
* **macOS/Linux**: `curl -LsSf https://astral.sh/uv/install.sh | sh`
* **Windows**: `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`

### Setup & Installation

Clone this repository and set up dependencies:
```bash
git clone https://github.com/b1krams/helix-mcp.git
cd helix-mcp
uv sync
```

### Running Locally

To run the MCP server on stdio transport:
```bash
uv run python -m helix_mcp.server
```

---

## Connecting to Clients

### Claude Desktop Configuration
Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "helix-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/helix-mcp",
        "run",
        "python",
        "-m",
        "helix_mcp.server"
      ]
    }
  }
}
```
*(Make sure to replace `/absolute/path/to/helix-mcp` with your actual full workspace path).*

---

## Development & Testing

Run the offline pytest suite to verify all tools:
```bash
uv run pytest
```

Formatting and Linting:
```bash
uv run ruff check
```