README.md

metadata

title: MarkdownFS
emoji: 📝
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: true
license: mit
short_description: Versioned markdown FS for AI agents — REST + MCP + UI.
tags:
  - agent
  - mcp
  - filesystem
  - rust
  - markdown
  - vcs

MarkdownFS

A versioned virtual filesystem for markdown — built for AI agents, runnable on a free Hugging Face Space.

Every commit, write, search, permission check, and MCP call you see in the app is the same Rust binary you can run locally. One database, three transports, zero lock-in.

What it does

• Markdown-only filesystem with Unix-style permissions, users, groups, and tokens.
• Git-style version control — commit working state, browse log, revert to any snapshot.
• Search across content (grep) and names (find), permission-aware.
• Three transports sharing one database:
  • Web UI at / — tree, viewer/editor, commits, search, admin panel.
  • REST API under /fs, /vcs, /search, /admin, /auth — for any HTTP client.
  • MCP server at /mcp — drop-in agent memory for Claude Desktop, Cursor, or any MCP client.

Try it now

Click the App tab above to open the live UI. On first visit you'll create the admin account and get an API token — save it.

Use it from your code

// TypeScript
import { MarkdownFS } from "markdownfs";
const mdfs = new MarkdownFS({
  baseUrl: "https://subramanya97-markdownfs.hf.space",
  token: process.env.MDFS_TOKEN,
});
await mdfs.fs.write("notes/idea.md", "# my idea");
const text = await mdfs.fs.read("notes/idea.md");
await mdfs.vcs.commit("first note");

# Python
from markdownfs import MarkdownFS
mdfs = MarkdownFS(base_url="https://subramanya97-markdownfs.hf.space",
                  token=os.environ["MDFS_TOKEN"])
mdfs.fs.write("notes/idea.md", "# my idea")
print(mdfs.fs.read("notes/idea.md"))

# curl
SPACE=https://subramanya97-markdownfs.hf.space
curl -X PUT  "$SPACE/fs/notes/idea.md" -H "Authorization: Bearer $TOK" --data-binary "# my idea"
curl         "$SPACE/fs/notes/idea.md" -H "Authorization: Bearer $TOK"
curl -X POST "$SPACE/vcs/commit"        -H "Authorization: Bearer $TOK" -H 'content-type: application/json' -d '{"message":"first note"}'

Use it from Claude Desktop / Cursor (MCP)

Add this to your client's MCP config:

{
  "mcpServers": {
    "markdownfs": {
      "type": "http",
      "url": "https://subramanya97-markdownfs.hf.space/mcp"
    }
  }
}

The agent now has 11 tools: read_file, write_file, list_directory, search_files, find_files, create_directory, delete_file, move_file, commit, get_history, revert. Every call respects Unix permissions on the Space.

Agent acting on behalf of a user

Send X-MarkdownFS-On-Behalf-Of: <username> alongside your token. The session's permissions become the intersection of agent + user (least privilege). Useful when an autonomous agent should only do what one specific user could do.

Multi-user from the UI

The admin panel (👥 button, top-right when signed in as a wheel member) lets you:

• Create users (with optional agent flag)
• Issue / regenerate API tokens
• Add users to groups
• chmod / chown any file or directory
• Delete users

User homes default to 0700 so tenants are isolated by default.

Persistence

This Space mounts a Hugging Face Persistent Storage volume at /data. To enable it, set MARKDOWNFS_DATA_DIR=/data under Settings → Variables and secrets and restart. Without persistent storage, data is wiped on every container restart.

Configuration

Variable	Default	Notes
MARKDOWNFS_DATA_DIR	/home/mdfs/data	Set to /data for persistence
MARKDOWNFS_LISTEN	0.0.0.0:7860	HF routes traffic here
MARKDOWNFS_AUTOSAVE_SECS	5	Auto-save interval
MARKDOWNFS_MAX_FILE_SIZE	10485760 (10 MB)
RUST_LOG	markdownfs=info

Run it elsewhere

# Docker
docker run -p 7860:7860 ghcr.io/subramanya1997/markdownfs:latest

# Build from source (Rust 1.85+)
git clone https://github.com/subramanya1997/markdownfs && cd markdownfs
cargo build --release && ./target/release/mdfs-server

Full docs at docs.markdownfs.com.