urirun-connector-mcp-filesystem

Sandboxed filesystem connector for ifURI / urirun, in the spirit of MCP filesystem servers. Query routes list/read/stat/find duplicates under one root. The guarded move command is also sandboxed and defaults to dry-run.

Catalog page: https://connect.ifuri.com/connectors/mcp-filesystem

Routes

URI	Operation
fs://host/dir/query/list	list a directory
fs://host/file/query/read	read a text file (size-capped)
fs://host/file/query/blob	read a binary file as base64 (size-capped)
fs://host/path/query/stat	stat a path
fs://host/dir/command/prune_empty	remove empty directories under a sandboxed path
fs://host/duplicates/query/find	find exact duplicate files by SHA-256
fs://host/file/command/write_text	write a UTF-8 text file under the sandbox root
fs://host/file/command/write_blob	write a base64-decoded binary file under the sandbox root
fs://host/file/command/move_to_dir	move one file into a sandboxed directory
fs://host/file/command/move	move or rename one file to a sandboxed path

Sandbox

Everything resolves under IFURI_FS_ROOT (default: the current working directory). Paths that escape the root are rejected with ok: false. Query routes never write or delete. fs://host/dir/command/prune_empty, fs://host/file/command/write_text, fs://host/file/command/write_blob, fs://host/file/command/move_to_dir and fs://host/file/command/move are the mutating routes; they default to dry_run: true. File writes and moves do not overwrite unless overwrite: true.

Install

pip install "urirun-connector-mcp-filesystem @ git+https://github.com/if-uri/urirun-connector-mcp-filesystem.git@v0.1.0"
# or, from the hub:
urirun connectors install mcp-filesystem --execute

Use

export IFURI_FS_ROOT="$PWD"
urirun-mcp-filesystem bindings > bindings.json
urirun compile bindings.json --out registry.json
urirun run 'fs://host/dir/query/list' registry.json \
  --payload '{"path":"."}' --execute --allow 'fs://host/*'

urirun run 'fs://host/duplicates/query/find' registry.json \
  --payload '{"path":".","extensions":"pdf,png,jpg"}' \
  --execute --allow 'fs://host/*'

urirun run 'fs://host/file/query/blob' registry.json \
  --payload '{"path":"2026.05/invoice.pdf","max_bytes":10485760}' \
  --execute --allow 'fs://host/*'

urirun run 'fs://host/file/command/move_to_dir' registry.json \
  --payload '{"path":"2026.05/manual.pdf","target_dir":"no_invoice","dry_run":true}' \
  --execute --allow 'fs://host/*'

urirun run 'fs://host/file/command/move' registry.json \
  --payload '{"path":"2026.05/_by_supplier/saas/me/invoice.pdf","target_path":"2026.05/2026.05.12-saas-invoice.pdf","dry_run":true}' \
  --execute --allow 'fs://host/*'

urirun run 'fs://host/dir/command/prune_empty' registry.json \
  --payload '{"path":".","exclude":"no_invoice","dry_run":true}' \
  --execute --allow 'fs://host/*'

urirun run 'fs://host/file/command/write_text' registry.json \
  --payload '{"path":"index.php","content":"<?php echo \"ok\";","dry_run":true}' \
  --execute --allow 'fs://host/*'

urirun run 'fs://host/file/command/write_blob' registry.json \
  --payload '{"path":"2026-06/invoice.pdf","bytes_b64":"JVBERg==","dry_run":true}' \
  --execute --allow 'fs://host/*'

After installation, urirun can discover this connector automatically through the urirun.bindings entry-point group:

urirun discover --out connectors.bindings.json --registry-out connectors.registry.json
urirun list --entry-points

The connector projects to MCP tools and A2A skills like any other urirun connector (python3 -m urirun.v2_mcp tools registry.json).

License

Released under the terms in LICENSE.