All servers / Developer / Vitest Agent MCP server
Vitest Agent MCP server
Model Context Protocol server for vitest-agent. Exposes 30 tools for agent access to test data, TDD lifecycle, and session management.
Tested by ConnectATDScore 89 out of 100. Tested 2026-11-18 on package version 6.1.11. Package: @vitest-agent/mcp · source
Score breakdown
| Runs | 18 / 20 | |
|---|---|---|
| Tool descriptions | 19 / 20 | |
| Package safety | 20 / 20 | |
| Maintenance | 20 / 20 | |
| Adoption | 12 / 20 |
What we saw
- Starts and answers the MCP handshake: yes (22.6 seconds including download)
- Tools offered: 30
- Last published: 2026-11-16
- Weekly downloads (npm): 2,569
- License: MIT · Direct dependencies: 10
Want this server set up for your team?
ConnectATD builds AI automation and wires up MCP servers like this one. Tell us what you are trying to do.
Talk to ConnectATDTools and how they are described
Agents choose tools from these descriptions. Under each name you can see how many of its parameters are explained.
pingno parametersPing the MCP server — returns 'pong' and the distribution (carrier package) it was launched through. Used to verify hot-patch reload.
helpno parametersList all available MCP tools with parameters. The markdown reference is in structuredContent.helpText.
test_status1 of 1 parameter describedUse when you need each project's current pass/fail state from the most recent run. Returns a typed JSON object in structuredContent ({ dataAvailable, manifestUpdatedAt, projectFilter?, entries[] } or absent variant); an entry carries strayOutput when the project's latest run wrote straight to the terminal.
test_overview1 of 1 parameter describedUse when you want a summary of the test landscape with per-project run metrics. Returns a typed JSON object in structuredContent ({ dataAvailable, projectFilter?, runs[] } or absent variant).
test_coverage1 of 1 parameter describedUse when coverage drops and you need per-metric gap analysis against thresholds and targets. Returns a typed JSON object in structuredContent ({ dataAvailable, project, coverage } or absent variant).
test_history4 of 4 parameters describedUse when failures recur and you need flaky, persistent, and recovered test classifications. Returns a typed JSON object in structuredContent (project, hasData, history, flaky[], persistent[], recovered[], strayOutput: how many of the last 10 runs wrote straight to the terminal). Optional testName/modulePath narrow to a single test; limit caps runs kept per test (default 20) — omit all three only when you actually need the whole project's history.
test_trends2 of 2 parameters describedUse when you want to see whether a project's coverage is trending up or down over time. Returns a typed JSON object in structuredContent ({ dataAvailable, project, trends? }).
test_errors2 of 2 parameters describedUse when a test fails and you need error detail, diffs, and the cite-able test_errors.id / stack_frames.id values needed by hypothesis (action: record). Returns a typed JSON object in structuredContent; read structuredContent.errors[].
file_coverage2 of 2 parameters describedUse when you need coverage for one source file: per-metric values, uncovered lines, and related tests. Returns a typed JSON object in structuredContent ({ dataAvailable, matched?, filePath, report?, totals?, relatedTestFiles[] }).
settings_listno parametersUse when you need every captured settings snapshot and its hash. Returns a typed JSON object in structuredContent ({ count, settings[] }).
cache_healthno parametersUse when you suspect stale data and need manifest presence, project states, and staleness. Returns a typed JSON object in structuredContent ({ manifestPresent, manifest?, ageMs?, stale? }).
configure1 of 1 parameter describedUse when you need the captured Vitest settings for a test run. Returns a typed JSON object in structuredContent ({ found, source, settings?, requestedHash? }).
commit_changes1 of 1 parameter describedUse when you need commit metadata and changed files captured by the post-commit hook. Returns up to 20 most-recent when sha is omitted. Returns a typed JSON object in structuredContent ({ filterSha?, count, commits[] }).
turn_search4 of 4 parameters describedUse when you need to find past turns across sessions by type, time, or session. Returns a typed JSON object in structuredContent ({ count, turns[] }).
failure_signature_get1 of 1 parameter describedUse when you have a failure-signature hash and need its first-seen date and occurrence history. Returns a typed JSON object in structuredContent ({ found, signatureHash?, firstSeenAt?, occurrenceCount?, recentErrors?[] } or absent variant).
acceptance_metricsno parametersUse when you need the four spec Annex A acceptance metrics computed from the current database. Returns a typed JSON object in structuredContent (per-metric { total, ratio, ... }).
triage_brief2 of 2 parameters describedUse when you need to orient on the current test landscape: failing tests, flaky tests, runs that wrote stray output past Vitest's console capture, open TDD sessions, and suggested next actions. Returns a typed envelope in structuredContent ({ hasContent, markdown }).
wrapup_prompt4 of 4 parameters describedUse when a session is ending and you need a tailored wrap-up prompt (Stop / SessionEnd / PreCompact / TDD handoff / UserPromptSubmit nudge variants). Returns a typed envelope in structuredContent ({ hasContent, kind, markdown }).
inventoryno parametersUse to discover what exists in the workspace, with a kind discriminator: project / module / suite / session / tag. structuredContent discriminates on `inventoryKind` (project, module, suite, session_detail, session_list, tag_scoped, tag_unscoped) so callers can branch on the response shape without parsing markdown.
testno parametersUse to inspect tests, with an action discriminator: action='list' (project?, state?, module?, limit?) returns matching tests; action='get' (fullName, project?, modulePath?) returns details + errors + run history — a fullName that exists in more than one module returns found=false with ambiguous=true and candidateModules[], so pass modulePath to disambiguate; action='for_file' (filePath) returns test modules covering a source file; action='for_tag' (tag, project?) returns tests carrying a tag, grouped by project; action='annotations' (fullName, project?, modulePath?) returns the test annotations the author recorded via context.annotate; action='artifacts' (fullName, project?, modulePath?) returns the test artifacts recorded for the test — both return attachment descriptors (contentType, path, byteSize) and omit inline bodies unless maxBytes (a non-negative integer byte budget for the whole response, default 0) is passed, and neither has anything to do with TDD artifacts (see tdd_artifact_list). structuredContent carries the typed payload (discriminate on `action`, then on `found` for get).
register_agent6 of 9 parameters describedUse when an LLM-agent invocation starts and must be recorded in the per-project store. Idempotent on (chatId, agentType, parentAgentId, clientNonce). Returns ok:true with agentId on insert, or ok:false with error.code='AGENT_ALREADY_REGISTERED'/'PARENT_AGENT_NOT_FOUND'/'SESSION_NOT_FOUND'/'INVALID_AGENT_TYPE_PREFIX' on the four documented failure modes. agentType must begin with the host-kind prefix (e.g., 'claude-code-main').
noteno parametersUse to manage notes, with a CRUD action discriminator: action='create' writes a scoped note; action='list' (scope?, project?, testFullName?) returns matching notes; action='get' (id) returns a structured note; action='update' (id, ...patch) edits; action='delete' (id) removes; action='search' (query) does FTS5 across title and content. structuredContent always carries the typed result (discriminate on `action`).
hypothesisno parametersUse to manage debugging hypotheses, with a CRUD action discriminator: action='record' (content, tddTaskId?, optional citation ids) writes a hypothesis — the binding session is resolved server-side from the recovered host context (active TDD subagent, else main session); pass tddTaskId (returned by tdd_task action='start') to bind deterministically to that task's session, and do not pass sessionId when recording; action='validate' (id, outcome, validatedAt?) records a validation outcome — validatedAt is optional and defaults server-side to now when omitted, or is honored verbatim when supplied; action='list' (sessionId?, outcome?, limit?) returns matching hypotheses.
tdd_taskno parametersUse to manage a TDD task lifecycle, with an action discriminator: action='start' (goal, sessionId|chatId, parentTddTaskId?, startedAt?, runId?) opens a new task; action='end' (tddTaskId, outcome, summaryNoteId?) closes one; action='get' (tddTaskId) returns the full task detail; action='resume' (tddTaskId) returns a compact digest.
tdd_phase_transition_request7 of 7 parameters describedUse when advancing a TDD cycle and you need a phase transition validated and recorded. Validates goal status, behavior↔goal membership, and D2 artifact-evidence binding rules; returns accept/deny. On accept, auto-promotes a behavior 'pending' → 'in_progress' when behaviorId is supplied. citedArtifactId is OPTIONAL — when omitted, the most recent matching artifact is auto-resolved (kind comes from citedArtifactKind if supplied, otherwise from the transition's required-evidence rule). Transitions like spike→red that require no artifact need neither field. The accepted response echoes citedArtifactId + citedArtifactSource so the caller can see which row was picked.
tdd_goalno parametersUse to manage TDD goals, with a CRUD action discriminator: action='create' (tddTaskId, goal) is idempotent on (tddTaskId, goal); action='update' (id, goal?, status?) edits text and/or lifecycle status; action='delete' (id) hard-deletes (prefer status:'abandoned'); action='get' (id) reads with nested behaviors; action='list' (tddTaskId) returns all goals for a TDD task.
tdd_behaviorno parametersUse to manage TDD behaviors, with a CRUD action discriminator: action='create' (goalId, behavior, suggestedTestName?, dependsOnBehaviorIds?) is idempotent on (goalId, behavior); action='update' (id, ...patch) edits; action='delete' (id) hard-deletes; action='get' (id) reads; action='list_by_goal' (goalId) lists one goal's behaviors; action='list_by_tdd_task' (tddTaskId) lists across all goals.
tdd_artifact_list5 of 5 parameters describedUse when you need the artifact id to cite in tdd_phase_transition_request without querying SQLite directly. Lists TDD artifacts (test_written, test_failed_run, code_written, test_passed_run, refactor, test_weakened) for a tdd_task, newest first. Filters: artifactKind, phaseId, behaviorId, limit (default 50).
tdd_progress_push1 of 1 parameter describedUse when a TDD orchestrator needs to report progress to the main agent over a Claude Code channel. The MCP server validates the payload against the ChannelEvent union and resolves goalId/sessionId server-side from behaviorId for behavior-scoped events (so a stale orchestrator context cannot push the wrong tree coordinates). Best-effort — returns { ok: true } regardless of whether channels are active.
run_tests7 of 8 parameters describedUse to run Vitest tests, with optional file, project, and tag filters. structuredContent carries the typed AgentReport plus per-test classifications (discriminate on `kind`: ok, timeout, error, no-match). Unknown parameters are rejected — accepted keys are files, project, tags, passWithNoTests, timeout, projectRoot. When projectRoot is omitted, the server anchors the Vitest root at the directory of the vitest (or vite) config Vitest would load anyway, walking up from its boot dir and stopping at the git root — so a server booted inside a package subtree still resolves the root config's relative globalSetup/setupFiles correctly. projectRoot overrides that for this call and is used verbatim, but only after validation: it must be an existing directory belonging to the same git repository as ctx.cwd (checked via `git rev-parse --path-format=absolute --git-common-dir`, which needs git 2.31 or newer and is identical across a repo and all its worktrees, including a sibling worktree checked out from the same repo). A path in a different repository, or a non-existent path, is rejected with `{ kind: "error" }` naming both paths — never a silent fallback to ctx.cwd. The resolved root actually used is always echoed back on success. When the plugin hook supplies the caller working directory (the hook-injected _callerCwd), a call from a different working tree of the same repository than the resolved root is refused with `{ kind: "error" }` naming both trees; pass projectRoot (your own worktree path) to run there. An absent or indeterminate caller directory never refuses. An error result with `reason: "stale-install"` means the vitest install was replaced under this long-lived server (the lockfile was regenerated) and the resolved vitest/node entry is gone; restart the MCP server (/mcp in Claude Code) rather than retrying. The legacy format=json arg is dropped — structuredContent supersedes it.
Tested in a sandbox with an empty environment: no API keys, a throwaway folder, nothing from a real account. A passing test shows the server runs and responds. It is not a security audit.