par5-mcp 0.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Release and Publish
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.RELEASE_PAT }}
+
+  publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - run: npm run build
+
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+	".": "0.0.0"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 jrandolf
+
+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,269 @@
+# par5-mcp
+
+An MCP (Model Context Protocol) server that enables parallel execution of shell commands and AI coding agents across lists of items. Perfect for batch processing files, running linters across multiple targets, or delegating complex tasks to multiple AI agents simultaneously.
+
+## Features
+
+- **List Management**: Create, update, delete, and inspect lists of items (file paths, URLs, identifiers, etc.)
+- **Parallel Shell Execution**: Run shell commands across all items in a list with batched parallelism
+- **Multi-Agent Orchestration**: Spawn Claude, Gemini, or Codex agents in parallel to process items
+- **Streaming Output**: Results stream to files in real-time for monitoring progress
+- **Batched Processing**: Commands and agents run in batches of 10 to avoid overwhelming the system
+
+## Installation
+
+```bash
+npm install par5-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g par5-mcp
+```
+
+## Usage
+
+### As an MCP Server
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "par5": {
+      "command": "npx",
+      "args": ["par5-mcp"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "par5": {
+      "command": "par5-mcp"
+    }
+  }
+}
+```
+
+## Available Tools
+
+### List Management
+
+#### `create_list`
+
+Creates a named list of items for parallel processing.
+
+**Parameters:**
+- `items` (string[]): Array of items to store in the list
+
+**Returns:** A unique list ID to use with other tools
+
+**Example:**
+```
+create_list(items: ["src/a.ts", "src/b.ts", "src/c.ts"])
+// Returns: list_id = "abc-123-..."
+```
+
+#### `get_list`
+
+Retrieves the items in an existing list by its ID.
+
+**Parameters:**
+- `list_id` (string): The list ID returned by `create_list`
+
+#### `update_list`
+
+Updates an existing list by replacing its items with a new array.
+
+**Parameters:**
+- `list_id` (string): The list ID to update
+- `items` (string[]): The new array of items
+
+#### `delete_list`
+
+Deletes an existing list by its ID.
+
+**Parameters:**
+- `list_id` (string): The list ID to delete
+
+#### `list_all_lists`
+
+Lists all existing lists and their item counts.
+
+**Parameters:** None
+
+---
+
+### Parallel Execution
+
+#### `run_shell_across_list`
+
+Executes a shell command for each item in a list. Commands run in batches of 10 parallel processes.
+
+**Parameters:**
+- `list_id` (string): The list ID to iterate over
+- `command` (string): Shell command with `$item` placeholder
+
+**Variable Substitution:**
+- Use `$item` in your command - it will be replaced with each list item (properly shell-escaped)
+
+**Example:**
+```
+run_shell_across_list(
+  list_id: "abc-123",
+  command: "wc -l $item"
+)
+```
+
+This runs `wc -l 'src/a.ts'`, `wc -l 'src/b.ts'`, etc. in parallel.
+
+**Output:**
+- stdout and stderr are streamed to separate files per item
+- File paths are returned for you to read the results
+
+#### `run_agent_across_list`
+
+Spawns an AI coding agent for each item in a list. Agents run in batches of 10 with a 5-minute timeout per agent.
+
+**Parameters:**
+- `list_id` (string): The list ID to iterate over
+- `agent` (enum): `"claude"`, `"gemini"`, or `"codex"`
+- `prompt` (string): Prompt with `{{item}}` placeholder
+
+**Available Agents:**
+| Agent | CLI | Auto-Accept Flag |
+|-------|-----|------------------|
+| `claude` | Claude Code CLI | `--dangerously-skip-permissions` |
+| `gemini` | Google Gemini CLI | `--yolo` |
+| `codex` | OpenAI Codex CLI | `--dangerously-bypass-approvals-and-sandbox` |
+
+**Variable Substitution:**
+- Use `{{item}}` in your prompt - it will be replaced with each list item
+
+**Example:**
+```
+run_agent_across_list(
+  list_id: "abc-123",
+  agent: "claude",
+  prompt: "Review {{item}} for security vulnerabilities and suggest fixes"
+)
+```
+
+**Output:**
+- stdout and stderr are streamed to separate files per item
+- File paths are returned for you to read the agent outputs
+
+## Workflow Example
+
+Here's a typical workflow for processing multiple files:
+
+1. **Create a list of files to process:**
+   ```
+   create_list(items: ["src/auth.ts", "src/api.ts", "src/utils.ts"])
+   ```
+
+2. **Run a shell command across all files:**
+   ```
+   run_shell_across_list(
+     list_id: "<returned-id>",
+     command: "cat $item | grep -n 'TODO'"
+   )
+   ```
+
+3. **Or delegate to AI agents:**
+   ```
+   run_agent_across_list(
+     list_id: "<returned-id>",
+     agent: "claude",
+     prompt: "Add comprehensive JSDoc comments to all exported functions in {{item}}"
+   )
+   ```
+
+4. **Read the output files** to check results
+
+5. **Clean up:**
+   ```
+   delete_list(list_id: "<returned-id>")
+   ```
+
+## Configuration
+
+The following environment variables can be used to configure par5-mcp:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PAR5_BATCH_SIZE` | Number of parallel processes per batch | `10` |
+| `PAR5_AGENT_ARGS` | Additional arguments passed to all agents | (none) |
+| `PAR5_CLAUDE_ARGS` | Additional arguments passed to Claude CLI | (none) |
+| `PAR5_GEMINI_ARGS` | Additional arguments passed to Gemini CLI | (none) |
+| `PAR5_CODEX_ARGS` | Additional arguments passed to Codex CLI | (none) |
+| `PAR5_DISABLE_CLAUDE` | Set to any value to disable the Claude agent | (none) |
+| `PAR5_DISABLE_GEMINI` | Set to any value to disable the Gemini agent | (none) |
+| `PAR5_DISABLE_CODEX` | Set to any value to disable the Codex agent | (none) |
+
+**Example:**
+
+```json
+{
+  "mcpServers": {
+    "par5": {
+      "command": "npx",
+      "args": ["par5-mcp"],
+      "env": {
+        "PAR5_BATCH_SIZE": "20",
+        "PAR5_CLAUDE_ARGS": "--model claude-sonnet-4-20250514"
+      }
+    }
+  }
+}
+```
+
+## Output Files
+
+Results are written to temporary files in the system temp directory under `par5-mcp-results/`:
+
+```
+/tmp/par5-mcp-results/<run-id>/
+  ├── auth.ts.stdout.txt
+  ├── auth.ts.stderr.txt
+  ├── api.ts.stdout.txt
+  ├── api.ts.stderr.txt
+  └── ...
+```
+
+File names are derived from the item value (sanitized for filesystem safety).
+
+## Development
+
+### Building from Source
+
+```bash
+git clone <repository-url>
+cd par5-mcp
+npm install
+npm run build
+```
+
+### Running Locally
+
+```bash
+npm start
+```
+
+## Requirements
+
+- Node.js 18+
+- For `run_agent_across_list`:
+  - `claude` agent requires [Claude Code CLI](https://claude.ai/code) installed
+  - `gemini` agent requires [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed
+  - `codex` agent requires [Codex CLI](https://github.com/openai/codex) installed
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,488 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir, open } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// Helper to create a safe filename from an item string
+function toSafeFilename(item) {
+    // Get basename if it's a path
+    const name = basename(item);
+    // Replace unsafe characters with underscores
+    return name.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 100);
+}
+// Batch size for parallel execution (configurable via PAR5_BATCH_SIZE env var)
+const BATCH_SIZE = parseInt(process.env.PAR5_BATCH_SIZE || "10", 10);
+// Helper to run a command and stream stdout/stderr to separate files
+// Returns a promise that resolves when the command completes
+function runCommandToFiles(command, stdoutFile, stderrFile, options = {}) {
+    return new Promise((resolve) => {
+        (async () => {
+            const stdoutHandle = await open(stdoutFile, "w");
+            const stderrHandle = await open(stderrFile, "w");
+            const stdoutStream = stdoutHandle.createWriteStream();
+            const stderrStream = stderrHandle.createWriteStream();
+            const child = spawn("sh", ["-c", command], {
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            let timeoutId;
+            if (options.timeout) {
+                timeoutId = setTimeout(() => {
+                    child.kill("SIGTERM");
+                }, options.timeout);
+            }
+            child.stdout.pipe(stdoutStream);
+            child.stderr.pipe(stderrStream);
+            child.on("close", async () => {
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                stdoutStream.end();
+                stderrStream.end();
+                await stdoutHandle.close();
+                await stderrHandle.close();
+                resolve();
+            });
+            child.on("error", async (err) => {
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                stderrStream.write(`\nERROR: ${err.message}\n`);
+                stdoutStream.end();
+                stderrStream.end();
+                await stdoutHandle.close();
+                await stderrHandle.close();
+                resolve();
+            });
+        })();
+    });
+}
+// Helper to run commands in batches
+async function runInBatches(tasks) {
+    for (let i = 0; i < tasks.length; i += BATCH_SIZE) {
+        const batch = tasks.slice(i, i + BATCH_SIZE);
+        await Promise.all(batch.map((task) => runCommandToFiles(task.command, task.stdoutFile, task.stderrFile, {
+            timeout: task.timeout,
+        })));
+    }
+}
+// Create output directory for results
+const outputDir = join(tmpdir(), "par5-mcp-results");
+// Store for lists
+const lists = new Map();
+// Create the MCP server
+const server = new McpServer({
+    name: "par5-mcp",
+    version: "1.0.0",
+});
+// Tool: create_list
+server.registerTool("create_list", {
+    description: `Creates a named list of items for parallel processing. Use this tool when you need to perform the same operation across multiple files, URLs, or any collection of items.
+
+WHEN TO USE:
+- Before running shell commands or AI agents across multiple items
+- When you have a collection of file paths, URLs, identifiers, or any strings to process in parallel
+
+WORKFLOW:
+1. Call create_list with your array of items
+2. Use the returned list_id with run_shell_across_list or run_agent_across_list
+3. The list persists for the duration of the session
+
+EXAMPLE: To process files ["src/a.ts", "src/b.ts", "src/c.ts"], first create a list, then use run_shell_across_list or run_agent_across_list with the returned id.`,
+    inputSchema: {
+        items: z
+            .array(z.string())
+            .describe("Array of items to store in the list. Each item can be a file path, URL, identifier, or any string that will be substituted into commands or prompts."),
+    },
+}, async ({ items }) => {
+    const id = randomUUID();
+    lists.set(id, items);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Successfully created a list with ${items.length} items. The list ID is "${id}". You can now use this ID with run_shell_across_list or run_agent_across_list to process each item in parallel. The commands will run in the background and stream output to files. After starting the commands, you should sleep briefly and then read the output files to check results.`,
+            },
+        ],
+    };
+});
+// Tool: get_list
+server.registerTool("get_list", {
+    description: `Retrieves the items in an existing list by its ID.
+
+WHEN TO USE:
+- To inspect the contents of a list before processing
+- To verify which items are in a list
+- To check if a list exists`,
+    inputSchema: {
+        list_id: z.string().describe("The list ID returned by create_list."),
+    },
+}, async ({ list_id }) => {
+    const items = lists.get(list_id);
+    if (!items) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: No list found with ID "${list_id}". The list may have been deleted or the ID is incorrect.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const itemList = items.map((item, i) => `${i + 1}. ${item}`).join("\n");
+    return {
+        content: [
+            {
+                type: "text",
+                text: `List "${list_id}" contains ${items.length} items:\n\n${itemList}`,
+            },
+        ],
+    };
+});
+// Tool: update_list
+server.registerTool("update_list", {
+    description: `Updates an existing list by replacing its items with a new array.
+
+WHEN TO USE:
+- To modify the contents of an existing list
+- To add or remove items from a list
+- To reorder items in a list`,
+    inputSchema: {
+        list_id: z.string().describe("The list ID returned by create_list."),
+        items: z
+            .array(z.string())
+            .describe("The new array of items to replace the existing list contents."),
+    },
+}, async ({ list_id, items }) => {
+    if (!lists.has(list_id)) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: No list found with ID "${list_id}". The list may have been deleted or the ID is incorrect. Use create_list to create a new list.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const oldCount = lists.get(list_id)?.length;
+    lists.set(list_id, items);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Successfully updated list "${list_id}". Changed from ${oldCount} items to ${items.length} items.`,
+            },
+        ],
+    };
+});
+// Tool: delete_list
+server.registerTool("delete_list", {
+    description: `Deletes an existing list by its ID.
+
+WHEN TO USE:
+- To clean up lists that are no longer needed
+- To free up memory after processing is complete`,
+    inputSchema: {
+        list_id: z.string().describe("The list ID returned by create_list."),
+    },
+}, async ({ list_id }) => {
+    if (!lists.has(list_id)) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: No list found with ID "${list_id}". The list may have already been deleted or the ID is incorrect.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const itemCount = lists.get(list_id)?.length;
+    lists.delete(list_id);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Successfully deleted list "${list_id}" which contained ${itemCount} items.`,
+            },
+        ],
+    };
+});
+// Tool: list_all_lists
+server.registerTool("list_all_lists", {
+    description: `Lists all existing lists and their item counts.
+
+WHEN TO USE:
+- To see all available lists in the current session
+- To find a list ID you may have forgotten
+- To check how many lists exist`,
+    inputSchema: {},
+}, async () => {
+    if (lists.size === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No lists exist. Use create_list to create a new list.",
+                },
+            ],
+        };
+    }
+    const listInfo = Array.from(lists.entries())
+        .map(([id, items]) => `- "${id}": ${items.length} items`)
+        .join("\n");
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Found ${lists.size} list(s):\n\n${listInfo}`,
+            },
+        ],
+    };
+});
+// Tool: run_shell_across_list
+server.registerTool("run_shell_across_list", {
+    description: `Executes a shell command for each item in a previously created list. Commands run in batches of ${BATCH_SIZE} parallel processes, with stdout and stderr streamed to separate files.
+
+WHEN TO USE:
+- Running the same shell command across multiple files (e.g., linting, formatting, compiling)
+- Batch processing with command-line tools
+- Any operation where you need to execute shell commands on a collection of items
+
+HOW IT WORKS:
+1. Each item in the list is substituted into the command where $item appears
+2. Commands run in batches of ${BATCH_SIZE} at a time to avoid overwhelming the system
+3. Output streams directly to files as the commands execute
+4. This tool waits for all commands to complete before returning
+
+AFTER COMPLETION:
+- Read the stdout files to check results
+- Check stderr files if you encounter errors or unexpected output
+- Files are named based on the item (e.g., "myfile.ts.stdout.txt")
+
+VARIABLE SUBSTITUTION:
+- Use $item in your command - it will be replaced with each list item (properly shell-escaped)
+- Example: "cat $item" becomes "cat 'src/file.ts'" for item "src/file.ts"`,
+    inputSchema: {
+        list_id: z
+            .string()
+            .describe("The list ID returned by create_list. This identifies which list of items to iterate over."),
+        command: z
+            .string()
+            .describe("Shell command to execute for each item. Use $item as a placeholder - it will be replaced with the current item value (properly escaped). Example: 'wc -l $item' or 'cat $item | grep TODO'"),
+    },
+}, async ({ list_id, command }) => {
+    const items = lists.get(list_id);
+    if (!items) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: No list found with ID "${list_id}". Please call create_list first to create a list of items, then use the returned ID with this tool.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Create output directory
+    const runId = randomUUID();
+    const runDir = join(outputDir, runId);
+    await mkdir(runDir, { recursive: true });
+    const results = [];
+    const tasks = [];
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        // Replace $item with the actual item value (properly escaped)
+        const escapedItem = item.replace(/'/g, "'\\''");
+        const expandedCommand = command.replace(/\$item/g, `'${escapedItem}'`);
+        const safeFilename = toSafeFilename(item);
+        const stdoutFile = join(runDir, `${safeFilename}.stdout.txt`);
+        const stderrFile = join(runDir, `${safeFilename}.stderr.txt`);
+        tasks.push({
+            command: expandedCommand,
+            stdoutFile,
+            stderrFile,
+        });
+        results.push({
+            item,
+            files: { stdout: stdoutFile, stderr: stderrFile },
+        });
+    }
+    // Run commands in batches of 10
+    await runInBatches(tasks);
+    // Build prose response
+    const fileList = results
+        .map((r) => `- ${r.item}: stdout at "${r.files.stdout}", stderr at "${r.files.stderr}"`)
+        .join("\n");
+    const numBatches = Math.ceil(items.length / BATCH_SIZE);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Completed ${results.length} shell commands in ${numBatches} batch(es) of up to ${BATCH_SIZE} parallel commands each. Output has been streamed to files.
+
+OUTPUT FILES:
+${fileList}
+
+NEXT STEPS:
+1. Read the stdout files to check the results of each command
+2. If there are errors, check the corresponding stderr files for details
+
+All commands have completed and output files are ready to read.`,
+            },
+        ],
+    };
+});
+// Determine which agents are enabled based on PAR5_DISABLE_* env vars
+const ALL_AGENTS = ["claude", "gemini", "codex"];
+const ENABLED_AGENTS = ALL_AGENTS.filter((agent) => {
+    const disableVar = `PAR5_DISABLE_${agent.toUpperCase()}`;
+    return !process.env[disableVar];
+});
+// Tool: run_agent_across_list (only registered if at least one agent is enabled)
+if (ENABLED_AGENTS.length > 0) {
+    const agentDescriptions = {
+        claude: "claude: Claude Code CLI (uses --dangerously-skip-permissions for autonomous operation)",
+        gemini: "gemini: Google Gemini CLI (uses --yolo for auto-accept)",
+        codex: "codex: OpenAI Codex CLI (uses --dangerously-bypass-approvals-and-sandbox for autonomous operation)",
+    };
+    const availableAgentsDoc = ENABLED_AGENTS.map((a) => `- ${agentDescriptions[a]}`).join("\n");
+    server.registerTool("run_agent_across_list", {
+        description: `Spawns an AI coding agent for each item in a previously created list. Agents run in batches of ${BATCH_SIZE} parallel processes with automatic permission skipping enabled.
+
+WHEN TO USE:
+- Performing complex code analysis, refactoring, or generation across multiple files
+- Tasks that require AI reasoning rather than simple shell commands
+- When you need to delegate work to multiple AI agents working in parallel
+
+AVAILABLE AGENTS:
+${availableAgentsDoc}
+
+HOW IT WORKS:
+1. Each item in the list is substituted into the prompt where {{item}} appears
+2. Agents run in batches of ${BATCH_SIZE} at a time to avoid overwhelming the system
+3. Each agent has a 5-minute timeout
+4. Output streams directly to files as the agents work
+5. This tool waits for all agents to complete before returning
+
+AFTER COMPLETION:
+- Read the stdout files to check the results from each agent
+- Check stderr files if you encounter errors
+- Files are named based on the item (e.g., "myfile.ts.stdout.txt")
+
+VARIABLE SUBSTITUTION:
+- Use {{item}} in your prompt - it will be replaced with each list item
+- Example: "Review {{item}} for bugs" becomes "Review src/file.ts for bugs" for item "src/file.ts"`,
+        inputSchema: {
+            list_id: z
+                .string()
+                .describe("The list ID returned by create_list. This identifies which list of items to iterate over."),
+            agent: z
+                .enum(ENABLED_AGENTS)
+                .describe(`Which AI agent to use: ${ENABLED_AGENTS.map((a) => `'${a}'`).join(", ")}. All agents run with permission-skipping flags for autonomous operation.`),
+            prompt: z
+                .string()
+                .describe("The prompt to send to each agent. Use {{item}} as a placeholder - it will be replaced with the current item value. Example: 'Review {{item}} and suggest improvements' or 'Add error handling to {{item}}'"),
+        },
+    }, async ({ list_id, agent, prompt }) => {
+        const items = lists.get(list_id);
+        if (!items) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: No list found with ID "${list_id}". Please call create_list first to create a list of items, then use the returned ID with this tool.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Create output directory
+        const runId = randomUUID();
+        const runDir = join(outputDir, runId);
+        await mkdir(runDir, { recursive: true });
+        const results = [];
+        const tasks = [];
+        // Build the agent command with skip permission flags and streaming output
+        // Additional args can be passed via PAR5_AGENT_ARGS (all agents) or PAR5_CLAUDE_ARGS, PAR5_GEMINI_ARGS, PAR5_CODEX_ARGS (per-agent)
+        const getAgentCommand = (agentName, expandedPrompt) => {
+            const escapedPrompt = expandedPrompt.replace(/'/g, "'\\''");
+            const agentArgs = process.env.PAR5_AGENT_ARGS || "";
+            switch (agentName) {
+                case "claude": {
+                    // Claude Code CLI with --dangerously-skip-permissions and streaming output
+                    const claudeArgs = process.env.PAR5_CLAUDE_ARGS || "";
+                    return `claude --dangerously-skip-permissions --output-format stream-json --verbose ${agentArgs} ${claudeArgs} -p '${escapedPrompt}'`;
+                }
+                case "gemini": {
+                    // Gemini CLI with yolo mode and streaming JSON output
+                    const geminiArgs = process.env.PAR5_GEMINI_ARGS || "";
+                    return `gemini --yolo --output-format stream-json ${agentArgs} ${geminiArgs} '${escapedPrompt}'`;
+                }
+                case "codex": {
+                    // Codex CLI exec subcommand with full-auto flag and JSON streaming output
+                    const codexArgs = process.env.PAR5_CODEX_ARGS || "";
+                    return `codex exec --dangerously-bypass-approvals-and-sandbox ${agentArgs} ${codexArgs} '${escapedPrompt}'`;
+                }
+                default:
+                    throw new Error(`Unknown agent: ${agentName}`);
+            }
+        };
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            // Replace {{item}} with the actual item value
+            const expandedPrompt = prompt.replace(/\{\{item\}\}/g, item);
+            const safeFilename = toSafeFilename(item);
+            const stdoutFile = join(runDir, `${safeFilename}.stdout.txt`);
+            const stderrFile = join(runDir, `${safeFilename}.stderr.txt`);
+            tasks.push({
+                command: getAgentCommand(agent, expandedPrompt),
+                stdoutFile,
+                stderrFile,
+                timeout: 300000, // 5 minute timeout per item
+            });
+            results.push({
+                item,
+                files: { stdout: stdoutFile, stderr: stderrFile },
+            });
+        }
+        // Run agents in batches of 10
+        await runInBatches(tasks);
+        // Build prose response
+        const fileList = results
+            .map((r) => `- ${r.item}: stdout at "${r.files.stdout}", stderr at "${r.files.stderr}"`)
+            .join("\n");
+        const agentNames = {
+            claude: "Claude Code",
+            gemini: "Google Gemini",
+            codex: "OpenAI Codex",
+        };
+        const numBatches = Math.ceil(items.length / BATCH_SIZE);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Completed ${results.length} ${agentNames[agent]} agents in ${numBatches} batch(es) of up to ${BATCH_SIZE} parallel agents each. Output has been streamed to files.
+
+OUTPUT FILES:
+${fileList}
+
+NEXT STEPS:
+1. Read the stdout files to check the results from each agent
+2. If there are errors, check the corresponding stderr files for details
+
+All agents have completed (with a 5-minute timeout per agent) and output files are ready to read.`,
+                },
+            ],
+        };
+    });
+}
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "par5-mcp",
+	"version": "0.0.0",
+	"description": "MCP server for parallel list operations - run shell commands and AI agents across lists in parallel",
+	"main": "dist/index.js",
+	"bin": {
+		"par5-mcp": "./dist/index.js"
+	},
+	"scripts": {
+		"build": "tsc",
+		"start": "node dist/index.js",
+		"prepublishOnly": "npm run build"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"parallel",
+		"batch",
+		"shell",
+		"ai-agents",
+		"claude",
+		"gemini",
+		"codex",
+		"automation"
+	],
+	"author": "jrandolf",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jrandolf/par5-mcp.git"
+	},
+	"bugs": {
+		"url": "https://github.com/jrandolf/par5-mcp/issues"
+	},
+	"homepage": "https://github.com/jrandolf/par5-mcp#readme",
+	"engines": {
+		"node": ">=18"
+	},
+	"type": "module",
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.25.1",
+		"zod": "^4.2.1"
+	},
+	"devDependencies": {
+		"@types/node": "^25.0.3",
+		"typescript": "^5.9.3"
+	}
+}

package/release-please-config.json

@@ -0,0 +1,12 @@
+{
+	"$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+	"packages": {
+		".": {
+			"release-type": "node",
+			"bump-minor-pre-major": true,
+			"bump-patch-for-minor-pre-major": true,
+			"initial-version": "0.1.0",
+			"include-component-in-tag": false
+		}
+	}
+}