agent-pool-mcp 1.2.1 → 1.4.0

package/README.md

@@ -282,7 +282,7 @@ src/
 - **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.
 - **Adaptive Polling**: Pipeline daemon uses 3s intervals when active, 30s when idle.
-- **File-Based Communication**: Pipeline agents communicate through `.agent/runs/` JSON files — each Gemini process has its own MCP server instance but shares state via filesystem.
+- **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.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-pool-mcp",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "type": "module",
   "description": "MCP Server for multi-agent task delegation and orchestration via Gemini CLI",
   "main": "index.js",

package/src/scheduler/daemon.js

@@ -17,9 +17,9 @@ import { join, dirname } from 'node:path';
 import { matchesCron } from './cron.js';
 
 const POLL_INTERVAL_MS = 30_000; // Check schedules every 30 seconds
-const PID_FILE = '.agent/scheduler.pid';
-const SCHEDULE_FILE = '.agent/schedule.json';
-const RESULTS_DIR = '.agent/scheduled-results';
+const PID_FILE = '.agents/scheduler.pid';
+const SCHEDULE_FILE = '.agents/schedule.json';
+const RESULTS_DIR = '.agents/scheduled-results';
 
 /** @type {string} */
 const cwd = process.argv[2] || process.cwd();
@@ -163,8 +163,8 @@ function executeSchedule(schedule) {
 
 import { readdirSync } from 'node:fs';
 
-const PIPELINES_DIR = '.agent/pipelines';
-const RUNS_DIR = '.agent/runs';
+const PIPELINES_DIR = '.agents/pipelines';
+const RUNS_DIR = '.agents/runs';
 
 /**
  * Spawn a Gemini CLI agent for a pipeline step.

package/src/scheduler/pipeline.js

@@ -1,8 +1,8 @@
 /**
  * Pipeline management — CRUD for pipeline definitions and run state.
  *
- * Pipelines are stored as JSON templates in .agent/pipelines/.
- * Each execution creates a run state in .agent/runs/.
+ * Pipelines are stored as JSON templates in .agents/pipelines/.
+ * Each execution creates a run state in .agents/runs/.
  *
  * @module agent-pool/scheduler/pipeline
  */
@@ -12,8 +12,8 @@ import { join, dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { ensureDaemon } from './scheduler.js';
 
-const PIPELINES_DIR = '.agent/pipelines';
-const RUNS_DIR = '.agent/runs';
+const PIPELINES_DIR = '.agents/pipelines';
+const RUNS_DIR = '.agents/runs';
 
 // ─── Helpers ────────────────────────────────────────────────
 

package/src/scheduler/scheduler.js

@@ -15,9 +15,9 @@ import { nextCronRun } from './cron.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DAEMON_SCRIPT = join(__dirname, 'daemon.js');
 
-const SCHEDULE_FILE = '.agent/schedule.json';
-const RESULTS_DIR = '.agent/scheduled-results';
-const PID_FILE = '.agent/scheduler.pid';
+const SCHEDULE_FILE = '.agents/schedule.json';
+const RESULTS_DIR = '.agents/scheduled-results';
+const PID_FILE = '.agents/scheduler.pid';
 
 // ─── Schedule CRUD ──────────────────────────────────────────
 

package/src/server.js

@@ -6,9 +6,12 @@
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {
   ListToolsRequestSchema,
   CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { randomUUID } from 'node:crypto';
 
@@ -108,9 +111,33 @@ export function createServer() {
 
   const server = new Server(
     { name: 'agent-pool', version: '1.2.1' },
-    { capabilities: { tools: {} } },
+    { capabilities: { tools: {}, resources: {} } },
   );
 
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [{
+      uri: 'agent-pool://guide',
+      name: 'Usage Guide',
+      description: 'Comprehensive guide for agent-pool',
+      mimeType: 'text/markdown',
+    }],
+  }));
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    if (request.params.uri === 'agent-pool://guide') {
+      const guidePath = path.resolve(__dirname, '..', 'GUIDE.md');
+      const content = fs.readFileSync(guidePath, 'utf-8');
+      return {
+        contents: [{
+          uri: request.params.uri,
+          mimeType: 'text/markdown',
+          text: content,
+        }],
+      };
+    }
+    throw new Error(`Resource not found: ${request.params.uri}`);
+  });
+
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOL_DEFINITIONS,
   }));
@@ -155,6 +182,8 @@ export function createServer() {
           response = handleCancelSchedule(args); break;
         case 'get_scheduled_results':
           response = handleGetScheduledResults(args); break;
+        case 'get_usage_guide':
+          response = handleGetUsageGuide(args); break;
         case 'create_pipeline':
           response = handleCreatePipeline(args); break;
         case 'run_pipeline':
@@ -169,6 +198,8 @@ export function createServer() {
           response = handleSignalStepComplete(args); break;
         case 'bounce_back':
           response = handleBounceBack(args); break;
+        case 'get_usage_guide':
+          response = handleGetUsageGuide(args); break;
         default:
           response = { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
       }
@@ -391,7 +422,7 @@ function handleScheduleTask(args) {
     return {
       content: [{
         type: 'text',
-        text: `⏰ Task scheduled.\n\n- **Schedule ID**: \`${result.scheduleId}\`\n- **Cron**: \`${args.cron}\`\n- **Next run**: ${result.nextRun || 'unknown'}\n- **Prompt**: ${args.prompt.substring(0, 100)}...\n\nDaemon is running in the background. Results will be saved to \`.agent/scheduled-results/\`.\nUse \`list_schedules\` to see all schedules, \`get_scheduled_results\` to read outputs.`,
+        text: `⏰ Task scheduled.\n\n- **Schedule ID**: \`${result.scheduleId}\`\n- **Cron**: \`${args.cron}\`\n- **Next run**: ${result.nextRun || 'unknown'}\n- **Prompt**: ${args.prompt.substring(0, 100)}...\n\nDaemon is running in the background. Results will be saved to \`.agents/scheduled-results/\`.\nUse \`list_schedules\` to see all schedules, \`get_scheduled_results\` to read outputs.`,
       }],
     };
   } catch (error) {
@@ -616,3 +647,44 @@ function handleBounceBack(args) {
   }
 }
 
+/** @param {object} args */
+function handleGetUsageGuide(args) {
+  const guidePath = path.resolve(__dirname, '..', 'GUIDE.md');
+  if (!fs.existsSync(guidePath)) {
+    return { content: [{ type: 'text', text: 'Guide not found.' }], isError: true };
+  }
+  
+  const fullContent = fs.readFileSync(guidePath, 'utf-8');
+  
+  if (!args.topic) {
+    return { content: [{ type: 'text', text: fullContent }] };
+  }
+  
+  const topicLower = args.topic.toLowerCase();
+  const lines = fullContent.split('\n');
+  let inTopic = false;
+  let topicContent = [];
+  
+  for (const line of lines) {
+    if (line.toLowerCase().startsWith(`## ${topicLower}`)) {
+      inTopic = true;
+      topicContent.push(line);
+      continue;
+    }
+    
+    if (inTopic && line.startsWith('## ')) {
+      break; // End of section
+    }
+    
+    if (inTopic) {
+      topicContent.push(line);
+    }
+  }
+  
+  if (topicContent.length === 0) {
+    return { content: [{ type: 'text', text: `Topic '${args.topic}' not found in the guide.\n\nAvailable topics: delegation, pipelines, scheduling, skills, peer-review, sessions.` }] };
+  }
+  
+  return { content: [{ type: 'text', text: topicContent.join('\n').trim() }] };
+}
+

package/src/tool-definitions.js

@@ -6,6 +6,26 @@
  */
 
 export const TOOL_DEFINITIONS = [
+  {
+    name: 'get_usage_guide',
+    description: [
+      'Get the comprehensive usage guide for agent-pool with examples and best practices.',
+      'Call this FIRST when planning how to use agent-pool tools for parallel work, pipelines, or scheduling.',
+      'Returns practical examples for each feature area.',
+      '',
+      'Available topics: delegation, pipelines, scheduling, skills, peer-review, sessions.',
+      'Omit topic to get the full guide.',
+    ].join('\n'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        topic: {
+          type: 'string',
+          description: 'Optional topic filter: delegation, pipelines, scheduling, skills, peer-review, sessions',
+        },
+      },
+    },
+  },
   {
     name: 'delegate_task',
     description: [
@@ -179,7 +199,7 @@ export const TOOL_DEFINITIONS = [
     description: [
       'Schedule a Gemini CLI agent to run on a cron schedule or as a delayed one-shot.',
       'Spawns a persistent daemon that survives IDE/CLI restarts.',
-      'Results are saved to .agent/scheduled-results/ and can be retrieved with get_scheduled_results.',
+      'Results are saved to .agents/scheduled-results/ and can be retrieved with get_scheduled_results.',
       '',
       'Cron format: standard 5-field (minute hour day month weekday).',
       'Examples: "*/30 * * * *" (every 30 min), "0 9 * * MON-FRI" (9am weekdays), "0 */2 * * *" (every 2 hours).',