[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1515":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":21,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":14,"starSnapshotCount":14,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},1515,"markdownfs","subramanya1997\u002Fmarkdownfs","subramanya1997","A high-performance, in-memory virtual file system for Markdown files. Unix-like commands, Git-style versioning, content-addressable storage, and multi-user permissions — built in Rust.",null,"Rust",215,15,206,0,1,4,3,43.51,false,"master",true,[],"2026-06-12 04:00:10","# markdownfs\n\nA 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\u002FREST API, and MCP (Model Context Protocol) for AI agents.\n\n`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.\n\nOnly Markdown (`.md`) files are supported by design.\n\n> **🚀 Live demo:** [`subramanya97-markdownfs.hf.space`](https:\u002F\u002Fsubramanya97-markdownfs.hf.space) — a free Hugging Face Space running this exact binary. Web UI, REST, and MCP all available at one URL.\n>\n> **📚 Docs:** [docs.markdownfs.com](https:\u002F\u002Fdocs.markdownfs.com\u002F) · **🤗 Space:** [huggingface.co\u002Fspaces\u002FSubramanya97\u002Fmarkdownfs](https:\u002F\u002Fhuggingface.co\u002Fspaces\u002FSubramanya97\u002Fmarkdownfs)\n\n## Access Methods\n\nmdfs can be used five ways:\n\n| Method | Surface | Use Case |\n|---|---|---|\n| **CLI\u002FREPL** | `markdownfs` binary | Interactive terminal use |\n| **HTTP\u002FREST API** | `mdfs-server` binary | Web apps, services, any HTTP client |\n| **MCP Server** | `mdfs-mcp` binary | AI agents (Cursor, Claude, etc.) |\n| **TypeScript SDK** | `markdownfs` on npm | Node 18+ \u002F browsers, via Bun or npm |\n| **Python SDK** | `markdownfs` on PyPI | Python 3.9+, sync and async |\n\nAll transports share the same concurrent core (`MarkdownDb`) with `tokio::RwLock` for safe multi-reader\u002Fsingle-writer access.\n\n📚 **Full documentation:** [docs.markdownfs.com](https:\u002F\u002Fdocs.markdownfs.com\u002F)\n\n## Quick Start\n\n### CLI\n\n```bash\ncargo build --release\ncargo run --release --bin markdownfs\n```\n\nOn first launch, you create an admin account. mdfs sets up your home directory and drops you right in:\n\n```\nmarkdownfs v0.2.0 — Markdown Virtual File System\n\nWelcome! Let's set up your account.\nAdmin username: alice\n\nCreated admin 'alice' (uid=1, groups=[alice, wheel])\nHome directory: \u002Fhome\u002Falice\n\nType 'help' for available commands, 'exit' to quit.\n\nalice@markdownfs:~ $ touch hello.md\nalice@markdownfs:~ $ write hello.md # Welcome to mdfs\nalice@markdownfs:~ $ cat hello.md\n# Welcome to mdfs\n```\n\n### HTTP Server\n\n```bash\nMARKDOWNFS_LISTEN=127.0.0.1:3000 cargo run --release --bin mdfs-server\n```\n\n### MCP Server\n\n```bash\ncargo run --release --bin mdfs-mcp\n```\n\nAdd to your MCP client config (e.g., Cursor `mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"mdfs\": {\n      \"command\": \"\u002Fpath\u002Fto\u002Fmdfs-mcp\",\n      \"env\": {\n        \"MARKDOWNFS_DATA_DIR\": \"\u002Fpath\u002Fto\u002Fdata\"\n      }\n    }\n  }\n}\n```\n\n## Documentation\n\nDetailed guides are available in the [`docs\u002F`](docs\u002F) folder:\n\n| Guide | Description |\n|---|---|\n| [Getting Started](docs\u002Fgetting-started.md) | Install, build, first run walkthrough for CLI, HTTP, and MCP |\n| [User Management](docs\u002Fuser-management.md) | Users, groups, permissions, chmod\u002Fchown, delegation, team setup |\n| [Filesystem Guide](docs\u002Ffilesystem-guide.md) | Files, directories, search, pipes, symlinks |\n| [Version Control](docs\u002Fversion-control.md) | Commit, log, revert, deduplication |\n| [HTTP API Guide](docs\u002Fhttp-api-guide.md) | Full REST endpoint reference with curl examples |\n| [MCP Guide](docs\u002Fmcp-guide.md) | AI agent integration, tool reference, setup for Cursor\u002FClaude |\n| [Agent Workspace Positioning](docs\u002Fagent-workspace-positioning.md) | Messaging, category, narrative, and competitive framing |\n| [Agent Workspace Demo](docs\u002Fagent-workspace-demo.md) | Runnable 7-minute demo using CLI tools and the HTTP API |\n| [Demo Readiness](docs\u002Fdemo-readiness.md) | Which gaps matter before the first polished demo |\n| [Semantic Index](docs\u002Fsemantic-index.md) | Vector-based retrieval as a derived index over markdown workspaces |\n| [Execution Roadmap](docs\u002Fexecution-roadmap.md) | How to evolve from workspace layer to execution layer |\n\n## Examples\n\nExample demo content lives in [`examples\u002F`](examples\u002F):\n\n| Example | Description |\n|---|---|\n| [Incident Workspace](examples\u002Fincident-workspace\u002FREADME.md) | Seed markdown files for the agent-workspace demo |\n| [Notebook Examples](examples\u002Fnotebooks\u002FREADME.md) | Jupyter walkthroughs for getting started, mounting, and user-to-agent delegation |\n\n## HTTP API Reference\n\nAll endpoints accept `Authorization: Bearer \u003Ctoken>` or `Authorization: User \u003Cusername>` headers.\n\n### Filesystem\n\n| Method | Endpoint | Description |\n|---|---|---|\n| `GET` | `\u002Ffs\u002F{path}` | Read file (markdown) or list directory (JSON) |\n| `PUT` | `\u002Ffs\u002F{path}` | Write file or create directory (`X-Markdownfs-Type: directory`) |\n| `DELETE` | `\u002Ffs\u002F{path}?recursive=true` | Delete file or directory |\n| `POST` | `\u002Ffs\u002F{path}?op=copy&dst=...` | Copy file |\n| `POST` | `\u002Ffs\u002F{path}?op=move&dst=...` | Move file |\n| `GET` | `\u002Ffs\u002F{path}?stat=true` | File metadata (JSON) |\n\n### Search\n\n| Method | Endpoint | Description |\n|---|---|---|\n| `GET` | `\u002Fsearch\u002Fgrep?pattern=...&path=...&recursive=true` | Search file contents |\n| `GET` | `\u002Fsearch\u002Ffind?path=...&name=...` | Find files by glob |\n| `GET` | `\u002Ftree\u002F{path}` | Directory tree |\n\n### Version Control\n\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `\u002Fvcs\u002Fcommit` | Commit (`{\"message\": \"...\"}`) |\n| `GET` | `\u002Fvcs\u002Flog` | Commit history |\n| `POST` | `\u002Fvcs\u002Frevert` | Revert (`{\"hash\": \"...\"}`) |\n| `GET` | `\u002Fvcs\u002Fstatus` | Status |\n\n### Auth & Health\n\n| Method | Endpoint | Description |\n|---|---|---|\n| `POST` | `\u002Fauth\u002Flogin` | Login (`{\"username\": \"...\"}`) |\n| `GET` | `\u002Fhealth` | Health check + stats |\n\n### Example\n\n```bash\n# Write a file\ncurl -X PUT http:\u002F\u002Flocalhost:3000\u002Ffs\u002Fdocs\u002Freadme.md \\\n  -H \"Authorization: User alice\" \\\n  -d \"# Hello World\"\n\n# Read it back\ncurl http:\u002F\u002Flocalhost:3000\u002Ffs\u002Fdocs\u002Freadme.md\n\n# Commit\ncurl -X POST http:\u002F\u002Flocalhost:3000\u002Fvcs\u002Fcommit \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"message\": \"initial commit\"}'\n\n# Search\ncurl \"http:\u002F\u002Flocalhost:3000\u002Fsearch\u002Fgrep?pattern=Hello&recursive=true\"\n```\n\n## MCP Tools\n\nThe MCP server exposes these tools for AI agents:\n\n| Tool | Description |\n|---|---|\n| `read_file` | Read a markdown file by path |\n| `write_file` | Write content to a file (creates if needed) |\n| `list_directory` | List files in a directory |\n| `search_files` | Grep for a pattern across files |\n| `find_files` | Find files by glob pattern |\n| `create_directory` | Create a directory (with parents) |\n| `delete_file` | Delete a file or directory |\n| `move_file` | Move or rename |\n| `commit` | Commit current state |\n| `get_history` | Show commit log |\n| `revert` | Revert to a commit |\n\n## CLI Commands\n\n### File Operations\n\n| Command | Description |\n|---|---|\n| `ls [-l] [path]` | List directory contents (filtered by permission) |\n| `cd [path]` | Change directory |\n| `pwd` | Print working directory |\n| `mkdir [-p] \u003Cpath>` | Create directory |\n| `touch \u003Cfile.md>` | Create empty markdown file |\n| `cat \u003Cfile>` | Display file contents |\n| `write \u003Cfile> [content]` | Write content to file |\n| `edit \u003Cfile.md>` | Multi-line editor with auto-commit |\n| `rm [-r] \u003Cpath>` | Remove file or directory |\n| `mv \u003Csrc> \u003Cdst>` | Move or rename |\n| `cp \u003Csrc> \u003Cdst>` | Copy file |\n| `stat \u003Cpath>` | Show metadata |\n| `tree [path]` | Directory tree |\n| `find [path] [-name pattern]` | Find files |\n| `grep [-r] \u003Cpattern> [path]` | Search contents |\n| `chmod \u003Cmode> \u003Cpath>` | Change permissions |\n| `chown \u003Cuser:group> \u003Cpath>` | Change ownership |\n| `ln -s \u003Ctarget> \u003Clink>` | Symbolic link |\n\n### User Management\n\n| Command | Description |\n|---|---|\n| `adduser \u003Cname>` | Create user with home directory (admin only) |\n| `addagent \u003Cname>` | Create agent with API token |\n| `deluser \u003Cname>` | Delete user (root only) |\n| `addgroup \u003Cname>` | Create group |\n| `delgroup \u003Cname>` | Delete group |\n| `usermod -aG \u003Cgroup> \u003Cuser>` | Add user to group |\n| `groups [user]` | Show group memberships |\n| `whoami` | Show current user |\n| `su \u003Cuser>` | Switch user |\n\n### Version Control\n\n| Command | Description |\n|---|---|\n| `commit \u003Cmessage>` | Snapshot state |\n| `log` | Show history |\n| `revert \u003Chash>` | Revert to commit |\n| `status` | Summary |\n\n## Configuration\n\nEnvironment variables:\n\n| Variable | Default | Description |\n|---|---|---|\n| `MARKDOWNFS_DATA_DIR` | Current directory | Data storage directory |\n| `MARKDOWNFS_LISTEN` | `127.0.0.1:3000` | HTTP server listen address |\n| `MARKDOWNFS_AUTOSAVE_SECS` | `5` | Auto-save interval (seconds) |\n| `MARKDOWNFS_AUTOSAVE_WRITES` | `100` | Auto-save after N writes |\n| `MARKDOWNFS_MAX_FILE_SIZE` | `10485760` (10MB) | Maximum file size |\n| `MARKDOWNFS_MAX_INODES` | `1000000` | Maximum number of inodes |\n| `MARKDOWNFS_MAX_DEPTH` | `256` | Maximum directory depth |\n| `RUST_LOG` | `markdownfs=info` | Log level (tracing) |\n\n## Architecture\n\n```\nsrc\u002F\n  db.rs            Concurrent MarkdownDb (Arc\u003CRwLock\u003CDbInner>>)\n  config.rs        Configuration from env vars\n  server\u002F          HTTP\u002FREST API (axum)\n    mod.rs           Router setup\n    routes_fs.rs     Filesystem endpoints\n    routes_vcs.rs    VCS endpoints\n    routes_auth.rs   Auth + health endpoints\n    middleware.rs    Auth extraction\n  bin\u002F\n    mdfs_server.rs  HTTP server binary\n    mdfs_mcp.rs     MCP server binary\n    mdfs_mount.rs   FUSE mount binary\n  auth\u002F            Multi-user identity & permissions\n    mod.rs           User, Group types\n    registry.rs      UserRegistry CRUD\n    perms.rs         Permission checks\n    session.rs       Session context\n  cmd\u002F             Command dispatch & pipes\n  fs\u002F              Virtual filesystem core\n    mod.rs           VirtualFs — inodes, path resolution, all ops\n    inode.rs         Inode types\n  store\u002F           Content-addressable object store\n  vcs\u002F             Version control (commit, revert, log)\n  persist.rs       Disk persistence (atomic bincode)\n  error.rs         VfsError enum\n  main.rs          CLI\u002FREPL binary\n```\n\n## Performance\n\n~102.8x average speedup over native filesystem in the latest release benchmark run (in-memory, zero-copy reads, content-addressable dedup).\n\n```bash\ncargo test --release --test perf -- --nocapture\ncargo test --release --test perf_comparison -- --nocapture\n```\n\n## Testing\n\n239 tests across 5 suites:\n\n```bash\ncargo test                        # all tests (18 unit + 111 integration + 37 perf + 1 perf_comparison + 72 permissions)\ncargo test --test integration     # 111 integration tests\ncargo test --test permissions     # 72 permission tests\ncargo test --test perf --release  # 37 perf benchmarks\n```\n\n## Docs site\n\nThe MkDocs source lives in `docs\u002F`. Build locally with:\n\n```bash\nuv sync\nuv run mkdocs serve   # http:\u002F\u002Flocalhost:8000\nuv run mkdocs build --strict\n```\n\nCI deploys to [docs.markdownfs.com](https:\u002F\u002Fdocs.markdownfs.com\u002F) on every push to `master`. See `.github\u002Fworkflows\u002Fdocs.yml`.\n\n## License\n\nMIT\n","markdownfs 是一个高性能的内存虚拟文件系统，专为 Markdown 文件设计。它使用 Rust 语言构建，支持类 Unix 命令、Git 风格的版本控制、内容寻址存储以及多用户权限管理。该项目还提供了 HTTP\u002FREST API 和 MCP（Model Context Protocol）接口，适用于 AI 代理的工作空间需求，如持久化的 Markdown 内存、可检查的工件、搜索、权限管理、提交和回滚等功能。由于其高效并发处理能力和多种访问方式的支持，包括 CLI\u002FREPL、HTTP\u002FREST API、MCP 服务器及 TypeScript 和 Python SDK，非常适合需要快速处理大量 Markdown 文档的应用场景，尤其是在开发协作工具或基于文本的 AI 应用时。",2,"2026-06-11 02:44:25","CREATED_QUERY"]