Skip to main content
Glama
deenesjakoruzh
aniketmehetre

Local Workspace Orchestrator

by aniketmehetre
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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/* │
└───────────────────────────┘                      └──────────────────────────┘

Related MCP server: ai-distiller-mcp

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

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers