mcp-launcher

command module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 15, 2026 License: MIT Imports: 17 Imported by: 0

README

mcp-launcher

CI Go Reference Go Report Card Platform

mcp-launcher is a zero-dependency Go CLI for exercising stdio MCP servers without opening a full AI client. It starts a target server as a subprocess, performs the MCP initialize flow, keeps a real stdio owner alive, and can probe tools, resources, daemon restarts, reconnects, and binary upgrade paths from the command line.

Use it when a server behaves differently under a real stdio client than it does under a hand-written unit test.

Quick Start

Install with Go:

go install github.com/thebtf/mcp-launcher@latest

Or build from source:

git clone https://github.com/thebtf/mcp-launcher.git
cd mcp-launcher
go test ./...
go build .

Start a live MCP stdio session against your server:

mcp-launcher -binary ./my-mcp-server -mode hold -hold 600

Call a tool and print both the raw MCP response and decoded text payload:

mcp-launcher \
  -binary ./my-mcp-server \
  -mode tool \
  -tool sessions \
  -args '{"action":"health"}'

Read an MCP resource:

mcp-launcher \
  -binary ./my-mcp-server \
  -mode resource \
  -uri my-server://health

Why This Exists

Manual server launches hide client lifecycle bugs. A real stdio MCP client owns stdin, reads stdout line-by-line, handles notifications while waiting for responses, sends notifications/initialized, and may disconnect or reconnect at awkward times.

mcp-launcher gives you that pressure without the rest of an AI application:

  • Reproduce restart handoff failures with an actual subprocess owner.
  • Verify that tools/list, tools/call, and resources/read work after the initialize handshake.
  • Exercise daemon control sockets while the stdio client is still connected.
  • Check that deferred binary installs become visible before reconnect verification starts.
  • Switch between full inherited environment and a clean allow-list environment.

Requirements

  • Go 1.22 or newer.
  • A target MCP stdio server binary.
  • No runtime dependencies beyond the Go standard library.
  • A daemon control socket only for test, phase2, persist, and kill-reconnect modes.

Windows, macOS, and Linux are supported for stdio launch flows. The -cleanup-binary-processes helper is Windows-only.

Commands

mcp-launcher -binary <server> [options] [-- extra server args...]
Modes
Mode What it does
hold Starts the server, completes MCP initialization, and keeps the session open for external testing.
call Calls any JSON-RPC method after initialization.
tool Calls an MCP tool through tools/call.
resource Reads an MCP resource through resources/read.
install Calls the server's upgrade tool with a local source binary, closes stdio, reconnects, and verifies health.
test Starts a daemon, connects one owner session, sends one graceful restart over the control socket, and checks the successor daemon.
phase2 Runs two graceful restarts: original daemon, then successor daemon. Useful for handoff deadlock repros.
persist Verifies that a daemon survives stdio disconnect and that the next session reuses the same daemon PID.
kill-reconnect Hard-kills the daemon, closes stdio, then measures new-session recovery time.
Flags
Flag Default Description
-binary required MCP server executable path.
-cwd . Working directory for the subprocess.
-mode hold One of hold, call, tool, resource, install, test, phase2, persist, or kill-reconnect.
-hold 300 Seconds to keep the session open in hold mode.
-watch 60 Seconds to watch daemon liveness after disconnect in persist mode.
-ctl empty Daemon control socket path. Required for test, phase2, persist, and kill-reconnect.
-daemon-flag --muxcore-daemon Flag used to start the target server in daemon mode.
-env-mode full full passes the parent environment; clean forwards a platform allow-list.
-timeout 120 MCP request timeout in seconds, including initialize and tools/list.
-expect-tools 0 Expected tools/list count after session init. 0 disables the check.
-expect-version empty Expected MCP serverInfo.version after session init.
-method empty JSON-RPC method for call mode.
-params {} JSON params for call mode.
-tool empty MCP tool name for tool mode.
-args {} JSON object arguments for tool mode.
-uri empty MCP resource URI for resource mode.
-source empty Local source binary for install mode.
-force false Sends force=true to upgrade(action=apply) in install mode.
-upgrade-mode auto Upgrade mode passed to the server: auto, hot_swap, or deferred.
-reconnect-delay 2 Initial/retry delay for install reconnect verification. Explicit values override automatic post-exit waiting.
-cleanup-binary-processes false After a one-shot mode, kill remaining Windows processes with the same image name as -binary. Use only with unique smoke-test binary names.

Everything after -- is forwarded to the target server:

mcp-launcher -binary ./my-mcp-server -mode hold -- --config ./dev.json

Common Workflows

Keep a real owner session alive
mcp-launcher -binary ./my-mcp-server -mode hold -hold 600

This is the simplest way to keep stdin/stdout ownership active while another tool triggers a restart or inspects daemon state.

Probe a tool
mcp-launcher \
  -binary ./my-mcp-server \
  -mode tool \
  -tool sessions \
  -args '{"action":"health"}' \
  -expect-tools 27

-expect-tools turns the post-initialize tools/list count into an assertion.

Probe a resource
mcp-launcher \
  -binary ./my-mcp-server \
  -mode resource \
  -uri my-server://health
Verify a deferred binary install
mcp-launcher \
  -binary ./my-server-current.exe \
  -cwd /path/to/server/project \
  -mode install \
  -source ./my-server-next.exe \
  -force \
  -upgrade-mode auto \
  -expect-version 1.2.3

install mode fingerprints the installed binary, calls upgrade, closes the install session, waits for post-exit replacement when the payload or disconnect indicates one is scheduled, reconnects, calls sessions(action="health"), and tries to read aimux://health when that resource exists.

Verify daemon persistence across stdio disconnect
mcp-launcher \
  -binary ./my-server \
  -mode persist \
  -ctl /tmp/my-server.ctl.sock \
  -watch 60

PASS means the daemon PID stayed alive for the full watch window and the second session reattached to the same PID.

Architecture Overview

flowchart LR
    CLI["mcp-launcher CLI"]
    Client["mcpClient"]
    Server["Target MCP stdio server"]
    Control["Daemon control socket"]
    Modes["Mode runner"]

    CLI --> Modes
    Modes --> Client
    Client -- stdin JSON-RPC --> Server
    Server -- stdout JSON-RPC --> Client
    Modes -- status / graceful-restart --> Control
    Control --> Server

The project is intentionally small:

  • main.go contains the CLI, stdio JSON-RPC client, daemon control socket client, mode runners, install reconnect logic, and cleanup helpers.
  • mcpClient starts the target subprocess, writes JSON-RPC requests to stdin, reads newline-delimited JSON-RPC from stdout, routes responses by request ID, and collects notifications separately.
  • controlSend talks to a raw Unix domain control socket for daemon status and graceful restart commands.
  • main_test.go and install_reconnect_test.go cover client cleanup on tool errors, Windows PID fallback cleanup, install reconnect delay decisions, post-exit install detection, replacement waiting, and binary fingerprinting.

MCP Session Flow

Each session follows this sequence before the selected mode does its work:

launcher -> server: initialize
server   -> launcher: initialize result with serverInfo
launcher -> server: notifications/initialized
launcher -> server: tools/list
server   -> launcher: tools/list result

After that, mode-specific work runs against the same live subprocess session.

Troubleshooting

error: -binary is required

Symptom: The launcher exits immediately with usage text.

Cause: -binary is the only required flag for every mode.

Fix: Pass the target MCP stdio server executable:

mcp-launcher -binary ./my-mcp-server -mode hold

Verify: The output includes spawn, pid=, initialize, and tools.

error: -ctl is required

Symptom: test, phase2, persist, or kill-reconnect exits before starting.

Cause: Those modes need the daemon control socket.

Fix: Pass the socket path used by your daemon:

mcp-launcher -binary ./my-mcp-server -mode phase2 -ctl /tmp/my-server.ctl.sock

Verify: The mode can print daemon status or restart results.

timeout waiting for initialize or timeout waiting for tools/list

Symptom: The subprocess starts, but the launcher times out during bootstrap.

Cause: The target server did not emit a JSON-RPC response on stdout before the timeout.

Fix: Run the target binary directly and check that stdout is reserved for MCP JSON-RPC. Logs should go to stderr. Increase -timeout only after checking that the server is actually starting.

Verify: mcp-launcher -binary ./my-mcp-server -mode hold -timeout 120 prints an initialize result and a tools count.

Install mode reconnects too early

Symptom: install mode reports that reconnect verification failed after an upgrade that schedules replacement after process exit.

Cause: The old process may need time to exit and replace the installed binary.

Fix: Let the automatic post-exit wait run, or choose an explicit delay:

mcp-launcher \
  -binary ./my-server-current.exe \
  -mode install \
  -source ./my-server-next.exe \
  -reconnect-delay 15

Verify: The output shows either installed binary changed or a successful sessions health payload.

cleanup-binary-processes removed the wrong process

Symptom: A process with the same executable name as the smoke binary was terminated.

Cause: Cleanup matches by image name on Windows.

Fix: Use -cleanup-binary-processes only with unique disposable binary copies, such as my-server-smoke-current.exe.

Verify: No unrelated process shares the same image name before enabling the flag.

Development

go test ./...
go vet .
go build .

The module has no third-party dependencies. See CONTRIBUTING.md for the contributor workflow.

Repository Setup Notes

Suggested GitHub description:

MCP stdio launcher for restart, reconnect, resource, tool, and upgrade smoke tests.

Suggested topics:

mcp, model-context-protocol, go, cli, devtools, testing, stdio, json-rpc, graceful-restart, smoke-testing

License

MIT. See LICENSE.

Documentation

Overview

mcp-launcher emulates how Claude Code and Codex spawn MCP servers as stdio subprocesses. Use it to test graceful restart, hot-swap handoff, session lifecycle, and MCP protocol compliance without a live AI client.

Modes:

hold   — spawn server, hold session open for external testing (default)
call   — call any JSON-RPC method after MCP initialize
tool   — call any MCP tool by name with JSON arguments
resource — read any MCP resource by URI
install — install a local binary through the server's upgrade tool, then reconnect and verify health
test   — single-phase: daemon + owner + graceful-restart + verify
phase2 — two-phase: bootstrap + restart on successor (deadlock reproducer)
persist — verify daemon survives stdio disconnect and reconnect
kill-reconnect — hard-kill daemon and measure new-session recovery

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL