pipen-mcp 0.2.0

A pipen CLI plugin that exposes pipen processes and pipelines as MCP (Model Context Protocol) tools, allowing AI assistants to discover and run bioinformatics pipelines.

---

Overview

pipen-mcp bridges pipen's process/pipeline ecosystem with AI assistants that support the Model Context Protocol. Once installed, any namespace registered via the pipen_cli_run entry point group is automatically discoverable and executable by an MCP-compatible client (e.g., Claude, VS Code Copilot, Cursor).

Installation

pip install pipen-mcp

pipen-mcp requires Python ≥ 3.10 and depends on:

• pipen-cli-run ≥ 1.0.1
• pipen-annotate ≥ 1.0
• mcp[cli] ≥ 2.0

Usage

pipen-mcp adds an mcp subcommand to the pipen CLI:

pipen mcp [--transport {stdio,sse,streamable-http}] [--host HOST] [--port PORT]

Option	Description	Default
--transport	MCP transport (stdio, sse, or streamable-http)	stdio
--host	Host to bind to (SSE / streamable-http only)	127.0.0.1
--port	Port to listen on (SSE / streamable-http only)	8520

stdio (default)

Suitable for direct integration with MCP clients that launch the server as a subprocess:

pipen mcp

SSE

Starts an HTTP server with Server-Sent Events transport:

pipen mcp --transport sse --host 0.0.0.0 --port 8520

Streamable HTTP

Starts an HTTP server with the streamable-HTTP transport:

pipen mcp --transport streamable-http --host 0.0.0.0 --port 8520

MCP Tools

The server exposes four tools that support a progressive-disclosure workflow:

Tool	Description
get_namespaces	List all available namespaces. Start here to discover what is installed.
get_processes	List all processes/pipelines available in a namespace.
get_process	Get the full argument schema for a specific process/pipeline.
run_process	Execute a process/pipeline with a list of CLI arguments.

Typical workflow

1. get_namespaces()
   → "delim", "bam", "rnaseq", ...

2. get_processes("delim")
   → RowsBinder (proc): Bind rows of input files
   → ColsBinder (proc): Bind columns of input files

3. get_process("delim", "RowsBinder")
   → Required:
       --in.infiles <list[str]>  Input files
   → Optional:
       --envs.sep <str> (default: '\t')  Separator
       --outdir <str>  Output directory
       ...

4. run_process("delim", "RowsBinder", [
       "--in.infiles", "/tmp/a.csv,/tmp/b.csv",
       "--envs.sep", ",",
       "--outdir", "/tmp/out"
   ])
   → Pipeline output / logs

Machine-usable argument schema

get_process keeps the rendering above as its text content and, in addition, returns the same information as structured content (structuredContent) whose JSON schema is advertised as the tool's outputSchema, so a client can validate arguments before calling run_process:

{
  "text": "Process: RowsBinder  (namespace: delim)\n...",
  "argument_schema": {
    "ns": "delim",
    "proc": "RowsBinder",
    "kind": "proc",
    "description": "Bind rows of input files",
    "source": "pipen-args",
    "flatten_proc_args": true,
    "processes": ["RowsBinder"],
    "arguments": [
      {
        "flag": "--in.infiles",
        "aliases": [],
        "dest": "in.infiles",
        "type": "file",
        "type_source": "declaration",
        "cli_type": "list[str]",
        "required": true,
        "has_default": false,
        "default": null,
        "description": "Input files",
        "group": "in",
        "proc": "RowsBinder",
        "action": "ExtendAction",
        "nargs": "+",
        "choices": null
      }
    ]
  },
  "error": null
}

Per argument the schema carries the flag, its type (taken from the process's own input/output/envs declarations when they declare one, otherwise the CLI type), whether it is required, its default when one exists, the docstring description and the group it belongs to: in, envs, out or pipeline for pipeline-level arguments.

The schema is read off the argx parser objects pipen-args builds for pipen run <ns> <proc> — the same objects that render pipen run <ns> <proc> -h+ — so it cannot drift from the command line that run_process executes.

VS Code / Copilot Integration

Add the server to your MCP configuration (~/.vscode/mcp.json or ~/.vscode-server/data/User/mcp.json):

{
  "servers": {
    "pipen-mcp": {
      "type": "stdio",
      "command": "pipen",
      "args": ["mcp"]
    }
  }
}

Or for SSE:

{
  "servers": {
    "pipen-mcp": {
      "type": "sse",
      "url": "http://127.0.0.1:8520/sse"
    }
  }
}

Authoring a Namespace

Any package can register processes/pipelines with pipen-mcp by declaring a pipen_cli_run entry point:

# pyproject.toml
[project.entry-points."pipen_cli_run"]
myns = "mypackage.ns.myns"

The referenced module should contain Proc subclasses (with an input attribute) or ProcGroup subclasses. Use pipen-annotate to document arguments — annotated fields are exposed in get_process output and used to build the tool schema.

# mypackage/ns/myns.py
"""My namespace — tools for processing text files."""
from pipen import Proc
from pipen_annotate import annotate

@annotate
class MyProc(Proc):
    """Concatenate rows from multiple files.

    Input:
        infiles (list): Input files to concatenate

    Envs:
        sep (str): Column separator. Default: ","
    """
    input = "infiles:files"
    output = "outfile:file:{{in.infiles[0] | stem}}_concat.tsv"
    script = "..."

License

MIT