@vitest-agent/mcp 1.0.0

package/tools/triage-brief.js

@@ -0,0 +1,42 @@
+import { publicProcedure } from "../context.js";
+import { formatTriageEffect } from "@vitest-agent/sdk";
+import { Effect, Schema } from "effect";
+
+//#region src/tools/triage-brief.ts
+/**
+* `triage_brief` MCP tool — Schema-driven implementation.
+*
+* The structured payload is a thin envelope around the markdown
+* rendering since this is a narrative tool — there's no underlying
+* record set the agent would parse separately. The `hasContent` flag
+* lets callers branch on the cold-start case without grepping prose.
+*
+* @packageDocumentation
+*/
+const TriageBriefResult = Schema.Struct({
+	hasContent: Schema.Boolean.annotations({ description: "`false` when no orientation signal is available yet (run tests to populate)." }),
+	markdown: Schema.String.annotations({ description: "Pre-rendered markdown brief or the empty-state message." })
+}).annotations({
+	identifier: "TriageBriefResult",
+	title: "triage_brief result",
+	description: "Orientation triage envelope. Branch on `hasContent` for cold-start; consume `markdown` for rendering."
+});
+const triageBrief = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({
+	project: Schema.optional(Schema.String),
+	maxLines: Schema.optional(Schema.Number)
+}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const md = yield* formatTriageEffect({
+		...input.project !== void 0 && { project: input.project },
+		...input.maxLines !== void 0 && { maxLines: input.maxLines }
+	});
+	return md.length > 0 ? {
+		hasContent: true,
+		markdown: md
+	} : {
+		hasContent: false,
+		markdown: "No orientation signal yet — run tests to populate the database."
+	};
+})));
+
+//#endregion
+export { TriageBriefResult, triageBrief };

package/tools/turn-search.js

@@ -0,0 +1,60 @@
+import { publicProcedure } from "../context.js";
+import { DataReader } from "@vitest-agent/sdk";
+import { Effect, ParseResult, Schema } from "effect";
+
+//#region src/tools/turn-search.ts
+/**
+* `turn_search` MCP tool — Schema-driven implementation.
+*
+* @packageDocumentation
+*/
+const TurnRow = Schema.Struct({
+	id: Schema.Number.annotations({ description: "Numeric primary key of this turn row." }),
+	sessionId: Schema.Number.annotations({ description: "Owning `sessions.id` (integer FK)." }),
+	turnNo: Schema.Number.annotations({ description: "Turn ordinal within the session (1-based)." }),
+	type: Schema.String.annotations({ description: "Turn category (`user_prompt`, `tool_call`, `tool_result`, `file_edit`, `hook_fire`, `note`, `hypothesis`)." }),
+	payload: Schema.String.annotations({ description: "Type-specific payload as a JSON-encoded string. Decode shape depends on `type`." }),
+	occurredAt: Schema.String.annotations({ description: "ISO-8601 timestamp the turn was recorded at." })
+}).annotations({
+	identifier: "TurnRow",
+	description: "One row from the turns log."
+});
+const TurnSearchResult = Schema.Struct({
+	count: Schema.Number.annotations({ description: "Number of matching turn rows returned." }),
+	turns: Schema.Array(TurnRow).annotations({ description: "Matching turns ordered by `occurredAt` ascending." })
+}).annotations({
+	identifier: "TurnSearchResult",
+	title: "turn_search result",
+	description: "Turn-log search results across all sessions, optionally filtered by session, time, type."
+});
+const formatTurnSearchMarkdown = (data) => {
+	if (data.turns.length === 0) return "No turns matched.";
+	const lines = ["# Turns", ""];
+	for (const t of data.turns) lines.push(`- session=${t.sessionId} turn=${t.turnNo} type=${t.type} at=${t.occurredAt}`);
+	return lines.join("\n");
+};
+const TurnSearchAsMarkdown = Schema.transformOrFail(TurnSearchResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatTurnSearchMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "TurnSearchAsMarkdown is one-way: markdown cannot be parsed back to TurnSearchResult."))
+});
+const turnSearch = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({
+	sessionId: Schema.optional(Schema.Number),
+	since: Schema.optional(Schema.String),
+	type: Schema.optional(Schema.Literal("user_prompt", "tool_call", "tool_result", "file_edit", "hook_fire", "note", "hypothesis")),
+	limit: Schema.optional(Schema.Number)
+}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const rows = yield* (yield* DataReader).searchTurns({
+		...input.sessionId !== void 0 && { sessionId: input.sessionId },
+		...input.since !== void 0 && { since: input.since },
+		...input.type !== void 0 && { type: input.type },
+		limit: input.limit ?? 100
+	});
+	return {
+		count: rows.length,
+		turns: rows
+	};
+})));
+
+//#endregion
+export { TurnSearchAsMarkdown, TurnSearchResult, turnSearch };

package/tools/wrapup-prompt.js

@@ -0,0 +1,49 @@
+import { publicProcedure } from "../context.js";
+import { formatWrapupEffect } from "@vitest-agent/sdk";
+import { Effect, Schema } from "effect";
+
+//#region src/tools/wrapup-prompt.ts
+/**
+* `wrapup_prompt` MCP tool — Schema-driven implementation.
+*
+* Same envelope shape as `triage_brief`: thin wrapper around the
+* markdown rendering with a `hasContent` discriminant for the empty
+* case.
+*
+* @packageDocumentation
+*/
+const WrapupPromptResult = Schema.Struct({
+	hasContent: Schema.Boolean.annotations({ description: "`false` when there is nothing to wrap up for the named session/kind." }),
+	kind: Schema.Literal("stop", "session_end", "pre_compact", "tdd_handoff", "user_prompt_nudge").annotations({ description: "Echo of the wrap-up kind that was rendered (defaulted to `session_end` when omitted)." }),
+	markdown: Schema.String.annotations({ description: "Pre-rendered wrap-up markdown or the empty-state message." })
+}).annotations({
+	identifier: "WrapupPromptResult",
+	title: "wrapup_prompt result",
+	description: "Wrap-up envelope. Branch on `hasContent` for the empty case; consume `markdown` for rendering."
+});
+const wrapupPrompt = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({
+	sessionId: Schema.optional(Schema.Number),
+	chatId: Schema.optional(Schema.String),
+	kind: Schema.optional(Schema.Literal("stop", "session_end", "pre_compact", "tdd_handoff", "user_prompt_nudge")),
+	userPromptHint: Schema.optional(Schema.String)
+}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const kind = input.kind ?? "session_end";
+	const md = yield* formatWrapupEffect({
+		...input.sessionId !== void 0 && { sessionId: input.sessionId },
+		...input.chatId !== void 0 && { chatId: input.chatId },
+		kind,
+		...input.userPromptHint !== void 0 && { userPromptHint: input.userPromptHint }
+	});
+	return md.length > 0 ? {
+		hasContent: true,
+		kind,
+		markdown: md
+	} : {
+		hasContent: false,
+		kind,
+		markdown: "Nothing to wrap up."
+	};
+})));
+
+//#endregion
+export { WrapupPromptResult, wrapupPrompt };

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}

package/utils/effect-to-zod.js

@@ -0,0 +1,81 @@
+import { JSONSchema } from "effect";
+import { z } from "zod";
+
+//#region src/utils/effect-to-zod.ts
+/**
+* Convert an Effect `Schema.Schema<A, I, never>` to a zod schema by
+* serializing it to JSON Schema (`JSONSchema.make`) and ingesting the
+* result via zod 4's `z.fromJSONSchema`.
+*
+* Trade-offs:
+*   - Effect-Schema-only refinements (custom predicates, Brand types)
+*     erase to plain JSON Schema primitives during the round-trip,
+*     so the resulting zod schema does not enforce them. Tools that
+*     need refinement enforcement at the MCP boundary should declare
+*     zod directly.
+*   - `Schema.NullOr(...)` round-trips correctly via JSON Schema's
+*     `oneOf` / nullable representation that zod understands.
+*   - `z.fromJSONSchema` is marked experimental in zod 4. The bridge
+*     contains a smoke-test in the corresponding test file so an
+*     incompatible upgrade surfaces immediately instead of in
+*     production tool registrations.
+*
+* Implementation note: zod 4's `z.fromJSONSchema` does not resolve
+* `$ref` lookups into `$defs` — every `{ $ref: "#/$defs/X" }` it
+* encounters throws "Reference not found". Effect's `JSONSchema.make`
+* emits a `$ref`-and-`$defs` representation whenever a Schema carries
+* an `identifier` annotation. The bridge therefore inlines every
+* `$ref` in the document before handing it to zod (recursive
+* substitution, then drop `$defs`). The schemas don't use
+* `Schema.suspend`, so the substitution is acyclic.
+*
+* MCP SDK constraint: `outputSchema` must normalise to a Zod object
+* schema (`normalizeObjectSchema` returns `undefined` for unions, then
+* `safeParseAsync(undefined, ...)` crashes with "Cannot read properties
+* of undefined (reading '_zod')"). When the resulting zod schema is not
+* object-typed (e.g. came from `Schema.Union` of discriminated
+* variants), the bridge wraps it in a permissive `z.object({}).catchall(z.unknown())`
+* so the SDK accepts it. The structured content the tool emits still
+* conforms to the original Effect Schema; consumers just don't get a
+* rich JSON Schema for the union in the tool listing. Restructure the
+* source schema as a single `Schema.Struct` with a discriminator field
+* if the rich listing matters.
+*/
+const effectToZodSchema = (schema) => {
+	const inlined = inlineAllRefs(JSONSchema.make(schema));
+	const zodSchema = z.fromJSONSchema(inlined);
+	if (isObjectLike(zodSchema)) return zodSchema;
+	return z.object({}).catchall(z.unknown());
+};
+const isObjectLike = (schema) => {
+	const def = schema._zod?.def;
+	return def?.type === "object" || def?.shape !== void 0;
+};
+const REF_PREFIX = "#/$defs/";
+/**
+* Walk a JSON Schema tree and replace every `$ref: "#/$defs/X"` node
+* with the contents of `$defs.X`, recursively. The `$defs` table is
+* dropped from the returned root.
+*/
+const inlineAllRefs = (root) => {
+	const defs = root.$defs ?? {};
+	const visit = (value) => {
+		if (Array.isArray(value)) return value.map(visit);
+		if (value === null || typeof value !== "object") return value;
+		const obj = value;
+		if (typeof obj.$ref === "string" && obj.$ref.startsWith(REF_PREFIX)) {
+			const target = defs[obj.$ref.slice(8)];
+			if (target !== void 0) return visit(target);
+		}
+		const out = {};
+		for (const [k, v] of Object.entries(obj)) {
+			if (k === "$defs") continue;
+			out[k] = visit(v);
+		}
+		return out;
+	};
+	return visit(root);
+};
+
+//#endregion
+export { effectToZodSchema };