fsp-py 0.0.1

File System Protocol — an MCP server exposing file system operations for a Plan 9–style mountable agent environment.

fsp — File System Protocol

pip install fsp-py
# or
uv add fsp-py

fsp is an MCP server that exposes file system operations over a uniform namespace. It is the first piece of a Plan 9–style mountable agent environment: any backend (local disk, database, vector store, remote service) can be projected as a path tree and accessed through a small set of composable tools.

The Unix design principles — uniform namespace, small composable tools, portability — have carried computing for fifty years. fsp brings them to agents over MCP.

What ships in 0.0.1

A minimal local-disk implementation of the file system surface:

• CRUD — read, write, edit, delete, move, copy, mkdir
• Navigation — ls, tree, stat
• Pattern Search — glob, grep

Stubs are present for retrieval (semantic_search, lexical_search, vector_search), graph traversal, graph ranking, and the query engine — they return a structured "not implemented" FSPResult so clients can discover the full surface today and pick up real implementations as later releases land their backends.

The only runtime dependency is mcp.

Run the server

# stdio (default — for desktop MCP clients)
fsp --root /path/to/expose

# HTTP/SSE
fsp --root /path/to/expose --transport sse --host 127.0.0.1 --port 8000

Use it from Python

from fsp import FSP

fs = FSP(root="/workspace")
print(fs.ls("/").data)
fs.write("/notes/today.md", "hello")
print(fs.grep("hello").data)

Every method returns the same FSPResult shape — ok, path, data, error, meta — so the output of one call can feed the next.

Roadmap

• mkconn and add_mount — multi-backend mount routing
• Database, vector store, and remote service backends
• Retrieval, graph traversal, and graph ranking implementations
• Query engine and CLI passthrough

License

Apache-2.0.