agent-pool-mcp 1.7.0 → 1.7.1
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 +82 -143
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,3 +1,7 @@
|
|
|
1
|
+
[](https://www.npmjs.com/package/agent-pool-mcp)
|
|
2
|
+
[](https://opensource.org/licenses/MIT)
|
|
3
|
+
[](https://nodejs.org)
|
|
4
|
+
|
|
1
5
|
# agent-pool-mcp
|
|
2
6
|
|
|
3
7
|
**MCP server for multi-agent orchestration** — parallel task delegation, sequential pipelines, cron scheduling, and cross-model peer review via [Gemini CLI](https://github.com/google-gemini/gemini-cli).
|
|
@@ -6,13 +10,9 @@
|
|
|
6
10
|
|
|
7
11
|
Compatible with [Antigravity](https://antigravity.dev), Cursor, Windsurf, Claude Code, and any MCP-enabled coding agent.
|
|
8
12
|
|
|
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.
|
|
13
|
+
Your primary IDE agent delegates background tasks to Gemini CLI workers in parallel — all sharing the same authentication from a single Gemini subscription.
|
|
12
14
|
|
|
13
|
-
When the primary agent and Gemini workers are **different foundation models** (e.g. Claude + Gemini), `consult_peer`
|
|
14
|
-
|
|
15
|
-
## How It Works
|
|
15
|
+
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
16
|
|
|
17
17
|
```
|
|
18
18
|
┌─────────────────────────────────┐
|
|
@@ -30,45 +30,18 @@ When the primary agent and Gemini workers are **different foundation models** (e
|
|
|
30
30
|
(task1) (task2) (review) (same auth, parallel)
|
|
31
31
|
```
|
|
32
32
|
|
|
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
|
-
```
|
|
33
|
+
> [!TIP]
|
|
34
|
+
> A single $20/month Google AI Ultra subscription can power dozens of parallel workers — no additional API keys required.
|
|
49
35
|
|
|
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.
|
|
36
|
+
### Task Delegation
|
|
55
37
|
|
|
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.
|
|
38
|
+
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
39
|
|
|
60
|
-
|
|
40
|
+
### Pipelines — Sequential Task Chains
|
|
61
41
|
|
|
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 |
|
|
42
|
+
Multi-step workflows with automatic handoff between steps:
|
|
68
43
|
|
|
69
|
-
**Example — 3-step pipeline:**
|
|
70
44
|
```javascript
|
|
71
|
-
// Agent creates the pipeline
|
|
72
45
|
create_pipeline({
|
|
73
46
|
name: "article-workflow",
|
|
74
47
|
steps: [
|
|
@@ -77,86 +50,59 @@ create_pipeline({
|
|
|
77
50
|
{ name: "review", prompt: "Review the draft for accuracy and style" }
|
|
78
51
|
]
|
|
79
52
|
})
|
|
80
|
-
|
|
81
|
-
// Agent starts execution — daemon handles the rest
|
|
82
53
|
run_pipeline({ pipeline_id: "article-workflow" })
|
|
83
54
|
```
|
|
84
55
|
|
|
85
|
-
|
|
86
|
-
Schedule agents to run automatically on a cron schedule:
|
|
56
|
+
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.
|
|
87
57
|
|
|
88
|
-
|
|
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.
|
|
58
|
+
### Cron Scheduler
|
|
92
59
|
|
|
93
|
-
|
|
60
|
+
Schedule agents on a cron expression — a detached daemon survives IDE/CLI restarts. Uses atomic file locks to prevent duplicate execution.
|
|
94
61
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
2
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
**Skill Tools:**
|
|
102
|
-
- **`list_skills`** — See all available skills and their tiers.
|
|
103
|
-
- **`install_skill`** — Copy a global or built-in skill to the project tier for local customization.
|
|
104
|
-
- **`create_skill` / `delete_skill`** — Manage skill files in project or global scope.
|
|
62
|
+
```
|
|
63
|
+
"0 9 * * MON-FRI" — 9am weekdays
|
|
64
|
+
"*/30 * * * *" — every 30 minutes
|
|
65
|
+
"0 */2 * * *" — every 2 hours
|
|
66
|
+
```
|
|
105
67
|
|
|
106
|
-
|
|
68
|
+
Results are saved to `.agents/scheduled-results/` and retrievable via `get_scheduled_results`.
|
|
107
69
|
|
|
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.
|
|
70
|
+
### 3-Tier Skill System
|
|
113
71
|
|
|
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.
|
|
72
|
+
Skills are Markdown files with YAML frontmatter that extend agent behavior:
|
|
117
73
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
74
|
+
1. **Project** — `.gemini/skills/` (local to repo, takes precedence)
|
|
75
|
+
2. **Global** — `~/.gemini/skills/` (available across all projects)
|
|
76
|
+
3. **Built-in** — shipped with agent-pool (`code-reviewer`, `test-writer`, `doc-fixer`, `orchestrator`)
|
|
121
77
|
|
|
122
|
-
|
|
78
|
+
Install a built-in or global skill into the project for local customization with `install_skill`.
|
|
123
79
|
|
|
124
|
-
|
|
125
|
-
Create `agent-pool.config.json` in your project root or `~/.config/agent-pool/config.json`:
|
|
80
|
+
### Per-Task Policies
|
|
126
81
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
{ "id": "gpu", "type": "ssh", "host": "gpu-server", "cwd": "/home/dev/project" }
|
|
132
|
-
],
|
|
133
|
-
"defaultRunner": "local"
|
|
134
|
-
}
|
|
135
|
-
```
|
|
82
|
+
Restrict tool usage for specific tasks using YAML policies:
|
|
83
|
+
- `"read-only"` — disables all file-writing and destructive shell tools
|
|
84
|
+
- `"safe-edit"` — allows file modifications but blocks arbitrary shell execution
|
|
85
|
+
- Custom path — `"/path/to/my-policy.yaml"`
|
|
136
86
|
|
|
137
|
-
|
|
87
|
+
### Cross-Model Peer Review
|
|
138
88
|
|
|
139
|
-
|
|
89
|
+
`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
90
|
|
|
141
|
-
|
|
142
|
-
|----------|---------|--------|
|
|
143
|
-
| `AGENT_POOL_DEPTH` | Current nesting level (auto-incremented) | `0` |
|
|
144
|
-
| `AGENT_POOL_MAX_DEPTH` | Max allowed depth | not set (no limit) |
|
|
91
|
+
### Security
|
|
145
92
|
|
|
146
|
-
|
|
93
|
+
- **Path Traversal Protection** — all skill and policy operations are sanitized to prevent access outside designated directories
|
|
94
|
+
- **Process Isolation** — tasks run as detached processes; `cancel_task` and server shutdown kill entire process groups
|
|
95
|
+
- **Credential Safety** — uses your local Gemini CLI authentication; no keys are stored or transmitted
|
|
147
96
|
|
|
148
|
-
##
|
|
97
|
+
## Quick Start
|
|
149
98
|
|
|
150
|
-
|
|
151
|
-
- **[Gemini CLI](https://github.com/google-gemini/gemini-cli)** — installed and authenticated:
|
|
99
|
+
**Prerequisites:** Node.js >= 20, [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and authenticated.
|
|
152
100
|
|
|
153
101
|
```bash
|
|
154
102
|
npm install -g @google/gemini-cli
|
|
155
103
|
gemini # First run: opens browser for OAuth
|
|
156
104
|
```
|
|
157
105
|
|
|
158
|
-
## Installation
|
|
159
|
-
|
|
160
106
|
Add to your IDE's MCP configuration:
|
|
161
107
|
|
|
162
108
|
```json
|
|
@@ -173,7 +119,7 @@ Add to your IDE's MCP configuration:
|
|
|
173
119
|
Restart your IDE — agent-pool-mcp will be downloaded and started automatically.
|
|
174
120
|
|
|
175
121
|
<details>
|
|
176
|
-
<summary
|
|
122
|
+
<summary>Where is my MCP config file?</summary>
|
|
177
123
|
|
|
178
124
|
| IDE | Config path |
|
|
179
125
|
|-----|------------|
|
|
@@ -185,7 +131,7 @@ Restart your IDE — agent-pool-mcp will be downloaded and started automatically
|
|
|
185
131
|
</details>
|
|
186
132
|
|
|
187
133
|
<details>
|
|
188
|
-
<summary
|
|
134
|
+
<summary>Alternative: global install</summary>
|
|
189
135
|
|
|
190
136
|
```bash
|
|
191
137
|
npm install -g agent-pool-mcp
|
|
@@ -201,9 +147,9 @@ Then use `"command": "agent-pool-mcp"` in your MCP config (no npx needed).
|
|
|
201
147
|
npx agent-pool-mcp --check
|
|
202
148
|
```
|
|
203
149
|
|
|
204
|
-
|
|
150
|
+
Runs diagnostics: checks Node.js, Gemini CLI, authentication, and remote runner connectivity.
|
|
205
151
|
|
|
206
|
-
### CLI
|
|
152
|
+
### CLI
|
|
207
153
|
|
|
208
154
|
```bash
|
|
209
155
|
npx agent-pool-mcp --check # Doctor mode: diagnose prerequisites
|
|
@@ -212,6 +158,31 @@ npx agent-pool-mcp --version # Show version
|
|
|
212
158
|
npx agent-pool-mcp --help # Full help
|
|
213
159
|
```
|
|
214
160
|
|
|
161
|
+
## Remote Workers (SSH)
|
|
162
|
+
|
|
163
|
+
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`:
|
|
164
|
+
|
|
165
|
+
```json
|
|
166
|
+
{
|
|
167
|
+
"runners": [
|
|
168
|
+
{ "id": "local", "type": "local" },
|
|
169
|
+
{ "id": "gpu", "type": "ssh", "host": "gpu-server", "cwd": "/home/dev/project" }
|
|
170
|
+
],
|
|
171
|
+
"defaultRunner": "local"
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Nested Orchestration
|
|
176
|
+
|
|
177
|
+
Install agent-pool inside Gemini CLI to enable hierarchical delegation — workers can spawn their own workers.
|
|
178
|
+
|
|
179
|
+
| Variable | Purpose | Default |
|
|
180
|
+
|----------|---------|--------|
|
|
181
|
+
| `AGENT_POOL_DEPTH` | Current nesting level (auto-incremented) | `0` |
|
|
182
|
+
| `AGENT_POOL_MAX_DEPTH` | Max allowed depth | not set (no limit) |
|
|
183
|
+
|
|
184
|
+
See [parallel-work guide](examples/parallel-work.md) and built-in `orchestrator` skill for patterns.
|
|
185
|
+
|
|
215
186
|
## MCP Ecosystem
|
|
216
187
|
|
|
217
188
|
Best used together with [**project-graph-mcp**](https://www.npmjs.com/package/project-graph-mcp) — AST-based codebase analysis:
|
|
@@ -221,8 +192,6 @@ Best used together with [**project-graph-mcp**](https://www.npmjs.com/package/pr
|
|
|
221
192
|
| **Primary IDE agent** | Delegates tasks, consults peer | Navigates codebase, runs analysis |
|
|
222
193
|
| **Gemini CLI workers** | Executes delegated tasks | Available as MCP tool inside workers |
|
|
223
194
|
|
|
224
|
-
Combined config for both:
|
|
225
|
-
|
|
226
195
|
```json
|
|
227
196
|
{
|
|
228
197
|
"mcpServers": {
|
|
@@ -238,53 +207,23 @@ Combined config for both:
|
|
|
238
207
|
}
|
|
239
208
|
```
|
|
240
209
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
- **Path Traversal Protection**: All skill and policy operations are sanitized to prevent access outside designated directories.
|
|
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.
|
|
210
|
+
> [!IMPORTANT]
|
|
211
|
+
> Each Gemini CLI worker gets its own MCP server instance but shares pipeline state via filesystem — no coordination overhead.
|
|
246
212
|
|
|
247
|
-
##
|
|
213
|
+
## Documentation
|
|
248
214
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
policies/ ← Tool restriction policies (YAML)
|
|
252
|
-
├── read-only.yaml
|
|
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
|
-
```
|
|
215
|
+
- [ARCHITECTURE.md](ARCHITECTURE.md) — Source code structure and process management details
|
|
216
|
+
- [examples/parallel-work.md](examples/parallel-work.md) — Delegation patterns and best practices
|
|
278
217
|
|
|
279
|
-
|
|
280
|
-
-
|
|
281
|
-
-
|
|
282
|
-
-
|
|
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.
|
|
218
|
+
## Related Projects
|
|
219
|
+
- [project-graph-mcp](https://github.com/rnd-pro/project-graph-mcp) — AST-based codebase analysis for AI agents
|
|
220
|
+
- [Symbiote.js](https://github.com/symbiotejs/symbiote.js) — Isomorphic Reactive Web Components framework
|
|
221
|
+
- [JSDA-Kit](https://github.com/rnd-pro/jsda-kit) — SSG/SSR toolkit for modern web applications
|
|
286
222
|
|
|
287
223
|
## License
|
|
288
224
|
|
|
289
|
-
MIT
|
|
225
|
+
MIT © [RND-PRO.com](https://rnd-pro.com)
|
|
226
|
+
|
|
227
|
+
---
|
|
290
228
|
|
|
229
|
+
**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.1",
|
|
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",
|