Complete OpenAPI-to-MCP feature set with transports, auth, validation, scaffold, and tests

Author: haasonsaas

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+      - run: npm test
+      - run: npm run smoke

.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npm pack
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            *.tgz

.gitignore

@@ -2,3 +2,4 @@ node_modules/
 dist/
 .DS_Store
 .env
+.cache/

README.md

@@ -2,28 +2,36 @@
 
 OpenAPI 3.x to MCP server bridge in TypeScript.
 
-This project takes an OpenAPI spec and exposes every operation as an MCP tool, while proxying calls to the original REST API.
-
-## Feature checklist
-
-- OpenAPI 3.0+ support
-  - Loads YAML/JSON, dereferences `$ref`, compiles operations into MCP tools.
-- Proxy behavior
-  - `tools/call` executes real HTTP requests against your API and returns structured results.
-- Authentication support (env-driven)
-  - API key, Bearer, Basic, OAuth2/OpenID Connect token injection.
-- Zod validation
-  - Generates Zod schemas from OpenAPI-derived JSON Schema for runtime input validation.
-- Typed server
-  - Fully typed TypeScript codebase with strict compile checks.
-- Multiple transports
+`mcp-openapi` takes an OpenAPI spec and turns it into an MCP server where each OpenAPI operation is an MCP tool. Tool calls are proxied to the original REST API with runtime validation and auth handling.
+
+## Capabilities
+
+- OpenAPI 3.0+ support (YAML/JSON, `$ref` dereference, operation compilation)
+- Proxy behavior to upstream REST API
+- Authentication via env vars:
+  - API keys (`in: header|query|cookie`)
+  - HTTP Bearer
+  - HTTP Basic
+  - OAuth2 / OpenID Connect (static token or client credentials token fetch)
+- Runtime validation:
+  - Zod validation generated from OpenAPI-derived JSON Schema
+  - AJV JSON Schema validation
+  - Response schema validation by HTTP status
+- Typed TypeScript implementation
+- Multiple transports:
   - `stdio`
   - `streamable-http` (Hono)
-  - deprecated `sse` (Hono + SDK SSE transport)
-- Project scaffold
-  - Includes `tsconfig.json`, `package.json`, scripts, entrypoint, tests.
-- Built-in HTML test clients
-  - `/test/streamable` and `/test/sse` for browser-based interaction testing.
+  - `sse` (legacy compatibility transport)
+- Built-in browser test clients:
+  - `/test/streamable`
+  - `/test/sse`
+- Project scaffold (`init`) that generates:
+  - `package.json`
+  - `tsconfig.json`
+  - `src/server.ts`
+  - `.env.example`
+  - `README.md`
+  - `Dockerfile`
 
 ## Install
 
@@ -33,13 +41,13 @@ npm install
 
 ## Run
 
-### 1) stdio transport (default)
+### stdio
 
 ```bash
 npm run dev -- --spec ./openapi.yaml
 ```
 
-### 2) StreamableHTTP transport (Hono)
+### StreamableHTTP
 
 ```bash
 npm run dev -- --spec ./openapi.yaml --transport streamable-http --port 3000
@@ -48,10 +56,11 @@ npm run dev -- --spec ./openapi.yaml --transport streamable-http --port 3000
 Endpoints:
 
 - `http://localhost:3000/health`
+- `http://localhost:3000/metrics`
 - `http://localhost:3000/mcp`
 - `http://localhost:3000/test/streamable`
 
-### 3) SSE transport (deprecated, for compatibility)
+### SSE (legacy)
 
 ```bash
 npm run dev -- --spec ./openapi.yaml --transport sse --port 3000
@@ -60,99 +69,52 @@ npm run dev -- --spec ./openapi.yaml --transport sse --port 3000
 Endpoints:
 
 - `http://localhost:3000/health`
+- `http://localhost:3000/metrics`
 - `http://localhost:3000/sse`
 - `http://localhost:3000/messages?sessionId=...`
 - `http://localhost:3000/test/sse`
 
-## Common options
+## CLI
 
 ```bash
---server-url <url>      Override OpenAPI server URL
---timeout-ms <ms>       HTTP timeout per attempt (default: 20000)
---retries <n>           Retries on 408/429/5xx + transient network errors (default: 2)
---retry-delay-ms <ms>   Base retry delay (default: 500)
---watch-spec            Reload tools when spec changes
+mcp-openapi --spec <openapi-file> [options]
+mcp-openapi init [dir]
 ```
 
-## Authentication env vars
-
-- API key: `MCP_OPENAPI_API_KEY`
-- Bearer: `MCP_OPENAPI_BEARER_TOKEN`
-- Basic: `MCP_OPENAPI_BASIC_USERNAME`, `MCP_OPENAPI_BASIC_PASSWORD`
-- OAuth2/OIDC bearer token: `MCP_OPENAPI_OAUTH2_ACCESS_TOKEN`
-- Per-scheme override: `MCP_OPENAPI_<SCHEME_NAME>_TOKEN`
-
-## Validation model
-
-Input validation pipeline for `tools/call`:
-
-1. Zod validation (generated from OpenAPI-derived schema)
-2. JSON Schema validation (Ajv)
-
-Success responses can also be validated against OpenAPI response schemas, and tool output is validated against MCP `outputSchema`.
-
-## Generated tool shape
-
-Each OpenAPI operation becomes an MCP tool with:
-
-- `name`
-- `description`
-- `inputSchema`
-- `outputSchema` (when available)
-- tool annotations (`readOnlyHint`, `idempotentHint`, etc.)
-
-Input argument groups:
-
-```json
-{
-  "path": {},
-  "query": {},
-  "header": {},
-  "cookie": {},
-  "body": {},
-  "pagination": {
-    "enabled": false,
-    "mode": "autoCursor",
-    "maxPages": 5,
-    "cursorParam": "cursor",
-    "nextCursorPath": "next_cursor",
-    "pageParam": "page",
-    "startPage": 1
-  }
-}
-```
-
-## Request/response features
-
-- Query/path/header/cookie style-aware serialization
-- Request body content types:
-  - `application/json`
-  - `application/x-www-form-urlencoded`
-  - `multipart/form-data`
-  - `application/octet-stream`
-- Pagination helpers:
-  - cursor mode
-  - incrementing page mode
-- Retry with `Retry-After` support
-- Progress notifications via MCP `_meta.progressToken`
-- Cancellation support via MCP cancellation
-
-## Build/test/smoke
+Options:
+
+- `--server-url <url>`
+- `--cache-path <file>`
+- `--print-tools`
+- `--validate-spec`
+- `--transport stdio|streamable-http|sse`
+- `--port <n>`
+- `--watch-spec`
+- `--timeout-ms <ms>`
+- `--retries <n>`
+- `--retry-delay-ms <ms>`
+- `--max-response-bytes <n>`
+- `--max-concurrency <n>`
+- `--allow-hosts host1,host2`
+
+## Auth env vars
+
+- `MCP_OPENAPI_API_KEY`
+- `MCP_OPENAPI_BEARER_TOKEN`
+- `MCP_OPENAPI_BASIC_USERNAME`
+- `MCP_OPENAPI_BASIC_PASSWORD`
+- `MCP_OPENAPI_OAUTH2_ACCESS_TOKEN`
+- `MCP_OPENAPI_OAUTH2_CLIENT_ID`
+- `MCP_OPENAPI_OAUTH2_CLIENT_SECRET`
+- `MCP_OPENAPI_<SCHEME_NAME>_TOKEN`
+- `MCP_OPENAPI_<SCHEME_NAME>_CLIENT_ID`
+- `MCP_OPENAPI_<SCHEME_NAME>_CLIENT_SECRET`
+
+## Build and verify
 
 ```bash
 npm run check
 npm run build
 npm test
 npm run smoke
 ```
-
-`npm run smoke` starts a full MCP client/server+HTTP flow and verifies that an OpenAPI spec is transformed into callable MCP tools.
-
-## Browser test clients
-
-After launching a web transport:
-
-- StreamableHTTP client: `http://localhost:<port>/test/streamable`
-- SSE client: `http://localhost:<port>/test/sse`
-
-These pages let you initialize, list tools, and call tools directly in-browser.

src/compile-cache.ts

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { compileOperations } from "./compiler.js";
+import { loadOpenApiDocument } from "./openapi.js";
+import type { OperationModel } from "./types.js";
+
+interface CacheEntry {
+  hash: string;
+  operations: OperationModel[];
+}
+
+export async function loadFromCompileCache(specPath: string, serverUrl: string | undefined, cachePath: string): Promise<Map<string, OperationModel> | null> {
+  try {
+    const doc = await loadOpenApiDocument(specPath);
+    const hash = computeHash({ doc, serverUrl });
+    const raw = await readFile(resolve(cachePath), "utf8");
+    const parsed = JSON.parse(raw) as CacheEntry;
+    if (parsed.hash !== hash) {
+      return null;
+    }
+
+    return new Map(parsed.operations.map((op) => [op.operationId, op]));
+  } catch {
+    return null;
+  }
+}
+
+export async function compileWithCache(specPath: string, serverUrl: string | undefined, cachePath: string): Promise<Map<string, OperationModel>> {
+  const cached = await loadFromCompileCache(specPath, serverUrl, cachePath);
+  if (cached) {
+    return cached;
+  }
+
+  const doc = await loadOpenApiDocument(specPath);
+  const operations = compileOperations(doc, serverUrl);
+  const entry: CacheEntry = {
+    hash: computeHash({ doc, serverUrl }),
+    operations: [...operations.values()]
+  };
+
+  const abs = resolve(cachePath);
+  await mkdir(dirname(abs), { recursive: true });
+  await writeFile(abs, JSON.stringify(entry), "utf8");
+
+  return operations;
+}
+
+function computeHash(value: unknown): string {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}

src/compiler.ts

@@ -30,6 +30,7 @@ export function compileOperations(doc: Record<string, unknown>, serverOverride?:
       const mergedParameters = mergeParameters(pathParameters, operationParameters);
       const requestBody = normalizeRequestBody(operation.requestBody);
       const response = normalizeSuccessResponse(operation.responses);
+      const responseSchemasByStatus = normalizeResponseSchemasByStatus(operation.responses);
 
       const effectiveSecurity = normalizeSecurity(operation.security) ?? pathSecurity ?? globalSecurity;
       const authOptions = toAuthRequirements(effectiveSecurity, securitySchemes);
@@ -50,6 +51,7 @@ export function compileOperations(doc: Record<string, unknown>, serverOverride?:
         requestBodyContentType: requestBody?.contentType,
         responseContentType: response?.contentType,
         successResponseSchema: response?.schema,
+        responseSchemasByStatus,
         servers: resolvedServers,
         authOptions,
         annotations: buildAnnotations(method)
@@ -398,6 +400,22 @@ function normalizeSuccessResponse(value: unknown): { contentType?: string; schem
   return undefined;
 }
 
+function normalizeResponseSchemasByStatus(value: unknown): Record<string, JsonSchema> {
+  if (!value || typeof value !== "object") {
+    return {};
+  }
+
+  const out: Record<string, JsonSchema> = {};
+  const responses = value as Record<string, unknown>;
+  for (const [status, rawResponse] of Object.entries(responses)) {
+    const normalized = normalizeResponseContent(rawResponse);
+    if (normalized?.schema) {
+      out[status] = normalized.schema;
+    }
+  }
+  return out;
+}
+
 function normalizeResponseContent(value: unknown): { contentType?: string; schema?: JsonSchema } | undefined {
   if (!isObject(value)) {
     return undefined;
@@ -589,7 +607,9 @@ function getSecuritySchemes(doc: Record<string, unknown>): Record<string, Securi
       name,
       type: String(scheme.type),
       in: isValidIn(scheme.in) ? scheme.in : undefined,
-      scheme: typeof scheme.scheme === "string" ? scheme.scheme : undefined
+      scheme: typeof scheme.scheme === "string" ? scheme.scheme : undefined,
+      tokenUrl: typeof scheme.tokenUrl === "string" ? scheme.tokenUrl : undefined,
+      scopes: isObject(scheme.scopes) ? (scheme.scopes as Record<string, string>) : undefined
     };
   }