plumb-mcp - MCP server for plumbing programs

SYNOPSIS

plumb-mcp [--docroot dir] [--http port]

DESCRIPTION

plumb-mcp is a Model Context Protocol (MCP) server that exposes plumbing programs as tools. It supports two transports:

stdio (default): JSON-RPC 2.0 over standard input/output, one message per line. The client launches plumb-mcp as a subprocess.
HTTP (--http port): Streamable HTTP transport (MCP spec 2025-03-26). Listens on 127.0.0.1:port and serves a single /mcp endpoint. POST requests carry JSON-RPC messages; responses are application/json. GET and DELETE return 405.

Two tools are provided:

check: Type-check a plumbing program from source text. Returns success or a list of errors. No execution, no cost.
call: Execute a plumbing pipeline. Parses and type-checks the source, spawns the pipeline, feeds the input, returns the first output line, and tears everything down. One-shot semantics: one input, one output.

Programs submitted as source text may use use declarations to import modules. Bare imports (e.g. use fs) resolve against the --docroot directory first, then the standard library search path (PLUMB_PATH and installed directories).

OPTIONS

--docroot dir: Set the document root directory for builtin tools (read, write, edit, grep, list, delete, exec). When set, file-access tools are restricted to paths under dir.
--http port: Run the Streamable HTTP transport instead of stdio. Binds to 127.0.0.1:port. The server validates the Origin header on all requests to prevent DNS rebinding attacks: requests with an Origin whose host is not localhost, 127.0.0.1, or ::1 are rejected with 403. Requests without an Origin header (non-browser clients) are allowed.

TOOLS

check

Input:

{ "source": "id : !String → !String = id" }

Success response:

{ "ok": true }

Error response (type error, parse error):

isError: true, with error message in content

call

Input:

{ "source": "id : !String → !String = id",
  "input": "hello" }

Success response:

The pipeline's first output line, as text content.

Error response (parse error, type error, pipeline crash):

isError: true, with error message in content

CONFIGURATION

To use with Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "plumbing": {
      "command": "plumb-mcp",
      "args": ["--docroot", "/path/to/workspace"]
    }
  }
}

To use with Claude Code, add to .mcp.json in the project root:

{
  "mcpServers": {
    "plumbing": {
      "command": "plumb-mcp",
      "args": ["--docroot", "."]
    }
  }
}

ENVIRONMENT

PLUMB_PATH: Colon-separated list of directories to search when resolving bare use declarations. Searched before the installed standard library directories.
PLUMB_RESOURCES: Colon-separated list of directories to search when resolving bare prompt file names in agent configs. Searched before the installed resource directories.
PLUMB_PROVIDER: Default LLM provider for agents in called pipelines.
PLUMB_MODEL: Default model for agents in called pipelines.
ANTHROPIC_API_KEY: API key for agents using provider "anthropic".
OPENAI_API_KEY: API key for agents using provider "openai".
PIPELINE_DEBUG: Set to 1 to enable debug logging on stderr.

EXIT STATUS

0: Normal shutdown (client closed stdin, or HTTP server terminated).