@kirrosh/zond 0.14.0 → 0.16.0

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

@@ -233,6 +233,13 @@ export function generateCrudSuite(
   const allEps = [group.create, group.list, group.read, group.update, group.delete].filter(Boolean) as EndpointInfo[];
   const suiteHeaders = getSuiteHeaders(allEps, securitySchemes);
 
+  // 0. List all (before create, to verify collection exists)
+  if (group.list) {
+    const step = generateStep(group.list, securitySchemes);
+    if (suiteHeaders) delete (step as any).headers;
+    tests.push(step);
+  }
+
   // 1. Create
   if (group.create) {
     const step = generateStep(group.create, securitySchemes);
@@ -335,6 +342,131 @@ export function findUnresolvedVars(suite: RawSuite, envKeys?: Set<string>): stri
   return [...vars];
 }
 
+/** Check if a schema has a specific field name (case-insensitive) */
+function schemaHasField(schema: OpenAPIV3.SchemaObject | undefined, ...names: string[]): boolean {
+  if (!schema?.properties) return false;
+  const keys = Object.keys(schema.properties).map(k => k.toLowerCase());
+  return names.some(n => keys.includes(n.toLowerCase()));
+}
+
+/** Generate auth suite with register+login consistency */
+export function generateAuthSuite(
+  authEndpoints: EndpointInfo[],
+  securitySchemes: SecuritySchemeInfo[],
+): RawSuite {
+  // Detect register → login pair
+  const registerEp = authEndpoints.find(ep =>
+    /\/(register|signup)\b/i.test(ep.path) && ep.method.toUpperCase() === "POST"
+  );
+  const loginEp = authEndpoints.find(ep =>
+    ep !== registerEp &&
+    /\/(login|signin|auth)\b/i.test(ep.path) &&
+    ep.method.toUpperCase() === "POST"
+  );
+
+  const hasCredentialPair = registerEp && loginEp &&
+    schemaHasField(registerEp.requestBodySchema, "email", "username") &&
+    schemaHasField(registerEp.requestBodySchema, "password") &&
+    schemaHasField(loginEp.requestBodySchema, "email", "username") &&
+    schemaHasField(loginEp.requestBodySchema, "password");
+
+  if (hasCredentialPair) {
+    return generateConsistentAuthSuite(registerEp, loginEp, authEndpoints, securitySchemes);
+  }
+
+  // Fallback: plain auth suite
+  const tests = authEndpoints.map(ep => generateStep(ep, securitySchemes));
+  const headers = getSuiteHeaders(authEndpoints, securitySchemes);
+
+  const suite: RawSuite = {
+    name: "auth",
+    tags: ["auth"],
+    fileStem: "auth",
+    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;
+      }
+    }
+  }
+
+  return suite;
+}
+
+/** Generate auth suite with consistent register → login credentials */
+function generateConsistentAuthSuite(
+  registerEp: EndpointInfo,
+  loginEp: EndpointInfo,
+  allAuthEndpoints: EndpointInfo[],
+  securitySchemes: SecuritySchemeInfo[],
+): RawSuite {
+  const tests: RawStep[] = [];
+
+  // Determine credential field: "email" or "username"
+  const useEmail = schemaHasField(registerEp.requestBodySchema, "email");
+  const credField = useEmail ? "email" : "username";
+  const credValue = useEmail ? "test_{{$timestamp}}@test.com" : "testuser_{{$timestamp}}";
+
+  // 0. Set shared credentials
+  const setStep: RawStep = {
+    name: "Set test credentials",
+    set: {
+      [`test_${credField}`]: credValue,
+      test_password: "TestPass123!",
+    },
+    expect: {},
+  } as RawStep;
+  tests.push(setStep);
+
+  // 1. Register step — replace credential fields with shared vars
+  const registerStep = generateStep(registerEp, securitySchemes);
+  if (registerStep.json && typeof registerStep.json === "object") {
+    const json = registerStep.json as Record<string, unknown>;
+    if (credField in json) json[credField] = `{{test_${credField}}}`;
+    if ("password" in json) json.password = "{{test_password}}";
+  }
+  tests.push(registerStep);
+
+  // 2. Login step — reuse same credentials + capture token
+  const loginStep = generateStep(loginEp, securitySchemes);
+  if (loginStep.json && typeof loginStep.json === "object") {
+    const json = loginStep.json as Record<string, unknown>;
+    if (credField in json) json[credField] = `{{test_${credField}}}`;
+    if ("password" in json) json.password = "{{test_password}}";
+  }
+  // Try to capture auth token from login response
+  const loginSchema = getSuccessSchema(loginEp);
+  if (loginSchema?.properties) {
+    const tokenField = Object.keys(loginSchema.properties).find(k =>
+      /token|access_token|accessToken|jwt/i.test(k)
+    );
+    if (tokenField) {
+      if (!loginStep.expect.body) loginStep.expect.body = {};
+      loginStep.expect.body[tokenField] = { capture: "auth_token" };
+    }
+  }
+  tests.push(loginStep);
+
+  // 3. Any remaining auth endpoints (not register/login)
+  const others = allAuthEndpoints.filter(ep => ep !== registerEp && ep !== loginEp);
+  for (const ep of others) {
+    tests.push(generateStep(ep, securitySchemes));
+  }
+
+  return {
+    name: "auth",
+    tags: ["auth"],
+    fileStem: "auth",
+    base_url: "{{base_url}}",
+    tests,
+  };
+}
+
 /** Main entry point: generate all suites from endpoints */
 export function generateSuites(opts: {
   endpoints: EndpointInfo[];
@@ -433,26 +565,7 @@ export function generateSuites(opts: {
 
   // 4. Auth suite (separate — requires real credentials)
   if (authEndpoints.length > 0) {
-    const tests = authEndpoints.map(ep => generateStep(ep, securitySchemes));
-    const headers = getSuiteHeaders(authEndpoints, securitySchemes);
-
-    const suite: RawSuite = {
-      name: "auth",
-      tags: ["auth"],
-      fileStem: "auth",
-      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;
-        }
-      }
-    }
-
+    const suite = generateAuthSuite(authEndpoints, securitySchemes);
     suites.push(suite);
   }
 

package/src/core/runner/executor.ts

@@ -286,6 +286,7 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
     suite_name: suite.name,
     suite_tags: suite.tags,
     suite_description: suite.description,
+    suite_file: suite.filePath,
     started_at: startedAt,
     finished_at: finishedAt,
     total: steps.length,

package/src/core/runner/send-request.ts

@@ -0,0 +1,94 @@
+import { executeRequest } from "./http-client.ts";
+import { loadEnvironment, substituteString, substituteDeep } from "../parser/variables.ts";
+import { getDb } from "../../db/schema.ts";
+import { findCollectionByNameOrId } from "../../db/queries.ts";
+
+function extractByPath(obj: unknown, path: string): unknown {
+  const segments = path.replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean);
+  let current: unknown = obj;
+  for (const seg of segments) {
+    if (current === null || current === undefined) return undefined;
+    if (Array.isArray(current)) {
+      const idx = parseInt(seg, 10);
+      if (isNaN(idx)) return undefined;
+      current = current[idx];
+    } else if (typeof current === 'object') {
+      current = (current as Record<string, unknown>)[seg];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+export interface SendAdHocRequestOptions {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: string;
+  timeout?: number;
+  envName?: string;
+  collectionName?: string;
+  jsonPath?: string;
+  maxResponseChars?: number;
+  dbPath?: string;
+  searchDir?: string;
+}
+
+export interface SendAdHocRequestResult {
+  status: number;
+  headers: Record<string, string>;
+  body: unknown;
+  duration_ms: number;
+}
+
+export async function sendAdHocRequest(options: SendAdHocRequestOptions): Promise<SendAdHocRequestResult> {
+  let searchDir = options.searchDir ?? process.cwd();
+  if (options.collectionName) {
+    getDb(options.dbPath);
+    const col = findCollectionByNameOrId(options.collectionName);
+    if (col?.base_dir) searchDir = col.base_dir;
+  }
+  const vars = await loadEnvironment(options.envName, searchDir);
+
+  const resolvedUrl = substituteString(options.url, vars) as string;
+  const parsedHeaders = options.headers ?? {};
+  const resolvedHeaders = Object.keys(parsedHeaders).length > 0 ? substituteDeep(parsedHeaders, vars) : {};
+  const resolvedBody = options.body ? substituteString(options.body, vars) as string : undefined;
+
+  // Auto-detect Content-Type for body if not explicitly set
+  const finalHeaders: Record<string, string> = { ...resolvedHeaders };
+  if (resolvedBody && !finalHeaders["Content-Type"] && !finalHeaders["content-type"]) {
+    try {
+      JSON.parse(resolvedBody);
+      finalHeaders["Content-Type"] = "application/json";
+    } catch {
+      // Not JSON — don't set content-type, let server decide
+    }
+  }
+
+  const response = await executeRequest(
+    {
+      method: options.method,
+      url: resolvedUrl,
+      headers: finalHeaders,
+      body: resolvedBody,
+    },
+    options.timeout ? { timeout: options.timeout } : undefined,
+  );
+
+  let responseBody: unknown = response.body_parsed ?? response.body;
+
+  if (options.jsonPath && responseBody !== undefined) {
+    responseBody = extractByPath(responseBody, options.jsonPath);
+  }
+
+  const result: SendAdHocRequestResult = {
+    status: response.status,
+    headers: response.headers,
+    body: responseBody,
+    duration_ms: response.duration_ms,
+  };
+
+  return result;
+}

package/src/core/runner/types.ts

@@ -38,6 +38,7 @@ export interface TestRunResult {
   suite_name: string;
   suite_tags?: string[];
   suite_description?: string;
+  suite_file?: string;
   started_at: string;
   finished_at: string;
   total: number;

package/src/db/queries.ts

@@ -103,6 +103,7 @@ export interface StoredStepResult {
   error_message: string | null;
   assertions: import("../core/runner/types.ts").AssertionResult[];
   captures: Record<string, unknown>;
+  suite_file: string | null;
 }
 
 // ──────────────────────────────────────────────
@@ -244,11 +245,11 @@ export function saveResults(runId: number, suiteResults: TestRunResult[]): void
     INSERT INTO results
       (run_id, suite_name, test_name, status, duration_ms,
        request_method, request_url, request_body,
-       response_status, response_body, response_headers, error_message, assertions, captures)
+       response_status, response_body, response_headers, error_message, assertions, captures, suite_file)
     VALUES
       ($run_id, $suite_name, $test_name, $status, $duration_ms,
        $request_method, $request_url, $request_body,
-       $response_status, $response_body, $response_headers, $error_message, $assertions, $captures)
+       $response_status, $response_body, $response_headers, $error_message, $assertions, $captures, $suite_file)
   `);
 
   db.transaction(() => {
@@ -272,6 +273,7 @@ export function saveResults(runId: number, suiteResults: TestRunResult[]): void
           $error_message: step.error ?? null,
           $assertions: step.assertions.length > 0 ? JSON.stringify(step.assertions) : null,
           $captures: Object.keys(step.captures).length > 0 ? JSON.stringify(step.captures) : null,
+          $suite_file: suite.suite_file ?? null,
         });
       }
     }

package/src/db/schema.ts

@@ -48,7 +48,7 @@ export function resetDb(): void {
 // Schema
 // ──────────────────────────────────────────────
 
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 
 const SCHEMA = `
   CREATE TABLE IF NOT EXISTS runs (
@@ -82,7 +82,8 @@ const SCHEMA = `
     error_message    TEXT,
     assertions       TEXT,
     captures         TEXT,
-    response_headers TEXT
+    response_headers TEXT,
+    suite_file       TEXT
   );
 
   CREATE TABLE IF NOT EXISTS collections (
@@ -153,7 +154,14 @@ function runMigrations(db: Database): void {
   if (ver >= SCHEMA_VERSION) return;
 
   db.transaction(() => {
-    db.exec(SCHEMA);
+    if (ver === 0) {
+      // Fresh database — create all tables
+      db.exec(SCHEMA);
+    }
+    if (ver >= 1 && ver < 2) {
+      // Migration v1→v2: add suite_file column to results
+      db.exec("ALTER TABLE results ADD COLUMN suite_file TEXT");
+    }
     db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
   })();
 }

package/src/mcp/descriptions.ts

@@ -3,12 +3,6 @@
  * Update descriptions here — they are imported by each tool file.
  */
 export const TOOL_DESCRIPTIONS = {
-  set_work_dir:
-    "Set the working directory for this MCP session. " +
-    "Call this FIRST before any other tool when using a shared MCP server (npx). " +
-    "Determines where zond.db and relative test paths resolve to. " +
-    "Pass the absolute path to your project root (same as workspace root in your editor).",
-
   setup_api:
     "Register a new API for testing. Creates directory structure, reads OpenAPI spec, " +
     "sets up environment variables, and creates a collection in the database. " +
@@ -20,15 +14,6 @@ export const TOOL_DESCRIPTIONS = {
     "all response schemas + response headers, security, deprecated flag. " +
     "Use when a test fails and you need complete endpoint spec without reading the whole file.",
 
-  save_test_suite:
-    "Save a YAML test suite file with validation. Parses and validates the YAML content " +
-    "before writing. Returns structured errors if validation fails so you can fix and retry. " +
-    "Use after generating test content with generate_and_save.",
-
-  save_test_suites:
-    "Save multiple YAML test suite files in a single call. Each file is validated before writing. " +
-    "Returns per-file results. Use when you have generated multiple suites at once.",
-
   run_tests:
     "Execute API tests from a YAML file or directory and return results summary with failures. " +
     "Use after saving test suites with save_test_suite. Check query_db(action: 'diagnose_failure') for detailed failure analysis.",
@@ -54,15 +39,6 @@ export const TOOL_DESCRIPTIONS = {
     "Start, stop, restart, or check status of the zond WebUI server. " +
     "Useful for viewing test results in a browser without leaving the MCP session.",
 
-  generate_and_save:
-    "Read an OpenAPI spec, auto-chunk by tags if large (>30 endpoints), " +
-    "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. " +
-    "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. " +
     "Supports GitHub Actions and GitLab CI. Auto-detects platform from project structure " +

package/src/mcp/server.ts

@@ -4,13 +4,10 @@ import { registerRunTestsTool } from "./tools/run-tests.ts";
 import { registerQueryDbTool } from "./tools/query-db.ts";
 import { registerSendRequestTool } from "./tools/send-request.ts";
 import { registerCoverageAnalysisTool } from "./tools/coverage-analysis.ts";
-import { registerSaveTestSuiteTool, registerSaveTestSuitesTool } from "./tools/save-test-suite.ts";
 import { registerSetupApiTool } from "./tools/setup-api.ts";
 import { registerManageServerTool } from "./tools/manage-server.ts";
 import { registerCiInitTool } from "./tools/ci-init.ts";
-import { registerSetWorkDirTool } from "./tools/set-work-dir.ts";
 import { registerDescribeEndpointTool } from "./tools/describe-endpoint.ts";
-import { registerGenerateAndSaveTool } from "./tools/generate-and-save.ts";
 import { version } from "../../package.json";
 
 export interface McpServerOptions {
@@ -25,19 +22,15 @@ export async function startMcpServer(options: McpServerOptions = {}): Promise<vo
     version,
   });
 
-  // Register all tools
+  // Register tools (slim set — removed set_work_dir, save_test_suite, save_test_suites)
   registerRunTestsTool(server, dbPath);
   registerQueryDbTool(server, dbPath);
   registerSendRequestTool(server, dbPath);
   registerCoverageAnalysisTool(server, dbPath);
-  registerSaveTestSuiteTool(server, dbPath);
-  registerSaveTestSuitesTool(server, dbPath);
   registerSetupApiTool(server, dbPath);
   registerManageServerTool(server, dbPath);
   registerCiInitTool(server);
-  registerSetWorkDirTool(server);
   registerDescribeEndpointTool(server);
-  registerGenerateAndSaveTool(server);
 
   // Connect via stdio transport
   const transport = new StdioServerTransport();

package/src/mcp/tools/describe-endpoint.ts

@@ -1,67 +1,8 @@
 import { z } from "zod";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { OpenAPIV3 } from "openapi-types";
-import { readOpenApiSpec } from "../../core/generator/index.ts";
-import { decycleSchema } from "../../core/generator/schema-utils.ts";
+import { describeEndpoint } from "../../core/generator/describe.ts";
 import { TOOL_DESCRIPTIONS } from "../descriptions.js";
 
-function generateTestSnippet(params: {
-  method: string;
-  path: string;
-  operationId?: string;
-  pathParams: string[];
-  queryParams: Array<{ name: string; required?: boolean }>;
-  requestBody?: { required?: boolean; schema?: OpenAPIV3.SchemaObject };
-  hasSecurity: boolean;
-  successStatus: string;
-}): string {
-  const { method, path, operationId, pathParams, queryParams, requestBody, hasSecurity, successStatus } = params;
-
-  // Build URL with path params as {{paramName}}
-  const urlPath = path.replace(/\{([^}]+)\}/g, (_, name) => `{{${name}}}`);
-  const url = `{{base_url}}${urlPath}`;
-
-  const lines: string[] = [];
-  const testName = operationId ?? `${method} ${path}`;
-  lines.push(`- name: "${testName}"`);
-  lines.push(`  ${method}: "${url}"`);
-
-  if (hasSecurity) {
-    lines.push(`  headers:`);
-    lines.push(`    Authorization: "Bearer {{auth_token}}"`);
-  }
-
-  // Required query params
-  const requiredQuery = queryParams.filter(p => p.required);
-  if (requiredQuery.length > 0) {
-    lines.push(`  query:`);
-    for (const p of requiredQuery) {
-      lines.push(`    ${p.name}: "{{${p.name}}}"`);
-    }
-  }
-
-  // Request body for POST/PUT/PATCH
-  if (requestBody && ["POST", "PUT", "PATCH"].includes(method)) {
-    const schema = requestBody.schema as OpenAPIV3.SchemaObject | undefined;
-    const required = Array.isArray(schema?.required) ? schema.required : [];
-    const properties = schema?.properties as Record<string, OpenAPIV3.SchemaObject> | undefined;
-    if (properties && Object.keys(properties).length > 0) {
-      lines.push(`  json:`);
-      for (const [propName, propSchema] of Object.entries(properties)) {
-        if (!required.includes(propName)) continue;
-        const type = (propSchema as OpenAPIV3.SchemaObject).type ?? "string";
-        const placeholder = type === "integer" || type === "number" ? 0 : type === "boolean" ? false : `"{{${propName}}}"`;
-        lines.push(`    ${propName}: ${placeholder}`);
-      }
-    }
-  }
-
-  lines.push(`  expect:`);
-  lines.push(`    status: ${successStatus}`);
-
-  return lines.join("\n");
-}
-
 export function registerDescribeEndpointTool(server: McpServer) {
   server.registerTool("describe_endpoint", {
     description: TOOL_DESCRIPTIONS.describe_endpoint,
@@ -72,165 +13,9 @@ export function registerDescribeEndpointTool(server: McpServer) {
     },
   }, async ({ specPath, method, path: endpointPath }) => {
     try {
-      const doc = await readOpenApiSpec(specPath) as OpenAPIV3.Document;
-
-      // Normalize inputs
-      const methodLower = method.toLowerCase() as OpenAPIV3.HttpMethods;
-      const normalizedPath = endpointPath.replace(/\/+$/, "") || "/";
-
-      // Find operation — try exact match first, then case-insensitive path match
-      let operation: OpenAPIV3.OperationObject | undefined;
-      let resolvedPath = normalizedPath;
-
-      const paths = doc.paths ?? {};
-
-      if (paths[normalizedPath]?.[methodLower]) {
-        operation = paths[normalizedPath][methodLower] as OpenAPIV3.OperationObject;
-      } else {
-        // Case-insensitive fallback
-        const lowerTarget = normalizedPath.toLowerCase();
-        for (const [p, pathItem] of Object.entries(paths)) {
-          if (p.toLowerCase() === lowerTarget && pathItem?.[methodLower]) {
-            operation = pathItem[methodLower] as OpenAPIV3.OperationObject;
-            resolvedPath = p;
-            break;
-          }
-        }
-      }
-
-      if (!operation) {
-        const available = Object.entries(paths).flatMap(([p, pathItem]) =>
-          Object.keys(pathItem ?? {})
-            .filter(k => ["get","post","put","patch","delete","head","options","trace"].includes(k))
-            .map(k => `${k.toUpperCase()} ${p}`)
-        ).sort();
-        return {
-          content: [{
-            type: "text" as const,
-            text: JSON.stringify({
-              error: `Endpoint ${method.toUpperCase()} ${endpointPath} not found in spec`,
-              availableEndpoints: available,
-            }, null, 2),
-          }],
-          isError: true,
-        };
-      }
-
-      const pathItem = paths[resolvedPath] ?? {};
-
-      // Merge path-level and operation-level parameters (operation overrides by name+in)
-      const pathLevelParams = (pathItem.parameters ?? []) as OpenAPIV3.ParameterObject[];
-      const opLevelParams = (operation.parameters ?? []) as OpenAPIV3.ParameterObject[];
-
-      const paramMap = new Map<string, OpenAPIV3.ParameterObject>();
-      for (const p of pathLevelParams) paramMap.set(`${p.in}:${p.name}`, p);
-      for (const p of opLevelParams) paramMap.set(`${p.in}:${p.name}`, p); // operation overrides
-
-      // Group by "in"
-      const grouped: Record<string, object[]> = { path: [], query: [], header: [], cookie: [] };
-      for (const p of paramMap.values()) {
-        const loc = p.in in grouped ? p.in : "query";
-        const schema = p.schema as OpenAPIV3.SchemaObject | undefined;
-        grouped[loc]!.push({
-          name: p.name,
-          required: p.required ?? false,
-          ...(schema?.type ? { type: schema.type } : {}),
-          ...(schema?.format ? { format: schema.format } : {}),
-          ...(schema?.enum ? { enum: schema.enum } : {}),
-          ...(schema?.default !== undefined ? { default: schema.default } : {}),
-          ...(p.description ? { description: p.description } : {}),
-        });
-      }
-
-      // Request body
-      let requestBody: object | undefined;
-      if (operation.requestBody) {
-        const rb = operation.requestBody as OpenAPIV3.RequestBodyObject;
-        const contentTypes = Object.keys(rb.content ?? {});
-        const preferredCt = contentTypes.find(ct => ct.includes("application/json")) ?? contentTypes[0];
-        const mediaObj = preferredCt ? rb.content[preferredCt] : undefined;
-        requestBody = {
-          required: rb.required ?? false,
-          ...(preferredCt ? { contentType: preferredCt } : {}),
-          ...(mediaObj?.schema ? { schema: mediaObj.schema } : {}),
-          ...(rb.description ? { description: rb.description } : {}),
-        };
-      }
-
-      // Responses
-      const responses: Record<string, object> = {};
-      for (const [statusCode, respObj] of Object.entries(operation.responses ?? {})) {
-        const resp = respObj as OpenAPIV3.ResponseObject;
-        const contentTypes = Object.keys(resp.content ?? {});
-        const preferredCt = contentTypes.find(ct => ct.includes("application/json")) ?? contentTypes[0];
-        const mediaObj = preferredCt ? resp.content?.[preferredCt] : undefined;
-
-        // Response headers
-        const headers: Record<string, object> = {};
-        for (const [hName, hObj] of Object.entries(resp.headers ?? {})) {
-          const h = hObj as OpenAPIV3.HeaderObject;
-          headers[hName] = {
-            ...(h.description ? { description: h.description } : {}),
-            ...(h.schema ? { schema: h.schema } : {}),
-          };
-        }
-
-        responses[statusCode] = {
-          description: resp.description,
-          headers,
-          ...(preferredCt ? { contentType: preferredCt } : {}),
-          ...(mediaObj?.schema ? { schema: mediaObj.schema } : {}),
-        };
-      }
-
-      // Security — merge doc-level and operation-level
-      const docSecurity = (doc.security ?? []) as OpenAPIV3.SecurityRequirementObject[];
-      const opSecurity = (operation.security ?? docSecurity) as OpenAPIV3.SecurityRequirementObject[];
-      const securityNames = [...new Set(opSecurity.flatMap(req => Object.keys(req)))];
-
-      // Derive success status (first 2xx, or first response code)
-      const responseCodes = Object.keys(operation.responses ?? {});
-      const successStatus = responseCodes.find(c => c.startsWith("2")) ?? responseCodes[0] ?? "200";
-
-      // Build testSnippet
-      const pathParamNames = [...paramMap.values()]
-        .filter(p => p.in === "path")
-        .map(p => p.name);
-      const queryParamsList = [...paramMap.values()]
-        .filter(p => p.in === "query")
-        .map(p => ({ name: p.name, required: p.required }));
-      const reqBodyForSnippet = requestBody
-        ? { required: (operation.requestBody as OpenAPIV3.RequestBodyObject)?.required, schema: (requestBody as any).schema }
-        : undefined;
-
-      const testSnippet = generateTestSnippet({
-        method: method.toUpperCase(),
-        path: resolvedPath,
-        operationId: operation.operationId,
-        pathParams: pathParamNames,
-        queryParams: queryParamsList,
-        requestBody: reqBodyForSnippet,
-        hasSecurity: securityNames.length > 0,
-        successStatus,
-      });
-
-      const result = {
-        method: method.toUpperCase(),
-        path: resolvedPath,
-        ...(operation.operationId ? { operationId: operation.operationId } : {}),
-        ...(operation.summary ? { summary: operation.summary } : {}),
-        ...(operation.description ? { description: operation.description } : {}),
-        ...(operation.tags?.length ? { tags: operation.tags } : {}),
-        deprecated: operation.deprecated ?? false,
-        security: securityNames,
-        parameters: grouped,
-        ...(requestBody ? { requestBody } : {}),
-        responses,
-        testSnippet,
-      };
-
+      const result = await describeEndpoint(specPath, method, endpointPath);
       return {
-        content: [{ type: "text" as const, text: JSON.stringify(decycleSchema(result), null, 2) }],
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
       };
     } catch (err) {
       return {