truss-api-mcp 1.0.0

package/src/lib/code-generator.ts

@@ -0,0 +1,1045 @@
+import type {
+  ParsedOpenApiSpec,
+  OpenApiEndpoint,
+  JsonSchema,
+  CodeLanguage,
+  HttpStyle,
+  TestFramework,
+  SpecComparison,
+  SpecChange,
+  MockServerConfig,
+  MockRoute,
+} from '../types.js';
+
+// ── Client Code Generation ──────────────────────────────────────────
+
+export function generateClient(
+  spec: ParsedOpenApiSpec,
+  language: CodeLanguage,
+  style: HttpStyle = 'fetch'
+): string {
+  switch (language) {
+    case 'typescript':
+      return generateTypeScriptClient(spec, style);
+    case 'python':
+      return generatePythonClient(spec);
+    case 'go':
+      return generateGoClient(spec);
+  }
+}
+
+// ── TypeScript Client ───────────────────────────────────────────────
+
+function generateTypeScriptClient(spec: ParsedOpenApiSpec, style: HttpStyle): string {
+  const baseUrl = spec.servers?.[0]?.url ?? 'http://localhost:3000';
+  const lines: string[] = [];
+
+  lines.push(`// Auto-generated API client for ${spec.info.title} v${spec.info.version}`);
+  lines.push(`// Generated by TRUSS API MCP`);
+  lines.push('');
+
+  if (style === 'axios') {
+    lines.push(`import axios, { type AxiosInstance, type AxiosResponse } from 'axios';`);
+    lines.push('');
+  }
+
+  // Generate interfaces from endpoints
+  const interfaces = generateTypeScriptInterfaces(spec);
+  if (interfaces) {
+    lines.push(interfaces);
+    lines.push('');
+  }
+
+  // Client class
+  lines.push(`export class ApiClient {`);
+  lines.push(`  private baseUrl: string;`);
+
+  if (style === 'axios') {
+    lines.push(`  private client: AxiosInstance;`);
+  } else {
+    lines.push(`  private headers: Record<string, string>;`);
+  }
+
+  lines.push('');
+  lines.push(`  constructor(baseUrl = '${baseUrl}', headers: Record<string, string> = {}) {`);
+  lines.push(`    this.baseUrl = baseUrl.replace(/\\/$/, '');`);
+
+  if (style === 'axios') {
+    lines.push(`    this.client = axios.create({`);
+    lines.push(`      baseURL: this.baseUrl,`);
+    lines.push(`      headers: { 'Content-Type': 'application/json', ...headers },`);
+    lines.push(`    });`);
+  } else {
+    lines.push(`    this.headers = { 'Content-Type': 'application/json', ...headers };`);
+  }
+
+  lines.push(`  }`);
+  lines.push('');
+
+  // Generate methods
+  for (const endpoint of spec.endpoints) {
+    const methodName = endpointToMethodName(endpoint);
+    const hasBody = ['POST', 'PUT', 'PATCH'].includes(endpoint.method);
+    const pathParams = endpoint.parameters.filter((p) => p.in === 'path');
+    const queryParams = endpoint.parameters.filter((p) => p.in === 'query');
+
+    // Build parameter list
+    const params: string[] = [];
+    for (const pp of pathParams) {
+      params.push(`${pp.name}: ${tsType(pp.schema)}`);
+    }
+    if (hasBody) {
+      params.push(`body: ${tsBodyType(endpoint.requestBody)}`);
+    }
+    if (queryParams.length > 0) {
+      const queryType = queryParams
+        .map((q) => `${q.name}${q.required ? '' : '?'}: ${tsType(q.schema)}`)
+        .join('; ');
+      params.push(`query?: { ${queryType} }`);
+    }
+
+    // JSDoc
+    if (endpoint.summary) {
+      lines.push(`  /** ${endpoint.summary} */`);
+    }
+
+    const returnType = tsResponseType(endpoint);
+
+    if (style === 'axios') {
+      lines.push(`  async ${methodName}(${params.join(', ')}): Promise<AxiosResponse<${returnType}>> {`);
+      const urlExpr = buildUrlExpr(endpoint, 'this.baseUrl');
+      const queryExpr = queryParams.length > 0 ? ', params: query' : '';
+      if (hasBody) {
+        lines.push(`    return this.client.${endpoint.method.toLowerCase()}(${urlExpr}, body${queryExpr ? `, { ${queryExpr.slice(2)} }` : ''});`);
+      } else {
+        lines.push(`    return this.client.${endpoint.method.toLowerCase()}(${urlExpr}${queryExpr ? `, { ${queryExpr.slice(2)} }` : ''});`);
+      }
+    } else {
+      lines.push(`  async ${methodName}(${params.join(', ')}): Promise<${returnType}> {`);
+      const urlExpr = buildUrlExpr(endpoint, 'this.baseUrl');
+
+      if (queryParams.length > 0) {
+        lines.push(`    const url = new URL(${urlExpr});`);
+        lines.push(`    if (query) {`);
+        lines.push(`      for (const [k, v] of Object.entries(query)) {`);
+        lines.push(`        if (v !== undefined) url.searchParams.set(k, String(v));`);
+        lines.push(`      }`);
+        lines.push(`    }`);
+        lines.push(`    const response = await fetch(url.toString(), {`);
+      } else {
+        lines.push(`    const response = await fetch(${urlExpr}, {`);
+      }
+
+      lines.push(`      method: '${endpoint.method}',`);
+      lines.push(`      headers: this.headers,`);
+      if (hasBody) {
+        lines.push(`      body: JSON.stringify(body),`);
+      }
+      lines.push(`    });`);
+      lines.push(`    if (!response.ok) {`);
+      lines.push(`      throw new Error(\`HTTP \${response.status}: \${response.statusText}\`);`);
+      lines.push(`    }`);
+      lines.push(`    return response.json() as Promise<${returnType}>;`);
+    }
+
+    lines.push(`  }`);
+    lines.push('');
+  }
+
+  lines.push(`}`);
+
+  return lines.join('\n');
+}
+
+function generateTypeScriptInterfaces(spec: ParsedOpenApiSpec): string {
+  const lines: string[] = [];
+  const seen = new Set<string>();
+
+  for (const endpoint of spec.endpoints) {
+    // Generate request body interface
+    if (endpoint.requestBody?.properties) {
+      const name = pascalCase(endpointToMethodName(endpoint)) + 'Request';
+      if (!seen.has(name)) {
+        seen.add(name);
+        lines.push(schemaToTsInterface(name, endpoint.requestBody));
+        lines.push('');
+      }
+    }
+
+    // Generate response interface
+    const okResponse = endpoint.responses.find(
+      (r) => r.status === '200' || r.status === '201'
+    );
+    if (okResponse?.schema?.properties) {
+      const name = pascalCase(endpointToMethodName(endpoint)) + 'Response';
+      if (!seen.has(name)) {
+        seen.add(name);
+        lines.push(schemaToTsInterface(name, okResponse.schema));
+        lines.push('');
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function schemaToTsInterface(name: string, schema: JsonSchema): string {
+  const lines = [`export interface ${name} {`];
+  if (schema.properties) {
+    const required = new Set(schema.required ?? []);
+    for (const [key, prop] of Object.entries(schema.properties)) {
+      const optional = required.has(key) ? '' : '?';
+      lines.push(`  ${key}${optional}: ${tsType(prop)};`);
+    }
+  }
+  lines.push('}');
+  return lines.join('\n');
+}
+
+function tsType(schema?: JsonSchema): string {
+  if (!schema) return 'unknown';
+  if (schema.enum) {
+    return schema.enum.map((v) => JSON.stringify(v)).join(' | ');
+  }
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  switch (type) {
+    case 'string':
+      return 'string';
+    case 'integer':
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'array':
+      return `${tsType(schema.items)}[]`;
+    case 'object':
+      if (schema.properties) {
+        const props = Object.entries(schema.properties)
+          .map(([k, v]) => `${k}: ${tsType(v)}`)
+          .join('; ');
+        return `{ ${props} }`;
+      }
+      return 'Record<string, unknown>';
+    default:
+      return 'unknown';
+  }
+}
+
+function tsBodyType(schema?: JsonSchema): string {
+  if (!schema) return 'Record<string, unknown>';
+  return tsType(schema);
+}
+
+function tsResponseType(endpoint: OpenApiEndpoint): string {
+  const okResp = endpoint.responses.find((r) => r.status === '200' || r.status === '201');
+  if (okResp?.schema) return tsType(okResp.schema);
+  return 'unknown';
+}
+
+// ── Python Client ───────────────────────────────────────────────────
+
+function generatePythonClient(spec: ParsedOpenApiSpec): string {
+  const baseUrl = spec.servers?.[0]?.url ?? 'http://localhost:3000';
+  const lines: string[] = [];
+
+  lines.push(`"""Auto-generated API client for ${spec.info.title} v${spec.info.version}"""`);
+  lines.push(`# Generated by TRUSS API MCP`);
+  lines.push('');
+  lines.push('from __future__ import annotations');
+  lines.push('');
+  lines.push('from dataclasses import dataclass');
+  lines.push('from typing import Any, Optional');
+  lines.push('');
+  lines.push('import requests');
+  lines.push('');
+  lines.push('');
+
+  // Dataclasses for request/response types
+  for (const endpoint of spec.endpoints) {
+    if (endpoint.requestBody?.properties) {
+      const className = snakeToPascal(endpointToMethodName(endpoint)) + 'Request';
+      lines.push(`@dataclass`);
+      lines.push(`class ${className}:`);
+      for (const [key, prop] of Object.entries(endpoint.requestBody.properties)) {
+        lines.push(`    ${key}: ${pyType(prop)}`);
+      }
+      lines.push('');
+      lines.push('');
+    }
+  }
+
+  lines.push(`class ApiClient:`);
+  lines.push(`    """API client for ${spec.info.title}"""`);
+  lines.push('');
+  lines.push(`    def __init__(self, base_url: str = "${baseUrl}", headers: Optional[dict[str, str]] = None):`);
+  lines.push(`        self.base_url = base_url.rstrip("/")`);
+  lines.push(`        self.session = requests.Session()`);
+  lines.push(`        self.session.headers.update({"Content-Type": "application/json"})`);
+  lines.push(`        if headers:`);
+  lines.push(`            self.session.headers.update(headers)`);
+  lines.push('');
+
+  for (const endpoint of spec.endpoints) {
+    const methodName = camelToSnake(endpointToMethodName(endpoint));
+    const hasBody = ['POST', 'PUT', 'PATCH'].includes(endpoint.method);
+    const pathParams = endpoint.parameters.filter((p) => p.in === 'path');
+    const queryParams = endpoint.parameters.filter((p) => p.in === 'query');
+
+    const params: string[] = ['self'];
+    for (const pp of pathParams) {
+      params.push(`${pp.name}: ${pyType(pp.schema)}`);
+    }
+    if (hasBody) {
+      params.push(`body: dict[str, Any]`);
+    }
+    if (queryParams.length > 0) {
+      params.push(`params: Optional[dict[str, Any]] = None`);
+    }
+
+    const docstring = endpoint.summary ? `        """${endpoint.summary}"""` : '';
+
+    lines.push(`    def ${methodName}(${params.join(', ')}) -> requests.Response:`);
+    if (docstring) lines.push(docstring);
+
+    // Build URL
+    let urlPath = endpoint.path;
+    for (const pp of pathParams) {
+      urlPath = urlPath.replace(`{${pp.name}}`, `{${pp.name}}`);
+    }
+    lines.push(`        url = f"{self.base_url}${urlPath}"`);
+
+    const kwargs: string[] = [];
+    if (hasBody) kwargs.push('json=body');
+    if (queryParams.length > 0) kwargs.push('params=params');
+
+    lines.push(
+      `        response = self.session.${endpoint.method.toLowerCase()}(url${kwargs.length ? ', ' + kwargs.join(', ') : ''})`
+    );
+    lines.push(`        response.raise_for_status()`);
+    lines.push(`        return response`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function pyType(schema?: JsonSchema): string {
+  if (!schema) return 'Any';
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  switch (type) {
+    case 'string':
+      return 'str';
+    case 'integer':
+      return 'int';
+    case 'number':
+      return 'float';
+    case 'boolean':
+      return 'bool';
+    case 'array':
+      return `list[${pyType(schema.items)}]`;
+    case 'object':
+      return 'dict[str, Any]';
+    default:
+      return 'Any';
+  }
+}
+
+// ── Go Client ───────────────────────────────────────────────────────
+
+function generateGoClient(spec: ParsedOpenApiSpec): string {
+  const baseUrl = spec.servers?.[0]?.url ?? 'http://localhost:3000';
+  const lines: string[] = [];
+
+  lines.push(`// Auto-generated API client for ${spec.info.title} v${spec.info.version}`);
+  lines.push(`// Generated by TRUSS API MCP`);
+  lines.push('');
+  lines.push('package apiclient');
+  lines.push('');
+  lines.push('import (');
+  lines.push('\t"bytes"');
+  lines.push('\t"encoding/json"');
+  lines.push('\t"fmt"');
+  lines.push('\t"io"');
+  lines.push('\t"net/http"');
+  lines.push('\t"net/url"');
+  lines.push(')');
+  lines.push('');
+
+  // Generate structs for request/response types
+  for (const endpoint of spec.endpoints) {
+    if (endpoint.requestBody?.properties) {
+      const structName = pascalCase(endpointToMethodName(endpoint)) + 'Request';
+      lines.push(schemaToGoStruct(structName, endpoint.requestBody));
+      lines.push('');
+    }
+
+    const okResp = endpoint.responses.find((r) => r.status === '200' || r.status === '201');
+    if (okResp?.schema?.properties) {
+      const structName = pascalCase(endpointToMethodName(endpoint)) + 'Response';
+      lines.push(schemaToGoStruct(structName, okResp.schema));
+      lines.push('');
+    }
+  }
+
+  // Client struct
+  lines.push('// Client is the API client.');
+  lines.push('type Client struct {');
+  lines.push('\tBaseURL    string');
+  lines.push('\tHTTPClient *http.Client');
+  lines.push('\tHeaders    map[string]string');
+  lines.push('}');
+  lines.push('');
+
+  // Constructor
+  lines.push('// NewClient creates a new API client.');
+  lines.push(`func NewClient(baseURL string) *Client {`);
+  lines.push('\tif baseURL == "" {');
+  lines.push(`\t\tbaseURL = "${baseUrl}"`);
+  lines.push('\t}');
+  lines.push('\treturn &Client{');
+  lines.push('\t\tBaseURL:    baseURL,');
+  lines.push('\t\tHTTPClient: &http.Client{},');
+  lines.push('\t\tHeaders: map[string]string{');
+  lines.push('\t\t\t"Content-Type": "application/json",');
+  lines.push('\t\t},');
+  lines.push('\t}');
+  lines.push('}');
+  lines.push('');
+
+  // Helper method
+  lines.push('func (c *Client) do(method, path string, body interface{}, result interface{}) error {');
+  lines.push('\tvar bodyReader io.Reader');
+  lines.push('\tif body != nil {');
+  lines.push('\t\tdata, err := json.Marshal(body)');
+  lines.push('\t\tif err != nil {');
+  lines.push('\t\t\treturn fmt.Errorf("marshal request: %w", err)');
+  lines.push('\t\t}');
+  lines.push('\t\tbodyReader = bytes.NewReader(data)');
+  lines.push('\t}');
+  lines.push('');
+  lines.push('\treq, err := http.NewRequest(method, c.BaseURL+path, bodyReader)');
+  lines.push('\tif err != nil {');
+  lines.push('\t\treturn fmt.Errorf("create request: %w", err)');
+  lines.push('\t}');
+  lines.push('\tfor k, v := range c.Headers {');
+  lines.push('\t\treq.Header.Set(k, v)');
+  lines.push('\t}');
+  lines.push('');
+  lines.push('\tresp, err := c.HTTPClient.Do(req)');
+  lines.push('\tif err != nil {');
+  lines.push('\t\treturn fmt.Errorf("execute request: %w", err)');
+  lines.push('\t}');
+  lines.push('\tdefer resp.Body.Close()');
+  lines.push('');
+  lines.push('\tif resp.StatusCode >= 400 {');
+  lines.push('\t\treturn fmt.Errorf("HTTP %d: %s", resp.StatusCode, resp.Status)');
+  lines.push('\t}');
+  lines.push('');
+  lines.push('\tif result != nil {');
+  lines.push('\t\tif err := json.NewDecoder(resp.Body).Decode(result); err != nil {');
+  lines.push('\t\t\treturn fmt.Errorf("decode response: %w", err)');
+  lines.push('\t\t}');
+  lines.push('\t}');
+  lines.push('\treturn nil');
+  lines.push('}');
+  lines.push('');
+
+  // Generate methods
+  for (const endpoint of spec.endpoints) {
+    const methodName = pascalCase(endpointToMethodName(endpoint));
+    const hasBody = ['POST', 'PUT', 'PATCH'].includes(endpoint.method);
+    const pathParams = endpoint.parameters.filter((p) => p.in === 'path');
+    const queryParams = endpoint.parameters.filter((p) => p.in === 'query');
+
+    // Build parameters
+    const goParams: string[] = [];
+    for (const pp of pathParams) {
+      goParams.push(`${pp.name} ${goType(pp.schema)}`);
+    }
+    if (hasBody) {
+      const bodyStruct = pascalCase(endpointToMethodName(endpoint)) + 'Request';
+      const hasStruct = endpoint.requestBody?.properties;
+      goParams.push(`body ${hasStruct ? '*' + bodyStruct : 'interface{}'}`);
+    }
+    if (queryParams.length > 0) {
+      goParams.push(`params map[string]string`);
+    }
+
+    const okResp = endpoint.responses.find((r) => r.status === '200' || r.status === '201');
+    const hasResponseStruct = okResp?.schema?.properties;
+    const respType = hasResponseStruct
+      ? '*' + pascalCase(endpointToMethodName(endpoint)) + 'Response'
+      : 'error';
+    const returnType = hasResponseStruct ? `(${respType}, error)` : 'error';
+
+    if (endpoint.summary) {
+      lines.push(`// ${methodName} ${endpoint.summary}`);
+    }
+    lines.push(`func (c *Client) ${methodName}(${goParams.join(', ')}) ${returnType} {`);
+
+    // Build URL path with substitutions
+    let urlPath = endpoint.path;
+    for (const pp of pathParams) {
+      urlPath = urlPath.replace(
+        `{${pp.name}}`,
+        `" + fmt.Sprintf("%v", ${pp.name}) + "`
+      );
+    }
+    // Clean up empty concatenations
+    urlPath = urlPath.replace(/\+ ""$/, '').replace(/"" \+ /, '');
+
+    if (queryParams.length > 0) {
+      lines.push(`\tpath := "${urlPath}"`);
+      lines.push(`\tif len(params) > 0 {`);
+      lines.push(`\t\tv := url.Values{}`);
+      lines.push(`\t\tfor k, val := range params {`);
+      lines.push(`\t\t\tv.Set(k, val)`);
+      lines.push(`\t\t}`);
+      lines.push(`\t\tpath += "?" + v.Encode()`);
+      lines.push(`\t}`);
+
+      if (hasResponseStruct) {
+        lines.push(`\tvar result ${pascalCase(endpointToMethodName(endpoint))}Response`);
+        lines.push(`\terr := c.do("${endpoint.method}", path, ${hasBody ? 'body' : 'nil'}, &result)`);
+        lines.push(`\treturn &result, err`);
+      } else {
+        lines.push(`\treturn c.do("${endpoint.method}", path, ${hasBody ? 'body' : 'nil'}, nil)`);
+      }
+    } else {
+      if (hasResponseStruct) {
+        lines.push(`\tvar result ${pascalCase(endpointToMethodName(endpoint))}Response`);
+        lines.push(`\terr := c.do("${endpoint.method}", "${urlPath}", ${hasBody ? 'body' : 'nil'}, &result)`);
+        lines.push(`\treturn &result, err`);
+      } else {
+        lines.push(`\treturn c.do("${endpoint.method}", "${urlPath}", ${hasBody ? 'body' : 'nil'}, nil)`);
+      }
+    }
+
+    lines.push('}');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function schemaToGoStruct(name: string, schema: JsonSchema): string {
+  const lines = [`type ${name} struct {`];
+  if (schema.properties) {
+    for (const [key, prop] of Object.entries(schema.properties)) {
+      const fieldName = pascalCase(key);
+      const tag = `\`json:"${key}"\``;
+      lines.push(`\t${fieldName} ${goType(prop)} ${tag}`);
+    }
+  }
+  lines.push('}');
+  return lines.join('\n');
+}
+
+function goType(schema?: JsonSchema): string {
+  if (!schema) return 'interface{}';
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  switch (type) {
+    case 'string':
+      return 'string';
+    case 'integer':
+      return 'int64';
+    case 'number':
+      return 'float64';
+    case 'boolean':
+      return 'bool';
+    case 'array':
+      return `[]${goType(schema.items)}`;
+    case 'object':
+      return 'map[string]interface{}';
+    default:
+      return 'interface{}';
+  }
+}
+
+// ── Test Generation ─────────────────────────────────────────────────
+
+export function generateTests(
+  spec: ParsedOpenApiSpec,
+  baseUrl: string,
+  framework: TestFramework = 'vitest'
+): string {
+  switch (framework) {
+    case 'jest':
+    case 'vitest':
+      return generateJsTests(spec, baseUrl, framework);
+    case 'pytest':
+      return generatePytestTests(spec, baseUrl);
+  }
+}
+
+function generateJsTests(
+  spec: ParsedOpenApiSpec,
+  baseUrl: string,
+  framework: TestFramework
+): string {
+  const lines: string[] = [];
+
+  lines.push(`// Auto-generated API tests for ${spec.info.title}`);
+  lines.push(`// Generated by TRUSS API MCP`);
+  lines.push('');
+
+  if (framework === 'vitest') {
+    lines.push(`import { describe, it, expect } from 'vitest';`);
+  }
+
+  lines.push('');
+  lines.push(`const BASE_URL = '${baseUrl}';`);
+  lines.push('');
+
+  // Group by tags or paths
+  const groups = groupEndpoints(spec.endpoints);
+
+  for (const [groupName, endpoints] of groups) {
+    lines.push(`describe('${groupName}', () => {`);
+
+    for (const endpoint of endpoints) {
+      const testName = `${endpoint.method} ${endpoint.path}`;
+      const hasBody = ['POST', 'PUT', 'PATCH'].includes(endpoint.method);
+
+      // Happy path test
+      lines.push(`  it('${testName} — returns success', async () => {`);
+
+      // Build URL with sample path params
+      let testUrl = endpoint.path;
+      for (const param of endpoint.parameters.filter((p) => p.in === 'path')) {
+        testUrl = testUrl.replace(`{${param.name}}`, sampleValue(param.schema, param.name));
+      }
+
+      // Add query params
+      const queryParams = endpoint.parameters.filter((p) => p.in === 'query' && p.required);
+      if (queryParams.length > 0) {
+        const qs = queryParams
+          .map((q) => `${q.name}=${encodeURIComponent(sampleValue(q.schema, q.name))}`)
+          .join('&');
+        testUrl += `?${qs}`;
+      }
+
+      lines.push(`    const response = await fetch(\`\${BASE_URL}${testUrl}\`, {`);
+      lines.push(`      method: '${endpoint.method}',`);
+      lines.push(`      headers: { 'Content-Type': 'application/json' },`);
+
+      if (hasBody && endpoint.requestBody) {
+        const sampleBody = generateSampleBody(endpoint.requestBody);
+        lines.push(`      body: JSON.stringify(${JSON.stringify(sampleBody, null, 6).replace(/\n/g, '\n      ')}),`);
+      }
+
+      lines.push(`    });`);
+      lines.push('');
+
+      // Assertions
+      const okStatus = endpoint.responses.find(
+        (r) => r.status === '200' || r.status === '201' || r.status === '204'
+      );
+      const expectedStatus = okStatus ? parseInt(okStatus.status, 10) : 200;
+
+      lines.push(`    expect(response.status).toBe(${expectedStatus});`);
+
+      if (expectedStatus !== 204) {
+        lines.push(`    const data = await response.json();`);
+        lines.push(`    expect(data).toBeDefined();`);
+
+        // Add property checks if schema is known
+        if (okStatus?.schema?.properties) {
+          for (const key of Object.keys(okStatus.schema.properties)) {
+            lines.push(`    expect(data).toHaveProperty('${key}');`);
+          }
+        }
+      }
+
+      lines.push(`  });`);
+      lines.push('');
+
+      // 404 test for endpoints with path params
+      if (endpoint.parameters.some((p) => p.in === 'path')) {
+        lines.push(`  it('${testName} — returns 404 for invalid ID', async () => {`);
+        let badUrl = endpoint.path;
+        for (const param of endpoint.parameters.filter((p) => p.in === 'path')) {
+          badUrl = badUrl.replace(`{${param.name}}`, '99999999');
+        }
+        lines.push(`    const response = await fetch(\`\${BASE_URL}${badUrl}\`, {`);
+        lines.push(`      method: '${endpoint.method}',`);
+        lines.push(`      headers: { 'Content-Type': 'application/json' },`);
+        lines.push(`    });`);
+        lines.push(`    expect(response.status).toBe(404);`);
+        lines.push(`  });`);
+        lines.push('');
+      }
+    }
+
+    lines.push('});');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function generatePytestTests(spec: ParsedOpenApiSpec, baseUrl: string): string {
+  const lines: string[] = [];
+
+  lines.push(`"""Auto-generated API tests for ${spec.info.title}"""`);
+  lines.push(`# Generated by TRUSS API MCP`);
+  lines.push('');
+  lines.push('import pytest');
+  lines.push('import requests');
+  lines.push('');
+  lines.push(`BASE_URL = "${baseUrl}"`);
+  lines.push('');
+  lines.push('');
+
+  for (const endpoint of spec.endpoints) {
+    const funcName = `test_${endpoint.method.toLowerCase()}_${endpoint.path.replace(/[/{}\-]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '')}`;
+    const hasBody = ['POST', 'PUT', 'PATCH'].includes(endpoint.method);
+
+    let testUrl = endpoint.path;
+    for (const param of endpoint.parameters.filter((p) => p.in === 'path')) {
+      testUrl = testUrl.replace(`{${param.name}}`, sampleValue(param.schema, param.name));
+    }
+
+    lines.push(`def ${funcName}():`);
+    if (endpoint.summary) {
+      lines.push(`    """${endpoint.summary}"""`);
+    }
+    lines.push(`    url = f"{BASE_URL}${testUrl}"`);
+
+    if (hasBody && endpoint.requestBody) {
+      const sampleBody = generateSampleBody(endpoint.requestBody);
+      lines.push(`    payload = ${JSON.stringify(sampleBody)}`);
+      lines.push(
+        `    response = requests.${endpoint.method.toLowerCase()}(url, json=payload, headers={"Content-Type": "application/json"})`
+      );
+    } else {
+      lines.push(
+        `    response = requests.${endpoint.method.toLowerCase()}(url, headers={"Content-Type": "application/json"})`
+      );
+    }
+
+    const okStatus = endpoint.responses.find(
+      (r) => r.status === '200' || r.status === '201' || r.status === '204'
+    );
+    const expectedStatus = okStatus ? parseInt(okStatus.status, 10) : 200;
+
+    lines.push(`    assert response.status_code == ${expectedStatus}`);
+
+    if (expectedStatus !== 204) {
+      lines.push(`    data = response.json()`);
+      lines.push(`    assert data is not None`);
+    }
+
+    lines.push('');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ── Mock Server Generation ──────────────────────────────────────────
+
+export function generateMockServer(spec: ParsedOpenApiSpec): MockServerConfig {
+  const routes: MockRoute[] = [];
+  const mockData: Record<string, unknown> = {};
+
+  for (const endpoint of spec.endpoints) {
+    const okResp = endpoint.responses.find(
+      (r) => r.status === '200' || r.status === '201'
+    );
+    const status = okResp ? parseInt(okResp.status, 10) : 200;
+
+    let mockResponse: unknown;
+    if (okResp?.schema) {
+      mockResponse = generateMockData(okResp.schema, endpoint.path);
+    } else {
+      mockResponse = { message: 'OK' };
+    }
+
+    // Convert OpenAPI path params to Express-style for json-server
+    const routePath = endpoint.path.replace(/\{(\w+)\}/g, ':$1');
+
+    routes.push({
+      method: endpoint.method,
+      path: routePath,
+      status,
+      response: mockResponse,
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    // Store in mock_data for json-server db.json format
+    const resourceName = endpoint.path
+      .split('/')[1]
+      ?.replace(/[^a-zA-Z0-9]/g, '') ?? 'data';
+
+    if (!mockData[resourceName] && Array.isArray(mockResponse)) {
+      mockData[resourceName] = mockResponse;
+    } else if (!mockData[resourceName] && typeof mockResponse === 'object') {
+      // For list endpoints, wrap in array
+      if (endpoint.method === 'GET' && !endpoint.parameters.some((p) => p.in === 'path')) {
+        mockData[resourceName] = [mockResponse];
+      }
+    }
+  }
+
+  return { routes, mock_data: mockData };
+}
+
+function generateMockData(schema: JsonSchema, context: string): unknown {
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+
+  switch (type) {
+    case 'string': {
+      if (schema.enum) return schema.enum[0];
+      if (schema.format === 'date-time') return '2026-01-15T10:00:00Z';
+      if (schema.format === 'email') return 'user@example.com';
+      if (schema.format === 'uri') return 'https://example.com';
+      return `sample_${context.replace(/[^a-z]/gi, '_')}`;
+    }
+    case 'integer':
+      return 1;
+    case 'number':
+      return 1.0;
+    case 'boolean':
+      return true;
+    case 'array':
+      return schema.items ? [generateMockData(schema.items, context)] : [];
+    case 'object': {
+      if (!schema.properties) return {};
+      const obj: Record<string, unknown> = {};
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        obj[key] = generateMockData(propSchema, key);
+      }
+      return obj;
+    }
+    default:
+      return null;
+  }
+}
+
+// ── Spec Comparison ─────────────────────────────────────────────────
+
+export function compareSpecs(
+  oldSpec: ParsedOpenApiSpec,
+  newSpec: ParsedOpenApiSpec
+): SpecComparison {
+  const breaking: SpecChange[] = [];
+  const nonBreaking: SpecChange[] = [];
+  const newEndpoints: SpecChange[] = [];
+  const removedEndpoints: SpecChange[] = [];
+
+  // Build maps
+  const oldMap = new Map<string, OpenApiEndpoint>();
+  const newMap = new Map<string, OpenApiEndpoint>();
+
+  for (const ep of oldSpec.endpoints) {
+    oldMap.set(`${ep.method} ${ep.path}`, ep);
+  }
+  for (const ep of newSpec.endpoints) {
+    newMap.set(`${ep.method} ${ep.path}`, ep);
+  }
+
+  // Find removed endpoints (breaking)
+  for (const [key, ep] of oldMap) {
+    if (!newMap.has(key)) {
+      const change: SpecChange = {
+        path: ep.path,
+        method: ep.method,
+        description: `Endpoint removed: ${ep.method} ${ep.path}`,
+      };
+      removedEndpoints.push(change);
+      breaking.push(change);
+    }
+  }
+
+  // Find new endpoints
+  for (const [key, ep] of newMap) {
+    if (!oldMap.has(key)) {
+      newEndpoints.push({
+        path: ep.path,
+        method: ep.method,
+        description: `New endpoint: ${ep.method} ${ep.path}`,
+      });
+    }
+  }
+
+  // Compare matching endpoints
+  for (const [key, oldEp] of oldMap) {
+    const newEp = newMap.get(key);
+    if (!newEp) continue;
+
+    // Check required parameters
+    const oldRequired = new Set(
+      oldEp.parameters.filter((p) => p.required).map((p) => p.name)
+    );
+    const newRequired = new Set(
+      newEp.parameters.filter((p) => p.required).map((p) => p.name)
+    );
+
+    // New required parameters = breaking
+    for (const name of newRequired) {
+      if (!oldRequired.has(name)) {
+        breaking.push({
+          path: oldEp.path,
+          method: oldEp.method,
+          description: `New required parameter: ${name}`,
+        });
+      }
+    }
+
+    // Removed required parameters = non-breaking (parameter relaxed)
+    for (const name of oldRequired) {
+      if (!newRequired.has(name)) {
+        nonBreaking.push({
+          path: oldEp.path,
+          method: oldEp.method,
+          description: `Required parameter removed (relaxed): ${name}`,
+        });
+      }
+    }
+
+    // New optional parameters = non-breaking
+    const oldParamNames = new Set(oldEp.parameters.map((p) => p.name));
+    for (const p of newEp.parameters) {
+      if (!oldParamNames.has(p.name) && !p.required) {
+        nonBreaking.push({
+          path: oldEp.path,
+          method: oldEp.method,
+          description: `New optional parameter: ${p.name}`,
+        });
+      }
+    }
+
+    // Check response schema changes
+    for (const oldResp of oldEp.responses) {
+      const newResp = newEp.responses.find((r) => r.status === oldResp.status);
+      if (!newResp) {
+        breaking.push({
+          path: oldEp.path,
+          method: oldEp.method,
+          description: `Response ${oldResp.status} removed`,
+        });
+        continue;
+      }
+
+      // Check if response properties were removed (breaking)
+      if (oldResp.schema?.properties && newResp.schema?.properties) {
+        for (const key of Object.keys(oldResp.schema.properties)) {
+          if (!(key in newResp.schema.properties)) {
+            breaking.push({
+              path: oldEp.path,
+              method: oldEp.method,
+              description: `Response property '${key}' removed from ${oldResp.status}`,
+            });
+          }
+        }
+        // New response properties = non-breaking
+        for (const key of Object.keys(newResp.schema.properties)) {
+          if (!(key in oldResp.schema.properties)) {
+            nonBreaking.push({
+              path: oldEp.path,
+              method: oldEp.method,
+              description: `New response property '${key}' added to ${newResp.status}`,
+            });
+          }
+        }
+      }
+    }
+
+    // Summary change = non-breaking
+    if (oldEp.summary !== newEp.summary) {
+      nonBreaking.push({
+        path: oldEp.path,
+        method: oldEp.method,
+        description: `Summary changed: "${oldEp.summary}" -> "${newEp.summary}"`,
+      });
+    }
+  }
+
+  return {
+    breaking_changes: breaking,
+    non_breaking: nonBreaking,
+    new_endpoints: newEndpoints,
+    removed_endpoints: removedEndpoints,
+  };
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+function endpointToMethodName(endpoint: OpenApiEndpoint): string {
+  if (endpoint.operationId) {
+    return camelCase(endpoint.operationId);
+  }
+  const parts = endpoint.path
+    .split('/')
+    .filter((p) => p && !p.startsWith('{'))
+    .map((p) => p.replace(/[^a-zA-Z0-9]/g, ''));
+  const verb = endpoint.method.toLowerCase();
+  return camelCase(`${verb}_${parts.join('_')}`);
+}
+
+function camelCase(str: string): string {
+  return str
+    .replace(/[-_]+(.)/g, (_, c: string) => c.toUpperCase())
+    .replace(/^(.)/, (_, c: string) => c.toLowerCase());
+}
+
+function pascalCase(str: string): string {
+  const cc = camelCase(str);
+  return cc.charAt(0).toUpperCase() + cc.slice(1);
+}
+
+function snakeToPascal(str: string): string {
+  return str
+    .split(/[-_]/)
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join('');
+}
+
+function camelToSnake(str: string): string {
+  return str.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+
+function buildUrlExpr(endpoint: OpenApiEndpoint, baseVarName: string): string {
+  const pathParams = endpoint.parameters.filter((p) => p.in === 'path');
+  if (pathParams.length === 0) {
+    return `\`\${${baseVarName}}${endpoint.path}\``;
+  }
+
+  let path = endpoint.path;
+  for (const pp of pathParams) {
+    path = path.replace(`{${pp.name}}`, `\${${pp.name}}`);
+  }
+  return `\`\${${baseVarName}}${path}\``;
+}
+
+function sampleValue(schema?: JsonSchema, name?: string): string {
+  if (!schema) return '1';
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  if (type === 'integer' || type === 'number') return '1';
+  if (name?.toLowerCase().includes('id')) return '1';
+  return 'test';
+}
+
+function generateSampleBody(schema: JsonSchema): Record<string, unknown> {
+  if (!schema.properties) return {};
+  const body: Record<string, unknown> = {};
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    body[key] = generateMockData(prop, key);
+  }
+  return body;
+}
+
+function groupEndpoints(
+  endpoints: OpenApiEndpoint[]
+): Map<string, OpenApiEndpoint[]> {
+  const groups = new Map<string, OpenApiEndpoint[]>();
+
+  for (const ep of endpoints) {
+    const group = ep.tags?.[0] ?? ep.path.split('/')[1] ?? 'API';
+    if (!groups.has(group)) groups.set(group, []);
+    groups.get(group)!.push(ep);
+  }
+
+  return groups;
+}