convez.ai
MCP ServerDevOps & InfraestruturaAvançado
thebtf

MCP Launcher

thebtf/mcp-launcher

Teste servidores MCP stdio com um cliente real em tempo real

Ver no GitHub
InicialPluginScore · de 0 a 100

CLI em Go para testar servidores MCP stdio sem abrir um cliente de IA completo. Inicia um servidor como subprocesso, realiza o fluxo MCP initialize e permite probar ferramentas, recursos, reinicializações, reconexões e atualizações de binários pela linha de comando.

Instalação

$npx convez-ai thebtf/mcp-launcher

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 5 meses
Versão
v0.3.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Reproduzir falhas de handoff de reinicialização com proprietário de subprocesso real
  • Verificar que tools/call e resources/read funcionam após inicialização
  • Exercitar soquetes de controle daemon enquanto cliente stdio está conectado
  • Auditoria de compatibilidade MCP separando comportamento genérico de envelopes específicos

Veredito

Ferramenta essencial para desenvolvedores de servidores MCP que precisam testar comportamento real sob pressão de cliente stdio. Elimina diferenças entre testes unitários e clientes reais com zero dependências Go.

README

A tradução para o português deste README ainda está na fila.

mcp-launcher

CI Go Reference Go Report Card License: MIT 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 that still preserves lifecycle-critical EOF policy when set.
  • Run a profile-aware compatibility audit that separates generic MCP behavior from Claude Code-style and Codex-style launch envelopes.

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

ModeWhat it does
holdStarts the server, completes MCP initialization, and keeps the session open for external testing.
callCalls any JSON-RPC method after initialization.
toolCalls an MCP tool through tools/call.
resourceReads an MCP resource through resources/read.
installCalls the server's upgrade tool with a local source binary, closes stdio, reconnects, and verifies health.
testStarts a daemon, connects one owner session, sends one graceful restart over the control socket, and checks the successor daemon.
phase2Runs two graceful restarts: original daemon, then successor daemon. Useful for handoff deadlock repros.
persistVerifies that a daemon survives stdio disconnect and that the next session reuses the same daemon PID.
kill-reconnectHard-kills the daemon, closes stdio, then measures new-session recovery time.
compatRuns a profile-aware MCP stdio compatibility audit and optionally writes a JSON report.

Flags

FlagDefaultDescription
-binaryrequiredMCP server executable path.
-cwd.Working directory for the subprocess.
-modeholdOne of hold, call, tool, resource, install, test, phase2, persist, kill-reconnect, or compat.
-hold300Seconds to keep the session open in hold mode.
-watch60Seconds to watch daemon liveness after disconnect in persist mode.
-ctlemptyDaemon control socket path. Required for test, phase2, persist, and kill-reconnect.
-daemon-flag--muxcore-daemonFlag used to start the target server in daemon mode.
-env-modefullfull passes the parent environment; clean forwards a platform allow-list and preserves aimux/muxcore smoke contract variables when set.
-timeout120MCP request timeout in seconds, including initialize and tools/list.
-compat-levelstandardCompatibility audit breadth: smoke, standard, lifecycle, or maximum.
-compat-profilesgeneric,claude-code,codexComma-separated profiles for compat: generic, claude-code, codex, fixture, openclaw-registry, or hermes. Reserved profiles return evidence-needed results until backed by docs or traces.
-compat-reportemptyWrites the compatibility audit JSON report to the provided path.
-expect-tools0Expected tools/list count after session init. 0 disables the check.
-expect-versionemptyExpected MCP serverInfo.version after session init.
-methodemptyJSON-RPC method for call mode.
-params{}JSON params for call mode.
-toolemptyMCP tool name for tool mode.
-args{}JSON object arguments for tool mode.
-uriemptyMCP resource URI for resource mode.
-sourceemptyLocal source binary for install mode.
-forcefalseSends force=true to upgrade(action=apply) in install mode.
-upgrade-modeautoUpgrade mode passed to the server: auto, hot_swap, or deferred.
-install-validationreplacementInstall proof strategy: replacement waits for -binary to change when a post-exit install is scheduled; active-pointer waits for an active pointer file to change and then verifies reconnect health/version.
-active-engine-fileemptyActive pointer file for -install-validation active-pointer; defaults to MCPMUX_ACTIVE_ENGINE_FILE.
-reconnect-delay2Initial/retry delay for install reconnect verification. Explicit values override the automatic post-exit reconnect delay, not replacement detection.
-cleanup-binary-processesfalseAfter 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

Run a compatibility audit

mcp-launcher \
  -binary ./my-mcp-server \
  -mode compat \
  -compat-level standard \
  -compat-report compat-report.json

The default audit runs generic, claude-code, and codex profiles. Results stay separated so a server can pass generic MCP checks while a named host envelope reports FAIL, BLOCKED, or UNSUPPORTED.

Compatibility levels are cumulative:

LevelUse when
smokeYou only need startup and MCP initialize proof.
standardYou want the default local compatibility matrix.
lifecycleYou also want lifecycle checks that need -ctl. Missing inputs are BLOCKED.
maximumYou want all currently known checks, including install-source prerequisites. Missing inputs are BLOCKED.

Reserved profiles such as fixture, openclaw-registry, and hermes do not guess behavior. They return an evidence-needed result until primary docs or a captured fixture trace exists.

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

By default, 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.

For muxcore active-pointer/successor installs where the stable -binary path is intentionally not replaced, use active-pointer validation:

mcp-launcher \
  -binary ./my-server-current.exe \
  -cwd /path/to/server/project \
  -mode install \
  -source ./my-server-next.exe \
  -force \
  -install-validation active-pointer \
  -active-engine-file ./active.txt \
  -expect-version 1.2.3

Active-pointer validation reads the pointer before upgrade, waits for it to change after handoff, then treats reconnect health, tool count, and expected version as the install proof. With -env-mode clean, the launcher still preserves aimux/muxcore smoke contract variables from the parent environment, including AIMUX_STDIN_EOF_POLICY and MCPMUX_ACTIVE_ENGINE_FILE.

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, install_reconnect_test.go, and env_test.go cover client cleanup on tool errors, Windows PID fallback cleanup, clean environment preservation, 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.

Ver o original no GitHub

Bom para

Relacionados