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

# Basic installation
pip install chuk-mcp-vfs

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

# Development
pip install -e .[dev]

# 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

# 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

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

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)

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())

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

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

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]

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
)

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

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

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

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,
)

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

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

# 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

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%