truss-api-mcp 1.0.0

package/evals/eval-openapi.ts

@@ -0,0 +1,506 @@
+/**
+ * Evaluation: OpenAPI parsing, spec generation, code generation, comparison
+ */
+
+import { parseOpenApiSpec, generateOpenApiFromExamples } from '../src/lib/openapi-parser.js';
+import { generateClient, generateTests, generateMockServer, compareSpecs } from '../src/lib/code-generator.js';
+import type { ParsedOpenApiSpec } from '../src/types.js';
+
+interface EvalResult {
+  name: string;
+  passed: boolean;
+  error?: string;
+}
+
+const results: EvalResult[] = [];
+
+function run(name: string, fn: () => void): void {
+  try {
+    fn();
+    results.push({ name, passed: true });
+  } catch (err) {
+    results.push({
+      name,
+      passed: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+function assert(condition: boolean, message: string): void {
+  if (!condition) throw new Error(message);
+}
+
+// ── Sample Specs ────────────────────────────────────────────────────
+
+const PETSTORE_SPEC = JSON.stringify({
+  openapi: '3.0.3',
+  info: { title: 'Petstore', version: '1.0.0', description: 'A sample pet store API' },
+  servers: [{ url: 'https://petstore.example.com/v1' }],
+  paths: {
+    '/pets': {
+      get: {
+        summary: 'List all pets',
+        operationId: 'listPets',
+        tags: ['pets'],
+        parameters: [
+          { name: 'limit', in: 'query', required: false, schema: { type: 'integer', maximum: 100 } },
+        ],
+        responses: {
+          '200': {
+            description: 'A list of pets',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    required: ['id', 'name'],
+                    properties: {
+                      id: { type: 'integer' },
+                      name: { type: 'string' },
+                      tag: { type: 'string' },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      post: {
+        summary: 'Create a pet',
+        operationId: 'createPet',
+        tags: ['pets'],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                required: ['name'],
+                properties: {
+                  name: { type: 'string' },
+                  tag: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+        responses: {
+          '201': { description: 'Pet created' },
+          '400': { description: 'Bad request' },
+        },
+      },
+    },
+    '/pets/{petId}': {
+      get: {
+        summary: 'Get a pet by ID',
+        operationId: 'getPet',
+        tags: ['pets'],
+        parameters: [
+          { name: 'petId', in: 'path', required: true, schema: { type: 'integer' } },
+        ],
+        responses: {
+          '200': {
+            description: 'A pet',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  required: ['id', 'name'],
+                  properties: {
+                    id: { type: 'integer' },
+                    name: { type: 'string' },
+                    tag: { type: 'string' },
+                  },
+                },
+              },
+            },
+          },
+          '404': { description: 'Pet not found' },
+        },
+      },
+      delete: {
+        summary: 'Delete a pet',
+        operationId: 'deletePet',
+        tags: ['pets'],
+        parameters: [
+          { name: 'petId', in: 'path', required: true, schema: { type: 'integer' } },
+        ],
+        responses: {
+          '204': { description: 'Pet deleted' },
+          '404': { description: 'Pet not found' },
+        },
+      },
+    },
+  },
+});
+
+const SWAGGER2_SPEC = JSON.stringify({
+  swagger: '2.0',
+  info: { title: 'Legacy API', version: '1.0.0' },
+  host: 'api.example.com',
+  basePath: '/v1',
+  schemes: ['https'],
+  paths: {
+    '/users': {
+      get: {
+        summary: 'List users',
+        parameters: [
+          { name: 'page', in: 'query', type: 'integer', required: false },
+        ],
+        responses: {
+          '200': {
+            description: 'A list of users',
+            schema: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  id: { type: 'integer' },
+                  email: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+      },
+      post: {
+        summary: 'Create user',
+        parameters: [
+          {
+            name: 'body',
+            in: 'body',
+            required: true,
+            schema: {
+              type: 'object',
+              required: ['email'],
+              properties: {
+                email: { type: 'string' },
+                name: { type: 'string' },
+              },
+            },
+          },
+        ],
+        responses: {
+          '201': { description: 'User created' },
+        },
+      },
+    },
+  },
+});
+
+// ── OpenAPI Parsing Tests ───────────────────────────────────────────
+
+run('Parse OpenAPI 3.0 JSON spec', () => {
+  const result = parseOpenApiSpec(PETSTORE_SPEC);
+
+  assert(result.info.title === 'Petstore', `Title should be Petstore, got ${result.info.title}`);
+  assert(result.info.version === '1.0.0', 'Version should be 1.0.0');
+  assert(result.endpoints.length === 4, `Expected 4 endpoints, got ${result.endpoints.length}`);
+  assert(result.servers?.length === 1, 'Should have 1 server');
+  assert(result.servers![0].url === 'https://petstore.example.com/v1', 'Server URL mismatch');
+});
+
+run('Parse Swagger 2.0 spec', () => {
+  const result = parseOpenApiSpec(SWAGGER2_SPEC);
+
+  assert(result.info.title === 'Legacy API', 'Title should be Legacy API');
+  assert(result.endpoints.length === 2, `Expected 2 endpoints, got ${result.endpoints.length}`);
+  assert(result.servers?.[0]?.url === 'https://api.example.com/v1', 'Server URL mismatch');
+});
+
+run('Parse YAML spec', () => {
+  const yamlSpec = `
+openapi: "3.0.0"
+info:
+  title: YAML API
+  version: "2.0.0"
+paths:
+  /health:
+    get:
+      summary: Health check
+      responses:
+        "200":
+          description: OK
+`;
+  const result = parseOpenApiSpec(yamlSpec);
+
+  assert(result.info.title === 'YAML API', 'Title should be YAML API');
+  assert(result.endpoints.length === 1, 'Should have 1 endpoint');
+  assert(result.endpoints[0].method === 'GET', 'Method should be GET');
+  assert(result.endpoints[0].path === '/health', 'Path should be /health');
+});
+
+run('Parse spec with $ref resolution', () => {
+  const specWithRefs = JSON.stringify({
+    openapi: '3.0.0',
+    info: { title: 'Ref Test', version: '1.0.0' },
+    paths: {
+      '/items': {
+        get: {
+          responses: {
+            '200': {
+              description: 'OK',
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/Item' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        Item: {
+          type: 'object',
+          properties: {
+            id: { type: 'integer' },
+            name: { type: 'string' },
+          },
+        },
+      },
+    },
+  });
+
+  const result = parseOpenApiSpec(specWithRefs);
+  const endpoint = result.endpoints[0];
+  const responseSchema = endpoint.responses[0].schema;
+
+  assert(responseSchema?.properties?.id !== undefined, 'Should resolve $ref to Item with id');
+  assert(responseSchema?.properties?.name !== undefined, 'Should resolve $ref to Item with name');
+});
+
+run('Reject invalid spec', () => {
+  let threw = false;
+  try {
+    parseOpenApiSpec('not a valid spec');
+  } catch {
+    threw = true;
+  }
+  assert(threw, 'Should throw on invalid spec');
+});
+
+run('Extract path parameters', () => {
+  const result = parseOpenApiSpec(PETSTORE_SPEC);
+  const getPet = result.endpoints.find((e) => e.operationId === 'getPet');
+
+  assert(getPet !== undefined, 'Should find getPet endpoint');
+  assert(getPet!.parameters.length === 1, 'Should have 1 parameter');
+  assert(getPet!.parameters[0].name === 'petId', 'Parameter should be petId');
+  assert(getPet!.parameters[0].in === 'path', 'Parameter should be in path');
+  assert(getPet!.parameters[0].required === true, 'Path parameter should be required');
+});
+
+run('Extract request body', () => {
+  const result = parseOpenApiSpec(PETSTORE_SPEC);
+  const createPet = result.endpoints.find((e) => e.operationId === 'createPet');
+
+  assert(createPet !== undefined, 'Should find createPet endpoint');
+  assert(createPet!.requestBody !== undefined, 'Should have request body');
+  assert(createPet!.requestBody!.properties?.name !== undefined, 'Body should have name property');
+});
+
+// ── Generate OpenAPI from Examples ──────────────────────────────────
+
+run('Generate OpenAPI from examples', () => {
+  const yamlOutput = generateOpenApiFromExamples([
+    {
+      method: 'GET',
+      url: 'https://api.example.com/users',
+      response_body: [{ id: 1, name: 'Alice', email: 'alice@example.com' }],
+      status: 200,
+    },
+    {
+      method: 'POST',
+      url: 'https://api.example.com/users',
+      request_body: { name: 'Bob', email: 'bob@example.com' },
+      response_body: { id: 2, name: 'Bob', email: 'bob@example.com' },
+      status: 201,
+    },
+    {
+      method: 'GET',
+      url: 'https://api.example.com/users/1',
+      response_body: { id: 1, name: 'Alice', email: 'alice@example.com' },
+      status: 200,
+    },
+  ]);
+
+  assert(yamlOutput.includes('openapi:'), 'Should contain openapi version');
+  assert(yamlOutput.includes('/users'), 'Should contain /users path');
+  assert(yamlOutput.includes('Auto-Generated API'), 'Should contain title');
+
+  // Verify it parses back
+  const parsed = parseOpenApiSpec(yamlOutput);
+  assert(parsed.endpoints.length >= 2, `Expected >= 2 endpoints, got ${parsed.endpoints.length}`);
+});
+
+// ── Client Code Generation ──────────────────────────────────────────
+
+let parsedPetstore: ParsedOpenApiSpec;
+
+run('Setup: Parse petstore for code gen', () => {
+  parsedPetstore = parseOpenApiSpec(PETSTORE_SPEC);
+});
+
+run('Generate TypeScript client (fetch)', () => {
+  const code = generateClient(parsedPetstore, 'typescript', 'fetch');
+
+  assert(code.includes('class ApiClient'), 'Should contain ApiClient class');
+  assert(code.includes('async listPets'), 'Should contain listPets method');
+  assert(code.includes('async createPet'), 'Should contain createPet method');
+  assert(code.includes('async getPet'), 'Should contain getPet method');
+  assert(code.includes('fetch('), 'Should use fetch()');
+  assert(code.includes("method: 'GET'"), 'Should have GET method');
+  assert(code.includes("method: 'POST'"), 'Should have POST method');
+  assert(code.includes('petstore.example.com'), 'Should contain base URL');
+});
+
+run('Generate TypeScript client (axios)', () => {
+  const code = generateClient(parsedPetstore, 'typescript', 'axios');
+
+  assert(code.includes('import axios'), 'Should import axios');
+  assert(code.includes('this.client'), 'Should use axios client instance');
+  assert(code.includes('class ApiClient'), 'Should contain ApiClient class');
+});
+
+run('Generate Python client', () => {
+  const code = generateClient(parsedPetstore, 'python');
+
+  assert(code.includes('import requests'), 'Should import requests');
+  assert(code.includes('class ApiClient:'), 'Should contain ApiClient class');
+  assert(code.includes('def list_pets'), 'Should contain list_pets method');
+  assert(code.includes('def create_pet'), 'Should contain create_pet method');
+  assert(code.includes('self.session'), 'Should use session');
+  assert(code.includes('raise_for_status'), 'Should check status');
+});
+
+run('Generate Go client', () => {
+  const code = generateClient(parsedPetstore, 'go');
+
+  assert(code.includes('package apiclient'), 'Should have package declaration');
+  assert(code.includes('type Client struct'), 'Should contain Client struct');
+  assert(code.includes('func NewClient'), 'Should have constructor');
+  assert(code.includes('func (c *Client)'), 'Should have methods on Client');
+  assert(code.includes('net/http'), 'Should import net/http');
+  assert(code.includes('json.Marshal'), 'Should use JSON marshaling');
+  assert(code.includes('json:"'), 'Should have JSON struct tags');
+});
+
+// ── Test Generation ─────────────────────────────────────────────────
+
+run('Generate Vitest tests', () => {
+  const code = generateTests(parsedPetstore, 'http://localhost:3000', 'vitest');
+
+  assert(code.includes("import { describe, it, expect } from 'vitest'"), 'Should import vitest');
+  assert(code.includes("describe('"), 'Should have describe blocks');
+  assert(code.includes('it('), 'Should have test cases');
+  assert(code.includes("expect(response.status)"), 'Should assert status');
+  assert(code.includes('BASE_URL'), 'Should use BASE_URL constant');
+});
+
+run('Generate Jest tests', () => {
+  const code = generateTests(parsedPetstore, 'http://localhost:3000', 'jest');
+
+  assert(code.includes("describe('"), 'Should have describe blocks');
+  assert(code.includes('.toBe('), 'Should use Jest matchers');
+});
+
+run('Generate Pytest tests', () => {
+  const code = generateTests(parsedPetstore, 'http://localhost:3000', 'pytest');
+
+  assert(code.includes('import pytest'), 'Should import pytest');
+  assert(code.includes('import requests'), 'Should import requests');
+  assert(code.includes('def test_'), 'Should have test functions');
+  assert(code.includes('assert response.status_code'), 'Should assert status code');
+});
+
+// ── Mock Server Generation ──────────────────────────────────────────
+
+run('Generate mock server config', () => {
+  const config = generateMockServer(parsedPetstore);
+
+  assert(config.routes.length === 4, `Expected 4 routes, got ${config.routes.length}`);
+  assert(config.routes.some((r) => r.method === 'GET' && r.path === '/pets'), 'Should have GET /pets');
+  assert(config.routes.some((r) => r.method === 'POST' && r.path === '/pets'), 'Should have POST /pets');
+  assert(config.routes.some((r) => r.path === '/pets/:petId'), 'Should convert path params to :param style');
+
+  // Mock data should exist
+  assert(typeof config.mock_data === 'object', 'Should have mock_data object');
+});
+
+// ── Spec Comparison ─────────────────────────────────────────────────
+
+run('Compare specs — detect breaking changes', () => {
+  const oldParsed = parseOpenApiSpec(PETSTORE_SPEC);
+
+  // Create a modified spec with breaking changes
+  const modified = JSON.parse(PETSTORE_SPEC);
+  // Remove an endpoint (breaking)
+  delete modified.paths['/pets/{petId}'].delete;
+  // Add a new required parameter (breaking)
+  modified.paths['/pets'].get.parameters.push({
+    name: 'api_key',
+    in: 'header',
+    required: true,
+    schema: { type: 'string' },
+  });
+  // Add a new endpoint (non-breaking)
+  modified.paths['/pets/{petId}/photos'] = {
+    get: {
+      summary: 'Get pet photos',
+      parameters: [{ name: 'petId', in: 'path', required: true, schema: { type: 'integer' } }],
+      responses: { '200': { description: 'Photos' } },
+    },
+  };
+
+  const newParsed = parseOpenApiSpec(JSON.stringify(modified));
+  const comparison = compareSpecs(oldParsed, newParsed);
+
+  assert(comparison.breaking_changes.length > 0, 'Should detect breaking changes');
+  assert(
+    comparison.breaking_changes.some((c) => c.description.includes('removed')),
+    'Should detect removed endpoint'
+  );
+  assert(
+    comparison.breaking_changes.some((c) => c.description.includes('required parameter')),
+    'Should detect new required parameter'
+  );
+  assert(comparison.new_endpoints.length > 0, 'Should detect new endpoints');
+});
+
+run('Compare specs — backwards compatible', () => {
+  const oldParsed = parseOpenApiSpec(PETSTORE_SPEC);
+
+  // Add only non-breaking changes
+  const modified = JSON.parse(PETSTORE_SPEC);
+  modified.paths['/pets'].get.parameters.push({
+    name: 'sort',
+    in: 'query',
+    required: false,
+    schema: { type: 'string' },
+  });
+
+  const newParsed = parseOpenApiSpec(JSON.stringify(modified));
+  const comparison = compareSpecs(oldParsed, newParsed);
+
+  assert(comparison.breaking_changes.length === 0, 'Should have no breaking changes');
+  assert(comparison.non_breaking.length > 0, 'Should have non-breaking changes');
+});
+
+// ── Report ──────────────────────────────────────────────────────────
+
+export { results };
+
+const passed = results.filter((r) => r.passed).length;
+const failed = results.filter((r) => !r.passed).length;
+
+console.log(`\nOpenAPI & Code Gen Evals: ${passed} passed, ${failed} failed\n`);
+for (const r of results) {
+  const icon = r.passed ? 'PASS' : 'FAIL';
+  console.log(`  [${icon}] ${r.name}`);
+  if (r.error) console.log(`         ${r.error}`);
+}

package/evals/run-evals.ts

@@ -0,0 +1,29 @@
+/**
+ * Run all evaluations for the API Testing MCP server.
+ */
+
+console.log('=== TRUSS API Testing MCP — Evaluations ===\n');
+
+// Import eval modules (they self-execute and print results)
+const httpModule = await import('./eval-http.js');
+const openapiModule = await import('./eval-openapi.js');
+
+// Aggregate results
+const allResults = [...httpModule.results, ...openapiModule.results];
+const passed = allResults.filter((r) => r.passed).length;
+const failed = allResults.filter((r) => !r.passed).length;
+const total = allResults.length;
+
+console.log('\n' + '='.repeat(50));
+console.log(`TOTAL: ${passed}/${total} passed, ${failed} failed`);
+console.log('='.repeat(50));
+
+if (failed > 0) {
+  console.log('\nFailing tests:');
+  for (const r of allResults.filter((r) => !r.passed)) {
+    console.log(`  - ${r.name}: ${r.error}`);
+  }
+  process.exit(1);
+}
+
+process.exit(0);

package/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["claw-factory"]
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "truss-api-mcp",
+  "version": "1.0.0",
+  "description": "API testing and documentation tools for Claude Code — test endpoints, parse OpenAPI specs, generate clients and tests",
+  "type": "module",
+  "bin": {
+    "truss-api-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "eval": "tsx evals/run-evals.ts"
+  },
+  "keywords": [
+    "mcp",
+    "api",
+    "testing",
+    "openapi",
+    "swagger",
+    "documentation",
+    "claude",
+    "claude-code"
+  ],
+  "author": "TRUSS",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "tsx": "^4.19.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0"
+  }
+}

package/smithery.yaml

@@ -0,0 +1,9 @@
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties:
+      TRUSS_LICENSE_KEY:
+        type: string
+        description: "License key for Pro features (optional)"
+    required: []