mcp-copilot-cli

Copilot-only MCP task orchestrator built on @modelcontextprotocol/sdk and @github/copilot-sdk.

It exposes a small MCP surface for launching resumable Copilot-backed background tasks, monitoring them through resources and MCP task primitives, and answering any follow-up questions the running Copilot session asks.

What It Does

• Uses your local GitHub Copilot OAuth session from ~/.copilot by default.
• Launches background tasks through a single spawn-agent tool.
• Supports resumable follow-ups with message-agent.
• Supports interactive answers with answer-agent.
• Supports cancellation and full task clearing with cancel-agent.
• Persists task state under ~/.super-agents/<workspace-md5>.json.
• Writes live task output to .super-agents/<task-id>.output inside the target workspace.
• Supports shared or isolated execution workspaces.
• Exposes both human-readable resources and MCP task handlers.

Public MCP Surface

Tools

• spawn-agent Launches a new Copilot-backed task.
• message-agent Resumes an existing Copilot session by creating a continuation task with a new task_id.
• cancel-agent Cancels one task, many tasks, or clears all tracked tasks.
• answer-agent Submits an answer to a pending question and resumes the waiting task.

Resources

• system:///status
• task:///all
• task:///{id}
• task:///{id}/session

Task Requests

• tasks/list
• tasks/get
• tasks/result
• tasks/cancel

Spawn Behavior

spawn-agent accepts:

• prompt
• agent_type: coder | planner | researcher | tester | general
• context_files
• model
• cwd
• timeout
• depends_on
• labels
• isolation_mode: shared | isolated

message-agent accepts:

• task_id
• message
• timeout
• cwd

cancel-agent accepts:

• task_id A single task id, an array of task ids, or "all".
• clear
• confirm

answer-agent accepts:

• task_id
• answer
• answers

When task_id is "all" for cancel-agent, both clear=true and confirm=true are required. For answer-agent, either answer or answers must be provided; the current runtime resolves the first string answer it receives.

Validation is role-aware:

• coder prompts must be at least 1000 characters and include at least one context file.
• planner and tester prompts must be at least 300 characters.
• researcher and general prompts must be at least 200 characters.
• context_files are capped at 20 files, 200 KB each, 500 KB total.

Task Lifecycle

Tracked tasks move through these statuses:

• pending
• waiting
• running
• waiting_answer
• completed
• failed
• cancelled
• rate_limited
• timed_out

Runtime Model

• Copilot profiles come from COPILOT_CONFIG_DIRS or default to ~/.copilot.
• The runtime rotates profiles on rate-limit failures with cooldown tracking.
• Running tasks stream assistant output and tool lifecycle events into the task log.
• Questions from Copilot move tasks into waiting_answer until answer-agent resumes them.
• Dependent tasks stay in waiting until all prerequisite tasks complete.
• isolated mode prefers git worktrees and falls back to a copied workspace.

Entry Points

Preferred local repo entrypoints:

• bin/mcp-copilot-cli.mjs
• node --import tsx src/index.ts

Package scripts:

• npm run serve
• npm run doctor
• npm run smoke
• npm run test:unit
• npm run build

Important Packaging Note

Do not rely on launching dist/src/index.js directly with plain node for production-style validation. The upstream @github/copilot-sdk dependency currently hits an ESM resolution issue around vscode-jsonrpc/node in that mode.

The stable verified launch paths in this repository are:

• bin/mcp-copilot-cli.mjs
• node --import tsx src/index.ts
• npm run serve

Requirements

• Node.js 22+
• GitHub Copilot CLI installed
• A valid local Copilot OAuth login
• Optional: mcpc 0.1.11 for MCP CLI testing

Quick Start

npm install
npm run build
npm run doctor -- --json
npm run serve

For mcpc, use the local wrapper entrypoint:

{
  "mcpServers": {
    "mcp-copilot-cli": {
      "command": "/absolute/path/to/bin/mcp-copilot-cli.mjs",
      "env": {
        "COPILOT_CLI_PATH": "/opt/homebrew/bin/copilot"
      }
    }
  }
}

Then:

mcpc --config /path/to/config.json mcp-copilot-cli connect @mcp-copilot-cli
mcpc @mcp-copilot-cli tools-list
mcpc @mcp-copilot-cli resources-read task:///all

For the published package, use npx as the stdio command:

{
  "mcpServers": {
    "mcp-copilot-cli": {
      "command": "npx",
      "args": ["-y", "mcp-copilot-cli"],
      "env": {
        "COPILOT_CLI_PATH": "/opt/homebrew/bin/copilot"
      }
    }
  }
}

Verification

Verified locally in this repository with:

• npm run build
• npm run test:unit
• npm run smoke
• node --import tsx src/cli/doctor.ts --json
• mcpc live-session E2E tests through bin/mcp-copilot-cli.mjs

The checked E2E path includes:

• spawning a task that outputs 1 through 9
• spawning a task that writes lorem.txt
• confirming task completion through MCP resources
• confirming the session payload and on-disk file contents