接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y @muvon/[email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add io.github.muvon-octofs -- npx -y @muvon/octofs@0.25.1在終端機中執行。
{ "mcpServers": { "io.github.muvon-octofs": { "command": "npx", "args": [ "-y", "@muvon/[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令？ 兩種安裝方式的差異
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
MCP Registry: io.github.Muvon/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:
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 │
└─────────────────────────────────────────────────────────────┘
cargo install octofs
brew install muvon/tap/octofs
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"]
}
}
}
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).
Published to the MCP Registry as io.github.Muvon/octofs.
Requires Rust 1.95+.
git clone https://github.com/muvon/octofs
cd octofs
cargo build --release
# Binary at ./target/release/octofs
The CLI uses a mcp subcommand — your config must pass ["mcp"] as args.
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/octofsor./target/release/octofs).
The MCP server starts automatically when your AI assistant connects.
Ask your AI assistant to:
unwrap() in the codebase"test.rs"view in parallel for several), list directories with glob patterns, search content.gitignore patterns during directory traversal-1 = last line)ssh://user@host:port/path URLs (see Remote Filesystem)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 lineEvery line is addressed by a composite id N:hh — its 1-indexed position plus a
2-character hex hash (FNV-1a) of its content. 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).
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.
Standard input/output transport. Works with all MCP clients.
octofs mcp
Streamable HTTP transport for remote access or multi-client scenarios.
octofs mcp --bind 0.0.0.0:12345
Connect clients to http://localhost:12345/mcp.
By default, Octofs operates in the current directory. Specify a different root:
{
"mcpServers": {
"octofs": {
"command": "octofs",
"args": ["mcp", "--path", "/path/to/your/project"]
}
}
}
All path parameters — and --path itself — accept ssh:// or sftp:// URLs:
# Remote session root: relative paths resolve on the remote host
octofs mcp --path ssh://[email protected]/var/www/app --ssh-key ~/.ssh/id_ed25519
view path="ssh://[email protected]/etc/nginx/nginx.conf"
ssh://host (no path) and ssh://host/~/dir resolve against the login user's home, like ssh host / scp host:dir. ssh://host/dir stays absolute.Include and Match) and honor HostName, User, Port, and a single ProxyJump. Explicit URL values win, so both ssh://dev/path and ssh://[email protected]:2222/path work as expected. Multi-hop ProxyJump and ProxyCommand routing are rejected with a clear error.IdentityAgent (e.g. 1Password) or $SSH_AUTH_SOCK, then key files — --ssh-key if given, the host's IdentityFile entries, then the defaults in ~/.ssh (id_ed25519, id_ecdsa). Passphrase-protected key files are not supported directly; use an agent instead.rsa crate has an unfixed timing side-channel (Marvin attack, RUSTSEC-2023-0071), so octofs is built without RSA entirely. Use an ed25519 key instead (ssh-keygen -t ed25519); ecdsa also works. RSA-only setups fail with a clear error naming the key.~/.ssh/known_hosts with the OpenSSH accept-new policy: unknown hosts are recorded on first use, a changed key fails closed.--ssh-timeout SECS — connection timeout (default 30). Connections are pooled per host, kept alive with transport keepalives, and reconnected automatically if they drop.shell stays local — commands always run on the machine where Octofs runs; only file tools (view, text_editor, batch_edit, extract_lines, workdir) reach remote hosts.view — Read files, list directories, search contentFile reading: (path is a single path; start/end are line numbers or line ids)
{"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": -20} // last 20 lines
{"path": "src/main.rs", "start": "12:a3", "end": "20:f1"} // line ids from prior output
Output renders every line as N:hh|content — the N:hh prefix is the line id
that batch_edit and extract_lines take as targets.
To read several files, make multiple view calls — they run in parallel.
Reuse content and line ids already returned. Read a complete relevant function or block
in one call, combining adjacent windows. If its location is unknown, use content with
enough context to understand the matches, then fetch only missing surrounding code.
Do not re-read overlapping ranges or repeatedly narrow a range just to pick edit targets.
Re-read when the file may have changed, output was truncated, or prior context is unavailable.
Empty files return [empty file, 0 lines] on an initial or forced full read.
Delta views: a whole-file view of a file the session already served returns
only the hunks changed since — the same .../-/+ style as edit results, with
removed lines collapsed to their old id range — or
[unchanged since you last viewed or edited it: N lines. Pass full: true to re-read.].
Octofs' own edits keep the cache current, so a re-view after your own batch_edit
costs one line. Ranged views and content search always render exactly what was asked.
full has no effect on ranges or searches; omit start/end and content search to
force a complete file read. It does not change output limits.
{"path": "src/main.rs", "full": true} // force the complete file (e.g. after context compaction)
Directory listing:
{"path": "src/"}
{"path": "src/", "pattern": "*.rs"}
{"path": "src/", "max_depth": 2, "include_hidden": true}
A bare listing of a remote directory (ssh://host/path, no pattern/content)
defaults to max_depth: 1 — root entries only — because every subdirectory costs
an SFTP round trip; pass max_depth explicitly to walk deeper. Searches with
pattern or content always walk the whole tree, like rg.
pattern uses the same gitignore-style glob grammar as ripgrep's -g/--glob:
without / it matches filenames at any depth, while a pattern containing /
matches the returned relative path. It supports * within one path component,
** across directories, ?, character classes such as [abc], brace alternatives
such as *.{rs,toml}, and leading ! exclusions. Use | to pass ordered globs in
one MCP string; later globs take precedence:
{"path": ".", "pattern": "**/*.{rs,toml}|!target/**"}
{"path": ".", "content": "unsafe", "pattern": "src/**/*.rs|!src/generated/**"}
The glob filters files discovered by Octofs' gitignore-aware traversal. Use
include_hidden: true to include hidden paths; gitignored paths remain excluded.
Patterns are limited to 4096 UTF-8 bytes, 64 |-separated rules, and 16 nested
brace levels. They must be a single line and are validated before traversal.
Escape a literal leading # or ! as \# or \!; otherwise # is rejected
instead of silently acting as a gitignore comment. Empty brace alternatives such
as {,rs} are rejected because ripgrep does not support them.
Content search: (literal by default; set regex: true for a Rust regex, (?i) = case-insensitive)
{"path": "src", "content": "fn main"}
{"path": "src", "content": "unwrap()", "context": 3}
{"path": "src", "content": "(?i)error", "regex": true}
{"path": "docs|scripts|BENCHMARK.md", "content": "update_benchmark.py", "context": 4}
For an rg-style search across several roots, path accepts |-separated literal
files and directories when content is set. The roots are not regexes: as with
rg's positional path arguments, each one must exist. A real path containing |
takes precedence over this shorthand. Root lists must be single-line, contain no
duplicates, and are limited to 32 roots and 8192 UTF-8 bytes.
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 textCreate file:
{"command": "create", "path": "src/new.rs", "content": "pub fn new() {}"}
Replace string: (old_text must match exactly once)
{
"command": "str_replace",
"path": "src/main.rs",
"old_text": "fn old()",
"new_text": "fn new()"
}
Replace ALL occurrences (rename-style edits):
{
"command": "str_replace",
"path": "src/main.rs",
"old_text": "old_name",
"new_text": "new_name",
"replace_all": true
}
Matching is progressive: exact → escaped-literal recovery (double-escaped \n/\t
interpreted when the result matches uniquely) → whitespace-normalized fuzzy with
indentation adjustment → rich diagnostics with the closest candidates and their
line ids. CRLF files are matched in LF space and keep their line endings on write.
Delete file: (recoverable with undo_edit)
{"command": "delete", "path": "src/old.rs"}
Undo last edit:
{"command": "undo_edit", "path": "src/main.rs"}
batch_edit — Atomic multi-operation editsPerform multiple insert/replace operations on a single file atomically.
Each operation has a start. For replace it's the first line of the range as a
line id copied from view output (add end for a range; omit it for a single
line). For insert it's the anchor to insert after — a line id, or the integers
0 (file start) / -1 (after last line). Every id is verified against the file
before anything applies; a stale id fails with the current content so the model
can retarget without a re-view. The result is a diff with fresh ids.
Insert at beginning:
{
"path": "src/main.rs",
"operations": [
{"operation": "insert", "start": 0, "content": "// Header\n"}
]
}
Replace lines:
{
"path": "src/main.rs",
"operations": [
{"operation": "replace", "start": "10:4b", "end": "15:c2", "content": "new code here"}
]
}
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 line id ("12:a3", verified against
the file). append_line positions the copy in the target: 0 = beginning,
-1 = end, N = after line N.
shell — Execute commandsCommands start in the foreground and return their output normally when they finish within about 10 seconds:
{"command": "cargo test"}
{"command": "cd foo && cargo build"}
If a command is still running at that boundary, the same process continues in
the background. The response returns its PID and linked output resource, and a
completion notification arrives when it exits. There is no background flag
and the command is never killed or restarted during the handoff. Multiple
distinct commands may run concurrently, including from the same working
directory. An exact duplicate command in the same working directory is rejected
while the first copy is still running.
A client that declares the MCP tasks extension (io.modelcontextprotocol/tasks,
SEP-2663) gets the promoted command as a task whose id is the job id. The client
polls tasks/get and receives the same result a foreground call would have
returned (an error result led by the exit code when the command failed);
tasks/cancel stops the command's process group. While the command runs, the
task's status message names its PID and kill command (kill -- -<pid>), the
elapsed time, and its latest output line.
Other clients get the completion as resources/updated for the job resource (on
a subscriptions/listen stream when the client opened one). Claude Code does not
surface that to the model, so octofs also sends it as a Claude Code channel
message (notifications/claude/channel) on pre-2026-07-28 connections — the
exit code and output tail wake the session. Claude Code accepts channel
messages only from servers enabled for the session, in interactive mode, and
only on pre-2026-07-28 connections. Claude Code negotiates 2026-07-28 with stdio
servers by default, so until it declares the tasks extension, opt out of that as
well:
MCP_PROTOCOL_NEGOTIATION=legacy claude --dangerously-load-development-channels server:octofs
Without it, read the job's resource link when you need the result.
On Windows, shutdown cleanup terminates only direct child processes (no Unix process-group semantics); use
taskkill /PID <pid> /Tfor process trees.
workdir — Manage working directoryGet current:
{}
Set new:
{"path": "/path/to/project"}
Reset to session root:
{"reset": true}
octofs/
├── src/
│ ├── main.rs # Entry point, STDIO/HTTP server setup, signal handling
│ ├── cli.rs # CLI argument parsing (clap): octofs mcp [OPTIONS]
│ ├── mcp/
│ │ ├── mod.rs # McpToolCall, SessionRoot
│ │ ├── server.rs # OctofsServer (rmcp tool impl), Params structs, SessionWorkdir
│ │ ├── request_ctx.rs # Per-request hint queue + stale-file stamps
│ │ └── fs/ # Filesystem tool implementations
│ │ ├── mod.rs # Re-exports
│ │ ├── core.rs # view, text_editor, batch_edit, extract_lines
│ │ ├── file_ops.rs # view_file_spec, create_file_spec
│ │ ├── text_editing.rs # str_replace, batch_edit, undo, per-file locking
│ │ ├── directory.rs # Directory listing + content search
│ │ ├── search.rs # search_content
│ │ ├── shell.rs # Command execution, background, process cleanup
│ │ ├── workdir.rs # Working directory management
│ │ ├── remote.rs # SSH/SFTP path abstraction, SshHandler, SFTP pool
│ │ └── fs_tests.rs # Integration tests (cfg(test))
│ └── utils/
│ ├── mod.rs # Module re-exports
│ ├── line_hash.rs # Composite line ids (N:hh), FNV-1a hashes, endpoint parsing
│ └── truncation.rs # Token estimation, smart truncation
Key design decisions:
rmcp 3.x) for protocol handlingtokio::fs, never blocking std::fstokio::sync::Mutex prevents concurrent write conflictsN:hh id is verified against the file at apply time; a stale id fails with the current content instead of editing the wrong line# Build
cargo build --release
# Run tests
cargo test
# Lint (zero warnings policy)
cargo clippy
# Format
cargo fmt
# Run locally
cargo run -- mcp
# All tests
cargo test
# Specific test
cargo test test_view_file
# With output
cargo test -- --nocapture
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Quick checklist:
cargo fmt before committingcargo clippy passes with zero warningsSee SECURITY.md for security policy and reporting vulnerabilities.
Apache-2.0 — See LICENSE
Built with 🦀 by Muvon
Star us on GitHub if Octofs helps you ship faster! ⭐
Standalone MCP filesystem tools server — view, edit, shell, workdir.
{ "mcpServers": { "io.github.muvon-octofs": { "command": "npx", "args": [ "-y", "@muvon/[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式，而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Octofs 透過 stdio 在本機執行。
上次檢查時間：2026-11-15。 Standalone MCP filesystem tools server — view, edit, shell, workdir.