@vitest-agent/mcp
Installed, started with no arguments, no environment and no input, and listed its tools. Run 2026-11-16.
Needs to start: nothing
Returns a result when called with no setup: 5 of 5 tools tried
Contacts while installing and starting: nothing
What it contacted
Nothing besides the npm registry it was installed from. Watched from outside its sandbox while it was installed and started with no input. Its tools may still contact things when called.
Starting it
npx -y @vitest-agent/mcp@6.1.10
Installing a package runs its code. Use a sandbox for anything you have not read.
Calling its tools
5 tools that take no input and look read-only were called once with nothing. 5 returned a result.
ping | Returned a result under 0.1 s · 38 characters |
help | Returned a result under 0.1 s · 9,496 characters |
test_status | Returned a result under 0.1 s · 46 characters |
test_overview | Returned a result under 0.1 s · 42 characters |
settings_list | Returned a result under 0.1 s · 25 characters |
During the calls it contacted nothing it had not already contacted.
Only tools whose names read like looking something up, with no required input, are tried, five at most. Tools that need input, and anything that sounds like it changes or sends something, are not called.
What its tools tell an agent
In the tool descriptions, nothing that talks about the user, other tools or private files, or uses hidden characters.
Found by simple pattern rules in each tool's description (up to 3,000 characters), quoted as written. Parameter descriptions are not scanned. A clean result is not a safety review.
Tools
ping
Ping the MCP server — returns 'pong' and the distribution (carrier package) it was launched through. Used to verify hot-patch reload.
help
List all available MCP tools with parameters. The markdown reference is in structuredContent.helpText.
test_status project
Use 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_overview project
Use 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_coverage project
Use 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).25 more tools
test_history project, testName, modulePath, limit
Use 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_trends project, limit
Use 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_errors project, errorName
Use 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_coverage filePath, project
Use 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_list
Use when you need every captured settings snapshot and its hash. Returns a typed JSON object in structuredContent ({ count, settings[] }).cache_health
Use when you suspect stale data and need manifest presence, project states, and staleness. Returns a typed JSON object in structuredContent ({ manifestPresent, manifest?, ageMs?, stale? }).configure settingsHash
Use when you need the captured Vitest settings for a test run. Returns a typed JSON object in structuredContent ({ found, source, settings?, requestedHash? }).commit_changes sha
Use 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_search sessionId, since, type, limit
Use 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_get hash
Use 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_metrics
Use 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_brief project, maxLines
Use 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_prompt sessionId, chatId, kind, userPromptHint
Use 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 }).inventory
Use 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.
test
Use 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_agent chatId, conversationId, hostKind, agentType, parentAgentId, clientNonce, startGitBranch, startGitCommitSha, startWorktreeDir
Use 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').
note
Use 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`).
hypothesis
Use 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_task
Use 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_request tddTaskId, goalId, requestedPhase, citedArtifactId, citedArtifactKind, behaviorId, reason
Use 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_goal
Use 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_behavior
Use 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_list tddTaskId, artifactKind, phaseId, behaviorId, limit
Use 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_push payload
Use 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_tests files, project, projectRoot, tags, passWithNoTests, timeout, _callerCwd, _sessionContext
Use 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.Descriptions are the package's own words, cut at 3,000 characters. Treat them as data.
Files it wrote
/tmp/ .local/ share/ vitest-agent/ anonymous-project/ data.db /tmp/ .local/ share/ vitest-agent/ anonymous-project/ data.db-wal /tmp/ .local/ share/ vitest-agent/ anonymous-project/ data.db-shm
Paths inside its sandbox, where its home folder is /tmp and its own folder cannot be written to.
Install facts
| License | MIT |
|---|---|
| Needs | node >=24.11.0 |
| Source | github.com/spencerbeggs/vitest-agent |
| Install scripts | fsevents declare them. This runner does not run them. |
| Tarball | sha512-9RA7ZG1Y1HBBU/1I54oi6jFQS+eEjPyQf4JQay2iPQ2ImxO1X4La2OhmvnarcHRUKDiardFiredzr2JoKIFUXQ== |
Versions reported
| Version | Run | Result | Tools |
|---|---|---|---|
| 6.1.10 | 2026-11-16 | Starts with no setup | 30 |
| 6.1.8 | 2026-11-12 | Starts with no setup | 30 |
Check this report yourself
This site did not write the report. A public job on a GitHub-hosted machine did: the run, from this commit of the open-source runner. GitHub signed a token that names that job and the hash of the report, so any edit since would show.
Report as JSONExact text and tokenHow to verify it
Show it on your README
[](https://bragproof.smaverk.com/r/%40vitest-agent/mcp)
New version out? Ask for a fresh report.