@kirrosh/zond 0.7.0

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

@@ -0,0 +1,241 @@
+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 { 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,
+    inputSchema: {
+      specPath: z.string().describe("Path to OpenAPI spec file (JSON or YAML) or HTTP URL"),
+      method: z.string().describe('HTTP method, e.g. "GET", "POST", "PUT"'),
+      path: z.string().describe('Endpoint path, e.g. "/pets/{petId}"'),
+    },
+  }, 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,
+      };
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ error: (err as Error).message }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}

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

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { readOpenApiSpec, extractEndpoints, extractSecuritySchemes } from "../../core/generator/index.ts";
+import { compressSchema, formatParam } from "../../core/generator/schema-utils.ts";
+import { TOOL_DESCRIPTIONS } from "../descriptions.js";
+
+export function registerExploreApiTool(server: McpServer) {
+  server.registerTool("explore_api", {
+    description: TOOL_DESCRIPTIONS.explore_api,
+    inputSchema: {
+      specPath: z.string().describe("Path to OpenAPI spec file (JSON or YAML)"),
+      tag: z.optional(z.string()).describe("Filter endpoints by tag"),
+      includeSchemas: z.optional(z.boolean()).describe("Include request/response body schemas and parameter types (default: false)"),
+    },
+  }, async ({ specPath, tag, includeSchemas }) => {
+    try {
+      const doc = await readOpenApiSpec(specPath);
+      const allEndpoints = extractEndpoints(doc);
+      const securitySchemes = extractSecuritySchemes(doc);
+      const servers = ((doc as any).servers ?? []) as Array<{ url: string; description?: string }>;
+
+      const endpoints = tag
+        ? allEndpoints.filter(ep => ep.tags.includes(tag))
+        : allEndpoints;
+
+      const result = {
+        title: (doc as any).info?.title,
+        version: (doc as any).info?.version,
+        servers: servers.map(s => ({ url: s.url, description: s.description })),
+        securitySchemes: securitySchemes.map(s => ({
+          name: s.name,
+          type: s.type,
+          ...(s.scheme ? { scheme: s.scheme } : {}),
+          ...(s.in ? { in: s.in, keyName: s.apiKeyName } : {}),
+        })),
+        totalEndpoints: allEndpoints.length,
+        ...(tag ? { filteredByTag: tag, matchingEndpoints: endpoints.length } : {}),
+        endpoints: endpoints.map(ep => {
+          const base: Record<string, unknown> = {
+            method: ep.method,
+            path: ep.path,
+            summary: ep.summary,
+            tags: ep.tags,
+            parameters: ep.parameters.map(p => ({
+              name: p.name,
+              in: p.in,
+              required: p.required ?? false,
+              ...(includeSchemas ? { type: formatParam(p).split(": ")[1] } : {}),
+            })),
+            hasRequestBody: !!ep.requestBodySchema,
+            responses: ep.responses.map(r => ({
+              statusCode: r.statusCode,
+              description: r.description,
+              ...(includeSchemas && r.schema ? { schema: compressSchema(r.schema) } : {}),
+            })),
+          };
+
+          if (includeSchemas) {
+            if (ep.requestBodySchema) {
+              base.requestBodySchema = compressSchema(ep.requestBodySchema);
+            }
+            if (ep.requestBodyContentType) {
+              base.requestBodyContentType = ep.requestBodyContentType;
+            }
+            if (ep.security.length > 0) {
+              base.security = ep.security;
+            }
+          }
+
+          return base;
+        }),
+      };
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ error: (err as Error).message }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}

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

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  scanCoveredEndpoints,
+  filterUncoveredEndpoints,
+} from "../../core/generator/index.ts";
+import { compressEndpointsWithSchemas, buildGenerationGuide } from "./generate-tests-guide.ts";
+import { planChunks, filterByTag } from "../../core/generator/chunker.ts";
+import { TOOL_DESCRIPTIONS } from "../descriptions.js";
+
+export function registerGenerateAndSaveTool(server: McpServer) {
+  server.registerTool("generate_and_save", {
+    description: TOOL_DESCRIPTIONS.generate_and_save,
+    inputSchema: {
+      specPath: z.string().describe("Path or URL to OpenAPI spec file"),
+      outputDir: z.optional(z.string()).describe("Directory for saving test files (default: ./tests/)"),
+      tag: z.optional(z.string()).describe("Generate tests only for this tag's endpoints"),
+      methodFilter: z.optional(z.array(z.string())).describe("Only include endpoints with these HTTP methods (e.g. [\"GET\"] for smoke tests)"),
+      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)"),
+    },
+  }, async ({ specPath, outputDir, tag, methodFilter, testsDir, overwrite }) => {
+    try {
+      const doc = await readOpenApiSpec(specPath);
+      let endpoints = extractEndpoints(doc);
+      const securitySchemes = extractSecuritySchemes(doc);
+      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/";
+
+      // Apply method filter
+      if (methodFilter && methodFilter.length > 0) {
+        const methods = methodFilter.map(m => m.toUpperCase());
+        endpoints = endpoints.filter(ep => methods.includes(ep.method.toUpperCase()));
+      }
+
+      // Coverage filtering
+      let coverageInfo: { covered: number; total: number; percentage: number } | undefined;
+      if (testsDir) {
+        const totalBefore = endpoints.length;
+        const covered = await scanCoveredEndpoints(testsDir);
+        const uncovered = filterUncoveredEndpoints(endpoints, covered);
+        const coveredCount = totalBefore - uncovered.length;
+        const percentage = totalBefore > 0 ? Math.round((coveredCount / totalBefore) * 100) : 100;
+        coverageInfo = { covered: coveredCount, total: totalBefore, percentage };
+        endpoints = uncovered;
+      }
+
+      if (endpoints.length === 0) {
+        const msg = testsDir
+          ? { fullyCovered: true, ...coverageInfo }
+          : { error: "No endpoints found in the spec" };
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(msg, null, 2) }],
+          isError: !testsDir,
+        };
+      }
+
+      // Tag filtering
+      if (tag) {
+        endpoints = filterByTag(endpoints, tag);
+        if (endpoints.length === 0) {
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({ error: `No endpoints found for tag "${tag}"` }, null, 2) }],
+            isError: true,
+          };
+        }
+      }
+
+      const plan = planChunks(endpoints);
+
+      // Plan mode: large API without specific tag
+      if (plan.needsChunking && !tag) {
+        const result: Record<string, unknown> = {
+          mode: "plan",
+          title: title ?? "API",
+          totalEndpoints: plan.totalEndpoints,
+          chunks: plan.chunks,
+          instruction:
+            `This API has ${plan.totalEndpoints} endpoints across ${plan.chunks.length} tags. ` +
+            `Call generate_and_save with tag parameter for each chunk sequentially. ` +
+            `Example: generate_and_save(specPath: '${specPath}', tag: '${plan.chunks[0].tag}')`,
+        };
+        if (coverageInfo) {
+          result.coverage = coverageInfo;
+        }
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      // Guide mode: small API or specific tag
+      const coverageHeader = coverageInfo
+        ? `## Coverage: ${coverageInfo.covered}/${coverageInfo.total} endpoints covered (${coverageInfo.percentage}%). Generating tests for ${endpoints.length} uncovered endpoints:`
+        : undefined;
+
+      const apiContext = compressEndpointsWithSchemas(endpoints, securitySchemes);
+      const guide = buildGenerationGuide({
+        title: tag ? `${title ?? "API"} — tag: ${tag}` : (title ?? "API"),
+        baseUrl,
+        apiContext,
+        outputDir: effectiveOutputDir,
+        securitySchemes,
+        endpointCount: endpoints.length,
+        coverageHeader,
+      });
+
+      const saveInstructions = `
+---
+## Save Instructions
+- Output directory: ${effectiveOutputDir}
+- Use \`save_test_suites\` to save all generated files in one call
+- Overwrite: ${overwrite ? "true" : "false (set overwrite: true in save_test_suites to replace existing files)"}
+- After saving, run \`run_tests\` to verify`;
+
+      return {
+        content: [{ type: "text" as const, text: guide + saveInstructions }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ error: (err as Error).message }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}

package/src/mcp/tools/generate-missing-tests.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  scanCoveredEndpoints,
+  filterUncoveredEndpoints,
+} from "../../core/generator/index.ts";
+import { compressEndpointsWithSchemas, buildGenerationGuide } from "./generate-tests-guide.ts";
+import { TOOL_DESCRIPTIONS } from "../descriptions.js";
+
+export function registerGenerateMissingTestsTool(server: McpServer) {
+  server.registerTool("generate_missing_tests", {
+    description: TOOL_DESCRIPTIONS.generate_missing_tests,
+    inputSchema: {
+      specPath: z.string().describe("Path or URL to OpenAPI spec file"),
+      testsDir: z.string().describe("Path to directory with existing test YAML files"),
+      outputDir: z.optional(z.string()).describe("Directory for saving new test files (default: same as testsDir)"),
+      methodFilter: z.optional(z.array(z.string())).describe("Only include endpoints with these HTTP methods (e.g. [\"GET\"] for smoke tests)"),
+      tag: z.optional(z.string()).describe("Filter endpoints by tag"),
+    },
+  }, async ({ specPath, testsDir, outputDir, methodFilter, tag }) => {
+    try {
+      const doc = await readOpenApiSpec(specPath);
+      let allEndpoints = extractEndpoints(doc);
+      const securitySchemes = extractSecuritySchemes(doc);
+      const baseUrl = ((doc as any).servers?.[0]?.url) as string | undefined;
+      const title = (doc as any).info?.title as string | undefined;
+
+      // Apply method filter before coverage check
+      if (methodFilter && methodFilter.length > 0) {
+        const methods = methodFilter.map(m => m.toUpperCase());
+        allEndpoints = allEndpoints.filter(ep => methods.includes(ep.method.toUpperCase()));
+      }
+      if (tag) {
+        const lower = tag.toLowerCase();
+        allEndpoints = allEndpoints.filter(ep => ep.tags.some(t => t.toLowerCase() === lower));
+      }
+
+      if (allEndpoints.length === 0) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ error: "No endpoints found in the spec" }, null, 2) }],
+          isError: true,
+        };
+      }
+
+      const covered = await scanCoveredEndpoints(testsDir);
+      const uncovered = filterUncoveredEndpoints(allEndpoints, covered);
+      const coveredCount = allEndpoints.length - uncovered.length;
+      const percentage = Math.round((coveredCount / allEndpoints.length) * 100);
+
+      if (uncovered.length === 0) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              fullyCovered: true,
+              percentage: 100,
+              totalEndpoints: allEndpoints.length,
+              covered: coveredCount,
+            }, null, 2),
+          }],
+        };
+      }
+
+      // Build guide for uncovered endpoints only
+      const apiContext = compressEndpointsWithSchemas(uncovered, securitySchemes);
+      const coverageHeader = `## Coverage: ${coveredCount}/${allEndpoints.length} endpoints covered (${percentage}%). Generating tests for ${uncovered.length} uncovered endpoints:`;
+
+      const guide = buildGenerationGuide({
+        title: title ?? "API",
+        baseUrl,
+        apiContext,
+        outputDir: outputDir ?? testsDir,
+        securitySchemes,
+        endpointCount: uncovered.length,
+        coverageHeader,
+      });
+
+      return {
+        content: [{ type: "text" as const, text: guide }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ error: (err as Error).message }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}