octofs

<div align="center">

🐙 Octofs

Give your AI assistant filesystem superpowers

   

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

Installation • Quick Start • Features • 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+.

# 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 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"] } } } ``

Hint Modes

Octofs detects shell misuse — commands like cat, grep, find, or sed that should use the dedicated MCP tools instead — and can enforce it in two modes:

Hard Mode (default)

The command is rejected with an error explaining which tool to use instead. The call fails; nothing executes.

Soft Mode

The command runs anyway, and the guidance is appended to the tool response as a ⚠️ hint.

Enable soft mode: ``json { "mcpServers": { "octofs": { "command": "/path/to/octofs", "args": ["--hint-mode", "soft"] } } } ``

Transport Modes

STDIO (default)

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

octofs  # defaults to STDIO

HTTP

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

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:

{
  "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} ``

pattern is a glob, not a content search: without / it matches the whole filename at any depth; with / it matches the workdir-relative path. It supports , ?, character classes such as [abc], and | alternatives such as .rs|*.toml.

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

{
  "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 taskkill /PID <pid> /T for process trees.

---

workdir — Manage working directory

Get current: ``json {} ``

Set new: ``json {"path": "/path/to/project"} ``

Reset to session root: ``json {"reset": true} ``

---

Architecture

octofs/
├── src/
│   ├── main.rs              # Entry point, STDIO/HTTP server setup
│   ├── cli.rs               # CLI argument parsing (clap)
│   └── mcp/
│       ├── server.rs        # MCP protocol handler (rmcp SDK)
│       ├── request_ctx.rs   # Per-request hints + stale-file stamps
│       └── fs/              # Filesystem tools
│           ├── core.rs          # view, batch_edit, extract_lines, text_editor
│           ├── text_editing.rs  # str_replace, undo, batch operations
│           ├── directory.rs     # Directory traversal
│           ├── file_ops.rs       # File operations
│           ├── search.rs          # Content search
│           ├── shell.rs           # Command execution
│           ├── workdir.rs         # Working directory management
│           └── fs_tests.rs        # Unit tests
└── src/utils/
    ├── line_hash.rs         # Content-based line hashing
    └── truncation.rs        # Smart content truncation

Key components:

• rmcp SDK — Official Rust MCP SDK for protocol handling
• Tokio — Async runtime for concurrent operations
• File locking — Per-file async locks prevent concurrent write conflicts
• Undo history — Up to 10 undo levels per file, thread-safe storage

---

Development

# Build
cargo build --release

# Run tests
cargo test

# Lint (zero warnings policy)
cargo clippy

# Format
cargo fmt

# Run locally
cargo run

Running Tests

# All tests
cargo test

# Specific test
cargo test test_view_file

# With output
cargo test -- --nocapture

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick checklist:

1. Run cargo fmt before committing
2. Ensure cargo clippy passes with zero warnings
3. Add tests for new functionality
4. Update documentation as needed

---

Security

See SECURITY.md for security policy and reporting vulnerabilities.

---

License

Apache-2.0 — See LICENSE

---

Acknowledgments

• rmcp — Official Rust MCP SDK
• Model Context Protocol — The protocol specification

---

<div align="center">

Built with 🦀 by Muvon

Star us on GitHub if Octofs helps you ship faster! ⭐

</div>