@vitest-agent/mcp 4.1.1 → 4.2.0

package/index.d.ts

@@ -166,7 +166,7 @@ export declare const PromptsLayer: Layer.Layer<never, never, McpSession>;
  *
  * @public
  */
-export declare const registerStrictToolkit: <Tools extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<Tools>) => Layer.Layer<never, never, Tool.HandlersFor<Tools> | Exclude<Tool.HandlerServices<Tools>, McpSchema.McpServerClient>>;
+export declare const registerStrictToolkit: <Tools extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<Tools>) => Layer.Layer<never, never, Tool.HandlersFor<Tools> | Exclude<Tool.HandlerServices<Tools>, McpSchema.McpRequestContext>>;
 //#endregion
 //#region src/server.d.ts
 /**
@@ -184,10 +184,33 @@ interface ServerLayerOptions {
   /** The `serverInfo.version` advertised on initialize (the package version in production). */
   readonly version: string;
 }
+/**
+ * The agent-facing orientation every client receives: in the `initialize`
+ * result on the stateful protocols and in the `server/discover` result on
+ * `2026-07-28`. Says what the server is for, which tool to reach for first,
+ * and how to read a result; the one-line human summary stays on
+ * `serverInfo.description`.
+ *
+ * @public
+ */
+export declare const SERVER_INSTRUCTIONS: string;
 /**
  * The server layer: every tool registered under the strict contract, plus
- * the six framing prompts, over `McpServer.layerStdio`. `protocols` is newest-first because the registry
- * falls back to `protocols[0]` for a client offering an unknown version.
+ * the six framing prompts, over `McpServer.layerStdio`.
+ *
+ * `protocols` order is load-bearing (rc.116 `unstable/ai/internal/mcpRuntime.ts`):
+ * a request carrying `_meta["io.modelcontextprotocol/protocolVersion"]`
+ * routes to that adapter, an `initialize` matches the STATEFUL adapters
+ * only, and anything else with no session falls to `protocols[0]`. The
+ * stateless `2026-07-28` adapter (SEP-2575: no handshake, no session,
+ * `server/discover` instead of `initialize`) is listed first, then the two
+ * newest stateful ones — every shipping client (Claude Code's default stdio
+ * session, Copilot, Cursor, the Inspector) still opens with `initialize`,
+ * which a server offering ONLY `2026-07-28` answers with
+ * `METHOD_NOT_FOUND`. At most one stateless adapter is allowed; a second
+ * fails the layer with `Cause.IllegalArgumentError`, which is why the
+ * error channel is `orDie`d: `protocols` is a static literal, so a failure
+ * there is an implementer-time defect.
  *
  * @param options - the advertised server version
  * @public

package/index.js

@@ -30,7 +30,7 @@ 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 { SERVER_INSTRUCTIONS, ServerLayer } from "./server.js";
 import { CURRENT_MCP_VERSION } from "./version.js";
 
-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 };
+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, SERVER_INSTRUCTIONS, 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/mcp",
-	"version": "4.1.1",
+	"version": "4.2.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": [
@@ -43,11 +43,11 @@
 		"vitest-agent-mcp": "bin/vitest-agent-mcp.js"
 	},
 	"dependencies": {
-		"@effect/platform-node": "4.0.0-rc.115",
-		"@effect/sql-sqlite-node": "4.0.0-rc.115",
-		"@vitest-agent/engine": "0.2.1",
-		"@vitest-agent/sdk": "5.1.0",
-		"effect": "4.0.0-rc.115"
+		"@effect/platform-node": "4.0.0-rc.116",
+		"@effect/sql-sqlite-node": "4.0.0-rc.116",
+		"@vitest-agent/engine": "0.2.2",
+		"@vitest-agent/sdk": "5.1.1",
+		"effect": "4.0.0-rc.116"
 	},
 	"peerDependencies": {
 		"vitest": "^5.0.0"

package/register-toolkit.js

@@ -1,7 +1,8 @@
 import { RenderText } from "./annotations.js";
 import { buildUnexpectedToolErrorEnvelope } from "./utils/tool-error-envelope.js";
-import { Cause, Context, Effect, Layer, Option, Result, Schema, Sink, Stream } from "effect";
-import { AiError, McpSchema, McpServer, Tool } from "effect/unstable/ai";
+import { Cause, Context, Effect, ErrorReporter, Layer, Option, References, Result, Schema, Stream } from "effect";
+import { AiError, McpSchema, McpServer, Tool, Toolkit } from "effect/unstable/ai";
+import { HttpServerRequest } from "effect/unstable/http";
 
 //#region src/register-toolkit.ts
 const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -214,13 +215,32 @@ const formatUnknownKeys = (levels) => levels.map((level) => {
 * primitive encoded result is omitted rather than sent through as-is.
 */
 const toStructuredContent = (value) => isPlainObject(value) ? value : void 0;
-const declaredFailureResult = (message) => new McpSchema.CallToolResult({
+const toolErrorResult = (message) => new McpSchema.CallToolResult({
 	isError: true,
 	content: [{
 		type: "text",
 		text: message
 	}]
 });
+const toolResultContent = (encoded) => encoded === void 0 ? [] : [{
+	type: "text",
+	text: JSON.stringify(encoded)
+}];
+const omitRequestServices = Context.omit(McpSchema.McpRequestContext, McpSchema.McpServerClient, HttpServerRequest.HttpServerRequest, References.CurrentLogLevel);
+const isParameterValidationError = (error) => AiError.isAiError(error) && error.reason._tag === "ToolParameterValidationError";
+/**
+* The input JSON Schema document as rc.116's `toolInputJsonSchema` builds it
+* (`Schema.toJsonSchemaDocument` with `onExcessProperty` following the
+* tool's strict mode, definitions attached as `$defs`); the top-level `$ref`
+* hoist happens in `inlineRootRefs` via `strictifyJsonSchema`.
+*/
+const toolInputJsonSchema = (schema, strict) => {
+	const document = Schema.toJsonSchemaDocument(schema, { onExcessProperty: strict ? "error" : "ignore" });
+	return Object.keys(document.definitions).length === 0 ? document.schema : {
+		...document.schema,
+		$defs: document.definitions
+	};
+};
 const envelopeResult = (toolName, err) => {
 	const envelope = buildUnexpectedToolErrorEnvelope(toolName, err);
 	return new McpSchema.CallToolResult({
@@ -234,26 +254,64 @@ const envelopeResult = (toolName, err) => {
 };
 /**
 * Register every tool of `toolkit` with the ambient `McpServer` under the
-* strict contract described in the module docs.
+* strict contract described in the module docs. A port of rc.116's
+* `McpServer.registerToolkit`; the deviations are enumerated in the module
+* header.
 *
 * @internal
 */
 const registerStrictToolkitEffect = Effect.fnUntraced(function* (toolkit) {
 	const registry = yield* McpServer.McpServer;
-	const built = yield* toolkit;
-	const services = yield* Effect.context();
+	const built = yield* toolkit.pipe(Effect.updateContext((context) => {
+		const services = new Map(context.mapUnsafe);
+		for (const tool of Object.values(toolkit.tools)) {
+			const handler = services.get(tool.id);
+			if (handler !== void 0) services.set(tool.id, {
+				...handler,
+				context: omitRequestServices(handler.context)
+			});
+		}
+		return Context.makeUnsafe(services);
+	}));
+	const services = omitRequestServices(yield* Effect.context());
+	const reportCause = (cause) => Effect.provideContext(ErrorReporter.report(cause), services);
+	const registrations = [];
 	for (const tool of Object.values(built.tools)) {
+		const internalToolError = (cause) => {
+			const failure = Cause.findFail(cause);
+			return Result.isFailure(failure) && !Cause.hasDies(cause) ? Effect.failCause(failure.failure) : Effect.logError(`tool ${tool.name} failed`, cause).pipe(Effect.andThen(reportCause(cause)), Effect.as(envelopeResult(tool.name, Result.isSuccess(failure) ? failure.success.error : Cause.squash(cause))));
+		};
+		const strict = Tool.getStrictMode(tool) === true;
+		const rawJsonSchema = Tool.isDynamic(tool) ? tool.jsonSchema : void 0;
+		if (strict && rawJsonSchema !== void 0) return yield* Effect.die(`McpServer cannot strictly validate the raw JSON Schema for tool '${tool.name}'; use an Effect Schema instead`);
+		const decodeOptions = strict ? { onExcessProperty: "error" } : void 0;
 		const annotations = tool.annotations;
 		const render = Context.get(annotations, RenderText);
-		const isDeclaredFailure = Schema.is(tool.failureSchema);
 		const toolMeta = Context.getOrUndefined(annotations, Tool.Meta);
+		const isDeclaredFailure = Schema.is(tool.failureSchema);
+		const encodeFailure = Schema.encodeUnknownEffect(tool.failureSchema);
+		const declaredFailureResult = (error) => error instanceof Error ? Effect.succeed(toolErrorResult(error.message)) : Effect.map(encodeFailure(error), (encoded) => new McpSchema.CallToolResult({
+			isError: true,
+			content: toolResultContent(encoded)
+		}));
+		const handleCause = (cause) => {
+			const failure = Cause.findFail(cause);
+			if (Result.isSuccess(failure)) {
+				const error = failure.success.error;
+				const origin = Context.get(Cause.reasonAnnotations(failure.success), Toolkit.FailureOrigin);
+				if (origin === "parameters" && isParameterValidationError(error)) return Effect.fail(new McpSchema.InvalidParams({ message: error.reason.message }));
+				if (origin === "handler" && isDeclaredFailure(error)) return Effect.catchCause(declaredFailureResult(error), internalToolError);
+			}
+			return internalToolError(cause);
+		};
 		const outputJsonSchema = inlineRootRefs(Tool.getJsonSchemaFromSchema(tool.successSchema));
-		const outputSchema = outputJsonSchema.type === "object" ? yield* Schema.decodeUnknownEffect(McpSchema.ToolJsonSchema)(outputJsonSchema).pipe(Effect.orDie) : void 0;
-		const servedInput = strictifyJsonSchema(Tool.getJsonSchema(tool));
-		const inputSchema = yield* Schema.decodeUnknownEffect(McpSchema.ToolJsonSchema)(servedInput).pipe(Effect.orDie);
+		const outputSchema = outputJsonSchema.type === "object" ? yield* Schema.decodeUnknownEffect(McpSchema.ToolOutputJson)(outputJsonSchema).pipe(Effect.orDie) : void 0;
+		const servedInput = strictifyJsonSchema(rawJsonSchema ?? toolInputJsonSchema(tool.parametersSchema, strict));
+		const inputSchema = yield* Schema.decodeUnknownEffect(McpSchema.ToolJson)(servedInput).pipe(Effect.orDie);
+		const description = Tool.getDescription(tool);
 		const mcpTool = new McpSchema.Tool({
 			name: tool.name,
-			description: Tool.getDescription(tool),
+			...description === void 0 ? {} : { description },
 			inputSchema,
 			...outputSchema === void 0 ? {} : { outputSchema },
 			annotations: {
@@ -263,38 +321,27 @@ const registerStrictToolkitEffect = Effect.fnUntraced(function* (toolkit) {
 				idempotentHint: Context.get(annotations, Tool.Idempotent),
 				openWorldHint: Context.get(annotations, Tool.OpenWorld)
 			},
-			_meta: toolMeta
+			...toolMeta === void 0 ? {} : { _meta: toolMeta }
 		});
-		yield* registry.addTool({
+		registrations.push({
 			tool: mcpTool,
 			annotations,
 			handle(payload) {
 				const raw = payload ?? {};
 				const unknownKeys = collectUnknownKeys(raw, servedInput);
 				if (unknownKeys.length > 0) return Effect.fail(new McpSchema.InvalidParams({ message: formatUnknownKeys(unknownKeys) }));
-				return built.handle(tool.name, raw).pipe(Stream.unwrap, Stream.run(Sink.last()), Effect.flatMap(Effect.fromOption), Effect.map((result) => {
-					const encoded = result.encodedResult;
-					const text = render?.(encoded) ?? JSON.stringify(encoded);
-					return new McpSchema.CallToolResult({
-						isError: false,
-						structuredContent: toStructuredContent(encoded),
-						content: encoded === void 0 ? [] : [{
-							type: "text",
-							text
-						}]
-					});
-				}), Effect.provideContext(services), Effect.catchCause((cause) => {
-					const failure = Cause.findError(cause);
-					if (Result.isFailure(failure) && !Cause.hasDies(cause)) return Effect.failCause(failure.failure);
-					const err = Result.isSuccess(failure) ? failure.success : Cause.squash(cause);
-					if (AiError.isAiError(err) && err.reason._tag === "ToolParameterValidationError") return Effect.fail(new McpSchema.InvalidParams({ message: err.reason.message }));
-					const logged = Effect.logError(`tool ${tool.name} failed`, cause);
-					if (isDeclaredFailure(err) && err instanceof Error) return Effect.as(logged, declaredFailureResult(err.message));
-					return Effect.as(logged, envelopeResult(tool.name, err));
-				}));
+				return built.handle(tool.name, raw, void 0, decodeOptions).pipe(Stream.unwrap, Stream.runLast, Effect.flatMap(Effect.fromOption), Effect.flatMap((result) => result.isFailure && result.failureOrigin !== "handler" ? Effect.failCause(Cause.annotate(Cause.fail(result.result), Context.make(Toolkit.FailureOrigin, result.failureOrigin ?? "result"))) : Effect.succeed(new McpSchema.CallToolResult({
+					isError: result.isFailure,
+					structuredContent: result.isFailure ? void 0 : toStructuredContent(result.encodedResult),
+					content: result.isFailure || result.encodedResult === void 0 ? toolResultContent(result.encodedResult) : [{
+						type: "text",
+						text: render?.(result.encodedResult) ?? JSON.stringify(result.encodedResult)
+					}]
+				}))), Effect.catchCause(handleCause), Effect.provideContext(services));
 			}
 		});
 	}
+	for (const registration of registrations) yield* registry.addTool(registration);
 });
 /**
 * A layer that registers `toolkit` with the strict contract. Same shape

package/server.js

@@ -5,16 +5,42 @@ import { Layer, Logger } from "effect";
 import { McpProtocol, McpServer } from "effect/unstable/ai";
 
 //#region src/server.ts
+/** One-line human summary agents see on `serverInfo.description`. */
+const DESCRIPTION = "vitest-agent MCP server: test results, coverage, history and TDD lifecycle for LLM coding agents.";
 /**
-* One-line pointer agents see on `serverInfo.description`. `instructions`
-* cannot be set through `McpServer.layerStdio` at rc.115, so this is the
-* at-initialize orientation hook.
+* The agent-facing orientation every client receives: in the `initialize`
+* result on the stateful protocols and in the `server/discover` result on
+* `2026-07-28`. Says what the server is for, which tool to reach for first,
+* and how to read a result; the one-line human summary stays on
+* `serverInfo.description`.
+*
+* @public
 */
-const DESCRIPTION = "vitest-agent MCP server: test results, coverage, history and TDD lifecycle for LLM coding agents. Call the `help` tool first for the full tool reference.";
+const SERVER_INSTRUCTIONS = [
+	"vitest-agent serves the test landscape of one Vitest project to LLM coding agents: run results, failure detail and history, coverage, flakiness, and the TDD lifecycle (tasks, goals, behaviors, phase transitions, hypotheses, notes).",
+	"Call the help tool first for the full tool reference; triage_brief orients on the current landscape; run_tests executes Vitest and persists the run so every query tool reads it back.",
+	"Every input is strict at every object level: an unknown key is rejected with a message naming the unrecognized key(s) and the accepted params, so fix the call rather than retrying it.",
+	"Every successful result carries the typed object in structuredContent and a text rendering (markdown where the tool renders one, otherwise the same JSON) in content[0].text; read structuredContent when you need fields.",
+	"An expected domain error is NOT an isError result: it is a normal result whose structuredContent has ok: false and an error object. tdd_goal and tdd_behavior put _tag, the failing ids and a remediation naming the tool to call next in that object; register_agent puts a code and a message in it, plus existingAgentId or expectedPrefix when the code calls for one.",
+	"An isError result means the call itself failed: invalid params (bare text in content[0].text, no structuredContent) or an unexpected crash inside the tool (structuredContent is an UnexpectedToolError envelope with ok: false and a remediation). Read the message and fix the call."
+].join("\n");
 /**
 * The server layer: every tool registered under the strict contract, plus
-* the six framing prompts, over `McpServer.layerStdio`. `protocols` is newest-first because the registry
-* falls back to `protocols[0]` for a client offering an unknown version.
+* the six framing prompts, over `McpServer.layerStdio`.
+*
+* `protocols` order is load-bearing (rc.116 `unstable/ai/internal/mcpRuntime.ts`):
+* a request carrying `_meta["io.modelcontextprotocol/protocolVersion"]`
+* routes to that adapter, an `initialize` matches the STATEFUL adapters
+* only, and anything else with no session falls to `protocols[0]`. The
+* stateless `2026-07-28` adapter (SEP-2575: no handshake, no session,
+* `server/discover` instead of `initialize`) is listed first, then the two
+* newest stateful ones — every shipping client (Claude Code's default stdio
+* session, Copilot, Cursor, the Inspector) still opens with `initialize`,
+* which a server offering ONLY `2026-07-28` answers with
+* `METHOD_NOT_FOUND`. At most one stateless adapter is allowed; a second
+* fails the layer with `Cause.IllegalArgumentError`, which is why the
+* error channel is `orDie`d: `protocols` is a static literal, so a failure
+* there is an implementer-time defect.
 *
 * @param options - the advertised server version
 * @public
@@ -23,12 +49,13 @@ const ServerLayer = (options) => Layer.mergeAll(registerStrictToolkit(Kit).pipe(
 	name: "vitest-agent",
 	version: options.version,
 	description: DESCRIPTION,
+	instructions: SERVER_INSTRUCTIONS,
 	protocols: [
+		McpProtocol.v2026_07_28,
 		McpProtocol.v2025_11_25,
-		McpProtocol.v2025_06_18,
-		McpProtocol.v2025_03_26
+		McpProtocol.v2025_06_18
 	]
 })), Layer.provide(Layer.succeed(Logger.LogToStderr, true)), Layer.orDie);
 
 //#endregion
-export { ServerLayer };
+export { SERVER_INSTRUCTIONS, ServerLayer };

package/version.js

@@ -7,7 +7,7 @@
 *
 * @public
 */
-const CURRENT_MCP_VERSION = "4.1.1";
+const CURRENT_MCP_VERSION = "4.2.0";
 
 //#endregion
 export { CURRENT_MCP_VERSION };