markdownfs

A high-performance, concurrent markdown database built in Rust. Supports Unix-like commands, Git-style versioning with content-addressable storage, disk persistence, multi-user permissioning, HTTP/REST API, and MCP (Model Context Protocol) for AI agents.

mdfs is also a strong fit for agent workspace use cases: durable markdown memory, inspectable artifacts, search, permissions, commits, and rollback in one shared surface.

Only Markdown (.md) files are supported by design.

🚀 Live demo: subramanya97-markdownfs.hf.space — a free Hugging Face Space running this exact binary. Web UI, REST, and MCP all available at one URL.

📚 Docs: docs.markdownfs.com · 🤗 Space: huggingface.co/spaces/Subramanya97/markdownfs

Access Methods

mdfs can be used five ways:

All transports share the same concurrent core (MarkdownDb) with tokio::RwLock for safe multi-reader/single-writer access.

📚 Full documentation: docs.markdownfs.com

Quick Start

CLI

cargo build --release
cargo run --release --bin markdownfs

On first launch, you create an admin account. mdfs sets up your home directory and drops you right in:

markdownfs v0.2.0 — Markdown Virtual File System

Welcome! Let's set up your account.
Admin username: alice

Created admin 'alice' (uid=1, groups=[alice, wheel])
Home directory: /home/alice

Type 'help' for available commands, 'exit' to quit.

alice@markdownfs:~ $ touch hello.md
alice@markdownfs:~ $ write hello.md # Welcome to mdfs
alice@markdownfs:~ $ cat hello.md
# Welcome to mdfs

HTTP Server

MARKDOWNFS_LISTEN=127.0.0.1:3000 cargo run --release --bin mdfs-server

MCP Server

cargo run --release --bin mdfs-mcp

Add to your MCP client config (e.g., Cursor mcp.json):

{
  "mcpServers": {
    "mdfs": {
      "command": "/path/to/mdfs-mcp",
      "env": {
        "MARKDOWNFS_DATA_DIR": "/path/to/data"
      }
    }
  }
}

Documentation

Detailed guides are available in the docs/ folder:

Examples

Example demo content lives in examples/:

HTTP API Reference

All endpoints accept Authorization: Bearer <token> or Authorization: User <username> headers.

Filesystem

Search

Version Control

Auth & Health

Example

# Write a file
curl -X PUT http://localhost:3000/fs/docs/readme.md \
  -H "Authorization: User alice" \
  -d "# Hello World"

# Read it back
curl http://localhost:3000/fs/docs/readme.md

# Commit
curl -X POST http://localhost:3000/vcs/commit \
  -H "Content-Type: application/json" \
  -d '{"message": "initial commit"}'

# Search
curl "http://localhost:3000/search/grep?pattern=Hello&recursive=true"

MCP Tools

The MCP server exposes these tools for AI agents:

CLI Commands

File Operations

User Management

Version Control

Configuration

Environment variables:

Architecture

src/
  db.rs            Concurrent MarkdownDb (Arc<RwLock<DbInner>>)
  config.rs        Configuration from env vars
  server/          HTTP/REST API (axum)
    mod.rs           Router setup
    routes_fs.rs     Filesystem endpoints
    routes_vcs.rs    VCS endpoints
    routes_auth.rs   Auth + health endpoints
    middleware.rs    Auth extraction
  bin/
    mdfs_server.rs  HTTP server binary
    mdfs_mcp.rs     MCP server binary
    mdfs_mount.rs   FUSE mount binary
  auth/            Multi-user identity & permissions
    mod.rs           User, Group types
    registry.rs      UserRegistry CRUD
    perms.rs         Permission checks
    session.rs       Session context
  cmd/             Command dispatch & pipes
  fs/              Virtual filesystem core
    mod.rs           VirtualFs — inodes, path resolution, all ops
    inode.rs         Inode types
  store/           Content-addressable object store
  vcs/             Version control (commit, revert, log)
  persist.rs       Disk persistence (atomic bincode)
  error.rs         VfsError enum
  main.rs          CLI/REPL binary

Performance

~102.8x average speedup over native filesystem in the latest release benchmark run (in-memory, zero-copy reads, content-addressable dedup).

cargo test --release --test perf -- --nocapture
cargo test --release --test perf_comparison -- --nocapture

Testing

239 tests across 5 suites:

cargo test                        # all tests (18 unit + 111 integration + 37 perf + 1 perf_comparison + 72 permissions)
cargo test --test integration     # 111 integration tests
cargo test --test permissions     # 72 permission tests
cargo test --test perf --release  # 37 perf benchmarks

Docs site

The MkDocs source lives in docs/. Build locally with:

uv sync
uv run mkdocs serve   # http://localhost:8000
uv run mkdocs build --strict

CI deploys to docs.markdownfs.com on every push to master. See .github/workflows/docs.yml.

License

MIT