octofs

<div align="center">

# 🐙 Octofs

**Give your AI assistant filesystem superpowers**

[![Rust](https://img.shields.io/badge/Rust-1.95+-orange.svg?logo=rust)](https://www.rust-lang.org)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-2025--03--26-green.svg)](https://modelcontextprotocol.io)
[![Version](https://img.shields.io/crates/v/octofs.svg)](https://crates.io/crates/octofs)

*The fastest, most capable filesystem MCP server. Built in Rust for AI agents that actually ship.*

[Installation](#installation) • [Quick Start](#quick-start) • [Features](#features) • [Tools Reference](#mcp-tools-reference)

MCP Registry name: `mcp-name: io.github.Muvon/octofs`

</div>

---

## Why Octofs?

Your AI coding assistant (Cursor, Claude, Windsurf, etc.) is smart—but it's **blind to your filesystem**. Octofs bridges that gap, giving your AI:

- **Eyes** — Read files, search content, explore directories
- **Hands** — Create, edit, batch-modify files atomically
- **Context** — Execute commands, manage working directories

```
┌─────────────────────────────────────────────────────────────┐
│  You: "Refactor all error handling to use anyhow::Context" │
├─────────────────────────────────────────────────────────────┤
│  AI without Octofs:                                         │
│  • "I can't see your project structure"                     │
│  • "Please paste the relevant files"                        │
│  • *Wastes 10 minutes on back-and-forth*                    │
├─────────────────────────────────────────────────────────────┤
│  AI with Octofs:                                            │
│  • Scans entire codebase in milliseconds                    │
│  • Finds all 47 error handling patterns                     │
│  • Suggests atomic batch edits                              │
│  • Applies changes with your approval                       │
└─────────────────────────────────────────────────────────────┘
```

## What Makes It Different

| Feature | Octofs | Others |
|---------|--------|--------|
| **Speed** | Rust-powered, sub-millisecond responses | Python/Node-based, slower |
| **Content Search** | Built-in search with context lines | String matching only |
| **Batch Operations** | Atomic multi-edit on single file | One-at-a-time |
| **Line Modes** | Hash-based (stable across edits) or number-based | Number-only |
| **Transport** | STDIO + HTTP (Streamable HTTP) | STDIO only |
| **Shell Integration** | Background process support | Limited or none |
| **Safety** | Gitignore-aware, path validation | Full filesystem access |

---

## Installation

### From Source

Requires Rust 1.95+.

```bash
# Clone and build
git clone https://github.com/muvon/octofs
cd octofs
cargo build --release

# Binary will be at ./target/release/octofs
# Optionally install globally
cargo install --path .
```

### Pre-built Binaries

Download from [GitHub Releases](https://github.com/muvon/octofs/releases) for your platform.

---

## Quick Start

### 1. Configure Your AI Assistant

**Cursor** (`~/.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "octofs": {
      "command": "/path/to/octofs"
    }
  }
}
```

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
  "mcpServers": {
    "octofs": {
      "command": "/path/to/octofs"
    }
  }
}
```

**Windsurf** (`~/.windsurf/mcp.json`):
```json
{
  "mcpServers": {
    "octofs": {
      "command": "/path/to/octofs"
    }
  }
}
```

### 2. Restart Your AI Assistant

The MCP server will start automatically when your AI assistant connects.

### 3. Try It

Ask your AI assistant to:
- "Show me the project structure"
- "Read the main.rs file"
- "Search for all uses of `unwrap()` in the codebase"
- "Create a new file called `test.rs`"

---

## Features

### 📁 Filesystem Operations

- **View Files & Directories** — Read a single file (call `view` in parallel for several), list directories with glob patterns, search content
- **Smart Truncation** — Large files are truncated intelligently to avoid overwhelming context
- **Gitignore-Aware** — Respects `.gitignore` patterns during directory traversal
- **Line Ranges** — Read specific line ranges with negative indexing support (`-1` = last line)

### ✏️ Text Editing

- **Create Files** — Create new files with automatic parent directory creation
- **String Replace** — Replace exact string matches with fuzzy fallback for whitespace
- **Delete** — Remove a file (recoverable via undo)
- **Undo** — Revert last edit (up to 10 undo levels per file)
- **Batch Edit** — Perform multiple insert/replace operations atomically on a single file
- **Stale-Write Protection** — Edits fail fast if the file changed on disk since it was last viewed (external-edit detection, like an IDE's "file changed on disk" guard)

### 🔍 Code Intelligence

- **Content Search** — Search for strings within files with context lines
- **Line Extraction** — Copy specific line ranges from one file to another

### 🖥️ Shell & System

- **Command Execution** — Run shell commands with output capture
- **Background Processes** — Run long commands in background, get PID for later management
- **Working Directory** — Set/get/reset working directory context for operations

---

## Configuration

### Line Identifier Modes

Octofs supports two modes for identifying lines in files:

#### Number Mode (default)

Lines are identified by 1-indexed line numbers:
```
1: fn main() {
2:     println!("Hello");
3: }
```

Use for: Simple operations, one-off edits.

#### Hash Mode

Lines are identified by 4-character hex hashes derived from content:
```
a3bd: fn main() {
c7f2:     println!("Hello");
e9f1: }
```

Use for: Complex multi-step edits where line numbers would shift. Hashes stay stable across edits.

**Enable hash mode:**
```json
{
  "mcpServers": {
    "octofs": {
      "command": "/path/to/octofs",
      "args": ["--line-mode", "hash"]
    }
  }
}
```

### Transport Modes

#### STDIO (default)

Standard input/output transport. Works with all MCP clients.

```bash
octofs  # defaults to STDIO
```

#### HTTP

Streamable HTTP transport for remote access or multi-client scenarios.

```bash
octofs --bind 0.0.0.0:12345
```

Connect clients to `http://localhost:12345/mcp`.

### Working Directory

By default, Octofs operates in the current directory. Specify a different root:

```json
{
  "mcpServers": {
    "octofs": {
      "command": "/path/to/octofs",
      "args": ["--path", "/path/to/your/project"]
    }
  }
}
```

---

## MCP Tools Reference

### `view` — Read files, list directories, search content

**File reading:** (`path` is a single path; `start`/`end` are line numbers or hashes)
```json
{"path": "src/main.rs"}                          // whole file
{"path": "src/main.rs", "start": 10, "end": 20}  // lines 10–20
{"path": "src/main.rs", "start": 42, "end": 42}  // single line
{"path": "src/main.rs", "start": 80}             // line 80 → end of file
{"path": "src/main.rs", "start": "a3bd", "end": "c7f2"}  // hash mode
```

To read several files, make multiple `view` calls — they run in parallel.

**Directory listing:**
```json
{"path": "src/"}
{"path": "src/", "pattern": "*.rs"}
{"path": "src/", "max_depth": 2, "include_hidden": true}
```

**Content search:** (literal by default; set `regex: true` for a Rust regex, `(?i)` = case-insensitive)
```json
{"path": "src", "content": "fn main"}
{"path": "src", "content": "unwrap()", "context": 3}
{"path": "src", "content": "(?i)error", "regex": true}
```

Directory listings annotate each file as `path<TAB>NL<TAB>~Nt` (line count + estimated tokens) so you can budget reads before opening files; binary files show `path<TAB>(binary)`.

---

### `text_editor` — Create, edit, replace text

**Create file:**
```json
{"command": "create", "path": "src/new.rs", "content": "pub fn new() {}"}
```

**Replace string:**
```json
{
  "command": "str_replace",
  "path": "src/main.rs",
  "old_text": "fn old()",
  "new_text": "fn new()"
}
```

**Delete file:** (recoverable with `undo_edit`)
```json
{"command": "delete", "path": "src/old.rs"}
```

**Undo last edit:**
```json
{"command": "undo_edit", "path": "src/main.rs"}
```

---

### `batch_edit` — Atomic multi-operation edits

Perform multiple insert/replace operations on a single file atomically.

Each operation has a `start` (line number or hash). For `insert` it's the anchor
(`0` = file start, `-1` = after last line, `N` = after line N). For `replace` add `end`
for a range (omit `end` for a single line). `start` and `end` must be the same kind —
both line numbers or both hashes (no mixing).

**Insert at beginning:**
```json
{
  "path": "src/main.rs",
  "operations": [
    {"operation": "insert", "start": 0, "content": "// Header\n"}
  ]
}
```

**Replace lines:**
```json
{
  "path": "src/main.rs",
  "operations": [
    {"operation": "replace", "start": 10, "end": 15, "content": "new code here"}
  ]
}
```

**Hash mode (stable across edits):**
```json
{
  "path": "src/main.rs",
  "operations": [
    {"operation": "replace", "start": "a3bd", "end": "c7f2", "content": "new code"}
  ]
}
```

---

### `extract_lines` — Copy lines between files

```json
{
  "from_path": "src/utils.rs",
  "from_start": 10,
  "from_end": 25,
  "append_path": "src/new.rs",
  "append_line": -1
}
```

`from_end` is optional (omit to copy a single line). `from_start`, `from_end`, and
`append_line` each accept a line number or a content hash. `append_line` positions the
copy in the target: `0` = beginning, `-1` = end, `N` = after line N.

---

### `shell` — Execute commands

**Foreground:**
```json
{"command": "cargo test"}
{"command": "cd foo && cargo build"}
```

**Background:**
```json
{"command": "python -m http.server 8000", "background": true}
// Returns PID; the response includes the platform-specific kill command
```

> On Windows, shutdown cleanup terminates only direct child processes (no Unix
> process-group semantics); use `taskk