chuk-mcp-vfs

MCP server providing virtual filesystem workspaces via the unified namespace architecture.

Features

✅ Unified Architecture - Built on chuk-artifacts namespace system ✅ Context-Aware - Automatic user/session scoping from MCP context ✅ Storage Scopes - SESSION (ephemeral), USER (persistent), SANDBOX (shared) ✅ Pydantic Native - All requests and responses use Pydantic models ✅ Async Native - Fully async/await throughout ✅ Type Safe - Enums and constants instead of magic strings ✅ Multiple Workspaces - Create and manage isolated virtual filesystems ✅ Full VFS Operations - read, write, ls, tree, mkdir, rm, mv, cp, cd, pwd, find, grep ✅ Checkpoints - Save and restore filesystem state at any point ✅ MCP Integration - Expose all operations as MCP tools for AI agents

Architecture

chuk-mcp-vfs           → Workspace management + VFS tools
    ↓ uses
chuk-artifacts         → Unified namespace architecture
    ↓ manages
Namespaces (WORKSPACE) → Each workspace is a namespace
    ↓ provides
chuk-virtual-fs        → Async VFS with multiple storage providers
    ↓
Storage Provider       → memory, filesystem, sqlite, s3

Key Concepts:

• Everything is VFS: Both blobs and workspaces are VFS-backed via namespaces
• Scopes: SESSION (per-conversation), USER (per-user persistent), SANDBOX (shared)
• Context-Aware: user_id and session_id automatically from MCP server context
• Grid Architecture: All namespaces stored in unified grid structure

Installation

# Basic installation
pip install chuk-mcp-vfs

# With FUSE mounting support (Linux/macOS)
pip install chuk-mcp-vfs[mount]

# Development
pip install -e .[dev]

Quick Start

As MCP Server

from chuk_mcp_vfs import run_server

# Start MCP server (stdio mode for Claude Desktop)
run_server()

Programmatic Usage

import asyncio
from chuk_mcp_vfs import (
    WorkspaceManager,
    ProviderType,
    StorageScope,
    WriteRequest,
)
from chuk_mcp_vfs.vfs_tools import VFSTools

async def main():
    # Initialize manager (uses chuk-artifacts under the hood)
    workspace_manager = WorkspaceManager()
    tools = VFSTools(workspace_manager)

    # Create SESSION-scoped workspace (ephemeral, tied to session)
    await workspace_manager.create_workspace(
        name="my-workspace",
        provider_type=ProviderType.MEMORY,
        scope=StorageScope.SESSION,  # or USER for persistence
    )

    # Write file
    await tools.write(WriteRequest(
        path="/hello.txt",
        content="Hello from VFS!"
    ))

    # Read file
    result = await tools.read("/hello.txt")
    print(result.content)

asyncio.run(main())

MCP Tools

Workspace Management

Tool	Description
workspace_create	Create new workspace with provider (memory, filesystem, sqlite, s3)
workspace_destroy	Delete workspace and clean up resources
workspace_list	List all workspaces
workspace_switch	Switch active workspace
workspace_info	Get workspace details
workspace_mount	Mount workspace via FUSE (planned)
workspace_unmount	Unmount workspace (planned)

File Operations

Tool	Description
read	Read file contents
write	Write file with content
ls	List directory contents
tree	Show directory tree structure
mkdir	Create directory
rm	Remove file/directory (with recursive option)
mv	Move/rename file/directory
cp	Copy file/directory (with recursive option)

Navigation

Tool	Description
cd	Change current working directory
pwd	Print working directory
find	Find files by glob pattern
grep	Search file contents

Checkpoints

Tool	Description
checkpoint_create	Create checkpoint of current state
checkpoint_restore	Restore from checkpoint
checkpoint_list	List all checkpoints
checkpoint_delete	Delete checkpoint

Usage with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "vfs": {
      "command": "chuk-mcp-vfs",
      "args": []
    }
  }
}

Then you can use natural language to interact with the filesystem:

You: Create a workspace called "myproject" and set up a Python project structure

Claude: [Uses workspace_create and mkdir tools]

You: Write a simple Flask app to main.py

Claude: [Uses write tool with Python code]

You: Create a checkpoint called "initial-setup"

Claude: [Uses checkpoint_create]

You: Make changes... actually restore to the checkpoint

Claude: [Uses checkpoint_restore]

Examples

See examples/basic_usage.py for a complete working example.

Storage Scopes

The unified architecture provides three storage scopes:

SESSION Scope (Ephemeral)

from chuk_mcp_vfs.models import StorageScope

# Create session-scoped workspace (default)
await workspace_manager.create_workspace(
    name="temp-work",
    scope=StorageScope.SESSION,  # Tied to current session
)

• Lifetime: Expires when session ends
• Perfect for: Temporary workspaces, caches, current work
• Grid path: grid/{sandbox}/sess-{session_id}/{namespace_id}
• Access: Only accessible from same session

USER Scope (Persistent)

# Create user-scoped workspace
await workspace_manager.create_workspace(
    name="my-project",
    scope=StorageScope.USER,  # Persists across sessions
)

• Lifetime: Persists across sessions
• Perfect for: User projects, personal data
• Grid path: grid/{sandbox}/user-{user_id}/{namespace_id}
• Access: Accessible from any session for the same user

SANDBOX Scope (Shared)

# Create sandbox-scoped workspace
await workspace_manager.create_workspace(
    name="shared-templates",
    scope=StorageScope.SANDBOX,  # Shared across all users
)

• Lifetime: Persists indefinitely
• Perfect for: Templates, shared docs, libraries
• Grid path: grid/{sandbox}/shared/{namespace_id}
• Access: Accessible by all users

Provider Types

from chuk_mcp_vfs.models import ProviderType

# In-memory (fast, temporary)
ProviderType.MEMORY

# Filesystem (persistent)
ProviderType.FILESYSTEM

# SQLite (portable database)
ProviderType.SQLITE

# S3 (cloud storage)
ProviderType.S3

Models (Pydantic)

All requests and responses are Pydantic models:

from chuk_mcp_vfs.models import (
    # Workspace models
    WorkspaceCreateRequest,
    WorkspaceCreateResponse,
    WorkspaceInfo,

    # File operation models
    WriteRequest,
    WriteResponse,
    ReadResponse,
    ListDirectoryResponse,

    # Navigation models
    FindRequest,
    FindResponse,
    GrepRequest,
    GrepResponse,

    # Checkpoint models
    CheckpointCreateRequest,
    CheckpointCreateResponse,
    CheckpointInfo,
)

Development

# Install with dev dependencies
pip install -e .[dev]

# Run tests
pytest

# Run tests with coverage
pytest --cov=chuk_mcp_vfs

# Type checking
mypy src

# Linting
ruff check src
ruff format src

Architecture Details

Workspace Manager

• Thin wrapper around chuk-artifacts ArtifactStore
• Each workspace is a WORKSPACE-type namespace
• Tracks current working directory per workspace
• Context-aware: automatically uses user_id/session_id from MCP context
• Thread-safe workspace operations

Namespace Integration

• All workspaces stored in unified grid architecture
• Automatic scope-based isolation (SESSION/USER/SANDBOX)
• Namespaces provide VFS instances via get_namespace_vfs()
• Grid paths make ownership and scope explicit

Checkpoint Manager

• Wraps chuk-virtual-fs AsyncSnapshotManager
• Provides workspace-scoped checkpoints
• Metadata tracking for each checkpoint

VFS Tools

• Wraps async VFS operations with Pydantic models
• Path resolution relative to current working directory
• Error handling and validation

MCP Integration

• Registers all tools with chuk-mcp-server
• Automatic JSON schema generation from Pydantic models
• Context variables for user/session tracking
• Stdio transport for Claude Desktop

Roadmap

• [x] Core VFS operations
• [x] Workspace management
• [x] Checkpoint system
• [x] Pydantic models
• [x] Basic tests
• [ ] FUSE mounting implementation
• [ ] Template system integration
• [ ] Workspace import/export
• [ ] File watching
• [ ] Permissions system
• [ ] Comprehensive tests

License

MIT - see LICENSE file

Contributing

Contributions welcome! Please ensure:

• All code uses Pydantic models (no dict returns)
• All code is async native
• Use enums/constants instead of magic strings
• Add tests for new features
• Update documentation

Credits

Built on top of:

• chuk-artifacts - Unified namespace architecture
• chuk-virtual-fs - Virtual filesystem engine
• chuk-mcp-server - MCP framework with context management