From ac8b4cc5ac7cde18652a3e0bbb80bac5821d90c6 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 15:05:45 +0100 Subject: [PATCH 01/14] imrove documentation --- README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 95 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 1e5bfa8..b726858 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,18 @@ # MCP Shell +[![CI](https://github.com/StacklokLabs/mcp-shell/actions/workflows/ci.yml/badge.svg)](https://github.com/StacklokLabs/mcp-shell/actions/workflows/ci.yml) +[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) + **Unix-style pipelines for MCP tools — coordinate thousands of tool calls in a single request** ## Overview MCP Shell is an MCP server that lets AI agents compose tool calls using Unix shell patterns. Instead of the agent orchestrating each tool call individually (loading all intermediate data into context), agents can express complex workflows as pipelines that execute server-side. -```bash -# What agents can express: -fetch https://api.example.com/users \ - | jq -c '.[] | .profile_url' \ - | for_each fetch \ - | jq '[.[] | select(.active)] | sort_by(.name)' +The agent writes pipelines that conceptually work like this: + +``` +fetch users → jq (extract profile URLs) → for_each fetch → jq (filter active, sort) ``` This single pipeline fetches a list, extracts URLs, fetches each one, filters the results, and returns only the final output to the agent — no intermediate data in context. @@ -65,9 +66,10 @@ Once running, MCP Shell is available to any AI agent that ToolHive supports — MCP Shell runs in a containerized environment through ToolHive, so commands have no direct access to the user's filesystem — only through explicitly configured MCP servers. - **Containerized**: Runs isolated from the host system -- **Allowed Commands**: Only safe, read-only data transformation commands are permitted -- **No Shell Injection**: Commands are executed with `shell=False`, args passed separately -- **MCP Tools Only**: All external operations go through approved MCP servers +- **Sandboxed**: Shell commands run inside [bubblewrap](https://github.com/containers/bubblewrap) with isolated namespaces (network, PID, filesystem) +- **Allowed commands only**: A fixed whitelist of safe, read-only data transformation commands (`jq`, `grep`, `sed`, `awk`, `sort`, `uniq`, `cut`, `wc`, `head`, `tail`, `tr`, `date`, `bc`, `paste`, `shuf`, `join`, `sleep`) +- **No shell injection**: Commands are executed with `shell=False`, arguments passed separately +- **MCP tools only**: All external operations go through approved MCP servers ## Usage Tips @@ -75,6 +77,81 @@ MCP Shell runs in a containerized environment through ToolHive, so commands have **Some agents need encouragement** — Most agents will use the shell naturally for complex tasks, but some may need a hint in their system prompt (e.g., "Use MCP Shell pipelines to combine multiple tool calls efficiently"). +## How It Works + +MCP Shell exposes four tools to the agent via MCP: + +| Tool | Purpose | +|---|---| +| `execute_pipeline` | Execute a pipeline of tool calls and shell commands | +| `list_all_tools` | Discover all tools available from MCP servers via ToolHive | +| `get_tool_details` | Get the full schema and description for a specific tool | +| `list_available_shell_commands` | Show the whitelist of allowed CLI commands | + +### Pipelines + +The agent constructs pipelines as JSON arrays of stages. Data flows from one stage to the next, similar to Unix pipes. There are three stage types: + +**Tool stages** call external MCP tools discovered through ToolHive: +```json +{"type": "tool", "name": "fetch", "server": "fetch", "args": {"url": "https://..."}} +``` + +**Command stages** transform data using whitelisted shell commands: +```json +{"type": "command", "command": "jq", "args": ["-c", ".results[] | {id, name}"]} +``` + +**Preview stages** show a summarized view of the data at any point in the pipeline, useful for the agent to understand the data structure before writing transformations: +```json +{"type": "preview", "chars": 3000} +``` + +### Batch processing with `for_each` + +Any tool stage can set `"for_each": true` to process items one-by-one. The preceding stage must output JSONL (one JSON object per line), and the tool is called once per line. Results are collected into an array. This enables patterns like "fetch a list of URLs, then fetch each one" in a single pipeline call, using a single reused connection for efficiency. + +### Example pipeline + +This is what the agent actually sends — a JSON array that fetches users, extracts their profile URLs, fetches each profile, and filters for active users: + +```json +[ + {"type": "tool", "name": "fetch", "server": "fetch", "args": {"url": "https://api.example.com/users"}}, + {"type": "command", "command": "jq", "args": ["-c", ".[] | {url: .profile_url}"]}, + {"type": "tool", "name": "fetch", "server": "fetch", "for_each": true}, + {"type": "command", "command": "jq", "args": ["-c", "[.[] | select(.active)] | sort_by(.name)"]} +] +``` + +## Development + +### Requirements + +- Python 3.13+ +- [uv](https://docs.astral.sh/uv/) for dependency management +- [bubblewrap](https://github.com/containers/bubblewrap) (`bwrap`) for command sandboxing + +### Setup + +```bash +uv sync --group dev +``` + +### Running tests + +```bash +uv run pytest +``` + +### Linting and type checking + +```bash +uv run ruff check . +uv run ruff format --check . +uv run pyright +``` + ## FAQ **Q: Does this work with my existing MCP servers?** @@ -85,9 +162,17 @@ A: Yes! MCP Shell coordinates any standard MCP servers running through ToolHive. A: Currently relies on ToolHive's authentication model for connected MCP servers. +**Q: Can I run this without ToolHive?** + +A: MCP Shell uses ToolHive for tool discovery and container management. Running without it is not currently supported. + +**Q: What shell commands are available?** + +A: A fixed whitelist: `jq`, `grep`, `sed`, `awk`, `sort`, `uniq`, `cut`, `wc`, `head`, `tail`, `tr`, `date`, `bc`, `paste`, `shuf`, `join`, `sleep`. See the [Security](#security) section. + ## Contributing -This is an experimental project. Contributions, ideas, and feedback are welcome! +Contributions, ideas, and feedback are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, including our DCO sign-off requirement. ## License From 0af3a404fe700cb1b007e1b05c5adfce8e156f86 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 15:08:40 +0100 Subject: [PATCH 02/14] keep naming consistent --- README.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index b726858..8a28619 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# MCP Shell +# Model Context Shell [![CI](https://github.com/StacklokLabs/mcp-shell/actions/workflows/ci.yml/badge.svg)](https://github.com/StacklokLabs/mcp-shell/actions/workflows/ci.yml) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) @@ -7,7 +7,7 @@ ## Overview -MCP Shell is an MCP server that lets AI agents compose tool calls using Unix shell patterns. Instead of the agent orchestrating each tool call individually (loading all intermediate data into context), agents can express complex workflows as pipelines that execute server-side. +Model Context Shell is an MCP server that lets AI agents compose tool calls using Unix shell patterns. Instead of the agent orchestrating each tool call individually (loading all intermediate data into context), agents can express complex workflows as pipelines that execute server-side. The agent writes pipelines that conceptually work like this: @@ -21,7 +21,7 @@ This single pipeline fetches a list, extracts URLs, fetches each one, filters th MCP is great — standardized interfaces, structured data, extensible ecosystem. But for complex workflows, agents hit real limits: -| | Without MCP Shell | With MCP Shell | +| | Without Model Context Shell | With Model Context Shell | |---|---|---| | **Orchestration** | Agent coordinates every tool call, loading intermediate results into context | Single pipeline request, only final result returned | | **Composition** | Tools combined through LLM reasoning | Native Unix-style piping between tools | @@ -59,27 +59,26 @@ thv run ghcr.io/stackloklabs/model-context-shell:latest --network host --foregro thv run ghcr.io/stackloklabs/model-context-shell:latest --foreground --transport streamable-http ``` -Once running, MCP Shell is available to any AI agent that ToolHive supports — no additional integration required. +Once running, Model Context Shell is available to any AI agent that ToolHive supports — no additional integration required. ## Security -MCP Shell runs in a containerized environment through ToolHive, so commands have no direct access to the user's filesystem — only through explicitly configured MCP servers. +Model Context Shell runs in a containerized environment through ToolHive, so commands have no direct access to the user's filesystem — only through explicitly configured MCP servers. -- **Containerized**: Runs isolated from the host system -- **Sandboxed**: Shell commands run inside [bubblewrap](https://github.com/containers/bubblewrap) with isolated namespaces (network, PID, filesystem) +- **Containerized**: ToolHive runs Model Context Shell in an isolated container, so shell commands have no access to the host filesystem or network - **Allowed commands only**: A fixed whitelist of safe, read-only data transformation commands (`jq`, `grep`, `sed`, `awk`, `sort`, `uniq`, `cut`, `wc`, `head`, `tail`, `tr`, `date`, `bc`, `paste`, `shuf`, `join`, `sleep`) - **No shell injection**: Commands are executed with `shell=False`, arguments passed separately - **MCP tools only**: All external operations go through approved MCP servers ## Usage Tips -**Connect only MCP Shell to your agent** — For best results, don't connect individual MCP servers directly to the agent alongside MCP Shell. When agents have direct access to tools, they may call them individually instead of composing efficient pipelines. MCP Shell can access all your MCP servers through ToolHive automatically. +**Connect only Model Context Shell to your agent** — For best results, don't connect individual MCP servers directly to the agent alongside Model Context Shell. When agents have direct access to tools, they may call them individually instead of composing efficient pipelines. Model Context Shell can access all your MCP servers through ToolHive automatically. -**Some agents need encouragement** — Most agents will use the shell naturally for complex tasks, but some may need a hint in their system prompt (e.g., "Use MCP Shell pipelines to combine multiple tool calls efficiently"). +**Some agents need encouragement** — Most agents will use the shell naturally for complex tasks, but some may need a hint in their system prompt (e.g., "Use Model Context Shell pipelines to combine multiple tool calls efficiently"). ## How It Works -MCP Shell exposes four tools to the agent via MCP: +Model Context Shell exposes four tools to the agent via MCP: | Tool | Purpose | |---|---| @@ -130,7 +129,6 @@ This is what the agent actually sends — a JSON array that fetches users, extra - Python 3.13+ - [uv](https://docs.astral.sh/uv/) for dependency management -- [bubblewrap](https://github.com/containers/bubblewrap) (`bwrap`) for command sandboxing ### Setup @@ -156,7 +154,7 @@ uv run pyright **Q: Does this work with my existing MCP servers?** -A: Yes! MCP Shell coordinates any standard MCP servers running through ToolHive. +A: Yes! Model Context Shell coordinates any standard MCP servers running through ToolHive. **Q: What about authentication?** @@ -164,7 +162,7 @@ A: Currently relies on ToolHive's authentication model for connected MCP servers **Q: Can I run this without ToolHive?** -A: MCP Shell uses ToolHive for tool discovery and container management. Running without it is not currently supported. +A: Model Context Shell uses ToolHive for tool discovery and container management. Running without it is not currently supported. **Q: What shell commands are available?** From 45c13a4eca0acfe2943e75e1cb2c51432b753383 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 15:24:33 +0100 Subject: [PATCH 03/14] restructure document --- README.md | 113 +++++++++++++++++++++--------------------------------- 1 file changed, 44 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 8a28619..1d18f8b 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@ **Unix-style pipelines for MCP tools — coordinate thousands of tool calls in a single request** -## Overview +## Introduction -Model Context Shell is an MCP server that lets AI agents compose tool calls using Unix shell patterns. Instead of the agent orchestrating each tool call individually (loading all intermediate data into context), agents can express complex workflows as pipelines that execute server-side. +Model Context Shell is an [MCP](https://modelcontextprotocol.io/) server that lets AI agents compose tool calls using Unix shell patterns. Instead of the agent orchestrating each tool call individually (loading all intermediate data into context), agents can express complex workflows as pipelines that execute server-side. The agent writes pipelines that conceptually work like this: @@ -17,11 +17,11 @@ fetch users → jq (extract profile URLs) → for_each fetch → jq (filter acti This single pipeline fetches a list, extracts URLs, fetches each one, filters the results, and returns only the final output to the agent — no intermediate data in context. -## Why This Matters +### Why this matters -MCP is great — standardized interfaces, structured data, extensible ecosystem. But for complex workflows, agents hit real limits: +[MCP](https://modelcontextprotocol.io/) is great — standardized interfaces, structured data, extensible ecosystem. But for complex workflows, agents hit real limits: -| | Without Model Context Shell | With Model Context Shell | +| | Without | With | |---|---|---| | **Orchestration** | Agent coordinates every tool call, loading intermediate results into context | Single pipeline request, only final result returned | | **Composition** | Tools combined through LLM reasoning | Native Unix-style piping between tools | @@ -29,7 +29,7 @@ MCP is great — standardized interfaces, structured data, extensible ecosystem. | **Reliability** | LLM-dependent control flow | Deterministic shell pipeline execution | | **Permissions** | Complex tasks push toward full shell access | Sandboxed execution with allowed commands only | -## Real-World Example +### Real-world example Example query: "List all Pokemon over 50 kg that have the chlorophyll ability" @@ -41,54 +41,17 @@ Instead of 7+ separate tool calls loading all Pokemon data into context, the age **Result**: 50%+ reduction in tokens and only the final answer loaded into context. -## Installation +### How it works -### Prerequisites - -- [ToolHive](https://toolhive.ai) (`thv`) for running and managing MCP servers - -### Quick Start - -Run the pre-built image from GitHub Container Registry: - -```bash -# Linux (requires --network host) -thv run ghcr.io/stackloklabs/model-context-shell:latest --network host --foreground --transport streamable-http - -# macOS / Windows (Docker Desktop bridge works automatically) -thv run ghcr.io/stackloklabs/model-context-shell:latest --foreground --transport streamable-http -``` - -Once running, Model Context Shell is available to any AI agent that ToolHive supports — no additional integration required. - -## Security - -Model Context Shell runs in a containerized environment through ToolHive, so commands have no direct access to the user's filesystem — only through explicitly configured MCP servers. - -- **Containerized**: ToolHive runs Model Context Shell in an isolated container, so shell commands have no access to the host filesystem or network -- **Allowed commands only**: A fixed whitelist of safe, read-only data transformation commands (`jq`, `grep`, `sed`, `awk`, `sort`, `uniq`, `cut`, `wc`, `head`, `tail`, `tr`, `date`, `bc`, `paste`, `shuf`, `join`, `sleep`) -- **No shell injection**: Commands are executed with `shell=False`, arguments passed separately -- **MCP tools only**: All external operations go through approved MCP servers - -## Usage Tips - -**Connect only Model Context Shell to your agent** — For best results, don't connect individual MCP servers directly to the agent alongside Model Context Shell. When agents have direct access to tools, they may call them individually instead of composing efficient pipelines. Model Context Shell can access all your MCP servers through ToolHive automatically. - -**Some agents need encouragement** — Most agents will use the shell naturally for complex tasks, but some may need a hint in their system prompt (e.g., "Use Model Context Shell pipelines to combine multiple tool calls efficiently"). - -## How It Works - -Model Context Shell exposes four tools to the agent via MCP: +The server exposes four tools to the agent via MCP: | Tool | Purpose | |---|---| | `execute_pipeline` | Execute a pipeline of tool calls and shell commands | -| `list_all_tools` | Discover all tools available from MCP servers via ToolHive | +| `list_all_tools` | Discover all tools available from MCP servers via [ToolHive](https://toolhive.ai) | | `get_tool_details` | Get the full schema and description for a specific tool | | `list_available_shell_commands` | Show the whitelist of allowed CLI commands | -### Pipelines - The agent constructs pipelines as JSON arrays of stages. Data flows from one stage to the next, similar to Unix pipes. There are three stage types: **Tool stages** call external MCP tools discovered through ToolHive: @@ -106,13 +69,9 @@ The agent constructs pipelines as JSON arrays of stages. Data flows from one sta {"type": "preview", "chars": 3000} ``` -### Batch processing with `for_each` - Any tool stage can set `"for_each": true` to process items one-by-one. The preceding stage must output JSONL (one JSON object per line), and the tool is called once per line. Results are collected into an array. This enables patterns like "fetch a list of URLs, then fetch each one" in a single pipeline call, using a single reused connection for efficiency. -### Example pipeline - -This is what the agent actually sends — a JSON array that fetches users, extracts their profile URLs, fetches each profile, and filters for active users: +Here is a full example — a pipeline that fetches users, extracts their profile URLs, fetches each profile, and filters for active users: ```json [ @@ -123,6 +82,40 @@ This is what the agent actually sends — a JSON array that fetches users, extra ] ``` +## Setup + +### Prerequisites + +- [ToolHive](https://toolhive.ai) (`thv`) — a runtime for managing MCP servers + +### Quick start + +Run the pre-built image from GitHub Container Registry: + +```bash +# Linux (requires --network host) +thv run ghcr.io/stackloklabs/model-context-shell:latest --network host --foreground --transport streamable-http + +# macOS / Windows (Docker Desktop bridge works automatically) +thv run ghcr.io/stackloklabs/model-context-shell:latest --foreground --transport streamable-http +``` + +Once running, Model Context Shell is available to any AI agent that ToolHive supports — no additional integration required. It works with any existing MCP servers running through ToolHive, and relies on ToolHive's authentication model for connected servers. + +### Tips + +**Connect only Model Context Shell to your agent** — For best results, don't connect individual MCP servers directly to the agent alongside Model Context Shell. When agents have direct access to tools, they may call them individually instead of composing efficient pipelines. The server can access all your MCP servers through ToolHive automatically. + +**Some agents need encouragement** — Most agents will use the shell naturally for complex tasks, but some may need a hint in their system prompt (e.g., "Use Model Context Shell pipelines to combine multiple tool calls efficiently"). + +## Security + +ToolHive runs Model Context Shell in an isolated container, so shell commands have no access to the host filesystem or network — only to explicitly configured MCP servers. + +- **Allowed commands only**: A fixed whitelist of safe, read-only data transformation commands (`jq`, `grep`, `sed`, `awk`, `sort`, `uniq`, `cut`, `wc`, `head`, `tail`, `tr`, `date`, `bc`, `paste`, `shuf`, `join`, `sleep`) +- **No shell injection**: Commands are executed with `shell=False`, arguments passed separately +- **MCP tools only**: All external operations go through approved MCP servers + ## Development ### Requirements @@ -150,24 +143,6 @@ uv run ruff format --check . uv run pyright ``` -## FAQ - -**Q: Does this work with my existing MCP servers?** - -A: Yes! Model Context Shell coordinates any standard MCP servers running through ToolHive. - -**Q: What about authentication?** - -A: Currently relies on ToolHive's authentication model for connected MCP servers. - -**Q: Can I run this without ToolHive?** - -A: Model Context Shell uses ToolHive for tool discovery and container management. Running without it is not currently supported. - -**Q: What shell commands are available?** - -A: A fixed whitelist: `jq`, `grep`, `sed`, `awk`, `sort`, `uniq`, `cut`, `wc`, `head`, `tail`, `tr`, `date`, `bc`, `paste`, `shuf`, `join`, `sleep`. See the [Security](#security) section. - ## Contributing Contributions, ideas, and feedback are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, including our DCO sign-off requirement. From d1da4d1fb9ccbb74a311f8cb7d93fcf7ce02cf5f Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 15:28:37 +0100 Subject: [PATCH 04/14] fix link --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1d18f8b..94493b7 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ The server exposes four tools to the agent via MCP: | Tool | Purpose | |---|---| | `execute_pipeline` | Execute a pipeline of tool calls and shell commands | -| `list_all_tools` | Discover all tools available from MCP servers via [ToolHive](https://toolhive.ai) | +| `list_all_tools` | Discover all tools available from MCP servers via [ToolHive](https://stacklok.com/download/) | | `get_tool_details` | Get the full schema and description for a specific tool | | `list_available_shell_commands` | Show the whitelist of allowed CLI commands | @@ -86,7 +86,7 @@ Here is a full example — a pipeline that fetches users, extracts their profile ### Prerequisites -- [ToolHive](https://toolhive.ai) (`thv`) — a runtime for managing MCP servers +- [ToolHive](https://stacklok.com/download/) (`thv`) — a runtime for managing MCP servers ### Quick start From 160752795b680748a51160e66e3bb1993ecf8589 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 15:30:06 +0100 Subject: [PATCH 05/14] add mermaid --- README.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 94493b7..cce2342 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,38 @@ This single pipeline fetches a list, extracts URLs, fetches each one, filters th ### Why this matters -[MCP](https://modelcontextprotocol.io/) is great — standardized interfaces, structured data, extensible ecosystem. But for complex workflows, agents hit real limits: +[MCP](https://modelcontextprotocol.io/) is great — standardized interfaces, structured data, extensible ecosystem. But for complex workflows, the agent has to orchestrate each tool call individually, loading all intermediate results into context: + +```mermaid +flowchart TB + A[Agent] + M[MCP Tool] + + A <--> M +``` + +Model Context Shell adds a pipeline layer between the agent and the tools. The agent sends a single pipeline, and the server coordinates the tools — only the final result goes back to the agent: + +```mermaid +flowchart TB + A[Agent] + S[Shell] + + T1[Tool A] + T2[Tool B] + T3[Tool C] + + A <--> S + + S --> T1 + T1 --> S + + S --> T2 + T2 --> S + + S --> T3 + T3 --> S +``` | | Without | With | |---|---|---| From c6f845b3a87da8792621fa423edac869b70c5f62 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 15:35:34 +0100 Subject: [PATCH 06/14] . --- README.md | 43 +++++++++++++++---------------------------- 1 file changed, 15 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index cce2342..365fe60 100644 --- a/README.md +++ b/README.md @@ -19,37 +19,22 @@ This single pipeline fetches a list, extracts URLs, fetches each one, filters th ### Why this matters -[MCP](https://modelcontextprotocol.io/) is great — standardized interfaces, structured data, extensible ecosystem. But for complex workflows, the agent has to orchestrate each tool call individually, loading all intermediate results into context: +[MCP](https://modelcontextprotocol.io/) is great — standardized interfaces, structured data, extensible ecosystem. But for complex workflows, the agent has to orchestrate each tool call individually, loading all intermediate results into context. Model Context Shell adds a pipeline layer — the agent sends a single pipeline, and the server coordinates the tools, returning only the final result: ```mermaid flowchart TB - A[Agent] - M[MCP Tool] - - A <--> M -``` - -Model Context Shell adds a pipeline layer between the agent and the tools. The agent sends a single pipeline, and the server coordinates the tools — only the final result goes back to the agent: - -```mermaid -flowchart TB - A[Agent] - S[Shell] - - T1[Tool A] - T2[Tool B] - T3[Tool C] - - A <--> S - - S --> T1 - T1 --> S - - S --> T2 - T2 --> S - - S --> T3 - T3 --> S + subgraph without["Without"] + A1[Agent] + A1 <--> T1a[Tool A] + A1 <--> T2a[Tool B] + A1 <--> T3a[Tool C] + end + subgraph with["With Model Context Shell"] + A2[Agent] <--> S[Shell] + S --> T1b[Tool A] --> S + S --> T2b[Tool B] --> S + S --> T3b[Tool C] --> S + end ``` | | Without | With | @@ -72,6 +57,8 @@ Instead of 7+ separate tool calls loading all Pokemon data into context, the age **Result**: 50%+ reduction in tokens and only the final answer loaded into context. +In practice, agents don't construct the perfect pipeline on the first try. They typically run a few exploratory queries first to understand the shape of the data before building the final pipeline. To keep this process fast and cheap, the server includes a preview stage powered by [headson](https://github.com/kantord/headson) that returns a compact structural summary of the data — enough for the agent to plan its transformations without loading the full dataset into context. + ### How it works The server exposes four tools to the agent via MCP: From 48f00b2d2975a203ac693b60e0923ec9ccfe1f3f Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 15:38:29 +0100 Subject: [PATCH 07/14] . --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 365fe60..952bd61 100644 --- a/README.md +++ b/README.md @@ -22,19 +22,22 @@ This single pipeline fetches a list, extracts URLs, fetches each one, filters th [MCP](https://modelcontextprotocol.io/) is great — standardized interfaces, structured data, extensible ecosystem. But for complex workflows, the agent has to orchestrate each tool call individually, loading all intermediate results into context. Model Context Shell adds a pipeline layer — the agent sends a single pipeline, and the server coordinates the tools, returning only the final result: ```mermaid -flowchart TB +flowchart LR subgraph without["Without"] + direction TB A1[Agent] A1 <--> T1a[Tool A] A1 <--> T2a[Tool B] A1 <--> T3a[Tool C] end subgraph with["With Model Context Shell"] + direction TB A2[Agent] <--> S[Shell] S --> T1b[Tool A] --> S S --> T2b[Tool B] --> S S --> T3b[Tool C] --> S end + without ~~~ with ``` | | Without | With | From 685fc0f1fa83e75bbb86a82a81476847ee35057a Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 15:40:41 +0100 Subject: [PATCH 08/14] . --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 952bd61..d22e25b 100644 --- a/README.md +++ b/README.md @@ -23,14 +23,14 @@ This single pipeline fetches a list, extracts URLs, fetches each one, filters th ```mermaid flowchart LR - subgraph without["Without"] + subgraph without["Standard Tool Call Workflow"] direction TB A1[Agent] A1 <--> T1a[Tool A] A1 <--> T2a[Tool B] A1 <--> T3a[Tool C] end - subgraph with["With Model Context Shell"] + subgraph with["Model Context Shell"] direction TB A2[Agent] <--> S[Shell] S --> T1b[Tool A] --> S From 7112a6471862cca2eadda05d06e730e799e6ddc7 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 15:44:14 +0100 Subject: [PATCH 09/14] . --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index d22e25b..abf197b 100644 --- a/README.md +++ b/README.md @@ -3,19 +3,20 @@ [![CI](https://github.com/StacklokLabs/mcp-shell/actions/workflows/ci.yml/badge.svg)](https://github.com/StacklokLabs/mcp-shell/actions/workflows/ci.yml) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) -**Unix-style pipelines for MCP tools — coordinate thousands of tool calls in a single request** +**Unix-style pipelines for MCP tools — compose complex tool workflows as single pipeline requests** ## Introduction -Model Context Shell is an [MCP](https://modelcontextprotocol.io/) server that lets AI agents compose tool calls using Unix shell patterns. Instead of the agent orchestrating each tool call individually (loading all intermediate data into context), agents can express complex workflows as pipelines that execute server-side. +Model Context Shell is an [MCP](https://modelcontextprotocol.io/) server that lets AI agents compose MCP tool calls similar to Unix shell scripting. Instead of the agent orchestrating each tool call individually (loading all intermediate data into context), agents can express complex workflows as pipelines that execute server-side. -The agent writes pipelines that conceptually work like this: +For example, an agent can express a multi-step workflow as a single pipeline: -``` -fetch users → jq (extract profile URLs) → for_each fetch → jq (filter active, sort) +```mermaid +flowchart LR + A[Fetch users] --> B[jq: extract profile URLs] --> C[for_each: fetch profiles] --> D[jq: filter active, sort] ``` -This single pipeline fetches a list, extracts URLs, fetches each one, filters the results, and returns only the final output to the agent — no intermediate data in context. +This pipeline fetches a list, extracts URLs, fetches each one, filters the results, and returns only the final output to the agent — no intermediate data in context. ### Why this matters From 1855d6c0f81bc3825b2e80e8e05871add2238938 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 15:50:28 +0100 Subject: [PATCH 10/14] . --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index abf197b..20b02e4 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ For example, an agent can express a multi-step workflow as a single pipeline: ```mermaid flowchart LR - A[Fetch users] --> B[jq: extract profile URLs] --> C[for_each: fetch profiles] --> D[jq: filter active, sort] + A["Fetch users (MCP)"] --> B["Extract profile URLs (Shell)"] --> C["for_each: Fetch profile (MCP)"] --> D["Filter and sort (Shell)"] ``` This pipeline fetches a list, extracts URLs, fetches each one, filters the results, and returns only the final output to the agent — no intermediate data in context. @@ -24,7 +24,7 @@ This pipeline fetches a list, extracts URLs, fetches each one, filters the resul ```mermaid flowchart LR - subgraph without["Standard Tool Call Workflow"] + subgraph without["Standard Workflow"] direction TB A1[Agent] A1 <--> T1a[Tool A] From ae6d7a1c6fee721bf80ad50b43621a2856055e9f Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 15:54:24 +0100 Subject: [PATCH 11/14] . --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 20b02e4..244afb9 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,13 @@ ## Introduction -Model Context Shell is an [MCP](https://modelcontextprotocol.io/) server that lets AI agents compose MCP tool calls similar to Unix shell scripting. Instead of the agent orchestrating each tool call individually (loading all intermediate data into context), agents can express complex workflows as pipelines that execute server-side. +Model Context Shell is a system that lets AI agents compose [MCP](https://modelcontextprotocol.io/) tool calls similar to Unix shell scripting. Instead of the agent orchestrating each tool call individually (loading all intermediate data into context), agents can express complex workflows as pipelines that execute server-side. For example, an agent can express a multi-step workflow as a single pipeline: ```mermaid flowchart LR - A["Fetch users (MCP)"] --> B["Extract profile URLs (Shell)"] --> C["for_each: Fetch profile (MCP)"] --> D["Filter and sort (Shell)"] + A["Fetch users (MCP)"] --> B["Extract profile URLs (Shell)"] --> C["for_each (Shell)"] --> C1["Fetch profile (MCP)"] --> D["Filter and sort (Shell)"] ``` This pipeline fetches a list, extracts URLs, fetches each one, filters the results, and returns only the final output to the agent — no intermediate data in context. @@ -59,12 +59,14 @@ Instead of 7+ separate tool calls loading all Pokemon data into context, the age - Fetched each Pokemon's details (7 API calls) - Filtered by weight and formatted the results -**Result**: 50%+ reduction in tokens and only the final answer loaded into context. +**Result**: Only the final answer is loaded into context — no intermediate API responses. In practice, agents don't construct the perfect pipeline on the first try. They typically run a few exploratory queries first to understand the shape of the data before building the final pipeline. To keep this process fast and cheap, the server includes a preview stage powered by [headson](https://github.com/kantord/headson) that returns a compact structural summary of the data — enough for the agent to plan its transformations without loading the full dataset into context. ### How it works +Model Context Shell is packaged as an MCP server, which makes it easy to use with any agent that supports the protocol. It could also be packaged as a library built directly into an agent. + The server exposes four tools to the agent via MCP: | Tool | Purpose | From ff7acf5758624a7b219eff6214d46de971023812 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 18:48:35 +0100 Subject: [PATCH 12/14] . --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index 244afb9..2e0e653 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,14 @@ Instead of 7+ separate tool calls loading all Pokemon data into context, the age In practice, agents don't construct the perfect pipeline on the first try. They typically run a few exploratory queries first to understand the shape of the data before building the final pipeline. To keep this process fast and cheap, the server includes a preview stage powered by [headson](https://github.com/kantord/headson) that returns a compact structural summary of the data — enough for the agent to plan its transformations without loading the full dataset into context. +### Design + +Agents already have access to full shell environments and can call any CLI tool, which has significant overlap with what MCP tools provide. Rather than duplicating that, Model Context Shell explores whether similar workflows can be achieved in a safer, simpler MCP-native environment. Patterns like parallel map-reduce over tool call results are not common today because MCP doesn't natively support them, but they seem like a natural fit for coordinating tool calls — imagine fetching all console errors via a Chrome DevTools MCP server and creating a separate GitHub issue for each one. A system tailored to these patterns can make them first-class operations. + +The execution engine works with JSON pipeline definitions directly — agents construct pipelines from the MCP tool schema alone, without needing shell syntax. Commands are never passed through a shell interpreter; each command and its arguments are passed as separate elements to the underlying process (`shell=False`), eliminating shell injection risks entirely. Data flows between stages as JSON, preserving types through the pipeline rather than reducing everything to strings. MCP tool arguments are validated against their JSON Schema by the receiving server, giving agents type-checked feedback when they construct pipelines incorrectly. + +The result is a more constrained system compared to a general-purpose shell — only a fixed set of data transformation commands is available, and all execution happens either inside a container or a [bubblewrap](https://github.com/containers/bubblewrap) sandbox. + ### How it works Model Context Shell is packaged as an MCP server, which makes it easy to use with any agent that supports the protocol. It could also be packaged as a library built directly into an agent. From f304be23b09d94c7050fddd835415e5f8dc88a99 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Mon, 16 Feb 2026 18:54:20 +0100 Subject: [PATCH 13/14] . --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2e0e653..0f41d5e 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ flowchart LR | | Without | With | |---|---|---| | **Orchestration** | Agent coordinates every tool call, loading intermediate results into context | Single pipeline request, only final result returned | -| **Composition** | Tools combined through LLM reasoning | Native Unix-style piping between tools | +| **Composition** | Tools combined by the agent one call at a time | Native Unix-style piping between tools | | **Data scale** | Limited by context window | Streaming/iterator model handles datasets larger than memory | | **Reliability** | LLM-dependent control flow | Deterministic shell pipeline execution | | **Permissions** | Complex tasks push toward full shell access | Sandboxed execution with allowed commands only | @@ -69,7 +69,7 @@ Agents already have access to full shell environments and can call any CLI tool, The execution engine works with JSON pipeline definitions directly — agents construct pipelines from the MCP tool schema alone, without needing shell syntax. Commands are never passed through a shell interpreter; each command and its arguments are passed as separate elements to the underlying process (`shell=False`), eliminating shell injection risks entirely. Data flows between stages as JSON, preserving types through the pipeline rather than reducing everything to strings. MCP tool arguments are validated against their JSON Schema by the receiving server, giving agents type-checked feedback when they construct pipelines incorrectly. -The result is a more constrained system compared to a general-purpose shell — only a fixed set of data transformation commands is available, and all execution happens either inside a container or a [bubblewrap](https://github.com/containers/bubblewrap) sandbox. +The result is a more constrained system compared to a general-purpose shell — only a fixed set of data transformation commands is available, and all execution happens inside a container. ### How it works @@ -142,7 +142,7 @@ Once running, Model Context Shell is available to any AI agent that ToolHive sup ## Security -ToolHive runs Model Context Shell in an isolated container, so shell commands have no access to the host filesystem or network — only to explicitly configured MCP servers. +ToolHive runs Model Context Shell in an isolated container, so shell commands have no access to the host filesystem or network. The MCP servers it coordinates also run in their own separate containers, managed by ToolHive. - **Allowed commands only**: A fixed whitelist of safe, read-only data transformation commands (`jq`, `grep`, `sed`, `awk`, `sort`, `uniq`, `cut`, `wc`, `head`, `tail`, `tr`, `date`, `bc`, `paste`, `shuf`, `join`, `sleep`) - **No shell injection**: Commands are executed with `shell=False`, arguments passed separately From 1807db840f1c325c02aabcade733ac1c265defb3 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Tue, 17 Feb 2026 13:33:52 +0100 Subject: [PATCH 14/14] . --- CONTRIBUTING.md | 20 ++++++++++---------- README.md | 2 +- SECURITY.md | 4 ++-- mcp-metadata.json | 1 + 4 files changed, 14 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4b77754..bc61ff4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,10 @@ -# Contributing to `mcp-shell` +# Contributing to Model Context Shell -First off, thank you for taking the time to contribute to MCP Shell! :+1: :tada: MCP Shell is released under the Apache 2.0 license. +First off, thank you for taking the time to contribute to Model Context Shell! :+1: :tada: Model Context Shell is released under the Apache 2.0 license. If you would like to contribute something or want to hack on the code, this document should help you get started. You can find some hints for starting -development in mcp-shell's -[README](https://github.com/StacklokLabs/mcp-shell/blob/main/README.md). +development in the project's +[README](https://github.com/StacklokLabs/model-context-shell/blob/main/README.md). ## Table of contents @@ -19,17 +19,17 @@ development in mcp-shell's ## Code of conduct This project adheres to the -[Contributor Covenant](https://github.com/StacklokLabs/mcp-shell/blob/main/CODE_OF_CONDUCT.md) +[Contributor Covenant](https://github.com/StacklokLabs/model-context-shell/blob/main/CODE_OF_CONDUCT.md) code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [code-of-conduct@stacklok.com](mailto:code-of-conduct@stacklok.com). ## Reporting security vulnerabilities -If you think you have found a security vulnerability in mcp-shell please DO +If you think you have found a security vulnerability in Model Context Shell please DO NOT disclose it publicly until we've had a chance to fix it. Please don't report security vulnerabilities using GitHub issues; instead, please follow this -[process](https://github.com/StacklokLabs/mcp-shell/blob/main/SECURITY.md) +[process](https://github.com/StacklokLabs/model-context-shell/blob/main/SECURITY.md) ## How to contribute @@ -46,7 +46,7 @@ sample project that reproduces the problem. ### Not sure how to start contributing? PRs to resolve existing issues are greatly appreciated and issues labeled as -["good first issue"](https://github.com/StacklokLabs/mcp-shell/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) +["good first issue"](https://github.com/StacklokLabs/model-context-shell/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) are a great place to start! ### Pull request process @@ -56,7 +56,7 @@ are a great place to start! of Origin. For additional details, check out the [DCO instructions](dco.md). - Create an issue outlining the fix or feature. -- Fork the mcp-shell repository to your own GitHub account and clone it +- Fork the repository to your own GitHub account and clone it locally. - Hack on your changes. - Correctly format your commit messages, see @@ -64,7 +64,7 @@ are a great place to start! - Open a PR by ensuring the title and its description reflect the content of the PR. - Ensure that CI passes, if it fails, fix the failures. -- Every pull request requires a review from the core mcp-shell team before +- Every pull request requires a review from the core team before merging. - Once approved, all of your commits will be squashed into a single commit with your PR title. diff --git a/README.md b/README.md index 0f41d5e..2cbc8a4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Model Context Shell -[![CI](https://github.com/StacklokLabs/mcp-shell/actions/workflows/ci.yml/badge.svg)](https://github.com/StacklokLabs/mcp-shell/actions/workflows/ci.yml) +[![CI](https://github.com/StacklokLabs/model-context-shell/actions/workflows/ci.yml/badge.svg)](https://github.com/StacklokLabs/model-context-shell/actions/workflows/ci.yml) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) **Unix-style pipelines for MCP tools — compose complex tool workflows as single pipeline requests** diff --git a/SECURITY.md b/SECURITY.md index e61bbe6..128e953 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -7,7 +7,7 @@ your contributions. ## Reporting a vulnerability To report a security issue, please use the GitHub Security Advisory -["Report a Vulnerability"](https://github.com/StacklokLabs/mcp-shell/security/advisories/new) +["Report a Vulnerability"](https://github.com/StacklokLabs/model-context-shell/security/advisories/new) tab. If you are unable to access GitHub you can also email us at @@ -80,7 +80,7 @@ These steps should be completed within the 1-7 days of Disclosure. - Create a new [security advisory](https://docs.github.com/en/code-security/security-advisories/) in affected repository by visiting - `https://github.com/StacklokLabs/mcp-shell/security/advisories/new` + `https://github.com/StacklokLabs/model-context-shell/security/advisories/new` - As many details as possible should be entered such as versions affected, CVE (if available yet). As more information is discovered, edit and update the advisory accordingly. diff --git a/mcp-metadata.json b/mcp-metadata.json index a34ac12..8ba6a3f 100644 --- a/mcp-metadata.json +++ b/mcp-metadata.json @@ -8,6 +8,7 @@ "tools": [ "execute_pipeline", "list_all_tools", + "get_tool_details", "list_available_shell_commands" ], "metadata": {