@vitest-agent/mcp 3.0.3 → 4.0.0

package/README.md

@@ -6,16 +6,17 @@
 
 > **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 six framing-only prompts.
+The `vitest-agent-mcp` MCP server bin, built on Effect's native `McpServer` (`effect/unstable/ai`). 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 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
+- **30 action-keyed tools** — one `Tool.make` per file, assembled into a single `Toolkit`; 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`, `tdd_progress_push` and more
 - **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
-- **Strict tool inputs** — an unknown key is rejected with an error naming it and listing the accepted params, instead of being stripped and running a wider query than the caller asked for
-- **Session-surviving error handling** — a resolver that throws returns a structured `UnexpectedToolError` envelope, and a stray unhandled rejection after the transport connects is logged to stderr rather than killing the server mid-session
-- **Programmatic API** — `buildMcpServer` constructs the server without connecting a transport; `parseSessionEnvExports` and `recoverSessionContextFromSessionEnv` recover the host session context from the Claude Code plugin's session-env files, so agent attribution survives a plugin reload
+- **Idempotent writes** — `tdd_task`, `tdd_goal`, `tdd_behavior` and `hypothesis` create-actions are idempotent on derived keys via the `withIdempotency` combinator; a replay carries `_idempotentReplay: true`
+- **Strict tool inputs** — every served `inputSchema` is strict at every object level; an unknown key is rejected with an error naming it and listing the accepted params, instead of being stripped and running a wider query than the caller asked for
+- **Session-surviving error handling** — a handler that dies returns a structured `UnexpectedToolError` envelope, every log line goes to stderr (stdout is the JSON-RPC wire), and a stray unhandled rejection after the transport connects is logged rather than killing the server mid-session
+- **Programmatic API** — `ServerLayer({ version })` is the whole server as an Effect `Layer` over any `Stdio` implementation (the test harness runs it over in-memory queues); `Kit`, `toolHandlers`, `PromptsLayer`, `registerStrictToolkit` and `McpSession` are exported for embedding or extension
+- **No MCP SDK, tRPC or zod** — the wire protocol, JSON Schema generation and input validation all come from `effect`; tool inputs and outputs are Effect `Schema` values end to end
 
 ## Install
 

package/annotations.js

@@ -0,0 +1,18 @@
+import { Context } from "effect";
+
+//#region src/annotations.ts
+/**
+* Renders a tool's encoded result as the human-readable `content[0].text`
+* channel (markdown, typically). Returning `undefined` — or leaving the
+* annotation unset — falls back to `JSON.stringify(encoded)`.
+*
+* Attach with `tool.annotate(RenderText, (encoded) => ...)`; the renderer
+* receives the wire-encoded result (the same value that becomes
+* `structuredContent`), never the decoded domain value.
+*
+* @public
+*/
+const RenderText = Context.Reference("@vitest-agent/mcp/RenderText", { defaultValue: () => void 0 });
+
+//#endregion
+export { RenderText };

package/bin/vitest-agent-mcp.js

@@ -1,149 +1,14 @@
 #!/usr/bin/env node
-import { createCurrentSessionIdRef, createSessionContextRef, sessionContextFromEnv } from "../context.js";
-import { McpLive } from "../layers/McpLive.js";
-import { startMcpServer } from "../server.js";
-import { recoverSessionContextFromSessionEnv } from "../session-env.js";
-import { shouldExitOnUncaughtException } from "../utils/crash-guards.js";
-import { safeFormatFatalError } from "../utils/safe-format-fatal-error.js";
-import { Effect, ManagedRuntime } from "effect";
-import * as NodeServices from "@effect/platform-node/NodeServices";
-import { PathResolutionLive, resolveDataPath, resolveLogFile, resolveLogLevel } from "@vitest-agent/sdk";
+import { main } from "../main.js";
 
 //#region src/bin.ts
 /**
-* Whether `server.connect(transport)` has resolved for this process.
-* Read by the `uncaughtException` handler below via
-* {@link shouldExitOnUncaughtException} — see that function's doc
-* comment for the judgment call this flag backs (issue #191).
-*/
-let transportConnected = false;
-/**
-* Issue #191, sub-item A: the MCP server used to be a bare
-* `main().catch(...)` with no process-level guards. Under Node >=15 an
-* unhandled promise rejection anywhere in the async chain — a
-* fire-and-forgotten Effect fiber, a background timer, anything that
-* never flows through a tool call's own await chain — crashes the
-* process by default, closing the stdio transport and silently
-* deregistering every tool from the client's perspective mid session,
-* with no recovery path. Register both guards at module scope, before
-* any async work in `main()` starts, so they also cover the dbPath
-* resolution / ManagedRuntime construction phase.
-*
-* Every throw or rejection *inside* a single tool call is already
-* caught by the MCP SDK's own `CallToolRequestSchema` handler (see
-* `server.ts`'s `registerTool` shadow for the structured-envelope
-* layer on top of that). Anything that reaches these handlers
-* therefore originated outside any tool-call boundary and, by
-* definition, has no in-flight caller waiting on it — logging and
-* continuing is safe because there is no request context to roll back
-* and no benefit to dropping every *other* in-flight and future tool
-* call over it.
-*/
-process.on("unhandledRejection", (reason) => {
-	process.stderr.write(`vitest-agent-mcp: unhandledRejection: ${safeFormatFatalError(reason)}\n`);
-});
-/**
-* Node's own guidance for `uncaughtException` is "do not resume normal
-* operation" — arbitrary in-process state may be corrupt. This process
-* accepts that residual risk once the transport is connected: see
-* `shouldExitOnUncaughtException`'s doc comment for the reasoning
-* (no long-lived mutable state outside SQLite's own transactions, and
-* silent process death mid-session is strictly worse). Before the
-* transport connects there is no client session to preserve by staying
-* alive, so this exits loudly instead.
-*/
-process.on("uncaughtException", (err, origin) => {
-	process.stderr.write(`vitest-agent-mcp: uncaughtException (${origin}): ${safeFormatFatalError(err)}\n`);
-	if (shouldExitOnUncaughtException(transportConnected)) {
-		process.exitCode = 1;
-		process.exit(1);
-	}
-});
-/**
-* 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 above against a *real* child process (a
-* crash in the test's own process is not something a unit test can
-* safely simulate). 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.
-*/
-function 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");
-	});
-}
-/**
-* Resolve the user's project directory.
-*
-* Precedence (most explicit wins):
-*
-* 1. `VITEST_AGENT_REPORTER_PROJECT_DIR` — set by the Claude Code plugin
-*    loader (`plugins/claude-code/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.
+* MCP server entry point for vitest-agent. Thin shim over `main.ts` — the
+* assembled program that owns the process.
 *
-* The plugin manifest (`plugins/claude-code/.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.
+* @packageDocumentation
 */
-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();
-	const initialSessionId = resolveInitialSessionId();
-	const dbPath = await Effect.runPromise(resolveDataPath(projectDir).pipe(Effect.provide(PathResolutionLive(projectDir)), Effect.provide(NodeServices.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, () => recoverSessionContextFromSessionEnv({ projectDir }))
-	};
-	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);
-	transportConnected = true;
-	scheduleTestCrashInjection();
-}
-main().catch((err) => {
-	process.stderr.write(`vitest-agent-mcp: ${safeFormatFatalError(err)}\n`);
-	process.exit(1);
-});
+main();
 
 //#endregion
 export {  };

package/{middleware/idempotency.js → idempotency.js}

@@ -1,16 +1,17 @@
-import { middleware, publicProcedure } from "../context.js";
 import { Effect, Option } from "effect";
-import { DataReader, DataStore } from "@vitest-agent/sdk";
+import { DataReader, DataStore } from "@vitest-agent/engine";
 
-//#region src/middleware/idempotency.ts
+//#region src/idempotency.ts
 /**
-* Registered idempotency specs for mutation procedures.
+* Registered idempotency specs for mutation tools.
 *
 * `hypothesis validate` is covered (key: `validate:${id}:${outcome}`).
 * `hypothesis record` is deliberately not covered — see the note in the
 * hypothesis spec below.
 *
 * Add an entry here whenever a new idempotent mutation is introduced.
+*
+* @public
 */
 const idempotencyKeys = [
 	{
@@ -68,61 +69,59 @@ const idempotencyKeys = [
 		}
 	}
 ];
-/** Lookup table keyed by procedure path for O(1) spec retrieval. */
+/** Lookup table keyed by tool name for O(1) spec retrieval. */
 const keySpecByPath = new Map(idempotencyKeys.map((s) => [s.procedurePath, s]));
+/** Merges the `_idempotentReplay` marker into an object payload; passes any other shape through unchanged. */
+const withReplayMarker = (parsed) => parsed !== null && typeof parsed === "object" ? {
+	...parsed,
+	_idempotentReplay: true
+} : parsed;
 /**
-* tRPC middleware that caches mutation results in `mcp_idempotent_responses`.
+* Wraps `handler` with idempotent-response caching keyed on `path`.
+*
+* Semantics (unchanged from the retired tRPC middleware):
 *
-* On every mutation call where the procedure path has a registered
-* `IdempotencyKeySpec`:
+* 1. Look up the `IdempotencyKeySpec` registered for `path`, and
+*    derive a key from `params` (already decoded — strict registration
+*    guarantees no key was stripped). No registered spec, or a `null`
+*    key, runs `handler` untouched with nothing cached.
+* 2. Cache HIT — `DataReader.findIdempotentResponse` returns the stored
+*    JSON. A row that parses falls through to step 2a; a row that fails
+*    to parse (corrupt or truncated) is treated as step 3, a cache MISS —
+*    it is not a reason to fail the call.
+* 2a. The parsed value is merged with `_idempotentReplay: true` for an
+*    object payload (a non-object payload passes through unchanged).
+*    `handler` does not run.
+* 3. Cache MISS — run `handler`, then persist the result via
+*    `DataStore.recordIdempotentResponse` best-effort: a persistence
+*    failure (or a cache-lookup failure) never surfaces to the caller, it
+*    is swallowed so a transient DB failure doesn't turn into a tool
+*    error.
 *
-* 1. Derive the idempotency key from the raw input.
-* 2. Look up `DataReader.findIdempotentResponse(path, key)`.
-*    - Cache HIT  → return the stored JSON result immediately (no handler).
-*    - Cache MISS → call `next()` to run the handler, then persist the result
-*      via `DataStore.recordIdempotentResponse`. Persistence errors are
-*      swallowed (best-effort) so a transient DB failure doesn't surface to
-*      the caller as a tool error.
+* The combinator reads no ambient state — `path` and `params` are its
+* only inputs beyond the `DataReader` / `DataStore` services it adds to
+* `handler`'s requirements.
 *
-* Procedures without a registered spec, or where key derivation returns
-* `null`, pass straight through to `next()` without any caching.
+* @public
 */
-const idempotent = middleware(async (opts) => {
-	const { ctx, path, type, getRawInput, next } = opts;
-	if (type !== "mutation") return next();
+const withIdempotency = (path, handler) => (params) => Effect.gen(function* () {
 	const spec = keySpecByPath.get(path);
-	if (!spec) return next();
-	const rawInput = await getRawInput();
-	const key = spec.deriveKey(rawInput);
-	if (key === null) return next();
-	const cached = await ctx.runtime.runPromise(Effect.gen(function* () {
-		return yield* (yield* DataReader).findIdempotentResponse(path, key);
-	}));
+	const key = spec === void 0 ? null : spec.deriveKey(params);
+	if (key === null) return yield* handler(params);
+	const cached = yield* (yield* DataReader).findIdempotentResponse(path, key).pipe(Effect.orElseSucceed(() => Option.none()));
 	if (Option.isSome(cached)) {
-		const parsed = JSON.parse(cached.value);
-		return {
-			ok: true,
-			data: parsed !== null && typeof parsed === "object" ? {
-				...parsed,
-				_idempotentReplay: true
-			} : parsed,
-			marker: "middlewareMarker",
-			ctx
-		};
+		const parsed = yield* Effect.try(() => JSON.parse(cached.value)).pipe(Effect.map(Option.some), Effect.orElseSucceed(() => Option.none()));
+		if (Option.isSome(parsed)) return withReplayMarker(parsed.value);
 	}
-	const result = await next();
-	if (result.ok) await ctx.runtime.runPromise(Effect.gen(function* () {
-		yield* (yield* DataStore).recordIdempotentResponse({
-			procedurePath: path,
-			key,
-			resultJson: JSON.stringify(result.data),
-			createdAt: (/* @__PURE__ */ new Date()).toISOString()
-		});
-	}).pipe(Effect.orElseSucceed(() => void 0)));
+	const result = yield* handler(params);
+	yield* (yield* DataStore).recordIdempotentResponse({
+		procedurePath: path,
+		key,
+		resultJson: JSON.stringify(result),
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	}).pipe(Effect.orElseSucceed(() => void 0));
 	return result;
 });
-/** Drop-in replacement for `publicProcedure` on idempotent mutations. */
-const idempotentProcedure = publicProcedure.use(idempotent);
 
 //#endregion
-export { idempotencyKeys, idempotentProcedure };
+export { idempotencyKeys, withIdempotency };