@kirrosh/zond 0.9.5 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.9.5",
+  "version": "0.12.0",
   "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",

package/src/core/generator/index.ts

@@ -12,3 +12,4 @@ export { compressEndpointsWithSchemas, buildGenerationGuide } from "./guide-buil
 export type { GuideOptions } from "./guide-builder.ts";
 export type { EndpointWarning, WarningCode } from "./endpoint-warnings.ts";
 export type { EndpointInfo, ResponseInfo, GenerateOptions, SecuritySchemeInfo, CrudGroup } from "./types.ts";
+export { generateSuites, generateStep, detectCrudGroups, generateCrudSuite, findUnresolvedVars } from "./suite-generator.ts";

package/src/core/generator/serializer.ts

@@ -34,6 +34,7 @@ export interface RawStep {
 
 export interface RawSuite {
   name: string;
+  tags?: string[];
   folder?: string;
   fileStem?: string;
   base_url?: string;
@@ -48,6 +49,9 @@ export interface RawSuite {
 export function serializeSuite(suite: RawSuite): string {
   const lines: string[] = [];
   lines.push(`name: ${yamlScalar(suite.name)}`);
+  if (suite.tags && suite.tags.length > 0) {
+    lines.push(`tags: [${suite.tags.join(", ")}]`);
+  }
   if (suite.base_url) {
     lines.push(`base_url: ${yamlScalar(suite.base_url)}`);
   }

package/src/core/generator/suite-generator.ts

@@ -0,0 +1,413 @@
+import type { OpenAPIV3 } from "openapi-types";
+import type { EndpointInfo, SecuritySchemeInfo, CrudGroup } from "./types.ts";
+import type { RawSuite, RawStep } from "./serializer.ts";
+import { generateFromSchema } from "./data-factory.ts";
+import { groupEndpointsByTag } from "./chunker.ts";
+
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+
+/** Convert OpenAPI path params {param} to test interpolation {{param}} */
+function convertPath(path: string): string {
+  return path.replace(/\{([^}]+)\}/g, "{{$1}}");
+}
+
+function slugify(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function getExpectedStatus(ep: EndpointInfo): number {
+  const success = ep.responses.find(r => r.statusCode >= 200 && r.statusCode < 300);
+  if (success) return success.statusCode;
+  if (ep.responses.length > 0) return ep.responses[0].statusCode;
+  return 200;
+}
+
+function getSuccessSchema(ep: EndpointInfo): OpenAPIV3.SchemaObject | undefined {
+  return ep.responses.find(r => r.statusCode >= 200 && r.statusCode < 300)?.schema;
+}
+
+function getBodyAssertions(ep: EndpointInfo): Record<string, Record<string, string>> | undefined {
+  const schema = getSuccessSchema(ep);
+  if (!schema) return undefined;
+
+  if (schema.type === "array") {
+    return { _body: { type: "array" } };
+  }
+
+  if (schema.properties) {
+    const assertions: Record<string, Record<string, string>> = {};
+    const props = Object.keys(schema.properties).slice(0, 5);
+    for (const prop of props) {
+      assertions[prop] = { exists: "true" };
+    }
+    return Object.keys(assertions).length > 0 ? assertions : undefined;
+  }
+
+  return undefined;
+}
+
+function getAuthHeaders(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+): Record<string, string> | undefined {
+  if (ep.security.length === 0) return undefined;
+
+  for (const secName of ep.security) {
+    const scheme = schemes.find(s => s.name === secName);
+    if (!scheme) continue;
+
+    if (scheme.type === "http" && scheme.scheme === "bearer") {
+      return { Authorization: "Bearer {{auth_token}}" };
+    }
+    if (scheme.type === "apiKey" && scheme.in === "header" && scheme.apiKeyName) {
+      return { [scheme.apiKeyName]: "{{api_key}}" };
+    }
+  }
+
+  return undefined;
+}
+
+function getRequiredQueryParams(ep: EndpointInfo): Record<string, unknown> | undefined {
+  const queryParams = ep.parameters.filter(p => p.in === "query" && p.required);
+  if (queryParams.length === 0) return undefined;
+
+  const query: Record<string, unknown> = {};
+  for (const p of queryParams) {
+    if (p.schema) {
+      query[p.name] = generateFromSchema(p.schema as OpenAPIV3.SchemaObject, p.name);
+    } else {
+      query[p.name] = "{{$randomString}}";
+    }
+  }
+  return query;
+}
+
+/** Check if all endpoints share the same auth headers → suite-level */
+function getSuiteHeaders(
+  endpoints: EndpointInfo[],
+  schemes: SecuritySchemeInfo[],
+): Record<string, string> | undefined {
+  if (endpoints.length === 0) return undefined;
+
+  const headerSets = endpoints.map(ep => getAuthHeaders(ep, schemes));
+  const first = headerSets[0];
+  if (!first) return undefined;
+
+  const firstJson = JSON.stringify(first);
+  const allSame = headerSets.every(h => JSON.stringify(h) === firstJson);
+  return allSame ? first : undefined;
+}
+
+/** Find the best field to capture from POST response (for CRUD chains) */
+function getCaptureField(ep: EndpointInfo): string {
+  const schema = getSuccessSchema(ep);
+  if (schema?.properties) {
+    if ("id" in schema.properties) return "id";
+    for (const [name, propSchema] of Object.entries(schema.properties)) {
+      const s = propSchema as OpenAPIV3.SchemaObject;
+      if (s.type === "integer" || s.format === "uuid") return name;
+    }
+  }
+  return "id";
+}
+
+// ──────────────────────────────────────────────
+// Public API
+// ──────────────────────────────────────────────
+
+/** Generate a single test step from an EndpointInfo */
+export function generateStep(
+  ep: EndpointInfo,
+  securitySchemes: SecuritySchemeInfo[],
+): RawStep {
+  const method = ep.method.toUpperCase();
+  const name = ep.operationId ?? ep.summary ?? `${method} ${ep.path}`;
+  const path = convertPath(ep.path);
+
+  const step: RawStep = {
+    name,
+    [method]: path,
+    expect: {
+      status: getExpectedStatus(ep),
+    },
+  };
+
+  const authHeaders = getAuthHeaders(ep, securitySchemes);
+  if (authHeaders) {
+    step.headers = authHeaders;
+  }
+
+  if (["POST", "PUT", "PATCH"].includes(method) && ep.requestBodySchema) {
+    step.json = generateFromSchema(ep.requestBodySchema);
+  }
+
+  const query = getRequiredQueryParams(ep);
+  if (query) {
+    step.query = query;
+  }
+
+  const body = getBodyAssertions(ep);
+  if (body) {
+    step.expect.body = body;
+  }
+
+  return step;
+}
+
+/** Detect CRUD groups from a list of endpoints */
+export function detectCrudGroups(endpoints: EndpointInfo[]): CrudGroup[] {
+  const groups: CrudGroup[] = [];
+  const postEndpoints = endpoints.filter(ep => ep.method.toUpperCase() === "POST" && !ep.deprecated);
+
+  for (const createEp of postEndpoints) {
+    const basePath = createEp.path;
+
+    // Find item endpoints: basePath/{param}
+    const itemPattern = new RegExp(`^${escapeRegex(basePath)}/\\{([^}]+)\\}$`);
+    const itemEndpoints = endpoints.filter(ep => !ep.deprecated && itemPattern.test(ep.path));
+
+    if (itemEndpoints.length === 0) continue;
+
+    const itemPath = itemEndpoints[0].path;
+    const idMatch = itemPath.match(/\{([^}]+)\}$/);
+    if (!idMatch) continue;
+    const idParam = idMatch[1];
+
+    const read = itemEndpoints.find(ep => ep.method.toUpperCase() === "GET");
+    if (!read) continue; // Minimum: POST + GET/{id}
+
+    const update = itemEndpoints.find(ep => ["PUT", "PATCH"].includes(ep.method.toUpperCase()));
+    const del = itemEndpoints.find(ep => ep.method.toUpperCase() === "DELETE");
+    const list = endpoints.find(ep => ep.method.toUpperCase() === "GET" && ep.path === basePath && !ep.deprecated);
+
+    const resource = basePath.split("/").filter(Boolean).pop() ?? "resource";
+
+    groups.push({
+      resource,
+      basePath,
+      itemPath,
+      idParam,
+      create: createEp,
+      list,
+      read,
+      update,
+      delete: del,
+    });
+  }
+
+  return groups;
+}
+
+/** Generate a CRUD chain suite from a CrudGroup */
+export function generateCrudSuite(
+  group: CrudGroup,
+  securitySchemes: SecuritySchemeInfo[],
+): RawSuite {
+  const captureField = group.create ? getCaptureField(group.create) : "id";
+  const captureVar = `${group.resource.replace(/s$/, "")}_id`;
+  const tests: RawStep[] = [];
+
+  const allEps = [group.create, group.list, group.read, group.update, group.delete].filter(Boolean) as EndpointInfo[];
+  const suiteHeaders = getSuiteHeaders(allEps, securitySchemes);
+
+  // 1. Create
+  if (group.create) {
+    const step = generateStep(group.create, securitySchemes);
+    if (!step.expect.body) step.expect.body = {};
+    step.expect.body[captureField] = { capture: captureVar };
+    if (suiteHeaders) delete (step as any).headers;
+    tests.push(step);
+  }
+
+  // 2. Read created
+  if (group.read) {
+    const step: RawStep = {
+      name: group.read.operationId ?? `Read created ${group.resource.replace(/s$/, "")}`,
+      GET: convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`),
+      expect: {
+        status: getExpectedStatus(group.read),
+        body: getBodyAssertions(group.read),
+      },
+    };
+    tests.push(step);
+  }
+
+  // 3. Update
+  if (group.update) {
+    const method = group.update.method.toUpperCase();
+    const step: RawStep = {
+      name: group.update.operationId ?? `Update ${group.resource.replace(/s$/, "")}`,
+      [method]: convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`),
+      expect: {
+        status: getExpectedStatus(group.update),
+      },
+    };
+    if (group.update.requestBodySchema) {
+      step.json = generateFromSchema(group.update.requestBodySchema);
+    }
+    tests.push(step);
+  }
+
+  // 4. Delete
+  if (group.delete) {
+    const step: RawStep = {
+      name: group.delete.operationId ?? `Delete ${group.resource.replace(/s$/, "")}`,
+      DELETE: convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`),
+      expect: {
+        status: getExpectedStatus(group.delete),
+      },
+    };
+    tests.push(step);
+
+    // 5. Verify deleted
+    if (group.read) {
+      tests.push({
+        name: `Verify ${group.resource.replace(/s$/, "")} deleted`,
+        GET: convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`),
+        expect: {
+          status: 404,
+        },
+      });
+    }
+  }
+
+  const suite: RawSuite = {
+    name: `${group.resource}-crud`,
+    tags: ["crud"],
+    fileStem: `crud-${slugify(group.resource)}`,
+    base_url: "{{base_url}}",
+    tests,
+  };
+
+  if (suiteHeaders) {
+    suite.headers = suiteHeaders;
+  }
+
+  return suite;
+}
+
+/** Find unresolved template variables in a suite (excluding known globals and captured vars) */
+export function findUnresolvedVars(suite: RawSuite): string[] {
+  const KNOWN = new Set(["base_url", "auth_token", "api_key"]);
+  const captured = new Set<string>();
+  for (const step of suite.tests) {
+    if (step.expect?.body) {
+      for (const val of Object.values(step.expect.body)) {
+        if (val && typeof val === "object" && "capture" in val) captured.add((val as any).capture);
+      }
+    }
+  }
+  const vars = new Set<string>();
+  const scan = (obj: unknown) => {
+    if (typeof obj === "string") {
+      for (const m of obj.matchAll(/\{\{([^$}][^}]*)\}\}/g)) {
+        if (!KNOWN.has(m[1]) && !captured.has(m[1])) vars.add(m[1]);
+      }
+    } else if (obj && typeof obj === "object") {
+      for (const v of Object.values(obj)) scan(v);
+    }
+  };
+  scan(suite);
+  return [...vars];
+}
+
+/** Main entry point: generate all suites from endpoints */
+export function generateSuites(opts: {
+  endpoints: EndpointInfo[];
+  securitySchemes: SecuritySchemeInfo[];
+}): RawSuite[] {
+  const { endpoints, securitySchemes } = opts;
+
+  // Filter deprecated
+  const active = endpoints.filter(ep => !ep.deprecated);
+
+  // 1. Detect CRUD groups
+  const crudGroups = detectCrudGroups(active);
+
+  // Collect endpoints consumed by CRUD groups
+  const crudEndpointKeys = new Set<string>();
+  for (const g of crudGroups) {
+    if (g.create) crudEndpointKeys.add(`${g.create.method.toUpperCase()} ${g.create.path}`);
+    if (g.list) crudEndpointKeys.add(`${g.list.method.toUpperCase()} ${g.list.path}`);
+    if (g.read) crudEndpointKeys.add(`${g.read.method.toUpperCase()} ${g.read.path}`);
+    if (g.update) crudEndpointKeys.add(`${g.update.method.toUpperCase()} ${g.update.path}`);
+    if (g.delete) crudEndpointKeys.add(`${g.delete.method.toUpperCase()} ${g.delete.path}`);
+  }
+
+  // Remaining endpoints (not in any CRUD group)
+  const remaining = active.filter(ep => !crudEndpointKeys.has(`${ep.method.toUpperCase()} ${ep.path}`));
+
+  const suites: RawSuite[] = [];
+
+  // 2. Group remaining by tag → smoke + smoke-unsafe
+  const byTag = groupEndpointsByTag(remaining);
+
+  for (const [tag, tagEndpoints] of byTag) {
+    const tagSlug = slugify(tag) || "api";
+
+    // GET endpoints → smoke suite
+    const getEndpoints = tagEndpoints.filter(ep => ep.method.toUpperCase() === "GET");
+    if (getEndpoints.length > 0) {
+      const tests = getEndpoints.map(ep => generateStep(ep, securitySchemes));
+      const headers = getSuiteHeaders(getEndpoints, securitySchemes);
+
+      const suite: RawSuite = {
+        name: `${tagSlug}-smoke`,
+        tags: ["smoke"],
+        fileStem: `smoke-${tagSlug}`,
+        base_url: "{{base_url}}",
+        tests,
+      };
+
+      if (headers) {
+        suite.headers = headers;
+        for (const t of tests) {
+          if (t.headers && JSON.stringify(t.headers) === JSON.stringify(headers)) {
+            delete (t as any).headers;
+          }
+        }
+      }
+
+      suites.push(suite);
+    }
+
+    // Non-GET endpoints → smoke-unsafe suite
+    const unsafeEndpoints = tagEndpoints.filter(ep => ep.method.toUpperCase() !== "GET");
+    if (unsafeEndpoints.length > 0) {
+      const tests = unsafeEndpoints.map(ep => generateStep(ep, securitySchemes));
+      const headers = getSuiteHeaders(unsafeEndpoints, securitySchemes);
+
+      const suite: RawSuite = {
+        name: `${tagSlug}-smoke-unsafe`,
+        tags: ["smoke", "unsafe"],
+        fileStem: `smoke-${tagSlug}-unsafe`,
+        base_url: "{{base_url}}",
+        tests,
+      };
+
+      if (headers) {
+        suite.headers = headers;
+        for (const t of tests) {
+          if (t.headers && JSON.stringify(t.headers) === JSON.stringify(headers)) {
+            delete (t as any).headers;
+          }
+        }
+      }
+
+      suites.push(suite);
+    }
+  }
+
+  // 3. CRUD suites
+  for (const group of crudGroups) {
+    suites.push(generateCrudSuite(group, securitySchemes));
+  }
+
+  return suites;
+}

package/src/core/runner/execute-run.ts

@@ -17,6 +17,7 @@ export interface ExecuteRunOptions {
   tag?: string[];
   envVars?: Record<string, string>;
   dryRun?: boolean;
+  rerunFilter?: Set<string>;  // "suite_name::test_name" keys to rerun
 }
 
 export interface ExecuteRunResult {
@@ -40,6 +41,17 @@ export async function executeRun(options: ExecuteRunOptions): Promise<ExecuteRun
     }
   }
 
+  // Rerun filter: keep only specific failed tests
+  if (options.rerunFilter && options.rerunFilter.size > 0) {
+    for (const suite of suites) {
+      suite.tests = suite.tests.filter(t => options.rerunFilter!.has(`${suite.name}::${t.name}`));
+    }
+    suites = suites.filter(s => s.tests.length > 0);
+    if (suites.length === 0) {
+      throw new Error("No matching tests found for rerun filter");
+    }
+  }
+
   // Safe mode: filter to GET-only tests
   if (safe) {
     for (const suite of suites) {

package/src/core/setup-api.ts

@@ -14,7 +14,7 @@ function toYaml(vars: Record<string, string>): string {
 }
 
 export interface SetupApiOptions {
-  name: string;
+  name?: string;
   spec?: string;
   dir?: string;
   envVars?: Record<string, string>;
@@ -29,13 +29,49 @@ export interface SetupApiResult {
   testPath: string;
   baseUrl: string;
   specEndpoints: number;
+  pathParams?: Record<string, string>;
 }
 
 export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult> {
-  const { name, spec, dbPath } = options;
+  const { spec, dbPath } = options;
 
   getDb(dbPath);
 
+  // Try to load and validate spec, extract base_url
+  let openapiSpec: string | null = null;
+  let baseUrl = "";
+  let endpointCount = 0;
+  const pathParams = new Map<string, string>();
+  let specTitle: string | undefined;
+  if (spec) {
+    const doc = await readOpenApiSpec(spec);
+    openapiSpec = spec;
+    if ((doc as any).servers?.[0]?.url) {
+      baseUrl = (doc as any).servers[0].url;
+    }
+    specTitle = (doc as any).info?.title;
+    const endpoints = extractEndpoints(doc);
+    endpointCount = endpoints.length;
+
+    // Collect unique path parameters with default values
+    for (const ep of endpoints) {
+      for (const param of (ep.parameters ?? []).filter(p => p.in === "path")) {
+        if (pathParams.has(param.name)) continue;
+        const schema = param.schema as any;
+        if (param.example !== undefined) pathParams.set(param.name, String(param.example));
+        else if (schema?.example !== undefined) pathParams.set(param.name, String(schema.example));
+        else if (schema?.type === "integer" || schema?.type === "number") pathParams.set(param.name, "1");
+        else pathParams.set(param.name, "example");
+      }
+    }
+  }
+
+  // Derive name: explicit > spec title > filename
+  const name = options.name
+    ?? specTitle?.replace(/[^a-zA-Z0-9_\-\.]/g, "-").toLowerCase()
+    ?? spec?.split(/[/\\]/).pop()?.replace(/\.\w+$/, "")
+    ?? "api";
+
   // Validate name uniqueness (or force-replace)
   const existing = findCollectionByNameOrId(name);
   if (existing) {
@@ -54,22 +90,13 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
   // Create directories
   mkdirSync(testPath, { recursive: true });
 
-  // Try to load and validate spec, extract base_url
-  let openapiSpec: string | null = null;
-  let baseUrl = "";
-  let endpointCount = 0;
-  if (spec) {
-    const doc = await readOpenApiSpec(spec);
-    openapiSpec = spec;
-    if ((doc as any).servers?.[0]?.url) {
-      baseUrl = (doc as any).servers[0].url;
-    }
-    endpointCount = extractEndpoints(doc).length;
-  }
-
   // Build environment variables
   const envVars: Record<string, string> = {};
   if (baseUrl) envVars.base_url = baseUrl;
+  // Add path parameter defaults (before user overrides)
+  for (const [k, v] of pathParams) {
+    if (!(k in envVars)) envVars[k] = v;
+  }
   if (options.envVars) {
     Object.assign(envVars, options.envVars);
   }
@@ -102,6 +129,8 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
     openapi_spec: openapiSpec ?? undefined,
   });
 
+  const pathParamsObj = pathParams.size > 0 ? Object.fromEntries(pathParams) : undefined;
+
   return {
     created: true,
     collectionId,
@@ -109,5 +138,6 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
     testPath: normalizedTestPath,
     baseUrl,
     specEndpoints: endpointCount,
+    ...(pathParamsObj ? { pathParams: pathParamsObj } : {}),
   };
 }

package/src/mcp/descriptions.ts

@@ -57,7 +57,9 @@ export const TOOL_DESCRIPTIONS = {
     "and return a focused test generation guide. For large APIs returns a chunking plan — " +
     "call again with tag parameter for each chunk. Use testsDir param to only generate for uncovered endpoints. " +
     "After generating YAML, use save_test_suites to save files, then run_tests to verify. " +
-    "Includes YAML format cheatsheet by default; pass includeFormat: false for subsequent tag chunks to save tokens.",
+    "Includes YAML format cheatsheet by default; pass includeFormat: false for subsequent tag chunks to save tokens. " +
+    "Use mode: 'generate' to auto-generate and save deterministic YAML test files (smoke + CRUD) without LLM. " +
+    "Default mode is 'generate'; use mode: 'guide' for the text-based generation guide.",
 
   ci_init:
     "Generate a CI/CD workflow file for running API tests automatically on push, PR, and schedule. " +

package/src/mcp/tools/generate-and-save.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { join } from "node:path";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import {
   readOpenApiSpec,
@@ -6,10 +7,14 @@ import {
   extractSecuritySchemes,
   scanCoveredEndpoints,
   filterUncoveredEndpoints,
+  serializeSuite,
+  generateSuites,
+  findUnresolvedVars,
 } from "../../core/generator/index.ts";
 import { compressEndpointsWithSchemas, buildGenerationGuide } from "../../core/generator/guide-builder.ts";
 import { planChunks, filterByTag } from "../../core/generator/chunker.ts";
 import { TOOL_DESCRIPTIONS } from "../descriptions.js";
+import { validateAndSave } from "./save-test-suite.ts";
 
 export function registerGenerateAndSaveTool(server: McpServer) {
   server.registerTool("generate_and_save", {
@@ -22,8 +27,11 @@ export function registerGenerateAndSaveTool(server: McpServer) {
       testsDir: z.optional(z.string()).describe("Path to existing tests directory — filters to uncovered endpoints only"),
       overwrite: z.optional(z.boolean()).describe("Hint for save_test_suites overwrite behavior (default: false)"),
       includeFormat: z.optional(z.boolean()).describe("Include YAML format reference (default: true, set false for subsequent tag chunks)"),
+      mode: z.optional(z.enum(["generate", "guide"])).describe(
+        "'generate' creates and saves YAML test files deterministically (default), 'guide' returns text for LLM-crafted tests"
+      ),
     },
-  }, async ({ specPath, outputDir, tag, methodFilter, testsDir, overwrite, includeFormat }) => {
+  }, async ({ specPath, outputDir, tag, methodFilter, testsDir, overwrite, includeFormat, mode }) => {
     try {
       const doc = await readOpenApiSpec(specPath);
       let endpoints = extractEndpoints(doc);
@@ -31,6 +39,7 @@ export function registerGenerateAndSaveTool(server: McpServer) {
       const baseUrl = ((doc as any).servers?.[0]?.url) as string | undefined;
       const title = (doc as any).info?.title as string | undefined;
       const effectiveOutputDir = outputDir ?? "./tests/";
+      const effectiveMode = mode ?? "generate";
 
       // Apply method filter
       if (methodFilter && methodFilter.length > 0) {
@@ -83,8 +92,11 @@ export function registerGenerateAndSaveTool(server: McpServer) {
           instruction:
             `This API has ${plan.totalEndpoints} endpoints across ${plan.chunks.length} tags. ` +
             `Call generate_and_save with tag parameter for each chunk sequentially. ` +
-            `Pass includeFormat: false for subsequent chunks to save tokens. ` +
-            `Example: generate_and_save(specPath: '${specPath}', tag: '${plan.chunks[0].tag}')`,
+            (effectiveMode === "guide"
+              ? `Pass includeFormat: false for subsequent chunks to save tokens. `
+              : "") +
+            `Example: generate_and_save(specPath: '${specPath}', tag: '${plan.chunks[0].tag}'` +
+            (effectiveMode === "guide" ? `, mode: 'guide'` : "") + `)`,
         };
         if (coverageInfo) {
           result.coverage = coverageInfo;
@@ -94,7 +106,57 @@ export function registerGenerateAndSaveTool(server: McpServer) {
         };
       }
 
-      // Guide mode: small API or specific tag
+      // ── Generate mode: deterministic YAML generation ──
+      if (effectiveMode === "generate") {
+        const suites = generateSuites({ endpoints, securitySchemes });
+
+        const files: Array<{
+          saved: boolean;
+          filePath: string;
+          tests: number;
+          error?: string;
+        }> = [];
+
+        for (const suite of suites) {
+          const yaml = serializeSuite(suite);
+          const fileName = (suite.fileStem ?? suite.name) + ".yaml";
+          const filePath = join(effectiveOutputDir, fileName);
+
+          const result = await validateAndSave(filePath, yaml, overwrite ?? false);
+          files.push({
+            saved: result.saved,
+            filePath: result.filePath ?? filePath,
+            tests: suite.tests.length,
+            ...(result.error ? { error: result.error } : {}),
+          });
+        }
+
+        const warnings: string[] = [];
+        for (const suite of suites) {
+          const unresolved = findUnresolvedVars(suite);
+          if (unresolved.length > 0)
+            warnings.push(`${suite.fileStem ?? suite.name}.yaml: unresolved [${unresolved.join(", ")}]`);
+        }
+
+        const response: Record<string, unknown> = {
+          mode: "generate",
+          suitesGenerated: suites.length,
+          files,
+          ...(warnings.length > 0 ? { warnings } : {}),
+          hint: files.some(f => !f.saved)
+            ? "Some files were not saved (already exist?). Use overwrite: true to replace."
+            : "Files saved. Run run_tests to verify. Use mode: 'guide' for LLM-crafted tests with more detail.",
+        };
+        if (coverageInfo) {
+          response.coverage = coverageInfo;
+        }
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(response, null, 2) }],
+        };
+      }
+
+      // ── Guide mode: text-based generation guide ──
       const coverageHeader = coverageInfo
         ? `## Coverage: ${coverageInfo.covered}/${coverageInfo.total} endpoints covered (${coverageInfo.percentage}%). Generating tests for ${endpoints.length} uncovered endpoints:`
         : undefined;

package/src/mcp/tools/query-db.ts

@@ -16,6 +16,27 @@ function parseBodySafe(raw: string | null | undefined): unknown {
   }
 }
 
+const USEFUL_HEADERS = new Set([
+  "content-type", "content-length", "location", "retry-after",
+  "www-authenticate", "allow",
+]);
+const USEFUL_PREFIXES = ["x-", "ratelimit"];
+
+function filterHeaders(raw: string | null | undefined): Record<string, string> | undefined {
+  if (!raw) return undefined;
+  try {
+    const h = JSON.parse(raw) as Record<string, string>;
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(h)) {
+      const l = k.toLowerCase();
+      if (USEFUL_HEADERS.has(l) || USEFUL_PREFIXES.some(p => l.startsWith(p))) {
+        out[k] = v;
+      }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+  } catch { return undefined; }
+}
+
 export function registerQueryDbTool(server: McpServer, dbPath?: string) {
   server.registerTool("query_db", {
     description: TOOL_DESCRIPTIONS.query_db,
@@ -137,9 +158,7 @@ export function registerQueryDbTool(server: McpServer, dbPath?: string) {
                 ...(hint ? { hint } : {}),
                 ...(sHint ? { schema_hint: sHint } : {}),
                 response_body: parseBodySafe(r.response_body),
-                response_headers: r.response_headers
-                  ? JSON.parse(r.response_headers)
-                  : undefined,
+                response_headers: filterHeaders(r.response_headers),
                 assertions: r.assertions,
                 duration_ms: r.duration_ms,
               };

package/src/mcp/tools/run-tests.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { executeRun } from "../../core/runner/execute-run.ts";
+import { getDb } from "../../db/schema.ts";
+import { getResultsByRunId } from "../../db/queries.ts";
 import { TOOL_DESCRIPTIONS } from "../descriptions.js";
 
 export function registerRunTestsTool(server: McpServer, dbPath?: string) {
@@ -13,8 +15,24 @@ export function registerRunTestsTool(server: McpServer, dbPath?: string) {
       tag: z.optional(z.array(z.string())).describe("Filter suites by tag (OR logic)"),
       envVars: z.optional(z.record(z.string(), z.string())).describe("Environment variables to inject (override env file, e.g. {\"TOKEN\": \"xxx\"})"),
       dryRun: z.optional(z.boolean()).describe("Show requests without sending them (always exits 0)"),
+      rerunFrom: z.optional(z.number().int()).describe("Re-run only tests that failed/errored in this run ID"),
     },
-  }, async ({ testPath, envName, safe, tag, envVars, dryRun }) => {
+  }, async ({ testPath, envName, safe, tag, envVars, dryRun, rerunFrom }) => {
+    // Build filter from previous failed run
+    let rerunFilter: Set<string> | undefined;
+    if (rerunFrom != null) {
+      getDb(dbPath);
+      const prevResults = getResultsByRunId(rerunFrom);
+      const failed = prevResults.filter(r => r.status === "fail" || r.status === "error");
+      if (failed.length === 0) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ error: `Run ${rerunFrom} has no failures to rerun` }, null, 2) }],
+          isError: true,
+        };
+      }
+      rerunFilter = new Set(failed.map(r => `${r.suite_name}::${r.test_name}`));
+    }
+
     const { runId, results } = await executeRun({
       testPath,
       envName,
@@ -24,6 +42,7 @@ export function registerRunTestsTool(server: McpServer, dbPath?: string) {
       tag,
       envVars,
       dryRun,
+      rerunFilter,
     });
 
     const total = results.reduce((s, r) => s + r.total, 0);
@@ -55,9 +74,6 @@ export function registerRunTestsTool(server: McpServer, dbPath?: string) {
         );
       }
     }
-    hints.push("Use manage_server(action: 'start') to launch the Web UI and view results visually in a browser at http://localhost:8080");
-    hints.push("Ask the user if they want to set up CI/CD to run these tests automatically on push. If yes, use ci_init to generate a workflow and help them push to GitHub/GitLab.");
-
     const summary = {
       runId,
       total,

package/src/mcp/tools/setup-api.ts

@@ -22,7 +22,7 @@ export function registerSetupApiTool(server: McpServer, dbPath?: string) {
   server.registerTool("setup_api", {
     description: TOOL_DESCRIPTIONS.setup_api,
     inputSchema: {
-      name: z.string().describe("API name (e.g. 'petstore')"),
+      name: z.optional(z.string()).describe("API name (auto-detected from spec title if omitted)"),
       specPath: z.optional(z.string()).describe("Path or URL to OpenAPI spec"),
       dir: z.optional(z.string()).describe("Base directory (default: ./apis/<name>/)"),
       envVars: z.optional(z.string()).describe("Environment variables as JSON string (e.g. '{\"base_url\": \"...\", \"token\": \"...\"}')"),