truss-api-mcp 1.0.0

package/src/lib/schema-validator.ts

@@ -0,0 +1,234 @@
+import type { JsonSchema, ValidationError, ValidationResult } from '../types.js';
+
+/**
+ * Validate a value against a JSON Schema (draft-07 subset).
+ * Supports: type, properties, required, items, enum, minimum, maximum,
+ * minLength, maxLength, pattern, additionalProperties, oneOf, anyOf, allOf, nullable.
+ */
+export function validateSchema(
+  value: unknown,
+  schema: JsonSchema,
+  path = '$'
+): ValidationResult {
+  const errors: ValidationError[] = [];
+  validate(value, schema, path, errors);
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate an HTTP response against expected status and optional schema.
+ */
+export function validateResponse(
+  response: { status: number; body: unknown },
+  expectedStatus: number,
+  expectedSchema?: JsonSchema
+): ValidationResult {
+  const errors: ValidationError[] = [];
+
+  if (response.status !== expectedStatus) {
+    errors.push({
+      path: '$.status',
+      message: `Expected status ${expectedStatus}, got ${response.status}`,
+      expected: String(expectedStatus),
+      actual: String(response.status),
+    });
+  }
+
+  if (expectedSchema) {
+    const bodyResult = validateSchema(response.body, expectedSchema, '$.body');
+    errors.push(...bodyResult.errors);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ── Internal Validation ─────────────────────────────────────────────
+
+function validate(
+  value: unknown,
+  schema: JsonSchema,
+  path: string,
+  errors: ValidationError[]
+): void {
+  // Handle nullable
+  if (schema.nullable && (value === null || value === undefined)) {
+    return;
+  }
+
+  // allOf: all must match
+  if (schema.allOf) {
+    for (const sub of schema.allOf) {
+      validate(value, sub, path, errors);
+    }
+    return;
+  }
+
+  // anyOf: at least one must match
+  if (schema.anyOf) {
+    const anyErrors: ValidationError[][] = [];
+    for (const sub of schema.anyOf) {
+      const subErrors: ValidationError[] = [];
+      validate(value, sub, path, subErrors);
+      if (subErrors.length === 0) return; // matched
+      anyErrors.push(subErrors);
+    }
+    errors.push({
+      path,
+      message: `Value does not match any of the ${schema.anyOf.length} schemas in anyOf`,
+    });
+    return;
+  }
+
+  // oneOf: exactly one must match
+  if (schema.oneOf) {
+    let matchCount = 0;
+    for (const sub of schema.oneOf) {
+      const subErrors: ValidationError[] = [];
+      validate(value, sub, path, subErrors);
+      if (subErrors.length === 0) matchCount++;
+    }
+    if (matchCount !== 1) {
+      errors.push({
+        path,
+        message: `Value must match exactly one schema in oneOf, but matched ${matchCount}`,
+      });
+    }
+    return;
+  }
+
+  // enum
+  if (schema.enum) {
+    if (!schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value))) {
+      errors.push({
+        path,
+        message: `Value must be one of: ${schema.enum.map((e) => JSON.stringify(e)).join(', ')}`,
+        actual: JSON.stringify(value),
+      });
+    }
+    return;
+  }
+
+  // type checking
+  if (schema.type) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    const actualType = getJsonType(value);
+
+    if (!types.includes(actualType)) {
+      // Allow integer to match number
+      if (!(actualType === 'integer' && types.includes('number'))) {
+        // Allow null if nullable
+        if (!(actualType === 'null' && schema.nullable)) {
+          errors.push({
+            path,
+            message: `Expected type ${types.join('|')}, got ${actualType}`,
+            expected: types.join('|'),
+            actual: actualType,
+          });
+          return;
+        }
+      }
+    }
+  }
+
+  // string validations
+  if (typeof value === 'string') {
+    if (schema.minLength !== undefined && value.length < schema.minLength) {
+      errors.push({
+        path,
+        message: `String length ${value.length} is less than minimum ${schema.minLength}`,
+      });
+    }
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+      errors.push({
+        path,
+        message: `String length ${value.length} exceeds maximum ${schema.maxLength}`,
+      });
+    }
+    if (schema.pattern) {
+      try {
+        if (!new RegExp(schema.pattern).test(value)) {
+          errors.push({
+            path,
+            message: `String does not match pattern: ${schema.pattern}`,
+          });
+        }
+      } catch {
+        // Invalid regex — skip validation
+      }
+    }
+  }
+
+  // number validations
+  if (typeof value === 'number') {
+    if (schema.minimum !== undefined && value < schema.minimum) {
+      errors.push({
+        path,
+        message: `Value ${value} is less than minimum ${schema.minimum}`,
+      });
+    }
+    if (schema.maximum !== undefined && value > schema.maximum) {
+      errors.push({
+        path,
+        message: `Value ${value} exceeds maximum ${schema.maximum}`,
+      });
+    }
+  }
+
+  // object validations
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>;
+
+    // required
+    if (schema.required) {
+      for (const req of schema.required) {
+        if (!(req in obj)) {
+          errors.push({
+            path: `${path}.${req}`,
+            message: `Missing required property: ${req}`,
+          });
+        }
+      }
+    }
+
+    // properties
+    if (schema.properties) {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        if (key in obj) {
+          validate(obj[key], propSchema, `${path}.${key}`, errors);
+        }
+      }
+    }
+
+    // additionalProperties
+    if (schema.additionalProperties === false && schema.properties) {
+      const allowed = new Set(Object.keys(schema.properties));
+      for (const key of Object.keys(obj)) {
+        if (!allowed.has(key)) {
+          errors.push({
+            path: `${path}.${key}`,
+            message: `Additional property not allowed: ${key}`,
+          });
+        }
+      }
+    }
+  }
+
+  // array validations
+  if (Array.isArray(value)) {
+    if (schema.items) {
+      for (let i = 0; i < value.length; i++) {
+        validate(value[i], schema.items, `${path}[${i}]`, errors);
+      }
+    }
+  }
+}
+
+function getJsonType(value: unknown): string {
+  if (value === null) return 'null';
+  if (value === undefined) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'number') {
+    return Number.isInteger(value) ? 'integer' : 'number';
+  }
+  return typeof value; // 'string', 'boolean', 'object'
+}

package/src/tools/compare-specs.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { requirePro } from '../lib/license.js';
+import { parseOpenApiSpec } from '../lib/openapi-parser.js';
+import { compareSpecs } from '../lib/code-generator.js';
+
+export function registerCompareSpecs(server: McpServer): void {
+  server.tool(
+    'compare_specs',
+    '[Pro] Diff two OpenAPI specs and find breaking changes, non-breaking changes, new endpoints, and removed endpoints. Essential for API versioning.',
+    {
+      old_spec: z.string().describe('The old/previous OpenAPI spec as JSON or YAML'),
+      new_spec: z.string().describe('The new/updated OpenAPI spec as JSON or YAML'),
+    },
+    async ({ old_spec, new_spec }) => {
+      try {
+        await requirePro();
+
+        const oldParsed = parseOpenApiSpec(old_spec);
+        const newParsed = parseOpenApiSpec(new_spec);
+        const comparison = compareSpecs(oldParsed, newParsed);
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                summary: {
+                  breaking_changes: comparison.breaking_changes.length,
+                  non_breaking_changes: comparison.non_breaking.length,
+                  new_endpoints: comparison.new_endpoints.length,
+                  removed_endpoints: comparison.removed_endpoints.length,
+                  is_backwards_compatible: comparison.breaking_changes.length === 0,
+                },
+                breaking_changes: comparison.breaking_changes,
+                non_breaking_changes: comparison.non_breaking,
+                new_endpoints: comparison.new_endpoints,
+                removed_endpoints: comparison.removed_endpoints,
+              }, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isLicense = message.includes('TRUSS Pro license');
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: message,
+                ...(isLicense
+                  ? {
+                      upgrade_url: 'https://truss.dev/pricing',
+                      price: '$25/mo',
+                    }
+                  : {}),
+              }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/generate-client.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { requirePro } from '../lib/license.js';
+import { parseOpenApiSpec } from '../lib/openapi-parser.js';
+import { generateClient } from '../lib/code-generator.js';
+
+export function registerGenerateClient(server: McpServer): void {
+  server.tool(
+    'generate_client',
+    '[Pro] Generate a typed API client from an OpenAPI spec. Supports TypeScript (fetch/axios), Python (requests), and Go (net/http). Produces ready-to-use code with type definitions.',
+    {
+      spec: z.string().describe('OpenAPI/Swagger spec as JSON or YAML string'),
+      language: z
+        .enum(['typescript', 'python', 'go'])
+        .describe('Target language for the client'),
+      style: z
+        .enum(['fetch', 'axios'])
+        .optional()
+        .default('fetch')
+        .describe('HTTP library style (TypeScript only, default: fetch)'),
+    },
+    async ({ spec, language, style }) => {
+      try {
+        await requirePro();
+
+        const parsed = parseOpenApiSpec(spec);
+        const code = generateClient(parsed, language, style);
+
+        const extensions: Record<string, string> = {
+          typescript: '.ts',
+          python: '.py',
+          go: '.go',
+        };
+
+        const filename = `api_client${extensions[language]}`;
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                filename,
+                language,
+                style: language === 'typescript' ? style : undefined,
+                endpoint_count: parsed.endpoints.length,
+                code,
+              }, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isLicense = message.includes('TRUSS Pro license');
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: message,
+                ...(isLicense
+                  ? {
+                      upgrade_url: 'https://truss.dev/pricing',
+                      price: '$25/mo',
+                    }
+                  : {}),
+              }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/generate-openapi.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { requirePro } from '../lib/license.js';
+import { generateOpenApiFromExamples } from '../lib/openapi-parser.js';
+
+export function registerGenerateOpenApi(server: McpServer): void {
+  server.tool(
+    'generate_openapi',
+    '[Pro] Auto-generate an OpenAPI 3.0 spec from example requests and responses. Infers schemas, path parameters, query parameters, and response types.',
+    {
+      examples: z.array(
+        z.object({
+          method: z.string().describe('HTTP method (GET, POST, etc.)'),
+          url: z.string().describe('Full URL of the request'),
+          request_body: z.unknown().optional().describe('Request body sent'),
+          response_body: z.unknown().describe('Response body received'),
+          status: z.number().describe('HTTP status code'),
+          headers: z.record(z.string(), z.string()).optional().describe('Request headers'),
+        })
+      ).min(1).describe('Array of example request/response pairs'),
+    },
+    async ({ examples }) => {
+      try {
+        await requirePro();
+
+        const yamlSpec = generateOpenApiFromExamples(examples as import('../types.js').RequestExample[]);
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: yamlSpec,
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isLicense = message.includes('TRUSS Pro license');
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: message,
+                ...(isLicense
+                  ? {
+                      upgrade_url: 'https://truss.dev/pricing',
+                      price: '$25/mo',
+                      features: [
+                        'Generate OpenAPI specs from examples',
+                        'Generate API test suites',
+                        'Mock server generation',
+                        'Spec comparison & breaking change detection',
+                        'Multi-language client code generation',
+                      ],
+                    }
+                  : {}),
+              }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/generate-tests.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { requirePro } from '../lib/license.js';
+import { parseOpenApiSpec } from '../lib/openapi-parser.js';
+import { generateTests } from '../lib/code-generator.js';
+
+export function registerGenerateTests(server: McpServer): void {
+  server.tool(
+    'generate_tests',
+    '[Pro] Generate a complete API test suite from an OpenAPI spec. Supports Jest, Vitest, and Pytest frameworks. Generates happy-path and error-case tests.',
+    {
+      spec: z.string().describe('OpenAPI/Swagger spec as JSON or YAML string'),
+      base_url: z.string().describe('Base URL of the API to test (e.g., http://localhost:3000)'),
+      framework: z
+        .enum(['jest', 'vitest', 'pytest'])
+        .optional()
+        .default('vitest')
+        .describe('Test framework to generate for (default: vitest)'),
+    },
+    async ({ spec, base_url, framework }) => {
+      try {
+        await requirePro();
+
+        const parsed = parseOpenApiSpec(spec);
+        const testCode = generateTests(parsed, base_url, framework);
+
+        const filename =
+          framework === 'pytest'
+            ? 'test_api.py'
+            : `api.test.${framework === 'jest' ? 'js' : 'ts'}`;
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                filename,
+                framework,
+                endpoint_count: parsed.endpoints.length,
+                code: testCode,
+              }, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isLicense = message.includes('TRUSS Pro license');
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: message,
+                ...(isLicense
+                  ? {
+                      upgrade_url: 'https://truss.dev/pricing',
+                      price: '$25/mo',
+                    }
+                  : {}),
+              }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/mock-server.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { requirePro } from '../lib/license.js';
+import { parseOpenApiSpec } from '../lib/openapi-parser.js';
+import { generateMockServer } from '../lib/code-generator.js';
+
+export function registerMockServer(server: McpServer): void {
+  server.tool(
+    'mock_server',
+    '[Pro] Generate a mock server configuration from an OpenAPI spec. Produces routes with sample responses and a db.json file ready for json-server or similar.',
+    {
+      spec: z.string().describe('OpenAPI/Swagger spec as JSON or YAML string'),
+    },
+    async ({ spec }) => {
+      try {
+        await requirePro();
+
+        const parsed = parseOpenApiSpec(spec);
+        const mockConfig = generateMockServer(parsed);
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                route_count: mockConfig.routes.length,
+                routes: mockConfig.routes,
+                mock_data: mockConfig.mock_data,
+                usage_instructions: {
+                  json_server: [
+                    '1. Save mock_data to db.json',
+                    '2. npx json-server db.json --port 3001',
+                    '3. Access endpoints at http://localhost:3001',
+                  ],
+                  custom: [
+                    'Use the routes array to configure any mock server.',
+                    'Each route has: method, path, status, response, headers.',
+                  ],
+                },
+              }, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isLicense = message.includes('TRUSS Pro license');
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: message,
+                ...(isLicense
+                  ? {
+                      upgrade_url: 'https://truss.dev/pricing',
+                      price: '$25/mo',
+                    }
+                  : {}),
+              }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/parse-openapi.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { parseOpenApiSpec } from '../lib/openapi-parser.js';
+
+export function registerParseOpenApi(server: McpServer): void {
+  server.tool(
+    'parse_openapi',
+    'Parse an OpenAPI 3.x or Swagger 2.0 spec (JSON or YAML) and list all endpoints with their parameters, request bodies, and response schemas.',
+    {
+      spec: z.string().describe('OpenAPI/Swagger spec content as JSON or YAML string'),
+    },
+    async ({ spec }) => {
+      try {
+        const parsed = parseOpenApiSpec(spec);
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                info: parsed.info,
+                servers: parsed.servers,
+                endpoint_count: parsed.endpoints.length,
+                endpoints: parsed.endpoints.map((ep) => ({
+                  method: ep.method,
+                  path: ep.path,
+                  summary: ep.summary,
+                  operationId: ep.operationId,
+                  tags: ep.tags,
+                  parameters: ep.parameters,
+                  request_body: ep.requestBody,
+                  responses: ep.responses,
+                })),
+              }, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: err instanceof Error ? err.message : String(err),
+                hint: 'Provide a valid OpenAPI 3.x or Swagger 2.0 spec as JSON or YAML string.',
+              }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}