test-server-mcp

MCP (Model Context Protocol) daemon for intelligent Vitest orchestration.

A single background daemon exposes an MCP server over loopback HTTP. AI agents (or CI) call its tools to run a project's Vitest suite intelligently — running only the tests affected by changed files (resolved via Vitest's own static import graph) and falling back to the full suite whenever selection is uncertain. Every run executes exactly one Vitest pass; coverage is available only on a full-suite run, from that same pass. Each project runs under its own Vitest in a dedicated worker subprocess; the daemon never imports a project's Vitest itself.

Features

• Incremental selection — run only tests affected by changed files, with a conservative full-suite fallback (never silently skips).

• Full-suite coverage — one native Vitest coverage pass, no separate measurement step.

• Watch mode — re-run affected tests as files change.

• Minimal output — failures first; full stacks fetched on demand.

• Human monitoring UI — a live status page at /ui.

Related MCP server: MCP RAG Agent Server

Quick start

pnpm install                 # install dependencies (pnpm only — never npm/yarn)
pnpm build                   # compile TypeScript to dist/
node ./bin/test-mcp.mjs link # put `test-mcp` on your PATH (optional, see below)

# From inside the project you want to orchestrate:
cd /path/to/your/project
test-mcp register

register scaffolds <git-root>/.test-mcp/, auto-boots the daemon, and registers the project with it — printing the projectId that MCP tool calls use. It also writes a test-mcp entry to .mcp.json and .cursor/mcp.json (creating or merging into either file, without touching other keys/servers) so your AI agent is connected with no extra step:

{
  "mcpServers": {
    "test-mcp": { "command": "test-mcp", "args": ["mcp-bridge"] }
  }
}

mcp-bridge is a local stdio process that reads the daemon's token itself and proxies to the HTTP endpoint — no token, env var, or path in the file, so both are safe to commit. It's a plain stdio server from the client's point of view, so the same entry works unmodified for Claude Code, Cursor, or any other MCP client. See docs/usage.md.

Connecting the MCP client only lets an agent call the tools — it doesn't tell the agent when to use them instead of pnpm test/vitest directly. For that, copy the snippet in docs/usage.md#agent-instructions into the project's own CLAUDE.md/AGENTS.md.

→ Full guide: docs/usage.md — CLI commands, the MCP tool catalog, watch mode, the monitoring UI, CI usage, configuration, and troubleshooting.

CLI

test-mcp start      # start the singleton daemon (idempotent)
test-mcp status     # running/stopped, pid, port, registered-project count
test-mcp stop       # graceful shutdown
test-mcp init       # scaffold <git-root>/.test-mcp/ without touching the daemon
test-mcp register   # scaffold + auto-boot daemon + register + write MCP client config
test-mcp mcp-bridge # stdio<->HTTP bridge; used by the .mcp.json / .cursor/mcp.json entry
test-mcp ui         # print the monitoring UI URL (http://127.0.0.1:<port>/ui)
test-mcp link       # symlink this CLI into a writable dir on your PATH
test-mcp unlink     # remove that symlink

Getting test-mcp on your PATH

test-mcp link symlinks the CLI into a writable directory already on your PATH (auto-detected — e.g. /opt/homebrew/bin — or pass --dir <dir>), so you can call test-mcp from anywhere. test-mcp unlink removes it (it only ever deletes its own symlink, never a real file). Until you link it, invoke the CLI as node ./bin/test-mcp.mjs.

Alternatively, use your package manager's linker: pnpm link --global (after a one-time pnpm setup) or npm link — both rely on the package's bin field.

Documentation

• Usage — how to build, run, and use it

• Architecture — components, contracts, invariants

• PRD — product requirements

• Patterns — validated implementation patterns

Development

pnpm typecheck      # tsc --noEmit
pnpm build          # compile to dist/
pnpm test           # vitest run (pretest builds first)
pnpm test:watch     # vitest in watch mode

Working on test-mcp? See CONTRIBUTING.md for the dev/BMAD workflow and the optional code-review-graph code-intelligence setup. (That tooling is for contributors only — it's not needed to use test-mcp.)