truss-api-mcp 1.0.0

package/src/lib/http-client.ts

@@ -0,0 +1,87 @@
+import type { HttpRequest, HttpResponse } from '../types.js';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 120_000;
+const MAX_RESPONSE_SIZE = 10 * 1024 * 1024; // 10MB
+
+/**
+ * Execute an HTTP request using native fetch() and return structured results.
+ */
+export async function executeRequest(req: HttpRequest): Promise<HttpResponse> {
+  const timeout = Math.min(req.timeout ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+
+  const headers: Record<string, string> = { ...req.headers };
+  let bodyPayload: string | undefined;
+
+  if (req.body !== undefined && req.body !== null) {
+    if (typeof req.body === 'string') {
+      bodyPayload = req.body;
+    } else {
+      bodyPayload = JSON.stringify(req.body);
+      if (!headers['Content-Type'] && !headers['content-type']) {
+        headers['Content-Type'] = 'application/json';
+      }
+    }
+  }
+
+  const start = performance.now();
+
+  const response = await fetch(req.url, {
+    method: req.method,
+    headers,
+    body: bodyPayload,
+    signal: AbortSignal.timeout(timeout),
+    redirect: 'follow',
+  });
+
+  const timing_ms = Math.round(performance.now() - start);
+
+  // Read response body
+  const contentType = response.headers.get('content-type') ?? '';
+  const contentLength = response.headers.get('content-length');
+
+  if (contentLength && parseInt(contentLength, 10) > MAX_RESPONSE_SIZE) {
+    throw new Error(`Response too large: ${contentLength} bytes (max ${MAX_RESPONSE_SIZE})`);
+  }
+
+  let body: unknown;
+  let size_bytes: number;
+
+  if (contentType.includes('application/json')) {
+    const text = await response.text();
+    size_bytes = new TextEncoder().encode(text).length;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+  } else if (
+    contentType.includes('text/') ||
+    contentType.includes('application/xml') ||
+    contentType.includes('application/yaml') ||
+    contentType.includes('application/javascript')
+  ) {
+    const text = await response.text();
+    size_bytes = new TextEncoder().encode(text).length;
+    body = text;
+  } else {
+    const buffer = await response.arrayBuffer();
+    size_bytes = buffer.byteLength;
+    body = `<binary data: ${size_bytes} bytes, content-type: ${contentType}>`;
+  }
+
+  // Collect response headers
+  const responseHeaders: Record<string, string> = {};
+  response.headers.forEach((value, key) => {
+    responseHeaders[key] = value;
+  });
+
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    headers: responseHeaders,
+    body,
+    timing_ms,
+    size_bytes,
+  };
+}

package/src/lib/license.ts

@@ -0,0 +1,121 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { LicenseStatus, LicenseTier } from '../types.js';
+
+const DATA_DIR = join(homedir(), '.truss');
+const CACHE_FILE = 'api-mcp-license-cache.json';
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const API_BASE_URL = process.env.TRUSS_API_BASE_URL || 'https://api.truss.dev';
+
+// Ensure data directory exists
+try {
+  mkdirSync(DATA_DIR, { recursive: true });
+} catch {
+  // ignore
+}
+
+interface LicenseCache {
+  key: string;
+  valid: boolean;
+  tier: LicenseTier;
+  expiresAt: string | null;
+  cachedAt: number;
+}
+
+function getCachePath(): string {
+  return join(DATA_DIR, CACHE_FILE);
+}
+
+function readCache(): LicenseCache | null {
+  try {
+    const raw = readFileSync(getCachePath(), 'utf-8');
+    const cache = JSON.parse(raw) as LicenseCache;
+    if (Date.now() - cache.cachedAt < CACHE_TTL_MS) {
+      return cache;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(cache: LicenseCache): void {
+  try {
+    writeFileSync(getCachePath(), JSON.stringify(cache, null, 2));
+  } catch {
+    // non-fatal
+  }
+}
+
+function isValidKeyFormat(key: string): boolean {
+  return /^truss_[0-9a-f]{32}$/.test(key);
+}
+
+async function validateRemote(key: string): Promise<{ valid: boolean; expiresAt: string | null }> {
+  const url = `${API_BASE_URL}/validate/${key}`;
+
+  try {
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        'Accept': 'application/json',
+        'User-Agent': '@truss-dev/api-testing-mcp/1.0.0',
+      },
+      signal: AbortSignal.timeout(5000),
+    });
+
+    if (!response.ok) {
+      return { valid: false, expiresAt: null };
+    }
+
+    const body = await response.json() as { valid: boolean; expires_at?: string };
+    return {
+      valid: body.valid === true,
+      expiresAt: body.expires_at ?? null,
+    };
+  } catch {
+    // Network error — fall back to format check
+    return { valid: isValidKeyFormat(key), expiresAt: null };
+  }
+}
+
+export async function getLicenseStatus(): Promise<LicenseStatus> {
+  const key = process.env.TRUSS_LICENSE_KEY;
+
+  if (!key) {
+    return { tier: 'free', valid: true, expiresAt: null };
+  }
+
+  if (!isValidKeyFormat(key)) {
+    return { tier: 'free', valid: false, expiresAt: null };
+  }
+
+  const cached = readCache();
+  if (cached && cached.key === key) {
+    return { tier: cached.tier, valid: cached.valid, expiresAt: cached.expiresAt };
+  }
+
+  const result = await validateRemote(key);
+  const tier: LicenseTier = result.valid ? 'pro' : 'free';
+
+  writeCache({
+    key,
+    valid: result.valid,
+    tier,
+    expiresAt: result.expiresAt,
+    cachedAt: Date.now(),
+  });
+
+  return { tier, valid: result.valid, expiresAt: result.expiresAt };
+}
+
+export async function requirePro(): Promise<void> {
+  const status = await getLicenseStatus();
+  if (status.tier !== 'pro') {
+    throw new Error(
+      'This feature requires a TRUSS Pro license ($25/mo). ' +
+      'Get yours at https://truss.dev/pricing and set TRUSS_LICENSE_KEY env var.'
+    );
+  }
+}

package/src/lib/openapi-parser.ts

@@ -0,0 +1,456 @@
+import * as yaml from 'js-yaml';
+import type {
+  ParsedOpenApiSpec,
+  OpenApiEndpoint,
+  OpenApiParameter,
+  OpenApiResponse,
+  JsonSchema,
+  OpenApiInfo,
+} from '../types.js';
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'] as const;
+
+/**
+ * Parse an OpenAPI 3.x or Swagger 2.0 spec from JSON or YAML string.
+ */
+export function parseOpenApiSpec(input: string): ParsedOpenApiSpec {
+  let doc: Record<string, unknown>;
+
+  // Try JSON first, then YAML
+  try {
+    doc = JSON.parse(input) as Record<string, unknown>;
+  } catch {
+    try {
+      doc = yaml.load(input) as Record<string, unknown>;
+    } catch (yamlErr) {
+      throw new Error(
+        `Failed to parse spec as JSON or YAML: ${yamlErr instanceof Error ? yamlErr.message : String(yamlErr)}`
+      );
+    }
+  }
+
+  if (!doc || typeof doc !== 'object') {
+    throw new Error('Spec must be a valid JSON or YAML object');
+  }
+
+  // Detect version
+  const isSwagger2 = typeof doc.swagger === 'string' && doc.swagger.startsWith('2.');
+  const isOpenApi3 = typeof doc.openapi === 'string' && doc.openapi.startsWith('3.');
+
+  if (!isSwagger2 && !isOpenApi3) {
+    throw new Error('Unsupported spec: must be OpenAPI 3.x or Swagger 2.0');
+  }
+
+  // Build a flat definitions map for $ref resolution
+  const definitions = buildDefinitions(doc);
+
+  const info = extractInfo(doc);
+  const servers = isOpenApi3 ? extractServers(doc) : extractSwagger2Servers(doc);
+  const endpoints = extractEndpoints(doc, definitions, isSwagger2);
+
+  return { info, servers, endpoints };
+}
+
+// ── Info ────────────────────────────────────────────────────────────
+
+function extractInfo(doc: Record<string, unknown>): OpenApiInfo {
+  const info = (doc.info ?? {}) as Record<string, unknown>;
+  return {
+    title: String(info.title ?? 'Untitled API'),
+    version: String(info.version ?? '0.0.0'),
+    description: info.description ? String(info.description) : undefined,
+  };
+}
+
+// ── Servers ─────────────────────────────────────────────────────────
+
+function extractServers(
+  doc: Record<string, unknown>
+): Array<{ url: string; description?: string }> | undefined {
+  const servers = doc.servers as Array<Record<string, unknown>> | undefined;
+  if (!Array.isArray(servers) || servers.length === 0) return undefined;
+  return servers.map((s) => ({
+    url: String(s.url ?? ''),
+    description: s.description ? String(s.description) : undefined,
+  }));
+}
+
+function extractSwagger2Servers(
+  doc: Record<string, unknown>
+): Array<{ url: string; description?: string }> | undefined {
+  const host = doc.host as string | undefined;
+  const basePath = (doc.basePath as string) ?? '';
+  const schemes = (doc.schemes as string[]) ?? ['https'];
+  if (!host) return undefined;
+  return schemes.map((scheme) => ({ url: `${scheme}://${host}${basePath}` }));
+}
+
+// ── Definitions / Components ────────────────────────────────────────
+
+function buildDefinitions(doc: Record<string, unknown>): Map<string, JsonSchema> {
+  const defs = new Map<string, JsonSchema>();
+
+  // OpenAPI 3.x components/schemas
+  const components = doc.components as Record<string, unknown> | undefined;
+  if (components?.schemas && typeof components.schemas === 'object') {
+    for (const [name, schema] of Object.entries(components.schemas as Record<string, unknown>)) {
+      defs.set(`#/components/schemas/${name}`, schema as JsonSchema);
+    }
+  }
+
+  // Swagger 2.0 definitions
+  const definitions = doc.definitions as Record<string, unknown> | undefined;
+  if (definitions && typeof definitions === 'object') {
+    for (const [name, schema] of Object.entries(definitions)) {
+      defs.set(`#/definitions/${name}`, schema as JsonSchema);
+    }
+  }
+
+  return defs;
+}
+
+function resolveRef(schema: JsonSchema, defs: Map<string, JsonSchema>, depth = 0): JsonSchema {
+  if (depth > 20) return schema; // prevent infinite recursion
+  if (schema.$ref) {
+    const resolved = defs.get(schema.$ref);
+    if (resolved) return resolveRef(resolved, defs, depth + 1);
+    // Unresolvable ref — return a stub
+    return { type: 'object', description: `Unresolved: ${schema.$ref}` };
+  }
+  return schema;
+}
+
+// ── Endpoints ───────────────────────────────────────────────────────
+
+function extractEndpoints(
+  doc: Record<string, unknown>,
+  defs: Map<string, JsonSchema>,
+  isSwagger2: boolean
+): OpenApiEndpoint[] {
+  const paths = doc.paths as Record<string, Record<string, unknown>> | undefined;
+  if (!paths) return [];
+
+  const endpoints: OpenApiEndpoint[] = [];
+
+  for (const [path, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== 'object') continue;
+
+    // Path-level parameters
+    const pathParams = (pathItem.parameters ?? []) as unknown[];
+
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method] as Record<string, unknown> | undefined;
+      if (!operation) continue;
+
+      const operationParams = (operation.parameters ?? []) as unknown[];
+      const allParams = [...(pathParams as Record<string, unknown>[]), ...(operationParams as Record<string, unknown>[])];
+
+      const parameters = extractParameters(allParams, defs, isSwagger2);
+      const requestBody = isSwagger2
+        ? extractSwagger2Body(allParams, defs)
+        : extractRequestBody(operation, defs);
+      const responses = extractResponses(operation, defs, isSwagger2);
+      const tags = Array.isArray(operation.tags) ? operation.tags.map(String) : undefined;
+
+      endpoints.push({
+        method: method.toUpperCase(),
+        path,
+        summary: String(operation.summary ?? operation.description ?? ''),
+        operationId: operation.operationId ? String(operation.operationId) : undefined,
+        parameters,
+        requestBody: requestBody ?? undefined,
+        responses,
+        tags,
+      });
+    }
+  }
+
+  return endpoints;
+}
+
+function extractParameters(
+  params: Record<string, unknown>[],
+  defs: Map<string, JsonSchema>,
+  isSwagger2: boolean
+): OpenApiParameter[] {
+  return params
+    .filter((p) => {
+      // Skip body params in Swagger 2 — handled separately
+      if (isSwagger2 && p.in === 'body') return false;
+      return p.in === 'query' || p.in === 'path' || p.in === 'header' || p.in === 'cookie';
+    })
+    .map((p) => {
+      let schema: JsonSchema | undefined;
+      if (p.schema) {
+        schema = resolveRef(p.schema as JsonSchema, defs);
+      } else if (isSwagger2 && p.type) {
+        schema = { type: String(p.type) };
+      }
+
+      return {
+        name: String(p.name ?? ''),
+        in: p.in as 'query' | 'path' | 'header' | 'cookie',
+        required: Boolean(p.required),
+        description: p.description ? String(p.description) : undefined,
+        schema,
+      };
+    });
+}
+
+function extractRequestBody(
+  operation: Record<string, unknown>,
+  defs: Map<string, JsonSchema>
+): JsonSchema | null {
+  const rb = operation.requestBody as Record<string, unknown> | undefined;
+  if (!rb) return null;
+
+  const content = rb.content as Record<string, Record<string, unknown>> | undefined;
+  if (!content) return null;
+
+  // Prefer application/json
+  const jsonContent = content['application/json'] ?? content[Object.keys(content)[0]];
+  if (!jsonContent?.schema) return null;
+
+  return resolveRef(jsonContent.schema as JsonSchema, defs);
+}
+
+function extractSwagger2Body(
+  params: Record<string, unknown>[],
+  defs: Map<string, JsonSchema>
+): JsonSchema | null {
+  const bodyParam = params.find((p) => p.in === 'body');
+  if (!bodyParam?.schema) return null;
+  return resolveRef(bodyParam.schema as JsonSchema, defs);
+}
+
+function extractResponses(
+  operation: Record<string, unknown>,
+  defs: Map<string, JsonSchema>,
+  isSwagger2: boolean
+): OpenApiResponse[] {
+  const responses = operation.responses as Record<string, Record<string, unknown>> | undefined;
+  if (!responses) return [];
+
+  return Object.entries(responses).map(([status, resp]) => {
+    let schema: JsonSchema | undefined;
+
+    if (isSwagger2) {
+      if (resp.schema) {
+        schema = resolveRef(resp.schema as JsonSchema, defs);
+      }
+    } else {
+      const content = resp.content as Record<string, Record<string, unknown>> | undefined;
+      if (content) {
+        const jsonContent = content['application/json'] ?? content[Object.keys(content)[0]];
+        if (jsonContent?.schema) {
+          schema = resolveRef(jsonContent.schema as JsonSchema, defs);
+        }
+      }
+    }
+
+    return {
+      status,
+      description: String(resp.description ?? ''),
+      schema,
+    };
+  });
+}
+
+// ── Generate OpenAPI from Examples ──────────────────────────────────
+
+import type { RequestExample } from '../types.js';
+
+/**
+ * Auto-generate an OpenAPI 3.0 spec from a set of request/response examples.
+ */
+export function generateOpenApiFromExamples(examples: RequestExample[]): string {
+  // Group examples by path pattern
+  const endpointMap = new Map<string, RequestExample[]>();
+
+  for (const ex of examples) {
+    let urlPath: string;
+    try {
+      const parsed = new URL(ex.url);
+      urlPath = parsed.pathname;
+    } catch {
+      urlPath = ex.url;
+    }
+
+    // Normalize numeric segments to path params
+    const normalized = urlPath.replace(/\/(\d+)/g, '/{id}');
+    const key = `${ex.method.toUpperCase()} ${normalized}`;
+
+    if (!endpointMap.has(key)) endpointMap.set(key, []);
+    endpointMap.get(key)!.push(ex);
+  }
+
+  // Extract base URL from first example
+  let baseUrl = '';
+  try {
+    const parsed = new URL(examples[0].url);
+    baseUrl = `${parsed.protocol}//${parsed.host}`;
+  } catch {
+    baseUrl = 'http://localhost:3000';
+  }
+
+  // Build paths
+  const paths: Record<string, Record<string, unknown>> = {};
+
+  for (const [key, exs] of endpointMap) {
+    const [method, path] = key.split(' ', 2);
+    if (!paths[path]) paths[path] = {};
+
+    const example = exs[0];
+    const methodLower = method.toLowerCase();
+
+    // Infer path parameters
+    const pathParams: Record<string, unknown>[] = [];
+    const paramMatches = path.match(/\{(\w+)\}/g);
+    if (paramMatches) {
+      for (const match of paramMatches) {
+        const name = match.replace(/[{}]/g, '');
+        pathParams.push({
+          name,
+          in: 'path',
+          required: true,
+          schema: { type: 'integer' },
+        });
+      }
+    }
+
+    // Infer query parameters from URL
+    const queryParams: Record<string, unknown>[] = [];
+    try {
+      const parsed = new URL(example.url);
+      for (const [qname, qvalue] of parsed.searchParams) {
+        queryParams.push({
+          name: qname,
+          in: 'query',
+          required: false,
+          schema: { type: inferJsonType(qvalue) },
+          example: qvalue,
+        });
+      }
+    } catch {
+      // ignore
+    }
+
+    const operation: Record<string, unknown> = {
+      summary: `${method} ${path}`,
+      operationId: `${methodLower}${path.replace(/[/{}\-]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '')}`,
+      parameters: [...pathParams, ...queryParams],
+      responses: {},
+    };
+
+    // Request body
+    if (example.request_body !== undefined && example.request_body !== null) {
+      operation.requestBody = {
+        required: true,
+        content: {
+          'application/json': {
+            schema: inferSchema(example.request_body),
+            example: example.request_body,
+          },
+        },
+      };
+    }
+
+    // Responses — collect all unique status codes
+    const statusCodes = new Set(exs.map((e) => e.status));
+    const responses: Record<string, unknown> = {};
+
+    for (const status of statusCodes) {
+      const statusExample = exs.find((e) => e.status === status);
+      responses[String(status)] = {
+        description: describeStatus(status),
+        content: statusExample?.response_body !== undefined
+          ? {
+              'application/json': {
+                schema: inferSchema(statusExample.response_body),
+                example: statusExample.response_body,
+              },
+            }
+          : undefined,
+      };
+    }
+
+    operation.responses = responses;
+    paths[path][methodLower] = operation;
+  }
+
+  const spec = {
+    openapi: '3.0.3',
+    info: {
+      title: 'Auto-Generated API',
+      version: '1.0.0',
+      description: `Generated from ${examples.length} example request(s)`,
+    },
+    servers: [{ url: baseUrl }],
+    paths,
+  };
+
+  return yaml.dump(spec, { lineWidth: 120, noRefs: true, sortKeys: false });
+}
+
+function inferJsonType(value: unknown): string {
+  if (value === null || value === undefined) return 'string';
+  if (typeof value === 'number' || (typeof value === 'string' && !isNaN(Number(value)) && value !== '')) {
+    return Number.isInteger(Number(value)) ? 'integer' : 'number';
+  }
+  if (typeof value === 'boolean' || value === 'true' || value === 'false') return 'boolean';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'object') return 'object';
+  return 'string';
+}
+
+function inferSchema(value: unknown): JsonSchema {
+  if (value === null || value === undefined) {
+    return { type: 'string', nullable: true };
+  }
+  if (typeof value === 'string') {
+    const schema: JsonSchema = { type: 'string' };
+    if (/^\d{4}-\d{2}-\d{2}/.test(value)) schema.format = 'date-time';
+    if (/^[^@]+@[^@]+\.[^@]+$/.test(value)) schema.format = 'email';
+    if (/^https?:\/\//.test(value)) schema.format = 'uri';
+    return schema;
+  }
+  if (typeof value === 'number') {
+    return Number.isInteger(value) ? { type: 'integer' } : { type: 'number' };
+  }
+  if (typeof value === 'boolean') {
+    return { type: 'boolean' };
+  }
+  if (Array.isArray(value)) {
+    return {
+      type: 'array',
+      items: value.length > 0 ? inferSchema(value[0]) : { type: 'string' },
+    };
+  }
+  if (typeof value === 'object') {
+    const properties: Record<string, JsonSchema> = {};
+    const required: string[] = [];
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      properties[k] = inferSchema(v);
+      if (v !== null && v !== undefined) required.push(k);
+    }
+    return { type: 'object', properties, required: required.length > 0 ? required : undefined };
+  }
+  return { type: 'string' };
+}
+
+function describeStatus(status: number): string {
+  const descriptions: Record<number, string> = {
+    200: 'Successful response',
+    201: 'Resource created',
+    204: 'No content',
+    400: 'Bad request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not found',
+    409: 'Conflict',
+    422: 'Unprocessable entity',
+    429: 'Too many requests',
+    500: 'Internal server error',
+  };
+  return descriptions[status] ?? `HTTP ${status}`;
+}