agent-pool-mcp 1.7.0 → 1.7.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +83 -146
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,18 +1,16 @@
|
|
|
1
|
-
|
|
1
|
+
[](https://www.npmjs.com/package/agent-pool-mcp)
|
|
2
|
+
[](https://opensource.org/licenses/MIT)
|
|
3
|
+
[](https://nodejs.org)
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
# agent-pool-mcp
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
Multi-agent orchestration via [Gemini CLI](https://github.com/google-gemini/gemini-cli) — parallel task delegation, sequential pipelines, cron scheduling, and cross-model peer review.
|
|
6
8
|
|
|
7
9
|
Compatible with [Antigravity](https://antigravity.dev), Cursor, Windsurf, Claude Code, and any MCP-enabled coding agent.
|
|
8
10
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
AI coding assistants are powerful, but they work **sequentially** — one task at a time. Agent-pool turns your single Gemini subscription into a **parallel agent workforce**: your primary IDE agent delegates background tasks to Gemini CLI workers, all sharing the same authentication.
|
|
12
|
-
|
|
13
|
-
When the primary agent and Gemini workers are **different foundation models** (e.g. Claude + Gemini), `consult_peer` becomes a **cross-model reasoning amplifier** — two independent architectures reviewing each other eliminate systematic blind spots that plague single-model workflows.
|
|
11
|
+
Your primary IDE agent delegates background tasks to Gemini CLI workers in parallel — all sharing the same authentication from a single Gemini subscription.
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
When the primary agent and Gemini workers are **different foundation models** (e.g. Claude + Gemini), `consult_peer` gives you cross-model review — two models check each other's reasoning independently.
|
|
16
14
|
|
|
17
15
|
```
|
|
18
16
|
┌─────────────────────────────────┐
|
|
@@ -30,45 +28,18 @@ When the primary agent and Gemini workers are **different foundation models** (e
|
|
|
30
28
|
(task1) (task2) (review) (same auth, parallel)
|
|
31
29
|
```
|
|
32
30
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
### 🚀 Task Delegation
|
|
36
|
-
- **`delegate_task`** — Non-blocking task delegation to Gemini CLI (full filesystem access).
|
|
37
|
-
- **`delegate_task_readonly`** — Read-only analysis (plan mode). Supports `session_id` to resume previous analyses.
|
|
38
|
-
- **`get_task_result`** — Poll task status, retrieve results, and see live progress (last 200 tool/message events).
|
|
39
|
-
- **`cancel_task`** — Kill a running task and its entire process group immediately.
|
|
40
|
-
|
|
41
|
-
### 🔗 Pipelines — Sequential Task Chains
|
|
42
|
-
Define multi-step workflows where agents execute sequentially, with automatic handoff:
|
|
43
|
-
|
|
44
|
-
```
|
|
45
|
-
┌─ frontend ─┐
|
|
46
|
-
research ─┤ ├── deploy
|
|
47
|
-
└─ backend ─┘
|
|
48
|
-
```
|
|
31
|
+
> [!TIP]
|
|
32
|
+
> A single $20/month Google AI Ultra subscription can power dozens of parallel workers — no additional API keys required.
|
|
49
33
|
|
|
50
|
-
|
|
51
|
-
- **`run_pipeline`** — Start executing a pipeline. A detached daemon manages the lifecycle.
|
|
52
|
-
- **`list_pipelines`** — See all definitions, active runs, and recent completions.
|
|
53
|
-
- **`get_pipeline_status`** — Step-by-step status with emoji indicators.
|
|
54
|
-
- **`cancel_pipeline`** — Stop a running pipeline and kill active step processes.
|
|
34
|
+
### Task Delegation
|
|
55
35
|
|
|
56
|
-
|
|
57
|
-
- **`signal_step_complete`** — Mark the current step as done. Accepts optional output and `run_id`.
|
|
58
|
-
- **`bounce_back`** — Return task to a previous step with feedback (e.g. "data incomplete"). Supports `maxBounces` limit.
|
|
36
|
+
Non-blocking task delegation to Gemini CLI workers. The primary agent fires off a task and continues working — polling for results when ready. Workers get full filesystem access (`delegate_task`) or read-only mode (`delegate_task_readonly`). Cancel anytime with `cancel_task`.
|
|
59
37
|
|
|
60
|
-
|
|
38
|
+
### Pipelines — Sequential Task Chains
|
|
61
39
|
|
|
62
|
-
|
|
63
|
-
|---------|-------------|
|
|
64
|
-
| `on_complete` | Start when a specific step succeeds |
|
|
65
|
-
| `on_complete_all` | Fan-in: start when ALL listed steps succeed |
|
|
66
|
-
| `on_file` | Start when a file appears and the producing process exits |
|
|
67
|
-
| Auto-fallback | Process death without signal → auto-complete/fail |
|
|
40
|
+
Multi-step workflows with automatic handoff between steps:
|
|
68
41
|
|
|
69
|
-
**Example — 3-step pipeline:**
|
|
70
42
|
```javascript
|
|
71
|
-
// Agent creates the pipeline
|
|
72
43
|
create_pipeline({
|
|
73
44
|
name: "article-workflow",
|
|
74
45
|
steps: [
|
|
@@ -77,86 +48,59 @@ create_pipeline({
|
|
|
77
48
|
{ name: "review", prompt: "Review the draft for accuracy and style" }
|
|
78
49
|
]
|
|
79
50
|
})
|
|
80
|
-
|
|
81
|
-
// Agent starts execution — daemon handles the rest
|
|
82
51
|
run_pipeline({ pipeline_id: "article-workflow" })
|
|
83
52
|
```
|
|
84
53
|
|
|
85
|
-
|
|
86
|
-
Schedule agents to run automatically on a cron schedule:
|
|
87
|
-
|
|
88
|
-
- **`schedule_task`** — Schedule a Gemini CLI agent with cron expression (e.g. `0 9 * * MON-FRI`).
|
|
89
|
-
- **`list_schedules`** — See all schedules with next run times and daemon status.
|
|
90
|
-
- **`cancel_schedule`** — Remove a schedule. Daemon auto-exits when no schedules remain.
|
|
91
|
-
- **`get_scheduled_results`** — Retrieve results from past scheduled executions.
|
|
54
|
+
Steps support triggers: `on_complete` (chain after one step), `on_complete_all` (fan-in after several), and `on_file` (start when a file appears). Agents can `bounce_back` to a previous step with feedback if data is incomplete.
|
|
92
55
|
|
|
93
|
-
|
|
56
|
+
### Cron Scheduler
|
|
94
57
|
|
|
95
|
-
|
|
96
|
-
Skills are Markdown files with YAML frontmatter that extend agent behavior. Agent-pool manages skills in three tiers:
|
|
97
|
-
1. **Project**: `.gemini/skills/` (local to repo, takes precedence).
|
|
98
|
-
2. **Global**: `~/.gemini/skills/` (available across all projects).
|
|
99
|
-
3. **Built-in**: Shipped with agent-pool (e.g., `code-reviewer`, `test-writer`, `doc-fixer`).
|
|
58
|
+
Schedule agents on a cron expression — a detached daemon survives IDE/CLI restarts. Uses atomic file locks to prevent duplicate execution.
|
|
100
59
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
60
|
+
```
|
|
61
|
+
"0 9 * * MON-FRI" — 9am weekdays
|
|
62
|
+
"*/30 * * * *" — every 30 minutes
|
|
63
|
+
"0 */2 * * *" — every 2 hours
|
|
64
|
+
```
|
|
105
65
|
|
|
106
|
-
|
|
66
|
+
Results are saved to `.agents/scheduled-results/` and retrievable via `get_scheduled_results`.
|
|
107
67
|
|
|
108
|
-
###
|
|
109
|
-
Restrict tool usage for specific tasks using YAML policies. Use built-in templates or custom paths:
|
|
110
|
-
- `policy: "read-only"` — Disables all file-writing and destructive shell tools.
|
|
111
|
-
- `policy: "safe-edit"` — Allows file modifications but blocks arbitrary shell execution.
|
|
112
|
-
- `policy: "/path/to/my-policy.yaml"` — Use a custom security policy.
|
|
68
|
+
### 3-Tier Skill System
|
|
113
69
|
|
|
114
|
-
|
|
115
|
-
- **`consult_peer`** — Architectural review with structured verdicts (AGREE / SUGGEST_CHANGES / DISAGREE).
|
|
116
|
-
- Supports iterative rounds: propose → get feedback → revise → re-send until consensus.
|
|
70
|
+
Skills are Markdown files with YAML frontmatter that extend agent behavior:
|
|
117
71
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
72
|
+
1. **Project** — `.gemini/skills/` (local to repo, takes precedence)
|
|
73
|
+
2. **Global** — `~/.gemini/skills/` (available across all projects)
|
|
74
|
+
3. **Built-in** — shipped with agent-pool (`code-reviewer`, `test-writer`, `doc-fixer`, `orchestrator`)
|
|
121
75
|
|
|
122
|
-
|
|
76
|
+
Install a built-in or global skill into the project for local customization with `install_skill`.
|
|
123
77
|
|
|
124
|
-
|
|
125
|
-
Create `agent-pool.config.json` in your project root or `~/.config/agent-pool/config.json`:
|
|
78
|
+
### Per-Task Policies
|
|
126
79
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
{ "id": "gpu", "type": "ssh", "host": "gpu-server", "cwd": "/home/dev/project" }
|
|
132
|
-
],
|
|
133
|
-
"defaultRunner": "local"
|
|
134
|
-
}
|
|
135
|
-
```
|
|
80
|
+
Restrict tool usage for specific tasks using YAML policies:
|
|
81
|
+
- `"read-only"` — disables all file-writing and destructive shell tools
|
|
82
|
+
- `"safe-edit"` — allows file modifications but blocks arbitrary shell execution
|
|
83
|
+
- Custom path — `"/path/to/my-policy.yaml"`
|
|
136
84
|
|
|
137
|
-
|
|
85
|
+
### Cross-Model Peer Review
|
|
138
86
|
|
|
139
|
-
|
|
87
|
+
`consult_peer` sends architectural proposals to a Gemini worker for structured review. The worker responds with a verdict: **AGREE**, **SUGGEST_CHANGES**, or **DISAGREE**. Supports iterative rounds until consensus.
|
|
140
88
|
|
|
141
|
-
|
|
142
|
-
|----------|---------|--------|
|
|
143
|
-
| `AGENT_POOL_DEPTH` | Current nesting level (auto-incremented) | `0` |
|
|
144
|
-
| `AGENT_POOL_MAX_DEPTH` | Max allowed depth | not set (no limit) |
|
|
89
|
+
### Security
|
|
145
90
|
|
|
146
|
-
|
|
91
|
+
- **Path Traversal Protection** — all skill and policy operations are sanitized to prevent access outside designated directories
|
|
92
|
+
- **Process Isolation** — tasks run as detached processes; `cancel_task` and server shutdown kill entire process groups
|
|
93
|
+
- **Credential Safety** — uses your local Gemini CLI authentication; no keys are stored or transmitted
|
|
147
94
|
|
|
148
|
-
##
|
|
95
|
+
## Quick Start
|
|
149
96
|
|
|
150
|
-
|
|
151
|
-
- **[Gemini CLI](https://github.com/google-gemini/gemini-cli)** — installed and authenticated:
|
|
97
|
+
**Prerequisites:** Node.js >= 20, [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and authenticated.
|
|
152
98
|
|
|
153
99
|
```bash
|
|
154
100
|
npm install -g @google/gemini-cli
|
|
155
101
|
gemini # First run: opens browser for OAuth
|
|
156
102
|
```
|
|
157
103
|
|
|
158
|
-
## Installation
|
|
159
|
-
|
|
160
104
|
Add to your IDE's MCP configuration:
|
|
161
105
|
|
|
162
106
|
```json
|
|
@@ -173,7 +117,7 @@ Add to your IDE's MCP configuration:
|
|
|
173
117
|
Restart your IDE — agent-pool-mcp will be downloaded and started automatically.
|
|
174
118
|
|
|
175
119
|
<details>
|
|
176
|
-
<summary
|
|
120
|
+
<summary>Where is my MCP config file?</summary>
|
|
177
121
|
|
|
178
122
|
| IDE | Config path |
|
|
179
123
|
|-----|------------|
|
|
@@ -185,7 +129,7 @@ Restart your IDE — agent-pool-mcp will be downloaded and started automatically
|
|
|
185
129
|
</details>
|
|
186
130
|
|
|
187
131
|
<details>
|
|
188
|
-
<summary
|
|
132
|
+
<summary>Alternative: global install</summary>
|
|
189
133
|
|
|
190
134
|
```bash
|
|
191
135
|
npm install -g agent-pool-mcp
|
|
@@ -201,9 +145,9 @@ Then use `"command": "agent-pool-mcp"` in your MCP config (no npx needed).
|
|
|
201
145
|
npx agent-pool-mcp --check
|
|
202
146
|
```
|
|
203
147
|
|
|
204
|
-
|
|
148
|
+
Runs diagnostics: checks Node.js, Gemini CLI, authentication, and remote runner connectivity.
|
|
205
149
|
|
|
206
|
-
### CLI
|
|
150
|
+
### CLI
|
|
207
151
|
|
|
208
152
|
```bash
|
|
209
153
|
npx agent-pool-mcp --check # Doctor mode: diagnose prerequisites
|
|
@@ -212,6 +156,31 @@ npx agent-pool-mcp --version # Show version
|
|
|
212
156
|
npx agent-pool-mcp --help # Full help
|
|
213
157
|
```
|
|
214
158
|
|
|
159
|
+
## Remote Workers (SSH)
|
|
160
|
+
|
|
161
|
+
Run workers on remote servers via SSH — same interface, transparent stdio forwarding. Create `agent-pool.config.json` in your project root or `~/.config/agent-pool/config.json`:
|
|
162
|
+
|
|
163
|
+
```json
|
|
164
|
+
{
|
|
165
|
+
"runners": [
|
|
166
|
+
{ "id": "local", "type": "local" },
|
|
167
|
+
{ "id": "gpu", "type": "ssh", "host": "gpu-server", "cwd": "/home/dev/project" }
|
|
168
|
+
],
|
|
169
|
+
"defaultRunner": "local"
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### Nested Orchestration
|
|
174
|
+
|
|
175
|
+
Install agent-pool inside Gemini CLI to enable hierarchical delegation — workers can spawn their own workers.
|
|
176
|
+
|
|
177
|
+
| Variable | Purpose | Default |
|
|
178
|
+
|----------|---------|--------|
|
|
179
|
+
| `AGENT_POOL_DEPTH` | Current nesting level (auto-incremented) | `0` |
|
|
180
|
+
| `AGENT_POOL_MAX_DEPTH` | Max allowed depth | not set (no limit) |
|
|
181
|
+
|
|
182
|
+
See [parallel-work guide](examples/parallel-work.md) and built-in `orchestrator` skill for patterns.
|
|
183
|
+
|
|
215
184
|
## MCP Ecosystem
|
|
216
185
|
|
|
217
186
|
Best used together with [**project-graph-mcp**](https://www.npmjs.com/package/project-graph-mcp) — AST-based codebase analysis:
|
|
@@ -221,8 +190,6 @@ Best used together with [**project-graph-mcp**](https://www.npmjs.com/package/pr
|
|
|
221
190
|
| **Primary IDE agent** | Delegates tasks, consults peer | Navigates codebase, runs analysis |
|
|
222
191
|
| **Gemini CLI workers** | Executes delegated tasks | Available as MCP tool inside workers |
|
|
223
192
|
|
|
224
|
-
Combined config for both:
|
|
225
|
-
|
|
226
193
|
```json
|
|
227
194
|
{
|
|
228
195
|
"mcpServers": {
|
|
@@ -238,53 +205,23 @@ Combined config for both:
|
|
|
238
205
|
}
|
|
239
206
|
```
|
|
240
207
|
|
|
241
|
-
|
|
208
|
+
> [!IMPORTANT]
|
|
209
|
+
> Each Gemini CLI worker gets its own MCP server instance but shares pipeline state via filesystem — no coordination overhead.
|
|
242
210
|
|
|
243
|
-
|
|
244
|
-
- **Process Isolation**: Tasks run as detached processes; `cancel_task` and server shutdown ensure no zombie processes remain by killing entire process groups.
|
|
245
|
-
- **Credential Safety**: Uses your local Gemini CLI authentication; no keys are stored or transmitted by this server.
|
|
211
|
+
## Documentation
|
|
246
212
|
|
|
247
|
-
|
|
213
|
+
- [ARCHITECTURE.md](ARCHITECTURE.md) — Source code structure and process management details
|
|
214
|
+
- [examples/parallel-work.md](examples/parallel-work.md) — Delegation patterns and best practices
|
|
248
215
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
└── safe-edit.yaml
|
|
254
|
-
skills/ ← Built-in Gemini CLI skills (Markdown)
|
|
255
|
-
├── code-reviewer.md
|
|
256
|
-
├── doc-fixer.md
|
|
257
|
-
├── orchestrator.md
|
|
258
|
-
└── test-writer.md
|
|
259
|
-
src/
|
|
260
|
-
├── cli.js ← CLI commands (--check, --init, --help)
|
|
261
|
-
├── server.js ← MCP server setup + tool routing
|
|
262
|
-
├── tool-definitions.js ← Tool schemas (JSON Schema)
|
|
263
|
-
├── tools/
|
|
264
|
-
│ ├── consult.js ← Peer review via Gemini CLI
|
|
265
|
-
│ ├── results.js ← Task store + result formatting (TTL cleanup, ring buffer)
|
|
266
|
-
│ └── skills.js ← 3-tier skill management (project/global/built-in)
|
|
267
|
-
├── runner/
|
|
268
|
-
│ ├── config.js ← Runner config loader (local/SSH)
|
|
269
|
-
│ ├── gemini-runner.js ← Process spawning (streaming JSON, depth tracking)
|
|
270
|
-
│ ├── process-manager.js ← PID tracking, system load awareness, group kill
|
|
271
|
-
│ └── ssh.js ← Shell escaping, remote PID tracking
|
|
272
|
-
└── scheduler/
|
|
273
|
-
├── cron.js ← Minimal cron expression parser (zero-dependency)
|
|
274
|
-
├── daemon.js ← Detached daemon: schedule ticks + pipeline lifecycle
|
|
275
|
-
├── pipeline.js ← Pipeline CRUD, run state, signals, bounce-back
|
|
276
|
-
└── scheduler.js ← Schedule management + daemon spawning
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
**Process management:**
|
|
280
|
-
- **Detached Spawn**: Workers are spawned in their own process groups.
|
|
281
|
-
- **TTL Cleanup**: Completed task results are purged from memory after 10 minutes.
|
|
282
|
-
- **Live Events**: Progress polling uses a ring buffer to show the latest activity without overwhelming context.
|
|
283
|
-
- **Depth Tracking**: Nested orchestration support with optional `AGENT_POOL_MAX_DEPTH` limit.
|
|
284
|
-
- **Adaptive Polling**: Pipeline daemon uses 3s intervals when active, 30s when idle.
|
|
285
|
-
- **File-Based Communication**: Pipeline agents communicate through `.agents/runs/` JSON files — each Gemini process has its own MCP server instance but shares state via filesystem.
|
|
216
|
+
## Related Projects
|
|
217
|
+
- [project-graph-mcp](https://github.com/rnd-pro/project-graph-mcp) — AST-based codebase analysis for AI agents
|
|
218
|
+
- [Symbiote.js](https://github.com/symbiotejs/symbiote.js) — Isomorphic Reactive Web Components framework
|
|
219
|
+
- [JSDA-Kit](https://github.com/rnd-pro/jsda-kit) — SSG/SSR toolkit for modern web applications
|
|
286
220
|
|
|
287
221
|
## License
|
|
288
222
|
|
|
289
|
-
MIT
|
|
223
|
+
MIT © [RND-PRO.com](https://rnd-pro.com)
|
|
224
|
+
|
|
225
|
+
---
|
|
290
226
|
|
|
227
|
+
**Made with ❤️ by the RND-PRO team**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent-pool-mcp",
|
|
3
|
-
"version": "1.7.
|
|
3
|
+
"version": "1.7.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "MCP Server for multi-agent task delegation and orchestration via Gemini CLI",
|
|
6
6
|
"main": "index.js",
|
|
@@ -31,7 +31,8 @@
|
|
|
31
31
|
"cron",
|
|
32
32
|
"ai"
|
|
33
33
|
],
|
|
34
|
-
"author": "
|
|
34
|
+
"author": "RND-PRO",
|
|
35
|
+
"homepage": "https://github.com/rnd-pro/agent-pool-mcp",
|
|
35
36
|
"license": "MIT",
|
|
36
37
|
"repository": {
|
|
37
38
|
"type": "git",
|