Metadata-Version: 2.4
Name: fsp-py
Version: 0.0.1
Summary: File System Protocol — an MCP server exposing file system operations for a Plan 9–style mountable agent environment.
Project-URL: Homepage, https://github.com/ClayGendron/fsp
Project-URL: Repository, https://github.com/ClayGendron/fsp
Project-URL: Issues, https://github.com/ClayGendron/fsp/issues
Author: Clay Gendron
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,file-system,llm,mcp,plan9
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2
Description-Content-Type: text/markdown

# `fsp` — File System Protocol

```bash
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

```bash
# 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

```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.
