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 · +Setup · +Security · +Development · +Specification · +RFC · +Contributing +
## Introduction @@ -132,7 +139,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 @@ -175,6 +213,22 @@ 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. + +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.