Ein MCP-Server (Model Context Protocol), der Shell-Befehle und KI-Codierungsagenten parallel über Listen von Elementen ausführt. Verwenden Sie ihn, um Dateien in Stapeln zu verarbeiten, Linter über Ziele auszuführen oder Arbeiten an mehrere Agenten zu delegieren.
Listenverwaltung: Listen von Elementen wie Dateipfaden, URLs und Kennungen erstellen, aktualisieren, löschen und anzeigen
Parallele Shell-Ausführung: Shell-Befehle mit gestapeltem Parallelismus über alle Elemente einer Liste ausführen
Multi-Agenten-Orchestrierung: Claude-, Gemini- oder Codex-Agenten parallel starten, um Elemente zu verarbeiten
Streaming-Ausgabe: Ergebnisse werden in Echtzeit in Dateien gestreamt, um den Fortschritt zu überwachen
Stapelverarbeitung: Befehle und Agenten laufen in Stapeln von 10, um das System nicht zu überlasten
Related MCP server: Claude Parallel Tasks MCP Server
npm install par5-mcpOder global installieren:
npm install -g par5-mcpFügen Sie Folgendes zu Ihrer MCP-Client-Konfiguration hinzu:
{
"mcpServers": {
"par5": {
"command": "npx",
"args": ["par5-mcp"]
}
}
}Oder wenn global installiert:
{
"mcpServers": {
"par5": {
"command": "par5-mcp"
}
}
}create_listErstellt eine benannte Liste von Elementen für die parallele Verarbeitung.
Parameter:
items (string[]): Array von Elementen, die in der Liste gespeichert werden sollen
Rückgabe: Eine eindeutige Listen-ID zur Verwendung mit anderen Tools
Beispiel:
create_list(items: ["src/a.ts", "src/b.ts", "src/c.ts"])
// Returns: list_id = "abc-123-..."get_listRuft die Elemente einer vorhandenen Liste anhand ihrer ID ab.
Parameter:
list_id (string): Die Listen-ID, die von create_list zurückgegeben wurde
update_listAktualisiert eine vorhandene Liste, indem ihre Elemente durch ein neues Array ersetzt werden.
Parameter:
list_id (string): Die zu aktualisierende Listen-ID
items (string[]): Das neue Array von Elementen
delete_listLöscht eine vorhandene Liste anhand ihrer ID.
Parameter:
list_id (string): Die zu löschende Listen-ID
list_all_listsListet alle vorhandenen Listen und ihre Elementanzahl auf.
Parameter: Keine
run_shell_across_listFührt einen Shell-Befehl für jedes Element in einer Liste aus. Befehle laufen in Stapeln von 10 parallelen Prozessen.
Parameter:
list_id (string): Die Listen-ID, über die iteriert werden soll
command (string): Shell-Befehl mit $item-Platzhalter
Variablenersetzung:
Verwenden Sie $item in Ihrem Befehl. Es wird durch jedes Listenelement ersetzt und shell-escaped.
Beispiel:
run_shell_across_list(
list_id: "abc-123",
command: "wc -l $item"
)Dies führt wc -l 'src/a.ts', wc -l 'src/b.ts' usw. parallel aus.
Ausgabe:
Standardausgabe und Standardfehler werden für jedes Element in separate Dateien gestreamt
Dateipfade werden zurückgegeben, damit Sie die Ergebnisse lesen können
run_agent_across_listStartet einen KI-Codierungsagenten für jedes Element in einer Liste. Agenten laufen in Stapeln von 10 mit einem Timeout von 5 Minuten pro Agent.
Parameter:
list_id (string): Die Listen-ID, über die iteriert werden soll
agent (enum): "claude", "gemini" oder "codex"
prompt (string): Prompt mit {{item}}-Platzhalter
Verfügbare Agenten:
Agent | CLI | Auto-Accept-Flag |
| Claude Code CLI |
|
| Google Gemini CLI |
|
| OpenAI Codex CLI |
|
Variablenersetzung:
Verwenden Sie {{item}} in Ihrem Prompt – es wird durch jedes Listenelement ersetzt
Beispiel:
run_agent_across_list(
list_id: "abc-123",
agent: "claude",
prompt: "Review {{item}} for security vulnerabilities and suggest fixes"
)Ausgabe:
Standardausgabe und Standardfehler werden für jedes Element in separate Dateien gestreamt
Dateipfade werden zurückgegeben, damit Sie die Agentenausgaben lesen können
Hier ist ein typischer Workflow zur Verarbeitung mehrerer Dateien:
Erstellen Sie eine Liste der zu verarbeitenden Dateien:
create_list(items: ["src/auth.ts", "src/api.ts", "src/utils.ts"])Führen Sie einen Shell-Befehl über alle Dateien aus:
run_shell_across_list(
list_id: "<returned-id>",
command: "cat $item | grep -n 'TODO'"
)Oder delegieren Sie an KI-Agenten:
run_agent_across_list(
list_id: "<returned-id>",
agent: "claude",
prompt: "Add comprehensive JSDoc comments to all exported functions in {{item}}"
)Lesen Sie die Ausgabedateien, um die Ergebnisse zu prüfen
Räumen Sie auf:
delete_list(list_id: "<returned-id>")Die folgenden Umgebungsvariablen können zur Konfiguration von par5-mcp verwendet werden:
Variable | Beschreibung | Standard |
| Anzahl paralleler Prozesse pro Stapel |
|
| Zusätzliche Argumente, die an alle Agenten übergeben werden | (keine) |
| Zusätzliche Argumente, die an die Claude-CLI übergeben werden | (keine) |
| Zusätzliche Argumente, die an die Gemini-CLI übergeben werden | (keine) |
| Zusätzliche Argumente, die an die Codex-CLI übergeben werden | (keine) |
| Auf einen beliebigen Wert setzen, um den Claude-Agenten zu deaktivieren | (keine) |
| Auf einen beliebigen Wert setzen, um den Gemini-Agenten zu deaktivieren | (keine) |
| Auf einen beliebigen Wert setzen, um den Codex-Agenten zu deaktivieren | (keine) |
Beispiel:
{
"mcpServers": {
"par5": {
"command": "npx",
"args": ["par5-mcp"],
"env": {
"PAR5_BATCH_SIZE": "20",
"PAR5_CLAUDE_ARGS": "--model claude-sonnet-4-20250514"
}
}
}
}Ergebnisse werden in temporäre Dateien im System-Temp-Verzeichnis unter par5-mcp-results/ geschrieben:
/tmp/par5-mcp-results/<run-id>/
├── auth.ts.stdout.txt
├── auth.ts.stderr.txt
├── api.ts.stdout.txt
├── api.ts.stderr.txt
└── ...Dateinamen werden aus dem Elementwert abgeleitet (für die Dateisystemsicherheit bereinigt).
Bitte starten Sie eine Discussion, bevor Sie eine Änderung vorschlagen. Wenn wir den Vorschlag annehmen, wird ein Mathematic-Maintainer oder ein KI-Agent ihn implementieren und einen Pull Request eröffnen. Wir verlinken diesen Pull Request mit der Discussion und nennen den ursprünglichen Autor des Vorschlags. GitHub beschränkt das Erstellen von Pull Requests auf Mathematic-Maintainer, Repository-Mitarbeiter mit Schreib-, Wartungs- oder Admin-Zugriff sowie autorisierte Wartungsagenten. Den vollständigen Prozess finden Sie in CONTRIBUTING.md.
git clone https://github.com/mathematic-inc/par5-mcp.git
cd par5-mcp
mise install
mise exec -- pnpm install --frozen-lockfile
mise exec -- hk install
mise exec -- pnpm buildmise exec -- pnpm startNode.js 20+
Für run_agent_across_list:
Der claude-Agent erfordert die Installation von Claude Code CLI
Der gemini-Agent erfordert die Installation von Gemini CLI
Der codex-Agent erfordert die Installation von Codex CLI
Apache-2.0
Dieses Projekt ist eine kostenlose Open-Source-Arbeit einer 501(c)(3)-gemeinnützigen Organisation. Wenn Sie es nützlich finden, erwägen Sie bitte eine Spende.
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:
Call create_list with your array of items
Use the returned list_id with run_shell_across_list or run_agent_across_list
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.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It states that the list persists for the session duration and returns a list_id, but does not disclose potential side effects, idempotency, maximum list size, or error conditions. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections (WHEN TO USE, WORKFLOW, EXAMPLE). Every sentence contributes meaningful information, and the most important purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema, no annotations), the description covers the purpose, usage guidelines, and workflow with an example. However, it does not explicitly describe the return value structure (e.g., list_id), though it is implied in the workflow. Slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for the 'items' parameter. The description adds value by explaining that each item can be a file path, URL, identifier, or any string for substitution in commands, which goes beyond the schema description. Could be more precise about constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Creates a named list of items for parallel processing', indicating the verb and resource. However, it mentions a 'named list' but the input schema only has an 'items' parameter, not a name. It distinguishes from siblings like create_list_from_shell by stating it takes an array of items, but could be more explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'WHEN TO USE' section specifying usage before running shell commands or AI agents across multiple items, and a 'WORKFLOW' with clear steps. It references sibling tools (run_shell_across_list, run_agent_across_list) as subsequent steps, providing excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a list by running a shell command and parsing its newline-delimited output.
WHEN TO USE:
When you need to create a list from command output (e.g., find, ls, grep, git ls-files)
When the list of items to process is determined by a shell command
As an alternative to manually specifying items in create_list
EXAMPLES:
"find src -name '*.ts'" to get all TypeScript files
"git ls-files '*.tsx'" to get all tracked TSX files
"ls *.json" to get all JSON files in current directory
"grep -l 'TODO' src/**/*.ts" to get files containing TODO
WORKFLOW:
Call create_list_from_shell with your command
The command's stdout is split by newlines to create list items
Empty lines are filtered out
Use the returned list_id with run_shell_across_list or run_agent_across_list
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Shell command to run. Its stdout will be split by newlines to create list items. Example: 'find src -name "*.ts"' or 'git ls-files' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description details behavior: runs command, splits stdout by newlines, filters empty lines, returns list_id. Lacks mention of error handling or permissions, but covers key aspects well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-organized with sections, examples, and a workflow. Every sentence adds value; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description fully explains the tool's purpose, usage, behavior, and return value. Complete for a single-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with description for the single parameter. Description adds context through examples and explanation of its role in creating list items, exceeding baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a list by running a shell command and parsing newline-delimited output. It distinguishes from sibling 'create_list' by specifying the method (shell command vs manual specification).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'WHEN TO USE' section lists appropriate scenarios and directly contrasts with 'create_list' as an alternative. Provides examples and a workflow, giving clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The list ID returned by create_list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states deletion but does not mention permanence, cascading effects, or permission requirements. For a destructive operation, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and includes a structured 'WHEN TO USE' section. However, it could be more concise by removing the bullet points or integrating them into a sentence. Still efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter delete operation, the description is mostly adequate. However, it lacks details about irreversible effects or prerequisites, which would improve completeness for a destructive action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter described as 'The list ID returned by create_list.' The description does not add further meaning beyond this, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Deletes' and the resource 'list by its ID', making the action clear. It distinguishes from sibling tools like create_list and get_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'WHEN TO USE' section with two clear scenarios (clean up lists, free memory). It does not explicitly state when not to use or mention alternatives, but provides enough context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The list ID returned by create_list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies a read-only operation ('retrieves') but does not explicitly state non-destructiveness, authentication needs, or behavior on missing list IDs. While adequate for a simple get, it lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a single sentence followed by three bullet points. All information is front-loaded and every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and no output schema, the description is largely complete. It covers purpose and usage context. However, it omits details about return format, error handling, and pagination, which would raise it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the only parameter (list_id) as 'The list ID returned by create_list' with 100% coverage. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieves the items in an existing list by its ID,' specifying the action (retrieves), resource (items in a list), and method (by ID). This distinguishes it from sibling tools like create_list or list_all_lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes a 'WHEN TO USE' section with three bullet points (inspect contents, verify items, check existence), providing clear context for when the tool is appropriate. However, it does not explicitly state when not to use or mention alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It correctly implies a read-only operation and lists output includes item counts, but lacks details on performance, data freshness, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear main sentence followed by a 'WHEN TO USE' list. Every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description is reasonably complete: it states the action and output (list IDs and item counts) and provides usage guidance. Minor missing information about output format or limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, so schema coverage is 100%. The description does not need to add parameter meaning. Baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lists all existing lists and their item counts', using a specific verb and resource. It distinguishes from sibling tools like get_list (single list) and create_list (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'WHEN TO USE' section with three clear use cases. It does not explicitly mention when not to use or alternatives, but the guidance is sufficient for this simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spawns an AI coding agent for each item in a previously created list. Agents run in batches of 10 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:
claude: Claude Code CLI (uses --dangerously-skip-permissions for autonomous operation)
gemini: Google Gemini CLI (uses --yolo for auto-accept)
codex: OpenAI Codex CLI (uses --dangerously-bypass-approvals-and-sandbox for autonomous operation)
opencode: OpenCode CLI (uses run command for non-interactive autonomous operation)
HOW IT WORKS:
Each item in the list is substituted into the prompt where {{item}} appears
Agents run in batches of 10 at a time to avoid overwhelming the system
Output streams directly to files as the agents work
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"
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | Which AI agent to use: 'claude', 'gemini', 'codex', 'opencode'. All agents run with permission-skipping flags for autonomous operation. | |
| model | No | Optional model to use. Passed as --model to the agent CLI. Examples: 'claude-opus-4-6', 'claude-sonnet-4-6' for Claude; 'gemini-2.5-pro' for Gemini; 'o3' for Codex. | |
| prompt | Yes | 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}}' | |
| list_id | Yes | The list ID returned by create_list. This identifies which list of items to iterate over. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: batching of 10, automatic permission skipping, agent-specific flags, streaming output to files, and blocking until all agents finish. It falls just short of explicitly warning about potential filesystem modifications from autonomous agents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well-organized with clear sections and front-loaded purpose. Some redundancy exists between HOW IT WORKS and VARIABLE SUBSTITUTION, but each section is otherwise purposeful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no output schema or annotations, the description covers the input lifecycle, concurrency behavior, output file naming, and post-completion steps. It does not describe failure handling or partial-failure behavior, but the provided details are sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context: how list_id connects to create_list, how {{item}} substitution works, and how agent choices map to CLI flags. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a precise verb, resource, and scope: it spawns an AI coding agent for each item in a previously created list. It also differentiates itself from the shell-based sibling by emphasizing AI reasoning and parallel agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
A dedicated WHEN TO USE section gives concrete contexts: complex analysis, refactoring, generation, and tasks needing AI rather than simple shell commands. It does not include explicit when-not-to-use or name the sibling tool, but the contrast with shell commands provides clear routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Executes a shell command for each item in a previously created list. Commands run in batches of 10 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:
Each item in the list is substituted into the command where $item appears
Commands run in batches of 10 at a time to avoid overwhelming the system
Output streams directly to files as the commands execute
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"
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | 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' | |
| list_id | Yes | The list ID returned by create_list. This identifies which list of items to iterate over. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It discloses batching (10 parallel), output streaming to files, variable substitution, and that the tool waits for completion. Missing error handling details (e.g., partial failure) prevent a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (WHEN TO USE, HOW IT WORKS, AFTER COMPLETION, VARIABLE SUBSTITUTION) and front-loaded with the core action. It is slightly lengthy but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, process, post-completion steps, and variable substitution. It lacks error handling behavior and edge cases (e.g., empty list). No output schema exists, but the return behavior (streaming to files) is explained. Overall, quite complete for a 2-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description adds value by explaining $item substitution, shell escaping, and providing examples, going beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Executes a shell command for each item in a previously created list.' It distinguishes from sibling 'run_agent_across_list' by focusing on shell commands and provides specific batching and streaming details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'WHEN TO USE' section explicitly lists scenarios like linting, formatting, compiling, and batch processing. It does not explicitly mention alternatives or when not to use, but the context of siblings and the description's focus on shell commands provide adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | The new array of items to replace the existing list contents. | |
| list_id | Yes | The list ID returned by create_list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It states the tool replaces items (destructive write), but fails to disclose other aspects like authorization needs, rate limits, or what happens to old data. This is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus three bullet points, with no extraneous text. The core action is front-loaded, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no annotations), the description adequately covers the purpose and usage. It lacks details on return values or errors, but these are not critical for a straightforward update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description's 'replaces its items with a new array' adds no new meaning beyond what the items parameter description already says. Thus, it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Updates an existing list by replacing its items with a new array.' This provides a specific verb (update) and resource (list), and it distinguishes from siblings like create_list and get_list by focusing on modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'WHEN TO USE' section with three relevant bullet points (modify contents, add/remove items, reorder items). It does not explicitly exclude cases or mention alternatives, but the guidance is clear for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.7run_agent_across_list1 field changedInput schema / properties / modelAdded value: +{
+ "description": "Optional model to use. Passed as --model to the agent CLI. Examples: 'claude-opus-4-6', 'claude-sonnet-4-6' for Claude; 'gemini-2.5-pro' for Gemini; 'o3' for Codex.",
+ "type": "string"
+}v1.0.0run_agent_across_list2 fields changedInput schema / properties / agent / descriptionPrevious value: -"Which AI agent to use: 'claude', 'gemini', 'codex'. All agents run with permission-skipping flags for autonomous operation."New value: +"Which AI agent to use: 'claude', 'gemini', 'codex', 'opencode'. All agents run with permission-skipping flags for autonomous operation."Input schema / properties / agent / enumPrevious value: -[
- "claude",
- "gemini",
- "codex"
-]New value: +[
+ "claude",
+ "gemini",
+ "codex",
+ "opencode"
+]create_listcreate_list_from_shelldelete_listget_listlist_all_listsrun_agent_across_listrun_shell_across_listupdate_listScored across 8 tools
Most tools are clearly distinct, but create_list and create_list_from_shell both create lists, which could cause minor confusion. However, the descriptions clearly differentiate manual entry vs. shell-command output, and all other tools (get/update/delete/list/runners) have unique purposes.
Tool names generally follow a verb_noun pattern (create_list, get_list, update_list, delete_list). Minor deviations include list_all_lists (repetitive) and run_shell_across_list/run_agent_across_list using a different prepositional style, but overall the convention is consistent.
Eight tools is well-scoped for a list-management and parallel-execution server: full CRUD for lists, two creation methods, and two execution modes. No redundancy or bloat.
The server covers the complete lifecycle: create lists from arrays or shell output, retrieve, update, delete, list all, and execute either shell commands or AI agents across list items. There are no obvious missing operations for the stated purpose.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Backend for AI agents: one batched tool over ~668 actions (hosting, storage, auth, payments).
