@vitest-agent/mcp 3.0.3 → 4.0.0

package/index.js

@@ -1,18 +1,36 @@
-import { createCallerFactory, createCurrentSessionIdRef, createSessionContextRef } from "./context.js";
-import { McpLive } from "./layers/McpLive.js";
-import { appRouter } from "./router.js";
-import { buildMcpServer, startMcpServer } from "./server.js";
-import { parseSessionEnvExports, recoverSessionContextFromSessionEnv } from "./session-env.js";
+import { RenderText } from "./annotations.js";
+import { withIdempotency } from "./idempotency.js";
+import { McpSession, createCurrentSessionIdRef, createSessionContextRef, sessionContextFromEnv } from "./session.js";
+import { PromptsLayer } from "./prompts/layer.js";
+import { registerStrictToolkit } from "./register-toolkit.js";
+import { AcceptanceMetricsResult } from "./tools/acceptance-metrics.js";
+import { CacheHealthResult } from "./tools/cache-health.js";
+import { CommitChangesInput, CommitChangesResult } from "./tools/commit-changes.js";
+import { ConfigureInput, ConfigureResult } from "./tools/configure.js";
+import { TestCoverageInput, TestCoverageResult } from "./tools/coverage.js";
+import { TestErrorsInput, TestErrorsResult } from "./tools/errors.js";
+import { FailureSignatureGetInput, FailureSignatureGetResult } from "./tools/failure-signature-get.js";
+import { FileCoverageInput, FileCoverageResult } from "./tools/file-coverage.js";
+import { HelpResult } from "./tools/help.js";
+import { TestHistoryInput, TestHistoryResult } from "./tools/history.js";
+import { InventoryInput, InventoryResult } from "./tools/inventory.js";
+import { NoteParams, NoteResult } from "./tools/note.js";
+import { TestOverviewInput, TestOverviewResult } from "./tools/overview.js";
+import { PingResult } from "./tools/ping.js";
+import { RegisterAgentInput, RegisterAgentResult } from "./tools/register-agent.js";
+import { RunTestsInput, RunTestsResult } from "./tools/run-tests.js";
+import { SettingsListResult } from "./tools/settings-list.js";
+import { TestStatusInput, TestStatusResult } from "./tools/status.js";
+import { TddArtifactListInput, TddArtifactListResult } from "./tools/tdd-artifact.js";
+import { PhaseTransitionInput, PhaseTransitionResult } from "./tools/tdd-phase-transition-request.js";
+import { TddProgressPushInput, TddProgressPushResult } from "./tools/tdd-progress-push.js";
+import { TestInput, TestResult } from "./tools/test.js";
+import { TestTrendsInput, TestTrendsResult } from "./tools/trends.js";
+import { TriageBriefInput, TriageBriefResult } from "./tools/triage-brief.js";
+import { TurnSearchInput, TurnSearchResult } from "./tools/turn-search.js";
+import { WrapupPromptInput, WrapupPromptResult } from "./tools/wrapup-prompt.js";
+import { Kit, ToolsLayer, toolHandlers } from "./toolkit.js";
+import { ServerLayer } from "./server.js";
+import { CURRENT_MCP_VERSION } from "./version.js";
 
-//#region src/index.ts
-/**
-* The version of this package, inlined at build time from
-* package.json#version via rslib-builder's __PACKAGE_VERSION__ substitution.
-* Exported for version introspection by downstream tooling.
-*
-* @public
-*/
-const CURRENT_MCP_VERSION = "3.0.3";
-
-//#endregion
-export { CURRENT_MCP_VERSION, McpLive, appRouter, buildMcpServer, createCallerFactory, createCurrentSessionIdRef, createSessionContextRef, parseSessionEnvExports, recoverSessionContextFromSessionEnv, startMcpServer };
+export { AcceptanceMetricsResult, CURRENT_MCP_VERSION, CacheHealthResult, CommitChangesInput, CommitChangesResult, ConfigureInput, ConfigureResult, FailureSignatureGetInput, FailureSignatureGetResult, FileCoverageInput, FileCoverageResult, HelpResult, InventoryInput, InventoryResult, Kit, McpSession, NoteParams, NoteResult, PhaseTransitionInput, PhaseTransitionResult, PingResult, PromptsLayer, RegisterAgentInput, RegisterAgentResult, RenderText, RunTestsInput, RunTestsResult, ServerLayer, SettingsListResult, TddArtifactListInput, TddArtifactListResult, TddProgressPushInput, TddProgressPushResult, TestCoverageInput, TestCoverageResult, TestErrorsInput, TestErrorsResult, TestHistoryInput, TestHistoryResult, TestInput, TestOverviewInput, TestOverviewResult, TestResult, TestStatusInput, TestStatusResult, TestTrendsInput, TestTrendsResult, ToolsLayer, TriageBriefInput, TriageBriefResult, TurnSearchInput, TurnSearchResult, WrapupPromptInput, WrapupPromptResult, createCurrentSessionIdRef, createSessionContextRef, registerStrictToolkit, sessionContextFromEnv, toolHandlers, withIdempotency };

package/main.d.ts

@@ -0,0 +1,31 @@
+//#region src/main.d.ts
+/**
+ * The assembled vitest-agent MCP server program over stdio. Owns the process.
+ *
+ * This module deliberately carries NO static imports of the server graph:
+ * the `unhandledRejection` and `uncaughtException` guards are registered
+ * before `NodeRuntime`, the engine platform and `ServerLayer` are ever
+ * evaluated, so a throw during module evaluation is still reported on stderr
+ * rather than crashing silently. Adding a static import here would defeat
+ * that. `bin.ts` is the published bin shim; this module is also published as
+ * the `./main` subpath so the carrier (`@vitest-agent/plugin`) can ship its
+ * own `vitest-agent-mcp` bin over it.
+ *
+ * Every `process` read lives here, not in the server layer or the tools.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Run the vitest-agent MCP server over stdio. Owns the process: registers
+ * the crash guards, resolves the project directory and `data.db` path,
+ * recovers the host session context, and launches the server layer under
+ * `NodeRuntime.runMain`.
+ *
+ * Not re-exported from `index.ts` — a library consumer's import graph must
+ * not pull in the process-owning module.
+ *
+ * @public
+ */
+export declare const main: () => Promise<void>;
+//#endregion
+//# sourceMappingURL=main.d.ts.map

package/main.js

@@ -0,0 +1,144 @@
+import { shouldExitOnUncaughtException } from "./utils/crash-guards.js";
+
+//#region src/main.ts
+/**
+* The assembled vitest-agent MCP server program over stdio. Owns the process.
+*
+* This module deliberately carries NO static imports of the server graph:
+* the `unhandledRejection` and `uncaughtException` guards are registered
+* before `NodeRuntime`, the engine platform and `ServerLayer` are ever
+* evaluated, so a throw during module evaluation is still reported on stderr
+* rather than crashing silently. Adding a static import here would defeat
+* that. `bin.ts` is the published bin shim; this module is also published as
+* the `./main` subpath so the carrier (`@vitest-agent/plugin`) can ship its
+* own `vitest-agent-mcp` bin over it.
+*
+* Every `process` read lives here, not in the server layer or the tools.
+*
+* @packageDocumentation
+*/
+/**
+* Whether the stdio transport is live for this process — set once the
+* whole server layer graph (the stdio protocol included) has been built.
+* Read by the `uncaughtException` guard via `shouldExitOnUncaughtException`;
+* see that function's doc comment for the judgment call this flag backs
+* (issue #191).
+*/
+let transportConnected = false;
+/**
+* Formatter for the crash guards. Starts as a dependency-free fallback so a
+* throw during module evaluation of the server graph is still described,
+* and is swapped for the SDK's `safeFormatFatalError` once that import
+* has resolved.
+*/
+let formatFatal = (error) => {
+	try {
+		return error instanceof Error ? error.stack ?? error.message : String(error);
+	} catch {
+		return "<unformattable error value>";
+	}
+};
+/**
+* Test-only crash injection, gated by an env var so it can never fire in a
+* normal install. Exists so `__test__/bin-crash-resilience.e2e.test.ts` can
+* exercise the guards against a *real* child process. Fires exactly once,
+* on the next event-loop turn after the transport is known to be connected,
+* so ordering relative to `transportConnected` is deterministic regardless
+* of client-side handshake timing.
+*/
+const scheduleTestCrashInjection = () => {
+	const kind = process.env.VITEST_AGENT_MCP_TEST_INJECT_CRASH;
+	if (kind !== "unhandledRejection" && kind !== "uncaughtException") return;
+	setImmediate(() => {
+		if (kind === "unhandledRejection") Promise.reject(/* @__PURE__ */ new Error("[test-injected] unhandledRejection"));
+		else throw new Error("[test-injected] uncaughtException");
+	});
+};
+/**
+* Optional first positional argument: an initial Claude Code chat UUID (the
+* host's `chatId`) to seed the MCP server's session association. Claude Code
+* substitutes unknown `${...}` variables to literal text in some surfaces, so
+* a literal substitution is treated as absent rather than seeding garbage.
+*
+* @param argv - the raw `process.argv`
+* @returns the trimmed seed, or `null` when absent, empty, or a literal `${...}`
+*/
+const resolveInitialSessionId = (argv) => {
+	const first = argv[2];
+	if (first === void 0) return null;
+	const trimmed = first.trim();
+	if (trimmed.length === 0) return null;
+	if (trimmed.startsWith("${") && trimmed.endsWith("}")) return null;
+	return trimmed;
+};
+/**
+* Run the vitest-agent MCP server over stdio. Owns the process: registers
+* the crash guards, resolves the project directory and `data.db` path,
+* recovers the host session context, and launches the server layer under
+* `NodeRuntime.runMain`.
+*
+* Not re-exported from `index.ts` — a library consumer's import graph must
+* not pull in the process-owning module.
+*
+* @public
+*/
+const main = async () => {
+	process.on("unhandledRejection", (reason) => {
+		process.stderr.write(`vitest-agent-mcp: unhandledRejection: ${formatFatal(reason)}\n`);
+	});
+	process.on("uncaughtException", (err, origin) => {
+		process.stderr.write(`vitest-agent-mcp: uncaughtException (${origin}): ${formatFatal(err)}\n`);
+		if (shouldExitOnUncaughtException(transportConnected)) {
+			process.exitCode = 1;
+			process.exit(1);
+		}
+	});
+	try {
+		const { safeFormatFatalError } = await import("./utils/safe-format-fatal-error.js");
+		formatFatal = safeFormatFatalError;
+		const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
+		const NodeServices = await import("@effect/platform-node/NodeServices");
+		const NodeStdio = await import("@effect/platform-node/NodeStdio");
+		const { Cause, Effect, Exit, Layer, Logger, Runtime } = await import("effect");
+		const { PathResolutionLive, PlatformLive, recoverSessionContextFromSessionEnv, resolveDataPath, resolveLogFile, resolveLogLevel, resolveProjectDir } = await import("@vitest-agent/engine");
+		const { McpSession, sessionContextFromEnv } = await import("./session.js");
+		const { ServerLayer } = await import("./server.js");
+		const { CURRENT_MCP_VERSION } = await import("./version.js");
+		const env = process.env;
+		const projectDir = resolveProjectDir({
+			env,
+			cwd: process.cwd()
+		});
+		const initialSessionId = resolveInitialSessionId(process.argv);
+		const dbPath = await Effect.runPromise(resolveDataPath(projectDir).pipe(Effect.provide(PathResolutionLive(projectDir)), Effect.provide(NodeServices.layer)));
+		const recovered = sessionContextFromEnv(env);
+		const homeDir = env.HOME ?? env.USERPROFILE ?? "";
+		const Session = McpSession.layer({
+			cwd: projectDir,
+			initialSessionId: initialSessionId ?? recovered?.chatId ?? null,
+			initialContext: recovered,
+			recover: () => recoverSessionContextFromSessionEnv({
+				projectDir,
+				homeDir
+			})
+		});
+		const Main = ServerLayer({ version: CURRENT_MCP_VERSION }).pipe(Layer.provide(Session), Layer.provide(PlatformLive({
+			dbPath,
+			env,
+			logLevel: resolveLogLevel(env),
+			logFile: resolveLogFile(env)
+		})), Layer.provide(NodeStdio.layer), Layer.provide(Layer.succeed(Logger.LogToStderr, true)));
+		const Connected = Layer.effectDiscard(Effect.sync(() => {
+			transportConnected = true;
+			scheduleTestCrashInjection();
+		})).pipe(Layer.provide(Main));
+		const program = Layer.launch(Connected).pipe(Effect.provideService(Logger.LogToStderr, true));
+		NodeRuntime.runMain(program, { teardown: (exit, onExit) => Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause) ? onExit(0) : Runtime.defaultTeardown(exit, onExit) });
+	} catch (err) {
+		process.stderr.write(`vitest-agent-mcp: startup failed: ${formatFatal(err)}\n`);
+		process.exit(1);
+	}
+};
+
+//#endregion
+export { main };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/mcp",
-	"version": "3.0.3",
+	"version": "4.0.0",
 	"private": false,
 	"description": "Model Context Protocol server for vitest-agent. Exposes 53 tools for agent access to test data, TDD lifecycle, and session management.",
 	"keywords": [
@@ -32,6 +32,11 @@
 			"import": "./index.js",
 			"default": "./index.js"
 		},
+		"./main": {
+			"types": "./main.d.ts",
+			"import": "./main.js",
+			"default": "./main.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"bin": {
@@ -40,11 +45,9 @@
 	"dependencies": {
 		"@effect/platform-node": "4.0.0-rc.115",
 		"@effect/sql-sqlite-node": "4.0.0-rc.115",
-		"@modelcontextprotocol/sdk": "^1.30.0",
-		"@trpc/server": "^11.18.0",
-		"@vitest-agent/sdk": "3.1.2",
-		"effect": "4.0.0-rc.115",
-		"zod": "^4.5.4"
+		"@vitest-agent/engine": "0.1.0",
+		"@vitest-agent/sdk": "4.0.0",
+		"effect": "4.0.0-rc.115"
 	},
 	"peerDependencies": {
 		"vitest": "^5.0.0"

package/prompts/layer.js

@@ -0,0 +1,108 @@
+import { McpSession } from "../session.js";
+import { explainFailurePrompt } from "./explain-failure.js";
+import { regressionSincePassPrompt } from "./regression-since-pass.js";
+import { tddResumePrompt } from "./tdd-resume.js";
+import { triagePrompt } from "./triage.js";
+import { whyFlakyPrompt } from "./why-flaky.js";
+import { wrapupPrompt } from "./wrapup.js";
+import { Effect, Layer, Schema } from "effect";
+import { McpSchema, McpServer } from "effect/unstable/ai";
+
+//#region src/prompts/layer.ts
+/**
+* The six prompt names `PromptsLayer` registers, in registration order.
+* Pinned against the `help` text by `__test__/help-drift.test.ts`.
+*
+* @internal
+*/
+const PROMPT_NAMES = [
+	"triage",
+	"why-flaky",
+	"regression-since-pass",
+	"explain-failure",
+	"tdd-resume",
+	"wrapup"
+];
+/** The `wrapup.kind` literal set, served as the argument's closed vocabulary. */
+const WRAPUP_KINDS = [
+	"stop",
+	"session_end",
+	"pre_compact",
+	"tdd_handoff",
+	"user_prompt_nudge"
+];
+const toMessages = (result) => result.messages.map((m) => ({
+	role: m.role,
+	content: McpSchema.TextContent.make({ text: m.content.text })
+}));
+const projectArg = Schema.optionalKey(Schema.String.annotate({ description: "Filter to a specific project" }));
+const Triage = McpServer.prompt({
+	name: PROMPT_NAMES[0],
+	description: "Orient toward a triage workflow over the most recent test run; compose triage_brief, failure_signature_get, hypothesis_record.",
+	parameters: { project: projectArg },
+	content: (args) => Effect.succeed(toMessages(triagePrompt(args.project !== void 0 ? { project: args.project } : {})))
+});
+const WhyFlaky = McpServer.prompt({
+	name: PROMPT_NAMES[1],
+	description: "Diagnose why a named test is flaky; compose test_history and failure_signature_get with timing/shared-state framing.",
+	parameters: {
+		test: Schema.String.annotate({ description: "Full hierarchical test name (e.g. 'Suite > nested > test')" }),
+		project: projectArg
+	},
+	content: (args) => Effect.succeed(toMessages(whyFlakyPrompt(args.project !== void 0 ? {
+		test: args.test,
+		project: args.project
+	} : { test: args.test })))
+});
+const RegressionSincePass = McpServer.prompt({
+	name: PROMPT_NAMES[2],
+	description: "Walk back from the test's most recent passing run to identify the change that broke it; compose test_history, commit_changes, turn_search.",
+	parameters: {
+		test: Schema.String.annotate({ description: "Full hierarchical test name" }),
+		project: projectArg
+	},
+	content: (args) => Effect.succeed(toMessages(regressionSincePassPrompt(args.project !== void 0 ? {
+		test: args.test,
+		project: args.project
+	} : { test: args.test })))
+});
+const ExplainFailure = McpServer.prompt({
+	name: PROMPT_NAMES[3],
+	description: "Synthesize a root-cause explanation from the recurrence history of a failure signature.",
+	parameters: { signature: Schema.String.annotate({ description: "16-char failure signature hex" }) },
+	content: (args) => Effect.succeed(toMessages(explainFailurePrompt({ signature: args.signature })))
+});
+const TddResume = McpServer.prompt({
+	name: PROMPT_NAMES[4],
+	description: "Resume the active TDD task from its current phase; iron-law reminder for evidence-bound transitions.",
+	parameters: { sessionId: Schema.optionalKey(Schema.String.annotate({ description: "Host session id (defaults to MCP server's recovered SessionContext)" })) },
+	content: (args) => Effect.gen(function* () {
+		const session = yield* McpSession;
+		const sessionId = args.sessionId ?? session.sessionContext.get()?.chatId ?? session.currentSessionId.get();
+		return toMessages(tddResumePrompt(sessionId === null ? {} : { sessionId }));
+	})
+});
+const Wrapup = McpServer.prompt({
+	name: PROMPT_NAMES[5],
+	description: "Surface the same wrapup content the post-hooks emit automatically.",
+	parameters: {
+		kind: Schema.optionalKey(Schema.Literals(WRAPUP_KINDS).annotate({ description: "Wrapup variant (default: user_prompt_nudge)" })),
+		since: Schema.optionalKey(Schema.String.annotate({ description: "ISO 8601 timestamp lower bound for activity to summarize" }))
+	},
+	content: (args) => {
+		const wrapupArgs = {};
+		if (args.kind !== void 0) wrapupArgs.kind = args.kind;
+		if (args.since !== void 0) wrapupArgs.since = args.since;
+		return Effect.succeed(toMessages(wrapupPrompt(wrapupArgs)));
+	}
+});
+/**
+* Every framing prompt as one layer; merged into `ServerLayer` beside the
+* toolkit registration. Requires `McpSession` for `tdd-resume`'s default.
+*
+* @public
+*/
+const PromptsLayer = Layer.mergeAll(Triage, WhyFlaky, RegressionSincePass, ExplainFailure, TddResume, Wrapup);
+
+//#endregion
+export { PROMPT_NAMES, PromptsLayer, WRAPUP_KINDS };