agent-pool-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladislav Matiyasevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# agent-pool-mcp
+
+**MCP server for multi-agent orchestration** — parallel task delegation and cross-model peer review via [Gemini CLI](https://github.com/google-gemini/gemini-cli).
+
+> Developed by [RND-PRO](https://rnd-pro.com)
+
+Compatible with [Antigravity](https://antigravity.dev), Cursor, Windsurf, Claude Code, and any MCP-enabled coding agent.
+
+## Why?
+
+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.
+
+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.
+
+## How It Works
+
+```
+┌─────────────────────────────────┐
+│  Primary IDE Agent              │  ← Claude, GPT, Gemini, etc.
+│  (Antigravity / Cursor / ...)   │
+└────────────┬────────────────────┘
+             │ MCP (stdio)
+┌────────────▼────────────────────┐
+│  agent-pool-mcp                 │  ← This server
+│  (task router + process mgmt)  │
+└──┬─────────┬─────────┬─────────┘
+   │         │         │
+   ▼         ▼         ▼
+  gemini    gemini    gemini       ← Gemini CLI workers
+  (task1)   (task2)   (review)       (same auth, parallel)
+```
+
+## Features
+
+### 🚀 Task Delegation
+- **`delegate_task`** — Non-blocking task delegation to Gemini CLI (full filesystem access).
+- **`delegate_task_readonly`** — Read-only analysis (plan mode). Supports `session_id` to resume previous analyses.
+- **`get_task_result`** — Poll task status, retrieve results, and see live progress (last 200 tool/message events).
+- **`cancel_task`** — Kill a running task and its entire process group immediately.
+
+### 📋 3-Tier Skill System
+Skills are Markdown files with YAML frontmatter that extend agent behavior. Agent-pool manages skills in three tiers:
+1.  **Project**: `.gemini/skills/` (local to repo, takes precedence).
+2.  **Global**: `~/.gemini/skills/` (available across all projects).
+3.  **Built-in**: Shipped with agent-pool (e.g., `code-reviewer`, `test-writer`, `doc-fixer`).
+
+**Skill Tools:**
+- **`list_skills`** — See all available skills and their tiers.
+- **`install_skill`** — Copy a global or built-in skill to the project tier for local customization.
+- **`create_skill` / `delete_skill`** — Manage skill files in project or global scope.
+
+*Note: When delegating with a skill, agent-pool uses "hybrid activation" — it ensures the skill is available in the project and instructs Gemini CLI to activate it natively.*
+
+### 🛡️ Per-Task Policies
+Restrict tool usage for specific tasks using YAML policies. Use built-in templates or custom paths:
+- `policy: "read-only"` — Disables all file-writing and destructive shell tools.
+- `policy: "safe-edit"` — Allows file modifications but blocks arbitrary shell execution.
+- `policy: "/path/to/my-policy.yaml"` — Use a custom security policy.
+
+### 🤝 Cross-Model Peer Review
+- **`consult_peer`** — Architectural review with structured verdicts (AGREE / SUGGEST_CHANGES / DISAGREE).
+- Supports iterative rounds: propose → get feedback → revise → re-send until consensus.
+
+### 📊 System Awareness & Management
+- **System Load Detection**: Automatically detects other running Gemini processes on the system and warns if the worker pool is saturated.
+- **Session Management**: `list_sessions` allows resuming previous Gemini CLI conversations by UUID.
+
+## Remote Workers (SSH)
+
+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`:
+
+```json
+{
+  "runners": [
+    { "id": "local", "type": "local" },
+    { "id": "gpu", "type": "ssh", "host": "gpu-server", "cwd": "/home/dev/project" }
+  ],
+  "defaultRunner": "local"
+}
+```
+
+## Nested Orchestration
+
+Install agent-pool inside Gemini CLI to enable **hierarchical delegation** — workers can spawn their own workers.
+
+| Variable | Purpose | Default |
+|----------|---------|--------|
+| `AGENT_POOL_DEPTH` | Current nesting level (auto-incremented) | `0` |
+| `AGENT_POOL_MAX_DEPTH` | Max allowed depth | not set (no limit) |
+
+See [parallel-work guide](examples/parallel-work.md) and built-in `orchestrator` skill for patterns.
+
+## Prerequisites
+
+- **Node.js >= 20** — [Download](https://nodejs.org)
+- **[Gemini CLI](https://github.com/google-gemini/gemini-cli)** — installed and authenticated:
+
+```bash
+npm install -g @google/gemini-cli
+gemini    # First run: opens browser for OAuth
+```
+
+## Installation
+
+Add to your IDE's MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "agent-pool": {
+      "command": "npx",
+      "args": ["-y", "agent-pool-mcp"]
+    }
+  }
+}
+```
+
+Restart your IDE — agent-pool-mcp will be downloaded and started automatically.
+
+<details>
+<summary>📍 Where is my MCP config file?</summary>
+
+| IDE | Config path |
+|-----|------------|
+| Antigravity | `~/.gemini/antigravity/mcp_config.json` |
+| Cursor | `.cursor/mcp.json` |
+| Windsurf | `.windsurf/mcp.json` |
+| Claude Code | Run: `claude mcp add agent-pool npx -y agent-pool-mcp` |
+
+</details>
+
+<details>
+<summary>📦 Alternative: global install</summary>
+
+```bash
+npm install -g agent-pool-mcp
+```
+
+Then use `"command": "agent-pool-mcp"` in your MCP config (no npx needed).
+
+</details>
+
+### Verify
+
+```bash
+npx agent-pool-mcp --check
+```
+
+This runs diagnostics: checks Node.js, Gemini CLI, authentication, and remote runner connectivity.
+
+### CLI Commands
+
+```bash
+npx agent-pool-mcp --check      # Doctor mode: diagnose prerequisites
+npx agent-pool-mcp --init       # Create template config (for SSH runners)
+npx agent-pool-mcp --version    # Show version
+npx agent-pool-mcp --help       # Full help
+```
+
+## MCP Ecosystem
+
+Agent-pool works alongside other MCP servers:
+
+| Layer | agent-pool-mcp | [project-graph-mcp](https://github.com/rnd-pro/project-graph-mcp) |
+|-------|---------------|-------------------|
+| **Primary IDE agent** | Delegates tasks, consults peer | Navigates codebase, runs analysis |
+| **Gemini CLI workers** | Executes delegated tasks | Available as MCP tool inside Gemini CLI |
+
+## Security
+
+- **Path Traversal Protection**: All skill and policy operations are sanitized to prevent access outside designated directories.
+- **Process Isolation**: Tasks run as detached processes; `cancel_task` and server shutdown ensure no zombie processes remain by killing entire process groups.
+- **Credential Safety**: Uses your local Gemini CLI authentication; no keys are stored or transmitted by this server.
+
+## Architecture
+
+```
+index.js                    ← Entry point (stdio transport)
+policies/                   ← Tool restriction policies (YAML)
+├── read-only.yaml
+└── safe-edit.yaml
+skills/                     ← Built-in Gemini CLI skills (Markdown)
+├── code-reviewer.md
+├── doc-fixer.md
+├── orchestrator.md
+└── test-writer.md
+src/
+├── cli.js                  ← CLI commands (--check, --init, --help)
+├── server.js               ← MCP server setup + tool routing
+├── tool-definitions.js     ← Tool schemas (JSON Schema)
+├── tools/
+│   ├── consult.js          ← Peer review via Gemini CLI
+│   ├── results.js          ← Task store + result formatting (TTL cleanup, ring buffer)
+│   └── skills.js           ← 3-tier skill management (project/global/built-in)
+└── runner/
+    ├── config.js           ← Runner config loader (local/SSH)
+    ├── gemini-runner.js    ← Process spawning (streaming JSON, depth tracking)
+    ├── process-manager.js  ← PID tracking, system load awareness, group kill
+    └── ssh.js              ← Shell escaping, remote PID tracking
+```
+
+**Process management:**
+- **Detached Spawn**: Workers are spawned in their own process groups.
+- **TTL Cleanup**: Completed task results are purged from memory after 10 minutes.
+- **Live Events**: Progress polling uses a ring buffer to show the latest activity without overwhelming context.
+- **Depth Tracking**: Nested orchestration support with optional `AGENT_POOL_MAX_DEPTH` limit.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+/**
+ * Agent Pool MCP Server — Entry Point
+ *
+ * Multi-agent task delegation and orchestration via Gemini CLI.
+ * Supports CLI modes: --check, --init, --version, --help.
+ *
+ * @module agent-pool
+ */
+
+import { handleCli, validateStartup } from './src/cli.js';
+
+// CLI mode: --check, --init, --version, --help
+if (handleCli(process.argv)) {
+  // CLI command handled, don't start MCP server
+} else {
+  // MCP server mode
+  startServer();
+}
+
+async function startServer() {
+  // Warn if prerequisites are missing (don't exit — let the agent handle it)
+  validateStartup();
+
+  // Import MCP deps only when starting server
+  const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+  const { createServer } = await import('./src/server.js');
+
+  // Register SIGTERM/SIGINT handlers for process cleanup
+  await import('./src/runner/process-manager.js');
+
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[agent-pool] MCP server v1.0.0 started');
+}
+

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "agent-pool-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "MCP Server for multi-agent task delegation and orchestration via Gemini CLI",
+  "main": "index.js",
+  "bin": {
+    "agent-pool-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "policies/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "gemini",
+    "gemini-cli",
+    "agent",
+    "multi-agent",
+    "delegation",
+    "orchestration",
+    "ai"
+  ],
+  "author": "Vladislav Matiyasevich",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rnd-pro/agent-pool-mcp.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  }
+}

package/policies/read-only.yaml

@@ -0,0 +1,13 @@
+# Read-only policy — prevents file modifications
+# Use with delegate_task(policy: "read-only") for safe analysis tasks
+
+- rule: ALWAYS deny
+  tool: write_file
+- rule: ALWAYS deny
+  tool: edit_file
+- rule: ALWAYS deny
+  tool: replace_file
+- rule: ALWAYS deny
+  tool: delete_file
+- rule: ALWAYS deny
+  tool: run_shell_command

package/policies/safe-edit.yaml

@@ -0,0 +1,7 @@
+# Safe-edit policy — allows file edits but denies shell commands
+# Use with delegate_task(policy: "safe-edit") for code-only tasks
+
+- rule: ALWAYS deny
+  tool: run_shell_command
+- rule: ALWAYS deny
+  tool: delete_file

package/skills/code-reviewer.md

@@ -0,0 +1,37 @@
+---
+name: code-reviewer
+description: Reviews code changes for bugs, style issues, and potential improvements.
+---
+
+# Code Reviewer
+
+You are a senior code reviewer. Analyze the given code or diff carefully.
+
+## Review Checklist
+
+1. **Correctness** — Does the code do what it's supposed to?
+2. **Edge cases** — Are boundary conditions handled?
+3. **Error handling** — Are errors caught and reported properly?
+4. **Performance** — Any obvious inefficiencies?
+5. **Security** — Any potential vulnerabilities?
+6. **Style** — Consistent naming, formatting, documentation?
+7. **DRY** — Any duplicated logic that should be extracted?
+
+## Output Format
+
+```markdown
+## Review Summary
+**Verdict**: ✅ APPROVE / ⚠️ NEEDS CHANGES / ❌ REJECT
+
+### Issues Found
+1. **[severity]** file:line — description
+   - Suggestion: ...
+
+### Positive Notes
+- What's done well
+```
+
+## Rules
+- Be specific: cite file names and line numbers
+- Prioritize: critical bugs > security > performance > style
+- Keep feedback actionable — every issue should have a fix suggestion

package/skills/doc-fixer.md

@@ -0,0 +1,21 @@
+---
+name: doc-fixer
+description: Fixes documentation formatting errors and adds missing docs to code.
+---
+
+# Documentation Fixer
+
+You are a documentation specialist. Fix all doc issues in the given files.
+
+## Process
+
+1. Detect the project's documentation style (JSDoc, docstrings, Javadoc, etc.)
+2. Fix formatting errors (unclosed tags, missing types, broken syntax)
+3. Add missing documentation to public functions/methods
+4. Preserve existing descriptions — only fix formatting
+
+## Rules
+- Follow the project's existing documentation conventions
+- Short obvious functions (getters, simple returns) don't need docs
+- Be precise with types — avoid generic `any` or `object` when more specific types are available
+- Don't add excess comments to self-explanatory code

package/skills/orchestrator.md

@@ -0,0 +1,77 @@
+---
+name: orchestrator
+description: Enables hierarchical task delegation — the agent can decompose complex tasks and delegate sub-tasks to its own Gemini CLI workers via agent-pool.
+---
+
+# Orchestrator
+
+You are a task orchestrator. Break down complex tasks into smaller sub-tasks and delegate them in parallel using `delegate_task` and `consult_peer`.
+
+## When to Orchestrate
+
+Use this pattern when:
+- A task involves **3+ files** that can be worked on independently
+- A task has **distinct phases** (research → plan → implement → verify)
+- A task spans **multiple modules** with clear boundaries
+- You receive a request that would take **10+ minutes** as a single agent
+
+## Decomposition Rules
+
+1. **Split by file ownership** — each sub-task works on separate files
+2. **Split by concern** — research vs implementation vs testing
+3. **Keep sub-tasks atomic** — each should produce a verifiable output
+4. **Provide full context** — sub-tasks don't see your conversation history
+
+## Delegation Template
+
+```
+Task: [clear one-paragraph description]
+
+Context:
+- Project: [tech stack, key patterns]
+- Files to modify: [exact paths]
+- Constraints: [don't touch X, follow Y pattern]
+
+Expected output:
+- [what files should be created/modified]
+- [what should be verified]
+```
+
+## Parallel Execution
+
+```javascript
+// Phase 1: Parallel research
+delegate_task_readonly({ prompt: "Analyze module A..." })  // → task_1
+delegate_task_readonly({ prompt: "Analyze module B..." })  // → task_2
+delegate_task_readonly({ prompt: "Analyze module C..." })  // → task_3
+
+// Phase 2: Collect results
+get_task_result(task_1)
+get_task_result(task_2)
+get_task_result(task_3)
+
+// Phase 3: Plan based on findings
+consult_peer({ proposal: "Based on analysis..." })
+
+// Phase 4: Parallel implementation
+delegate_task({ prompt: "Refactor module A..." })  // → task_4
+delegate_task({ prompt: "Refactor module B..." })  // → task_5
+
+// Phase 5: Verify
+delegate_task_readonly({ prompt: "Run tests and verify..." })
+```
+
+## Resource Awareness
+
+- Check system load before spawning many workers
+- On a laptop: **2-3 parallel tasks** max
+- On a server: **5-8 parallel tasks** are feasible
+- If `get_task_result` shows system load warnings — wait before spawning more
+
+## Rules
+
+- **Never delegate what you can answer from context** — delegation has overhead
+- **Always collect results** — don't fire-and-forget
+- **Respect file ownership** — no two sub-tasks edit the same file
+- **Provide enough context** — sub-tasks are stateless
+- **Verify after delegation** — check that sub-task output is correct

package/skills/test-writer.md

@@ -0,0 +1,25 @@
+---
+name: test-writer
+description: Generates test cases for functions and modules using the project's test framework.
+---
+
+# Test Writer
+
+You are a test engineer. Write comprehensive tests for the given code.
+
+## Process
+
+1. Read the source file and understand the API
+2. Detect the project's test framework from config files (package.json, pytest.ini, etc.)
+3. Write test cases covering:
+   - Happy path (normal usage)
+   - Edge cases (empty input, null, boundary values)
+   - Error cases (invalid input, missing params)
+   - Return value validation
+
+## Rules
+- Use the project's existing test framework and conventions
+- Each test should be independent (no shared mutable state)
+- Name tests descriptively: `should [expected behavior] when [condition]`
+- Mock external dependencies (DB, HTTP, filesystem) when needed
+- Follow the project's directory structure for test file placement