═══════════════════════════════════════════════════════════════════════════════
MCP CONFIGURATION QUICK REFERENCE - ORC Repository
═══════════════════════════════════════════════════════════════════════════════

MAIN FILES TO UNDERSTAND:
────────────────────────────────────────────────────────────────────────────────

1. CORE MCP IMPLEMENTATION
   • /orc/src/orc/mcp/server.py
     → MCP server instantiation, role-based tool registration (FastMCP)
     → Key functions: _get_role(), _build_server(), run()
   
   • /orc/src/orc/mcp/tools.py
     → Implementation of 7 MCP tools (get_task, create_task, review_task, etc.)
     → Unix socket client for coordination API
   
   • /orc/src/orc/mcp/client.py
     → HTTP client connecting to coordination API via Unix socket
     → Key function: get_client() using httpx with UDS transport

2. MCP CONFIG GENERATION (Runtime)
   • /orc/src/orc/ai/backends.py
     → Lines 143-180: generate_mcp_config() creates temp JSON config
     → Lines 330-425: Backend-specific CLI flags (copilot vs claude)
     → Maps abstract tool names to CLI-specific patterns

3. PERMISSION SYSTEM
   • /orc/src/orc/squad.py
     → Lines 81-122: PermissionConfig class (mode: confined/yolo)
     → Lines 85-90: ORC_DEFAULT_ALLOW_TOOLS (hardcoded defaults)
     → Lines 269-290: Permission resolution order
     → Lines 377-404: Squad profile loading from YAML

4. AGENT LAUNCHING
   • /orc/src/orc/cli/run.py
     → Lines 103-109: CoordinationServer startup, socket setup
     → Sets ORC_API_SOCKET environment variable for agents
   
   • /orc/src/orc/engine/context.py
     → Lines 188-237: Agent context building with worktree paths
     → Instructs agents which directories they can modify

5. CONFIGURATION FILES
   • /orc/.orc/config.yaml
     → Worktree base paths, branch names (project-level)
   
   • /orc/src/templates/default/orc_cfg/squads/default.yaml
     → Default squad profile with permission modes and composition

6. PATH CONFIGURATION
   • /orc/src/orc/config.py
     → Lines 89-91: feature_worktree_path() method
     → Lines 119-139: Worktree base resolution
     → Socket path: cfg.api_socket_path = .orc/run/orc.sock

═══════════════════════════════════════════════════════════════════════════════
ENVIRONMENT VARIABLES SET FOR AGENTS:
═══════════════════════════════════════════════════════════════════════════════

When launching MCP server (from backends.py lines 169-173):
  • ORC_API_SOCKET     → /path/to/.orc/run/orc.sock
  • ORC_AGENT_ID       → e.g., "coder-1", "planner-1"
  • ORC_AGENT_ROLE     → "planner", "coder", or "qa"
  • PYTHONPATH         → Points to orc package directory

═══════════════════════════════════════════════════════════════════════════════
MCP TOOLS AVAILABLE BY ROLE:
═══════════════════════════════════════════════════════════════════════════════

SHARED (ALL ROLES):
  ✓ get_task(task_filename)
  ✓ update_task_status(task_code, status)
  ✓ add_comment(task_code, comment)

PLANNER ONLY:
  ✓ get_vision(vision_filename)
  ✓ create_task(task_title, vision_file, overview, in_scope, out_of_scope, steps, notes, extra_files)
  ✓ close_vision(vision_file, summary, task_files)

CODER ONLY:
  ✓ close_task(task_code, message)

QA ONLY:
  ✓ review_task(task_code, outcome, message)

═══════════════════════════════════════════════════════════════════════════════
FILESYSTEM ACCESS RESTRICTIONS:
═══════════════════════════════════════════════════════════════════════════════

MAIN DIRECTORY:      ❌ OFF-LIMITS (human's workspace)
  Location: /orc/

ISOLATED WORKTREES:  ✅ ALLOWED
  Dev worktree:      .orc/worktrees/dev
  Feature worktrees: .orc/worktrees/0001-task-name
                     .orc/worktrees/0002-another-task
                     (one per agent task)

Worktree base can be overridden in .orc/config.yaml:
  # orc-worktree-base: /tmp/my-project-worktrees

═══════════════════════════════════════════════════════════════════════════════
PERMISSION MODES:
═══════════════════════════════════════════════════════════════════════════════

CONFINED (default, most restrictive):
  ✓ File read/write (via "read" and "write" tools)
  ✓ Git operations (via "shell(git:*)")
  ✓ ORC MCP tools (board operations)
  ✗ Other shell operations (must add to allow_tools)

YOLO (unrestricted):
  ✓ All tools and shell access (pre-MCP behavior)
  Set in squad profile: mode: yolo

Permission resolution order (later wins):
  1. ORC defaults (hardcoded)
  2. Squad-level permissions block
  3. Per-role permissions override

═══════════════════════════════════════════════════════════════════════════════
AGENT LAUNCH SEQUENCE:
═══════════════════════════════════════════════════════════════════════════════

1. orc run starts CoordinationServer listening on Unix socket
   → Socket path: .orc/run/orc.sock
   → Set as ORC_API_SOCKET environment variable

2. For each task, dispatcher:
   a) Generates temp MCP config JSON (mcpServers.orc.command, args, env)
   b) Generates temp context file (prompt)
   c) Spawns AI CLI (copilot or claude) with permission flags
   d) Passes MCP config and context paths

3. AI CLI subprocess:
   a) Reads MCP config from temp JSON
   b) Launches MCP server: python -m orc.mcp
   c) MCP server reads ORC_AGENT_ROLE, registers role-filtered tools
   d) MCP server runs on stdio, AI CLI communicates via stdio

4. Agent (via AI CLI):
   a) Receives context file with paths and instructions
   b) Uses MCP tools to interact with board
   c) Uses permitted shell/file tools to make changes
   d) Works in assigned worktree (set as cwd)

═══════════════════════════════════════════════════════════════════════════════
KEY DIFFERENCES FROM PRE-MCP:
═══════════════════════════════════════════════════════════════════════════════

BEFORE (pre-MCP):
  ✗ Required --yolo mode (unrestricted)
  ✗ Agent scripts injected as file paths
  ✗ Required Python environment in agents
  ✗ Complex script calling conventions in context

AFTER (MCP-based):
  ✓ Default to "confined" mode (restricted by default)
  ✓ Clean MCP tool API (no file path injection)
  ✓ No Python environment needed in agent
  ✓ Simple tool calls in prompt
  ✓ Role-based tool filtering
  ✓ Squad profiles define permissions

═══════════════════════════════════════════════════════════════════════════════
EXAMPLE: ADDING EXTRA TOOLS TO CODERS
═══════════════════════════════════════════════════════════════════════════════

In .orc/squads/default.yaml:

composition:
  - role: coder
    count: 1
    model: claude-sonnet-4.6
    permissions:
      allow_tools:
        - "shell(npm:*)"      # Add npm/yarn/pnpm access
        - "shell(cargo:*)"    # Add cargo/rust access
        - "shell(make:*)"     # Add make access

═══════════════════════════════════════════════════════════════════════════════
