Running a test server

test-servers/ provides composable MCP servers so tests and manual checks exercise a real server over a real transport instead of mocks. A server is assembled from presets (fixture factories in test-servers/src/preset-registry.ts) and configured declaratively with a JSON file under test-servers/configs/.

The full catalogue of showcase configs, one per feature, each with what to click and what the broken build did, is docs/test-servers.md. This skill is how to run one.

Three ways to use a fixture, pick the right one first

A fixture is stood up in one of three shapes, and most of what follows is about the third. Establish which one you are in before reading further, because the showcase config file and the protocol-era table belong to that one alone.

⚠️ The cut is how the server is stood up, not who is driving. Automated and by-hand is the wrong axis: the composable-config shape has both kinds of consumer, and a smoke that spawns it needs every bit of the config and era guidance a person at two terminals does.

Shape	Server runs	Config file	Consumers
In-process HTTP	inside the test process, built from the API	none, options are constructor args	integration tests, CLI tests, smoke:cli
Spawned stdio	a child process the transport (or the binary under test) starts	none, the stdio fixture runs its default config	integration tests, the CLI suites, smoke:cli, smoke:tui
Spawned composable HTTP	a child process started with --config	yes, a showcase --config <name>.json	the web smokes, pack:verify, and a person by hand

⚠️ "A smoke" is not a shape, smoke:cli uses the first two and smoke:tui the second, while only the config-driven web smokes use the third. Pick by the row, never by the caller's category.