@vitest-agent/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @vitest-agent/mcp
+
+[![npm](https://img.shields.io/npm/v/@vitest-agent/mcp?label=npm&color=cb3837)](https://www.npmjs.com/package/@vitest-agent/mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+> **Part of the [vitest-agent](https://vitest-agent.dev) ecosystem.** Most users want **[@vitest-agent/plugin](https://www.npmjs.com/package/@vitest-agent/plugin)**, which pulls this package in automatically. Install `@vitest-agent/mcp` directly only if you run the MCP server standalone.
+
+The `vitest-agent-mcp` MCP server bin. Exposes action-keyed tools over stdio that give LLM agents structured access to test data, coverage, history, failure signatures, TDD lifecycle state and more. Also surfaces four MCP resources (vendored Vitest docs and curated testing patterns) and six framing-only prompts.
+
+## Features
+
+- **29 action-keyed tools** — per-CRUD families collapse into single tools dispatching on an `action` discriminator; covers `test_status`, `test_overview`, `test_coverage`, `test_errors`, `run_tests`, `note`, `hypothesis`, `tdd_task`, `tdd_goal`, `tdd_behavior` and more
+- **Four MCP resources** — vendored Vitest documentation (`vitest://docs/`) and curated testing patterns (`vitest-agent://patterns/`) with per-page titles, descriptions and `audience`/`priority` annotations
+- **Six framing prompts** — `triage`, `why-flaky`, `regression-since-pass`, `explain-failure`, `tdd-resume`, `wrapup`
+- **Idempotency middleware** — `tdd_task`, `tdd_goal`, `tdd_behavior` and `hypothesis` create-actions are idempotent on derived keys
+
+## Install
+
+```bash
+npm install --save-dev @vitest-agent/mcp
+# or
+pnpm add -D @vitest-agent/mcp
+```
+
+`@vitest-agent/mcp` is a required peer of `@vitest-agent/plugin` and arrives automatically with modern pnpm and npm.
+
+## Quick start
+
+```bash
+npx vitest-agent-mcp
+# starts the MCP server over stdio
+# example output (varies by environment)
+```
+
+The server reads the SQLite database written by `AgentPlugin` via the same XDG-derived path, so a single test run populates data for all tools.
+
+## Documentation
+
+MCP reference and tool catalog at [vitest-agent.dev/mcp](https://vitest-agent.dev/mcp).
+
+## License
+
+[MIT](LICENSE)

package/bin/vitest-agent-mcp.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { createCurrentSessionIdRef, createSessionContextRef, sessionContextFromEnv } from "../context.js";
+import { McpLive } from "../layers/McpLive.js";
+import { startMcpServer } from "../server.js";
+import { CURRENT_MCP_VERSION } from "../index.js";
+import { NodeContext } from "@effect/platform-node";
+import { CURRENT_SDK_VERSION, PathResolutionLive, formatFatalError, resolveDataPath, resolveLogFile, resolveLogLevel } from "@vitest-agent/sdk";
+import { Effect, ManagedRuntime } from "effect";
+
+//#region src/bin.ts
+/**
+* Cross-package version drift check. Compares this MCP package's version
+* against @vitest-agent/sdk and writes a single stderr line on mismatch.
+* Observation-only — never throws. The `"0.0.0"` fallback marks a dev
+* build (rslib-builder did not substitute the literal); skip the check
+* to avoid spurious warnings during local source-loaded runs. See the
+* root CLAUDE.md "Cross-package version drift" section.
+*
+* @internal
+*/
+function checkVersionDrift() {
+	if ("1.0.0" === "0.0.0") return;
+	if (CURRENT_SDK_VERSION !== "1.0.0") process.stderr.write(`[@vitest-agent/mcp] version drift: @vitest-agent/mcp@${CURRENT_MCP_VERSION} with @vitest-agent/sdk@${CURRENT_SDK_VERSION}. Reinstall @vitest-agent/* packages so versions match.\n`);
+}
+/**
+* Resolve the user's project directory.
+*
+* Precedence (most explicit wins):
+*
+* 1. `VITEST_AGENT_REPORTER_PROJECT_DIR` — set by the Claude Code plugin
+*    loader (`plugin/bin/mcp-server.mjs`) to the resolved project root.
+*    The loader controls this end-to-end so the value is reliable when
+*    set.
+* 2. `CLAUDE_PROJECT_DIR` — exported by Claude Code for hook scripts and
+*    (per docs hints) MCP server subprocesses. Used when the loader is
+*    bypassed (e.g. someone wires the MCP binary up manually).
+* 3. `process.cwd()` — fall-through for direct invocation outside Claude
+*    Code, where the user is presumably running from their project root.
+*/
+function resolveProjectDir() {
+	return process.env.VITEST_AGENT_REPORTER_PROJECT_DIR ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+}
+/**
+* Optional first positional argument: an initial Claude Code chat UUID
+* (the host's `chatId`) to seed the MCP server's session association.
+*
+* The plugin manifest (`plugin/.claude-plugin/plugin.json`) can pass this
+* via Claude Code variable substitution if such a variable exists for
+* sessions (the documented substitutions are `${CLAUDE_PLUGIN_ROOT}` and
+* `${CLAUDE_PLUGIN_DATA}`; testing whether `${CLAUDE_SESSION_ID}` or a
+* similar name is honored in `mcpServers.args` is part of the reason
+* this seed path exists). When the seed is empty the agent is expected
+* to recover the chat id at boot. The legacy `set_current_session_id`
+* MCP tool was removed in Phase 3.
+*/
+function resolveInitialSessionId() {
+	const argv = process.argv[2];
+	if (argv === void 0) return null;
+	const trimmed = argv.trim();
+	if (trimmed.length === 0) return null;
+	if (trimmed.startsWith("${") && trimmed.endsWith("}")) return null;
+	return trimmed;
+}
+async function main() {
+	const projectDir = resolveProjectDir();
+	checkVersionDrift();
+	const initialSessionId = resolveInitialSessionId();
+	const dbPath = await Effect.runPromise(resolveDataPath(projectDir).pipe(Effect.provide(PathResolutionLive(projectDir)), Effect.provide(NodeContext.layer)));
+	const logLevel = resolveLogLevel();
+	const logFile = resolveLogFile();
+	const runtime = ManagedRuntime.make(McpLive(dbPath, logLevel, logFile));
+	const recoveredContext = sessionContextFromEnv(process.env);
+	const ctx = {
+		runtime,
+		cwd: projectDir,
+		currentSessionId: createCurrentSessionIdRef(initialSessionId ?? recoveredContext?.chatId ?? null),
+		sessionContext: createSessionContextRef(recoveredContext)
+	};
+	const chatIdResolved = initialSessionId ?? recoveredContext?.chatId ?? null;
+	console.error("[vitest-agent-mcp] Starting...");
+	console.error(`[vitest-agent-mcp] Project: ${projectDir}`);
+	console.error(`[vitest-agent-mcp] Database: ${dbPath}`);
+	console.error(`[vitest-agent-mcp] Initial chat id: ${chatIdResolved !== null ? "(set)" : "(none — SessionStart hook had not written CLAUDE_ENV_FILE yet)"}`);
+	if (recoveredContext !== null) console.error("[vitest-agent-mcp] Recovered session context: agent=(set) conversation=(set)");
+	await startMcpServer(ctx);
+}
+main().catch((err) => {
+	process.stderr.write(`vitest-agent-mcp: ${formatFatalError(err)}\n`);
+	process.exit(1);
+});
+
+//#endregion
+export {  };

package/context.js

@@ -0,0 +1,72 @@
+import { initTRPC } from "@trpc/server";
+
+//#region src/context.ts
+/**
+* Creates a new {@link CurrentSessionIdRef} with an optional initial value.
+*
+* @param initial - the starting chat id, or `null` when unknown at construction time
+* @returns a mutable ref holding the current session id
+* @public
+*/
+const createCurrentSessionIdRef = (initial = null) => {
+	let value = initial;
+	return {
+		get: () => value,
+		set: (id) => {
+			value = id;
+		}
+	};
+};
+/**
+* Creates a new {@link SessionContextRef} with an optional initial value.
+*
+* @param initial - the starting session context, or `null` when not yet recovered
+* @returns a mutable ref holding the current session context
+* @public
+*/
+const createSessionContextRef = (initial = null) => {
+	let value = initial;
+	return {
+		get: () => value,
+		set: (ctx) => {
+			value = ctx;
+		}
+	};
+};
+/**
+* Resolve the boot-time SessionContext from `process.env` (the
+* primary path: SessionStart wrote the exports to `CLAUDE_ENV_FILE`
+* and Claude Code auto-sources that file into the MCP server child).
+*
+* Returns `null` when any required value is absent — callers can
+* still attempt the session-map fallback before giving up.
+*/
+const sessionContextFromEnv = (env = process.env) => {
+	const chatId = env.VITEST_AGENT_CHAT_ID;
+	const conversationId = env.VITEST_AGENT_CONVERSATION_ID;
+	const mainAgentId = env.VITEST_AGENT_MAIN_AGENT_ID ?? env.VITEST_AGENT_AGENT_ID;
+	if (chatId === void 0 || conversationId === void 0 || mainAgentId === void 0) return null;
+	if (chatId.length === 0 || conversationId.length === 0 || mainAgentId.length === 0) return null;
+	return {
+		chatId,
+		conversationId,
+		mainAgentId
+	};
+};
+const t = initTRPC.context().create();
+const router = t.router;
+const publicProcedure = t.procedure;
+/**
+* Factory for creating server-side tRPC callers for the MCP router.
+*
+* Use with {@link appRouter} in tests or programmatic contexts to invoke
+* tool procedures without starting the MCP server.
+*
+* @public
+*/
+const createCallerFactory = t.createCallerFactory;
+/** Exported so middleware modules can attach to the same tRPC instance. */
+const middleware = t.middleware;
+
+//#endregion
+export { createCallerFactory, createCurrentSessionIdRef, createSessionContextRef, middleware, publicProcedure, router, sessionContextFromEnv };