Local Workspace Orchestrator

An MCP (Model Context Protocol) client-server system that connects Anthropic Claude 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

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

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

3. Run the orchestrator

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

{
  "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:

{
  "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

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