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

Running the MCP Server

The server supports two transport modes:

1. STDIO Transport (for Claude Desktop)

# Default - runs with stdio transport
chuk-mcp-vfs

# Explicitly specify stdio transport
chuk-mcp-vfs --transport stdio

# With debug logging
chuk-mcp-vfs --transport stdio --debug

2. SSE Transport (for HTTP/Streaming)

# Run with SSE transport (default: localhost:3000)
chuk-mcp-vfs --transport sse

# Custom host and port
chuk-mcp-vfs --transport sse --host 0.0.0.0 --port 8080

# With debug logging
chuk-mcp-vfs --transport sse --debug

CLI Options

usage: chuk-mcp-vfs [-h] [--transport {stdio,sse}] [--host HOST] [--port PORT] [--debug]

options:
  -h, --help            show this help message and exit
  --transport {stdio,sse}, -t {stdio,sse}
                        Transport type: 'stdio' for Claude Desktop or 'sse' for streaming HTTP (default: stdio)
  --host HOST           Host to bind to (only for SSE transport, default: 127.0.0.1)
  --port PORT, -p PORT  Port to bind to (only for SSE transport, default: 3000)
  --debug, -d           Enable debug logging

Programmatic Server Usage

from chuk_mcp_vfs import run_server

# Start with stdio transport (for Claude Desktop)
run_server(transport="stdio")

# Start with SSE transport (for HTTP/streaming)
run_server(transport="sse", host="0.0.0.0", port=8080)

Programmatic Workspace 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

File Operations

Navigation

Checkpoints

Usage with Claude Desktop

Add to claude_desktop_config.json:

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

Or install with uvx (no global installation needed):

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

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

Setup

# Install with dev dependencies (using uv)
uv pip install -e ".[dev]"

# Or with pip
pip install -e ".[dev]"

Quality Checks

The project uses uv as the package manager and includes comprehensive quality checks:

# Run all checks (lint, typecheck, tests with coverage)
make check

# Individual checks
make lint          # Lint with ruff
make format        # Format code with ruff
make typecheck     # Type check with mypy (zero errors!)
make test          # Run tests
make test-cov      # Run tests with coverage report

# Build
make build         # Build distribution packages
make clean         # Clean build artifacts

Test Coverage

The project maintains high test coverage:

Name                                     Coverage
------------------------------------------------------------
src/chuk_mcp_vfs/__init__.py                 100%
src/chuk_mcp_vfs/checkpoint_manager.py        98%
src/chuk_mcp_vfs/checkpoint_tools.py         100%
src/chuk_mcp_vfs/models.py                   100%
src/chuk_mcp_vfs/server.py                    66%
src/chuk_mcp_vfs/vfs_tools.py                 90%
src/chuk_mcp_vfs/workspace_manager.py         92%
src/chuk_mcp_vfs/workspace_tools.py          100%
------------------------------------------------------------
TOTAL                                         91%

77 test cases covering:

• Workspace management (18 tests)
• VFS operations (26 tests)
• Workspace tools (11 tests)
• Checkpoint management (7 tests)
• Checkpoint tools (4 tests)
• Server integration (10 tests)

Type Safety

The codebase is fully type-checked with mypy:

• ✅ Zero mypy errors
• ✅ All dependencies have py.typed markers
• ✅ Strict type checking enabled
• ✅ No Any types in public APIs

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

Completed ✅

• Core VFS operations (read, write, ls, tree, mkdir, rm, mv, cp, cd, pwd)
• Workspace management with namespace integration
• Checkpoint system with snapshot support
• Pydantic-native models (no dictionary goop!)
• Async-native implementation
• Type safety (zero mypy errors)
• Comprehensive test suite (91% coverage, 77 tests)
• GitHub Actions CI/CD workflows
• Search operations (find, grep)
• Multiple storage providers (memory, filesystem, sqlite, s3)
• Storage scopes (SESSION, USER, SANDBOX)
• Context-aware operations (automatic user_id/session_id)
• MCP server integration
• Full documentation

In Progress 🚧

• FUSE mounting implementation (placeholder exists)
• Template system integration (basic support exists)

Planned 📋

• Workspace import/export
• File watching and event notifications
• Permissions system
• Performance optimizations for large filesystems
• WebDAV server support
• Compression and deduplication
• Workspace sharing and collaboration features

License

Apache License 2.0 - 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