Octofs

🐙 Octofs

Give your AI assistant filesystem superpowers

*Standalone Rust binary that exposes filesystem tools over the Model Context Protocol. Built on rmcp 3.x, tokio, and axum.*

Installation · Quick Start · Features · Tools Reference · Docs · Architecture · Changelog · Contributing · Good first issues

MCP Registry: io.github.Muvon/octofs

---

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
• Reach — Transparent SSH/SFTP: every file tool accepts ssh:// URLs

┌─────────────────────────────────────────────────────────────┐

│ 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: │ │ • Reads your codebase directly │ │ • Finds all error handling patterns │ │ • Suggests atomic batch edits │ │ • Applies changes with your approval │ └─────────────────────────────────────────────────────────────┘

What Makes It Different

---

Installation

Cargo (crates.io)

cargo install octofs

Homebrew

brew install muvon/tap/octofs

npm (no Rust toolchain needed)

npx -y @muvon/octofs --version

The wrapper downloads the matching pre-built binary on first run. MCP config:

{

"mcpServers": { "octofs": { "command": "npx", "args": ["-y", "@muvon/octofs", "mcp"] } } }

Pre-built Binaries

Download from GitHub Releases for your platform:

Each release also ships .mcpb bundles for one-click install in clients that support MCP bundles (e.g. Claude Desktop).

MCP Registry

Published to the MCP Registry as io.github.Muvon/octofs.

From Source

Requires Rust 1.95+.

git clone https://github.com/muvon/octofs

cd octofs cargo build --release

Binary at ./target/release/octofs

---

Quick Start

Pair with Octocode

The shared-ID workflow requires the next Octocode release or a build of the updated source. OctoFS’s existing line-ID format is unchanged.

Use Octocode to find definitions, usages, and code relationships, then use OctoFS to read or edit the matching files. Octocode's MCP structural_search emits the same N:hh|content source line IDs that OctoFS accepts for batch_edit, using their shared Octolib utility. You do not need another view just to obtain IDs for lines already returned.

Run both servers against the same checkout. IDs describe that source snapshot: changed targets are verified at edit time, and an error supplies current context rather than guessing where to write. Exact-name lookups return complete small definitions; previews of larger matches name the ranges you can read with OctoFS.

1. Configure Your AI Assistant

The CLI uses a mcp subcommand — your config must pass ["mcp"] as args.

Claude Code (CLI):

claude mcp add octofs -- octofs mcp --path /path/to/your/project

claude mcp add octocode -- octocode mcp --path /path/to/your/project

Codex CLI:

codex mcp add octofs -- octofs mcp --path /path/to/your/project

codex mcp add octocode -- octocode mcp --path /path/to/your/project codex mcp list

The Octocode registration is optional. Install the servers you use and replace the paths with the same absolute checkout path. See the official Codex MCP documentation.

Cursor (~/.cursor/mcp.json):

{

"mcpServers": { "octofs": { "command": "octofs", "args": ["mcp"] } } }

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{

"mcpServers": { "octofs": { "command": "octofs", "args": ["mcp"] } } }

Windsurf (~/.windsurf/mcp.json):

{

"mcpServers": { "octofs": { "command": "octofs", "args": ["mcp"] } } }

If Octofs isn't on your PATH, use the full path to the binary (e.g. /usr/local/bin/octofs or ./target/release/octofs).

2. Restart Your AI Assistant

The MCP server starts 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 windows
• Gitignore-Aware — Respects .gitignore patterns during directory traversal
• Line Ranges — Read specific line ranges with negative indexing (-1 = last line)
• Remote Files (SSH/SFTP) — Every file tool accepts ssh://user@host:port/path URLs (see Remote Filesystem)

✏️ 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, in-memory)
• Batch Edit — Perform multiple insert/replace operations atomically on a single file
• Stale-Write Protection — Every edit target's N:hh id is verified against the file at apply time; a stale id fails with the current content and where it moved, instead of editing the wrong line

🔍 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 — Long commands automatically continue in background with completion notifications
• Working Directory — Set/get/reset working directory context for operations

---

Configuration

Line Identifiers

Every line is addressed by a composite id N:hh — its 1-indexed position plus a 2-character hex hash (FNV-1a) of its content. Octocode structural-search source output uses the same shared utility and IDs. view renders lines as N:hh|content:

1:a3|fn main() {

2:f1| println!("Hello"); 3:0e|}

Edit tools take these ids back as targets and verify the hash against the file before applying anything. A stale id (the file changed since it was viewed) fails with the current content around the target and where the expected content moved — so the model retargets from the error instead of re-reading the file. Edit results are diffs with fresh ids, so edits chain without re-viewing. Removed lines collapse to their old id range (-12:a3..15:f1 (4 lines)), and a trailing shift: lines after 40:b2 +3 line says how original line numbers below each edit moved, so ids the model still holds can be adjusted without a failed call.

This is the single line-id format — there is no mode switch. Plain line numbers are still accepted where a position alone is safe: view ranges (negative counts from the end) and the insert anchors 0 (file start) / -1 (append).

Shell Misuse Enforcement

Octofs detects shell misuse — commands like cat, grep, find, or sed that should use the dedicated MCP tools instead — and rejects them with an error explaining which tool to use. The call fails; nothing executes. This is intentional and not configurable: the dedicated tools give the model line ids, gitignore-awareness, and remote-host support that raw shell output cannot. Pipelines (cargo build 2>&1 | grep error) remain allowed — only standalone invocations of those programs are blocked.

Other guidance (out-of-bounds ranges, fuzzy-match notices) is appended to successful responses as ⚠️ hints without failing the call.

Transport Modes

STDIO (default)

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

octofs mcp

HTTP

Streamable HTTP transport for remote access or multi-client scenarios. Every tool, shell included, is reachable by whoever can connect, so access is gated:

# Loopback, no token: requests carrying a browser Origin header are rejected

octofs mcp --bind 127.0.0.1:12345

Any other address requires a bearer token; octofs refuses to start without one

OCTOFS_AUTH_TOKEN="$(openssl rand -hex 32)" octofs mcp --bind 0.0.0.0:12345

Connect clients to http://localhost:12345/mcp; with a token they send Authorization: Bearer . The server speaks plain HTTP, so put it behind TLS or an SSH tunnel when the token crosses a network. --auth-token works too, but command-line arguments are visible to other local users.

Working Directory

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

{

"mcpServers": { "octofs": { "command": "octo