# 🧛 Copilot Leecher

**English** | [中文](#中文说明)

> Squeeze every drop out of your GitHub Copilot premium requests — turn follow-up prompts into free MCP tool calls.

## Why This Exists

GitHub Copilot charges by **premium requests** (300/month on Pro; each Claude Opus 4.6 call costs 3 requests), *not* by tokens. Through experimentation, we discovered:

| Action | Costs a Premium Request? |
|---|---|
| New user prompt | ✅ Yes |
| Follow-up in the same session | ✅ Yes |
| Tool call / MCP call | ❌ **No** |

So the most cost-effective way to use Copilot is: **pack as much work as possible into a single premium request**.

The problem? Humans rarely express everything perfectly in one shot. Follow-up questions ("wait, also do X…") are inevitable — and each one burns another request.

**Copilot Leecher** solves this by providing a `request_review` MCP tool. When the agent finishes a task, it calls this tool and *blocks* — waiting for your feedback via a local web UI. Your feedback is returned as a **tool call result** (free!), not a new user prompt. The agent then acts on your feedback within the *same* request.

One prompt → review → refine → review → approve. **All for the price of a single premium request.**

## How It Works

```
You (1 prompt)                    Copilot Agent
    │                                  │
    ├─── "Implement feature X" ────────►  (works on it…)
    │                                  │
    │                  request_review() │  ← MCP tool call (FREE)
    │                                  │
    │   ┌──────────────────────────────┤
    │   │ Web UI (localhost:3456)      │
    │   │ "Also handle edge case Y"   │  ← your feedback
    │   └──────────────────────────────┤
    │                                  │
    │                  (improves work…) │
    │                                  │
    │                  request_review() │  ← still FREE
    │   ┌──────────────────────────────┤
    │   │ "ok"                         │  ← approved
    │   └──────────────────────────────┤
    │                                  │
    │            ✅ Done ◄──────────────┤
    │                                  │
    Total premium requests used: 1
```

## Quick Start

### 1. Install & Build

```bash
git clone https://github.com/user/copilot-leecher.git
cd copilot-leecher
npm install
npm run build
```

### 2. Configure VS Code

Add to your VS Code `settings.json`:

```json
{
  "github.copilot.chat.mcp.servers": {
    "copilot-leecher": {
      "command": "node",
      "args": ["/absolute/path/to/copilot-leecher/dist/index.js"]
    }
  }
}
```

> Replace the path with your actual absolute path.

### 3. Restart VS Code & Open Dashboard

Restart VS Code. The MCP server auto-starts an HTTP dashboard at **http://127.0.0.1:3456**.

### 4. Use It

In your Copilot Chat prompt or Agent Contract, instruct the agent:

```
After completing your work, call the request_review tool with a taskId and summary.
Wait for feedback. If approved, finish. Otherwise, improve and request review again.
```

Then open http://127.0.0.1:3456 to review and provide feedback.

## Architecture

```
┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
│  VS Code #1     │   │  VS Code #2     │   │  Browser        │
│  Copilot Agent  │   │  Copilot Agent  │   │  127.0.0.1:3456 │
└────────┬────────┘   └────────┬────────┘   └────────┬────────┘
         │ MCP                 │ MCP                  │ HTTP
    ┌────▼────┐           ┌────▼────┐                 │
    │MCP+HTTP │           │MCP only │                 │
    │Server #1│           │Server #2│                 │
    │(:3456)  │           │(skipped)│                 │
    └────┬────┘           └────┬────┘                 │
         └────────┬────────────┘                      │
                  ▼                                   │
    ┌──────────────────────────────────┐              │
    │  /tmp/copilot-reviewer-sessions/ │◄─────────────┘
    │  (file-system persistence)       │
    └──────────────────────────────────┘
```

- The first MCP process binds port 3456 for the web dashboard.
- Subsequent instances skip the HTTP server but share session data via the filesystem.

## MCP Tool: `request_review`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `taskId` | string | ✅ | Unique task identifier (e.g. `task-20260217-001`) |
| `summary` | string | ✅ | Brief summary of work done (2-3 sentences) |

**Returns**: `{ status, feedback, sessionId, reviewerUrl }`

- `status`: `"approved"` or `"needs_revision"`
- `feedback`: The reviewer's text

## HTTP API

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/sessions` | List all sessions |
| GET | `/api/sessions/pending` | List pending sessions |
| GET | `/api/sessions/:id` | Get session details |
| POST | `/api/sessions/:id/feedback` | Submit feedback `{ "feedback": "..." }` |
| GET | `/api/health` | Health check |

## Agent Contract Template

Add this to your prompt / system instructions:

```markdown
After completing all tasks, you MUST call the `request_review` tool.

- taskId: a unique identifier for the task
- summary: 2-3 sentences describing what you did

Then wait for expert feedback:
- "ok" / "approved" / "lgtm" → task complete, stop working
- anything else → improve your work based on the feedback, then call request_review again

NEVER finish without an approved review.
```

<details>
<summary><strong>Full Agent Contract Example (click to expand)</strong></summary>

```markdown
# Agent Contract

## Review Requirements

### When to Request Review
After completing all task steps, you MUST call `request_review`.

### How to Call
- **taskId**: Use format `[type]-[date]-[seq]` (e.g. `feature-20260217-001`)
- **summary**: 2-3 sentences summarizing your work

### Handling Feedback
1. **Approved** ("ok" / "approved" / "lgtm"): Stop working, confirm completion
2. **Needs revision**: Read feedback, improve, call request_review again
3. **Timeout**: Inform user, offer to retry

### Rules
- ❌ NEVER finish without approved review
- ❌ NEVER skip the review step
- ✅ Always request review after completing work
- ✅ Keep improving until approved
```

</details>

## Project Structure

```
src/
├── index.ts            # MCP server entry (auto-starts HTTP server)
├── reviewer-server.ts  # Express HTTP server + Web UI
├── types.ts            # TypeScript type definitions
└── shared-state.ts     # File-system-based session persistence
```

## Development

```bash
npm run watch     # watch mode
npm run dev       # build + run MCP server
```

## Troubleshooting

**MCP Server won't connect?**  
Ensure an absolute path in `settings.json` and that `dist/index.js` exists. Check VS Code Output panel → "MCP Server" logs.

**Port 3456 in use?**  
A second MCP instance auto-skips HTTP startup. Sessions are shared via `/tmp/copilot-reviewer-sessions/` — one dashboard shows all.

**Agent doesn't call request_review?**  
Make sure your Agent Contract / prompt explicitly requires it.

## License

MIT

---

# 中文说明

> 薅 GitHub Copilot Premium Request 羊毛的勤俭玩法 —— 把追问变成免费的 MCP tool call。

## 为什么做这个

GitHub Copilot 按 **premium request 次数**计费（Pro 套餐每月 300 次，一次 Claude Opus 4.6 调用算 3 次），而**不是**按 token 计费。经过实验，我们发现：

| 操作 | 消耗 Premium Request？ |
|---|---|
| 新的 user prompt | ✅ 是 |
| 同 session 中的追问/后续提问 | ✅ 是 |
| Tool call / MCP 调用 | ❌ **否** |

所以最划算的用法是：**让一次 premium request 做尽可能多的事情**。

问题是，人很难一次性把需求表达清楚，追问在所难免——但每次追问都会额外消耗一个 request。

**Copilot Leecher** 提供了一个 `request_review` MCP tool。Agent 完成任务后调用此工具，进入*阻塞等待*状态，你在本地 Web UI 上给出反馈。反馈以 **tool call result**（免费！）的形式返回给 Agent，而不是新的 user prompt。Agent 在*同一个 request* 内继续工作。

一次 prompt → 审查 → 改进 → 审查 → 通过。**全程只消耗一个 premium request。**

简单来说：这个 MCP 服务"骗"大模型把你事实上的追问当成 tool call result 来处理。

## 工作原理

```
你 (1 条 prompt)                  Copilot Agent
    │                                  │
    ├─── "实现功能 X" ─────────────────►  （开始干活…）
    │                                  │
    │                  request_review() │  ← MCP tool call（免费）
    │                                  │
    │   ┌──────────────────────────────┤
    │   │ Web UI (localhost:3456)      │
    │   │ "边界情况 Y 也处理一下"       │  ← 你的反馈
    │   └──────────────────────────────┤
    │                                  │
    │                  （继续改进…）     │
    │                                  │
    │                  request_review() │  ← 仍然免费
    │   ┌──────────────────────────────┤
    │   │ "ok"                         │  ← 通过
    │   └──────────────────────────────┤
    │                                  │
    │            ✅ 完成 ◄──────────────┤
    │                                  │
    消耗的 premium request 总数: 1
```

## 快速开始

### 1. 安装 & 构建

```bash
git clone https://github.com/user/copilot-leecher.git
cd copilot-leecher
npm install
npm run build
```

### 2. 配置 VS Code

在 `settings.json` 中添加：

```json
{
  "github.copilot.chat.mcp.servers": {
    "copilot-leecher": {
      "command": "node",
      "args": ["/你的绝对路径/copilot-leecher/dist/index.js"]
    }
  }
}
```

### 3. 重启 VS Code & 打开 Dashboard

重启 VS Code 后，MCP Server 会自动在 **http://127.0.0.1:3456** 启动 Web 审查界面。

### 4. 使用

在 Copilot Chat 提示词或 Agent Contract 中，指示 Agent：

```
完成所有工作后，调用 request_review 工具，附上 taskId 和工作摘要。
等待审查反馈：若反馈为 "ok" / "approved"，结束任务；否则根据反馈改进后重新请求审查。
未通过审查不得结束工作。
```

然后打开 http://127.0.0.1:3456 进行审查并提交反馈。

## Agent Contract 模板

```markdown
完成所有任务后，你**必须**调用 `request_review` tool：

- taskId: 任务唯一标识（如 feature-20260217-001）
- summary: 2-3 句简要描述完成了什么

然后等待专家反馈：
- "ok" / "approved" / "lgtm" / "通过" → 结束工作
- 其他内容 → 根据反馈改进，然后再次调用 request_review

**重要：未通过审查不得结束工作！**
```

<details>
<summary><strong>完整 Agent Contract 示例（点击展开）</strong></summary>

```markdown
# Agent Contract

## 审查要求

### 何时请求审查
完成所有任务步骤后，**必须**调用 `request_review`。

### 调用方式
- **taskId**: 格式 `[类型]-[日期]-[序号]`（如 `feature-20260217-001`）
- **summary**: 2-3 句描述你完成的工作

### 反馈处理
1. **通过**（"ok" / "approved" / "lgtm" / "通过"）：停止工作，确认完成
2. **需要改进**：阅读反馈，改进工作，再次调用 request_review
3. **超时**：告知用户，询问是否重新请求

### 规则
- ❌ 未经审查通过不得结束任务
- ❌ 不得跳过审查步骤
- ✅ 完成工作后立即请求审查
- ✅ 持续改进直到获批
```

</details>

## 常见问题

**Q: MCP Server 无法连接？**  
确保 `settings.json` 中使用绝对路径，且 `dist/index.js` 存在。查看 VS Code 输出面板 → "MCP Server" 日志。

**Q: 端口 3456 被占用？**  
第二个 MCP 实例会自动跳过 HTTP 启动。Session 通过 `/tmp/copilot-reviewer-sessions/` 文件共享，同一个 Dashboard 可见所有实例的会话。

**Q: Agent 不调用 request_review？**  
检查 Agent Contract 提示词中是否明确要求了。

## 许可证

MIT