From 239cb22003757e44964666fb69b4581501ae3749 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Tue, 17 Feb 2026 15:28:51 +0100 Subject: [PATCH 1/5] docs: add further details to readme --- README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2cbc8a4..6fe1844 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,6 @@ -# Model Context Shell +

Model Context Shell

-[![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** +

Unix-style pipelines for MCP tools — compose complex tool workflows as single pipeline requests

## Introduction From f344b23fb2aa9ed088c2768d146b6229a9c9a132 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Tue, 17 Feb 2026 15:32:29 +0100 Subject: [PATCH 2/5] add mini menu --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index 6fe1844..0290089 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,14 @@

Unix-style pipelines for MCP tools — compose complex tool workflows as single pipeline requests

+

+Introduction · +Setup · +Security · +Development · +Contributing +

+ ## Introduction 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. From 8a1114acef487ffd3f519d99fa86dd86f40780fe Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Tue, 17 Feb 2026 15:49:24 +0100 Subject: [PATCH 3/5] detailed insturctions --- README.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0290089..d9dffd2 100644 --- a/README.md +++ b/README.md @@ -137,7 +137,38 @@ 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, 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. +Once running, you can find the server's address with `thv list`, which shows the URL and port for each running server. If you've registered your AI client with `thv client setup`, ToolHive configures it to discover running servers automatically — see the [CLI quickstart](https://docs.stacklok.com/toolhive/tutorials/quickstart-cli) for details. + +Model Context Shell works with any existing MCP servers running through ToolHive, and relies on ToolHive's authentication model for connected servers. + +### Adding MCP servers for testing + +Model Context Shell coordinates tools from other MCP servers running through ToolHive. To try it out, start a few servers: + +```bash +# See what's available in the registry +thv registry list + +# Run a simple fetch server (great for testing pipelines) +thv run fetch + +# Check what's running +thv list +``` + +You can also run servers from npm/PyPI packages directly: + +```bash +thv run npx://@modelcontextprotocol/server-everything +``` + +For servers that need credentials (e.g. GitHub), pass secrets via ToolHive: + +```bash +thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github +``` + +See the [ToolHive documentation](https://docs.stacklok.com/toolhive) for the full guide, including [CLI quickstart](https://docs.stacklok.com/toolhive/tutorials/quickstart-cli) and [available integrations](https://docs.stacklok.com/toolhive/integrations). ### Tips From ffe088a513eddb87b27f9ab7154dee0a1015e9ba Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Tue, 17 Feb 2026 15:56:04 +0100 Subject: [PATCH 4/5] . --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index d9dffd2..368f900 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ Setup · Security · Development · +RFC · Contributing

@@ -211,6 +212,12 @@ uv run ruff format --check . uv run pyright ``` +## RFC + +This project is both a working tech demo and an early-stage RFC for the concept of composable MCP tool pipelines. Rather than writing a detailed specification upfront, the goal is to gather feedback on the idea by providing something concrete to try. + +If you have thoughts on the approach, ideas for improvements, or use cases we haven't considered, please share them in the [Discussions](https://github.com/StacklokLabs/model-context-shell/discussions) section. + ## Contributing Contributions, ideas, and feedback are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, including our DCO sign-off requirement. From db0c838cbb3466203a5d9d11423e11a96151dca0 Mon Sep 17 00:00:00 2001 From: Daniel Kantor Date: Tue, 17 Feb 2026 16:04:46 +0100 Subject: [PATCH 5/5] . --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 368f900..835798b 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ Setup · Security · Development · +Specification · RFC · Contributing

@@ -212,6 +213,16 @@ uv run ruff format --check . uv run pyright ``` +## Specification + +For now, this project serves as a living specification — the implementation _is_ the spec. As the idea matures, a more formal specification may be extracted from it. + +**Execution model.** The current execution model is a scriptable map-reduce pipeline. Stages run sequentially, with `for_each` providing the map step over tool calls. This could be extended with a more generic mini-interpreter for evaluating more complex pipelines, but the current thinking is that it would never grow into a full-blown programming language. After a certain level of complexity, it makes more sense for agents to write a larger piece of code directly, or combine written code with the shell approach. That said, the built-in access to tools like `jq` and `awk` already makes the pipeline model surprisingly capable for most data transformation tasks. + +**Pipeline schema.** The pipeline format is defined by the `execute_pipeline` tool in [`main.py`](https://github.com/StacklokLabs/model-context-shell/blob/main/main.py). Since FastMCP generates the JSON Schema from the function signature and docstring, this serves as the canonical schema definition. + +**ToolHive and security.** The reliance on ToolHive and container isolation is a practical choice — it was the simplest way to get a working, secure system. ToolHive handles tool discovery, container management, and networking, which let this project focus on the pipeline execution model itself. A different deployment model could be used in the future without changing the core concept. + ## RFC This project is both a working tech demo and an early-stage RFC for the concept of composable MCP tool pipelines. Rather than writing a detailed specification upfront, the goal is to gather feedback on the idea by providing something concrete to try.