workspacemcp

Secure, auditable workspace management for AI agents with MCP support

Part of the MCP AI Suite.

Features

• Sandboxed file operations -- read (cat -n numbered), write (atomic), edit (search & replace, replace_all), multi-edit (atomic, all-or-nothing), apply-patch (unified git diff), move, delete within a controlled root path
• Fast code navigation -- ripgrep-backed content search (Python fallback) + recursive ** glob, sorted newest-first
• Claude Code-style edit semantics -- old_string/new_string, rich errors with match line numbers, freshness guard (refuses edits to a file changed since last read)
• All four surfaces -- the same operations as a Python lib, an MCP server, a FastAPI app, and a CLI
• DLP content filter -- automatic secret detection and redaction before content reaches the agent
• Approval gate -- require human approval for writes to critical file patterns
• Auto-checkpointing -- automatic file snapshots before in-place edits and deletes of existing files for rollback (enabled by default)
• Checkpoint restore -- full workspace rollback to any previous snapshot
• Multi-tenant isolation -- per-namespace workspace directories with cross-tenant access prevention
• Semantic tree and workspace stats -- structural analysis with Mermaid diagram export
• Full audit logging -- every file operation recorded with agent ID, namespace, and timestamp

Installation

pip install mcpaisuite-workspacemcp
# Optional extras:
pip install mcpaisuite-workspacemcp[dev]          # Development tools
pip install mcpaisuite-workspacemcp[all]          # All integrations
pip install mcpaisuite-workspacemcp[ragmcp]       # RAG integration
pip install mcpaisuite-workspacemcp[memorymcp]    # Memory integration

Quick Start

from workspacemcp import WorkspaceFactory

workspace = WorkspaceFactory.create(root_path="/data/workspace", read_only=False)
entry = await workspace.write_file("hello.txt", "Hello, world!")
files = await workspace.list_files(recursive=True)

MCP Server

workspacemcp serve

Configuration

API Reference

WorkspacePipeline

Central orchestrator: sandbox -> DLP -> audit -> gate -> store.

await workspace.read_file(path, offset=0, limit=None, namespace="default") -> FileEntry
await workspace.write_file(path, content, namespace="default") -> FileEntry
await workspace.edit_file(path, old_text, new_text, replace_all=False, namespace="default") -> FileEntry
await workspace.multi_edit(path, edits, namespace="default") -> FileEntry   # atomic, all-or-nothing
await workspace.apply_patch(patch_text, namespace="default") -> dict        # apply a unified git diff
await workspace.delete_file(path, namespace="default")
await workspace.list_files(directory="", recursive=False, pattern=None) -> list[FileEntry]
await workspace.glob_files(pattern, directory="", namespace="default") -> list[str]   # supports **, mtime-sorted
await workspace.search_workspace(pattern, directory="", glob=None, case_sensitive=False) -> list[FileSearchResult]
await workspace.create_checkpoint(label="") -> Checkpoint
await workspace.restore_checkpoint(checkpoint_id) -> Checkpoint
await workspace.audit_log(action=None, limit=50) -> list[AuditEntry]

Edit semantics mirror Claude Code's tools (old_string/new_string, replace_all, rich errors with match line numbers, cat -n numbered reads) so the model transfers its skill directly. search_workspace uses ripgrep when available and falls back to a Python regex scan otherwise.

WorkspaceFactory

WorkspaceFactory.default(root_path=".")      # Read-only; in-memory file store, SQLite checkpoint/audit on disk
WorkspaceFactory.from_env()                  # Build from environment variables
WorkspaceFactory.from_yaml("config.yaml")    # Build from YAML config
WorkspaceFactory.create(root_path=..., read_only=False, tenant_isolation=True, ...)

Architecture

WorkspacePipeline enforces a security pipeline on every file operation: PathSandbox validates paths against the workspace root and restricted patterns, ContentFilter (DLP) scans for and redacts secrets, ApprovalGate requires human confirmation for sensitive file patterns, and all operations are audit-logged. Auto-checkpointing captures file state before in-place edits and deletes of existing files (enabled by default), enabling full rollback via restore_checkpoint.

Testing

pip install -e ".[dev]"
pytest tests/ -v

License

Apache-2.0 — see LICENSE.

Open source for individuals and open-source projects. For commercial use in closed-source products, a commercial license is available — contact contact@mcpaisuite.com.