truss-api-mcp 1.0.0

package/src/tools/test-endpoint.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { executeRequest } from '../lib/http-client.js';
+
+export function registerTestEndpoint(server: McpServer): void {
+  server.tool(
+    'test_endpoint',
+    'Send an HTTP request and get a structured response with status, headers, body, timing, and size. Supports GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.',
+    {
+      method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']).describe('HTTP method'),
+      url: z.string().url().describe('Full URL to send the request to'),
+      headers: z.record(z.string(), z.string()).optional().describe('Request headers as key-value pairs'),
+      body: z.unknown().optional().describe('Request body (auto-serialized to JSON for objects)'),
+      timeout: z.number().min(100).max(120000).optional().describe('Request timeout in milliseconds (default: 30000, max: 120000)'),
+    },
+    async ({ method, url, headers, body, timeout }) => {
+      try {
+        const response = await executeRequest({
+          method,
+          url,
+          headers: headers as Record<string, string> | undefined,
+          body,
+          timeout,
+        });
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers,
+                body: response.body,
+                timing_ms: response.timing_ms,
+                size_bytes: response.size_bytes,
+              }, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+
+        // Provide helpful error context
+        let hint = '';
+        if (message.includes('ECONNREFUSED')) {
+          hint = 'The server is not running or not accepting connections.';
+        } else if (message.includes('ENOTFOUND')) {
+          hint = 'DNS lookup failed. Check the URL hostname.';
+        } else if (message.includes('timeout') || message.includes('abort')) {
+          hint = 'Request timed out. Try increasing the timeout parameter.';
+        } else if (message.includes('certificate')) {
+          hint = 'SSL/TLS certificate error. The server may have an invalid certificate.';
+        }
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: message,
+                hint: hint || undefined,
+              }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/validate-response.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { validateResponse } from '../lib/schema-validator.js';
+
+export function registerValidateResponse(server: McpServer): void {
+  server.tool(
+    'validate_response',
+    'Validate an API response against an expected HTTP status code and optional JSON Schema. Returns validation result with detailed error messages.',
+    {
+      response: z.object({
+        status: z.number().describe('HTTP status code from the response'),
+        body: z.unknown().describe('Response body to validate'),
+      }).describe('The API response to validate'),
+      expected_status: z.number().describe('Expected HTTP status code'),
+      expected_schema: z.unknown().optional().describe('Expected JSON Schema (draft-07) for the response body'),
+    },
+    async ({ response, expected_status, expected_schema }) => {
+      try {
+        const result = validateResponse(
+          response as { status: number; body: unknown },
+          expected_status,
+          (expected_schema as import('../types.js').JsonSchema) ?? undefined,
+        );
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                valid: result.valid,
+                errors: result.errors,
+                ...(result.valid
+                  ? { message: 'Response matches expected status and schema.' }
+                  : { message: `Validation failed with ${result.errors.length} error(s).` }),
+              }, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: err instanceof Error ? err.message : String(err),
+              }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/types.ts

@@ -0,0 +1,156 @@
+// ── License Types ────────────────────────────────────────────────────
+
+export type LicenseTier = 'free' | 'pro';
+
+export interface LicenseStatus {
+  tier: LicenseTier;
+  valid: boolean;
+  expiresAt: string | null;
+}
+
+// ── HTTP Types ──────────────────────────────────────────────────────
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+
+export interface HttpRequest {
+  method: HttpMethod;
+  url: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+  timeout?: number;
+}
+
+export interface HttpResponse {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  body: unknown;
+  timing_ms: number;
+  size_bytes: number;
+}
+
+// ── OpenAPI Types ───────────────────────────────────────────────────
+
+export interface OpenApiInfo {
+  title: string;
+  version: string;
+  description?: string;
+}
+
+export interface OpenApiParameter {
+  name: string;
+  in: 'query' | 'path' | 'header' | 'cookie';
+  required: boolean;
+  description?: string;
+  schema?: JsonSchema;
+}
+
+export interface OpenApiResponse {
+  status: string;
+  description: string;
+  schema?: JsonSchema;
+}
+
+export interface OpenApiEndpoint {
+  method: string;
+  path: string;
+  summary: string;
+  operationId?: string;
+  parameters: OpenApiParameter[];
+  requestBody?: JsonSchema;
+  responses: OpenApiResponse[];
+  tags?: string[];
+}
+
+export interface ParsedOpenApiSpec {
+  info: OpenApiInfo;
+  servers?: Array<{ url: string; description?: string }>;
+  endpoints: OpenApiEndpoint[];
+}
+
+// ── JSON Schema Types ───────────────────────────────────────────────
+
+export interface JsonSchema {
+  type?: string | string[];
+  properties?: Record<string, JsonSchema>;
+  items?: JsonSchema;
+  required?: string[];
+  enum?: unknown[];
+  format?: string;
+  description?: string;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  additionalProperties?: boolean | JsonSchema;
+  oneOf?: JsonSchema[];
+  anyOf?: JsonSchema[];
+  allOf?: JsonSchema[];
+  $ref?: string;
+  nullable?: boolean;
+}
+
+// ── Validation Types ────────────────────────────────────────────────
+
+export interface ValidationError {
+  path: string;
+  message: string;
+  expected?: string;
+  actual?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+}
+
+// ── Code Generation Types ───────────────────────────────────────────
+
+export type CodeLanguage = 'typescript' | 'python' | 'go';
+export type HttpStyle = 'fetch' | 'axios';
+
+// ── Test Generation Types ───────────────────────────────────────────
+
+export type TestFramework = 'jest' | 'vitest' | 'pytest';
+
+// ── Spec Comparison Types ───────────────────────────────────────────
+
+export interface SpecChange {
+  path: string;
+  method?: string;
+  description: string;
+}
+
+export interface SpecComparison {
+  breaking_changes: SpecChange[];
+  non_breaking: SpecChange[];
+  new_endpoints: SpecChange[];
+  removed_endpoints: SpecChange[];
+}
+
+// ── Mock Server Types ───────────────────────────────────────────────
+
+export interface MockRoute {
+  method: string;
+  path: string;
+  status: number;
+  response: unknown;
+  headers?: Record<string, string>;
+}
+
+export interface MockServerConfig {
+  routes: MockRoute[];
+  mock_data: Record<string, unknown>;
+}
+
+// ── Example Types (for generate_openapi) ────────────────────────────
+
+export interface RequestExample {
+  method: string;
+  url: string;
+  request_body?: unknown;
+  response_body: unknown;
+  status: number;
+  headers?: Record<string, string>;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "evals"]
+}