# Local Workspace Orchestrator

An **MCP (Model Context Protocol)** client-server system that connects [Anthropic Claude](https://anthropic.com/) to your local filesystem through a set of workspace tools. The orchestrator lets Claude read files, analyse CSVs, execute scripts, generate plots, and more — all from an interactive chat interface.

## Architecture

```
┌───────────────────────────┐        stdio         ┌──────────────────────────┐
│  orchestrator_client.py   │ ◄──────────────────► │  workspace_server.py     │
│  (MCP Client + Anthropic) │     MCP protocol     │  (FastMCP Server)        │
│                           │                      │                          │
│  • Connects to 1+ servers │                      │  Tools:                  │
│  • Streams Claude output  │                      │   • list_workspace_files │
│  • Retries failed calls   │                      │   • summarize_csv_dataset│
│  • Saves chat history     │                      │   • execute_python_script│
│                           │                      │   • write_file           │
│                           │                      │   • run_shell_command    │
│                           │                      │   • plot_column_distrib. │
│                           │                      │                          │
│                           │                      │  Resources:              │
│                           │                      │   • workspace://files    │
│                           │                      │   • workspace://schema/* │
└───────────────────────────┘                      └──────────────────────────┘
```

## Quick Start

### 1. Clone & install

```bash
git clone <your-repo-url>
cd local-workspace-orchestrator

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt
```

### 2. Set up your API key

```bash
cp .env.example .env
# Edit .env and paste your Anthropic API key
```

### 3. Run the orchestrator

```bash
# Using uv
uv run orchestrator_client.py

# Or directly
python orchestrator_client.py
```

You'll see the interactive prompt:

```
======================================================
   Local Workspace Orchestrator Active
   Type queries, or /help for commands, 'quit' to exit.
======================================================

Orchestrator >
```

### 4. Try some queries

```
Orchestrator > list all files in this workspace
Orchestrator > summarize the sample_consumer.csv dataset
Orchestrator > plot the distribution of SpendingScore in sample_consumer.csv
Orchestrator > run the run_analysis.py script
```

## Server Configuration

The orchestrator reads `server_config.json` to know which MCP servers to launch. The format uses the standard MCP `mcpServers` structure:

```json
{
  "mcpServers": {
    "workspace_orchestrator": {
      "command": "uv",
      "args": ["run", "workspace_server.py"]
    }
  }
}
```

### Adding more servers

You can connect multiple servers — each will have its tools auto-discovered and registered:

```json
{
  "mcpServers": {
    "workspace_orchestrator": {
      "command": "uv",
      "args": ["run", "workspace_server.py"]
    },
    "my_other_server": {
      "command": "python",
      "args": ["other_server.py"]
    }
  }
}
```

## Chat Commands

| Command                   | Description                              |
| ------------------------- | ---------------------------------------- |
| `/tools`                  | List all registered tools by server      |
| `/save [filename]`        | Save conversation history to JSON file   |
| `/load [filename]`        | Load a saved conversation                |
| `/reconnect <server>`     | Reconnect to a dropped server            |
| `/history`                | Show conversation message count          |
| `/clear`                  | Clear conversation history               |
| `/help`                   | Show all available commands              |
| `quit`                    | Exit the orchestrator                    |

## Available Tools

### Read-only tools
| Tool                       | Description                                                      |
| -------------------------- | ---------------------------------------------------------------- |
| `list_workspace_files`     | List files and subdirectories in a workspace path                |
| `summarize_csv_dataset`    | Return shape, columns, dtypes, and summary statistics for a CSV  |
| `run_shell_command`        | Execute an allowlisted shell command (ls, cat, grep, etc.)       |

### Destructive tools
| Tool                       | Description                                                      |
| -------------------------- | ---------------------------------------------------------------- |
| `write_file`               | Create or overwrite a file in the workspace                      |
| `execute_python_script`    | Run a Python script and return stdout/stderr                     |
| `plot_column_distribution` | Generate a histogram PNG for a CSV column                        |

### Resources
| URI                              | Description                                |
| -------------------------------- | ------------------------------------------ |
| `workspace://files`              | Lists all files in the workspace root      |
| `workspace://schema/{file_name}` | Column names + dtypes for a CSV file       |

## Security

- **Path traversal protection**: All file-accepting tools validate paths using `os.path.realpath()` + `pathlib.Path.resolve()` to prevent directory traversal attacks.
- **Shell command allowlist**: `run_shell_command` only permits a curated set of read-only commands (`ls`, `cat`, `grep`, `head`, `tail`, etc.).
- **Script sandboxing**: `execute_python_script` runs scripts in a subprocess with a 30-second timeout, restricted to the workspace directory via `cwd`. Note: this is *not* a true sandbox — the subprocess has the same OS permissions as the server process.
- **Tool annotations**: Each tool carries `readOnlyHint` / `destructiveHint` annotations so MCP clients can reason about safety.

## CLI Options

```bash
python orchestrator_client.py --help

options:
  --log-level {DEBUG,INFO,WARNING,ERROR}   Set logging verbosity (default: INFO)
  --system-prompt TEXT                     Custom system prompt for Claude
  --config PATH                            Path to server_config.json
```

## Environment Variables

| Variable            | Description                                | Default |
| ------------------- | ------------------------------------------ | ------- |
| `ANTHROPIC_API_KEY` | Your Anthropic API key (**required**)       | —       |
| `LOG_LEVEL`         | Logging verbosity                          | `INFO`  |

## Project Structure

```
local-workspace-orchestrator/
├── orchestrator_client.py    # MCP client + Anthropic integration
├── workspace_server.py       # FastMCP server with workspace tools
├── server_config.json        # MCP server connection configuration
├── main.py                   # Stub entry point
├── run_analysis.py           # Example analysis script
├── sample_consumer.csv       # Sample dataset
├── pyproject.toml            # Project metadata + dependencies
├── requirements.txt          # Pinned pip dependencies
├── .env.example              # API key template
├── .gitignore                # Git ignore rules
└── README.md                 # This file
```

## License

MIT