Metadata-Version: 2.4
Name: mcpaisuite-workspacemcp
Version: 1.0.3
Summary: Secure, auditable workspace management for AI agents with MCP support
Project-URL: Homepage, https://github.com/gashel01/workspacemcp
Project-URL: Repository, https://github.com/gashel01/workspacemcp
Author-email: gashel01 <gaeldev@gmail.com>
License: AGPL-3.0-or-later
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog>=24.0
Provides-Extra: all
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: httpx>=0.25; extra == 'all'
Requires-Dist: mcpaisuite-memorymcp>=1.0; extra == 'all'
Requires-Dist: mcpaisuite-planningmcp>=1.0; extra == 'all'
Requires-Dist: mcpaisuite-ragmcp>=1.0; extra == 'all'
Requires-Dist: uvicorn>=0.23; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == 'api'
Requires-Dist: uvicorn>=0.23; extra == 'api'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: memorymcp
Requires-Dist: mcpaisuite-memorymcp>=1.0; extra == 'memorymcp'
Provides-Extra: planningmcp
Requires-Dist: mcpaisuite-planningmcp>=1.0; extra == 'planningmcp'
Provides-Extra: ragmcp
Requires-Dist: mcpaisuite-ragmcp>=1.0; extra == 'ragmcp'
Provides-Extra: webhooks
Requires-Dist: httpx>=0.25; extra == 'webhooks'
Description-Content-Type: text/markdown

# workspacemcp

> Secure, auditable workspace management for AI agents with MCP support

Part of the [MCP AI Suite](https://mcpaisuite.dev).

## 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

```bash
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

```python
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

```bash
workspacemcp serve
```

## Configuration

| Variable | Default | Description |
|---|---|---|
| `WORKSPACEMCP_ROOT` | `.` | Workspace root directory |
| `WORKSPACEMCP_READONLY` | `true` | Read-only mode |
| `WORKSPACEMCP_FILE_STORE` | `local` | File store: `local` or `memory` |
| `WORKSPACEMCP_CHECKPOINT_STORE` | `memory` | Checkpoint store: `memory` or `sqlite` |
| `WORKSPACEMCP_AUDIT` | `memory` | Audit backend: `memory` or `sqlite` |
| `WORKSPACEMCP_TENANT_ISOLATION` | `false` | Enable multi-tenant isolation |
| `WORKSPACEMCP_NAMESPACE` | `default` | Default namespace |

## API Reference

### WorkspacePipeline

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

```python
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

```python
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

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

## License

AGPL-3.0 — see [LICENSE](LICENSE).

Open source for individuals and open-source projects. For commercial use in closed-source products, a commercial license is available — contact [gaeldev@gmail.com](mailto:gaeldev@gmail.com).
