Skip to main content
Glama
Local Workspace Orchestrator

Local Workspace Orchestrator

로컬 워크스페이스 오케스트레이터

MCP (Model Context Protocol) 클라이언트-서버 시스템으로, Anthropic Claude를 워크스페이스 도구 세트를 통해 로컬 파일시스템에 연결합니다. 오케스트레이터는 Claude가 파일을 읽고, CSV를 분석하고, 스크립트를 실행하고, 플롯을 생성하는 등의 작업을 대화형 채팅 인터페이스에서 수행할 수 있게 합니다.

아키텍처

┌───────────────────────────┐        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

빠른 시작

1. 클론 및 설치

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

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

2. API 키 설정

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

3. 오케스트레이터 실행

# Using uv
uv run orchestrator_client.py

# Or directly
python orchestrator_client.py

대화형 프롬프트가 표시됩니다:

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

Orchestrator >

4. 몇 가지 쿼리 시도

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_config.json을 읽어 어떤 MCP 서버를 시작할지 결정합니다. 형식은 표준 MCP mcpServers 구조를 사용합니다:

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

서버 추가

여러 서버를 연결할 수 있습니다. 각 서버의 도구는 자동으로 검색되어 등록됩니다:

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

채팅 명령

명령

설명

/tools

서버별 등록된 모든 도구 나열

/save [filename]

대화 기록을 JSON 파일로 저장

/load [filename]

저장된 대화 불러오기

/reconnect <server>

연결이 끊긴 서버에 다시 연결

/history

대화 메시지 수 표시

/clear

대화 기록 지우기

/help

사용 가능한 모든 명령 표시

quit

오케스트레이터 종료

사용 가능한 도구

읽기 전용 도구

도구

설명

list_workspace_files

워크스페이스 경로의 파일 및 하위 디렉터리 나열

summarize_csv_dataset

CSV의 형태, 열, 데이터 타입 및 요약 통계 반환

run_shell_command

허용 목록에 있는 셸 명령 실행 (ls, cat, grep 등)

파괴적 도구

도구

설명

write_file

워크스페이스에 파일 생성 또는 덮어쓰기

execute_python_script

Python 스크립트를 실행하고 stdout/stderr 반환

plot_column_distribution

CSV 열에 대한 히스토그램 PNG 생성

리소스

URI

설명

workspace://files

워크스페이스 루트의 모든 파일 나열

workspace://schema/{file_name}

CSV 파일의 열 이름 및 데이터 타입

보안

  • 경로 탐색 보호: 파일을 허용하는 모든 도구는 os.path.realpath() + pathlib.Path.resolve()를 사용하여 경로를 검증하고 디렉터리 탐색 공격을 방지합니다.

  • 셸 명령 허용 목록: run_shell_command는 선별된 읽기 전용 명령 세트(ls, cat, grep, head, tail 등)만 허용합니다.

  • 스크립트 샌드박싱: execute_python_script는 30초 제한 시간으로 하위 프로세스에서 스크립트를 실행하며, cwd를 통해 워크스페이스 디렉터리로 제한됩니다. 참고: 이는 실제 샌드박스가 아닙니다 — 하위 프로세스는 서버 프로세스와 동일한 OS 권한을 가집니다.

  • 도구 주석: 각 도구는 readOnlyHint / destructiveHint 주석을 포함하여 MCP 클라이언트가 안전성을 판단할 수 있게 합니다.

CLI 옵션

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

환경 변수

변수

설명

기본값

ANTHROPIC_API_KEY

Anthropic API 키 (필수)

—

LOG_LEVEL

로깅 상세 수준

INFO

프로젝트 구조

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

라이선스

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers