api2ai 1.0.27 → 1.0.28

package/src/templates/env.js

@@ -0,0 +1,46 @@
+/**
+ * `.env` and `.env.example`. They differ only in placeholder credentials, so
+ * one template renders both (they used to be two copies that drifted).
+ */
+export function generateEnvFile({ baseUrl, port, requireApprovals = true, example = false }) {
+  const apiHost = safeHost(baseUrl);
+  return `# Server Configuration
+PORT=${port}
+# 127.0.0.1 locally; set HOST=0.0.0.0 to serve on a network / in a container
+# HOST=0.0.0.0
+NODE_ENV=development
+
+# API Configuration
+API_BASE_URL=${baseUrl || 'https://api.example.com'}
+
+# Authentication
+${example ? 'API_KEY=your-api-key-here' : '# API_KEY=your-api-key'}
+# API_AUTH_HEADER=Header-Name:header-value
+
+# Security — allowed API hosts (comma-separated). Empty = only API_BASE_URL's host${apiHost ? ` (${apiHost})` : ''}.
+# ALLOWED_API_HOSTS=${apiHost || 'api.example.com'}
+
+# Tool policy — set to true to allow medium/high-risk (mutating) tools
+ALLOW_RESTRICTED_TOOLS=false
+# Set to false to bypass per-call approval requirement for restricted tools
+REQUIRE_APPROVALS=${requireApprovals ? 'true' : 'false'}
+
+# Request limits
+REQUEST_TIMEOUT_MS=30000
+MAX_RESPONSE_BYTES=10485760
+
+# Public URL of this server, when it sits behind a proxy
+# MCP_URL=https://your-production-url.com
+
+# Browser origins allowed to call /mcp (comma-separated hostnames or URLs)
+# ALLOWED_ORIGINS=app1.com,https://app2.com
+`;
+}
+
+function safeHost(url) {
+  try {
+    return url ? new URL(url).host : '';
+  } catch {
+    return '';
+  }
+}

package/src/templates/http-client.js

@@ -0,0 +1,126 @@
+/** `src/http-client.js` of the generated server: one outbound request per tool call. */
+export function generateHttpClient() {
+  return `// HTTP client for API requests
+import { sanitizeHeaderParams, MAX_RESPONSE_BYTES, REQUEST_TIMEOUT_MS } from './policy.js';
+
+/**
+ * Join base URL and path template. Concatenated rather than \`new URL(path, base)\`:
+ * an absolute path would drop the base's own path (\`/api/v3\` + \`/pet\` → \`/pet\`).
+ */
+export function buildUrl(baseUrl, pathTemplate, pathParams = {}) {
+  let path = pathTemplate;
+  for (const [key, value] of Object.entries(pathParams)) {
+    path = path.replaceAll(\`{\${key}}\`, encodeURIComponent(String(value)));
+  }
+  return baseUrl.replace(/\\/+$/, '') + (path.startsWith('/') ? path : \`/\${path}\`);
+}
+
+export function buildQueryString(queryParams = {}) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(queryParams)) {
+    if (value === undefined || value === null) continue;
+    for (const v of Array.isArray(value) ? value : [value]) {
+      params.append(key, typeof v === 'object' ? JSON.stringify(v) : String(v));
+    }
+  }
+  return params.toString();
+}
+
+function encodeBody(body, contentType) {
+  if (typeof body === 'string') return body;
+  if (contentType.includes('application/x-www-form-urlencoded')) {
+    return buildQueryString(body);
+  }
+  return JSON.stringify(body);
+}
+
+/** Read the body, aborting as soon as it exceeds MAX_RESPONSE_BYTES. */
+async function readCapped(response) {
+  if (!response.body) return '';
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > MAX_RESPONSE_BYTES) {
+      await reader.cancel();
+      throw new Error(\`Response body exceeds \${MAX_RESPONSE_BYTES} bytes\`);
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export async function executeRequest(toolConfig, args, config = {}) {
+  const { baseUrl: configBaseUrl, headers: configHeaders = {} } = config;
+  const baseUrl = configBaseUrl || toolConfig.baseUrl;
+  if (!baseUrl) {
+    throw new Error(\`No base URL configured for tool: \${toolConfig.name}. Set API_BASE_URL.\`);
+  }
+
+  const pathParams = {};
+  const queryParams = {};
+  const rawHeaderParams = {};
+
+  for (const param of toolConfig.executionParameters || []) {
+    const value = args[param.name];
+    if (value === undefined) continue;
+    if (param.in === 'path') pathParams[param.name] = value;
+    else if (param.in === 'query') queryParams[param.name] = value;
+    else if (param.in === 'header') rawHeaderParams[param.name] = value;
+  }
+
+  let url = buildUrl(baseUrl, toolConfig.pathTemplate, pathParams);
+  const queryString = buildQueryString(queryParams);
+  if (queryString) url += (url.includes('?') ? '&' : '?') + queryString;
+
+  const method = toolConfig.method.toUpperCase();
+  const hasBody = args.requestBody !== undefined && !['GET', 'HEAD', 'OPTIONS'].includes(method);
+  const contentType = toolConfig.requestBodyContentType || 'application/json';
+
+  // configHeaders (auth) always win over spec-defined header params
+  const headers = {
+    Accept: 'application/json, */*;q=0.8',
+    ...sanitizeHeaderParams(rawHeaderParams),
+    ...configHeaders,
+  };
+  if (hasBody) headers['Content-Type'] = contentType;
+
+  let response;
+  try {
+    response = await fetch(url, {
+      method,
+      headers,
+      body: hasBody ? encodeBody(args.requestBody, contentType) : undefined,
+      // A redirect could carry the Authorization header to another host.
+      redirect: 'error',
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+  } catch (err) {
+    if (err?.name === 'TimeoutError') {
+      throw new Error(\`\${method} \${url} timed out after \${REQUEST_TIMEOUT_MS}ms\`);
+    }
+    throw new Error(\`\${method} \${url} failed: \${err?.cause?.message || err?.message || err}\`);
+  }
+
+  const declaredLength = Number.parseInt(response.headers.get('content-length') || '0', 10);
+  if (declaredLength > MAX_RESPONSE_BYTES) {
+    throw new Error(\`Response too large: \${declaredLength} bytes (max \${MAX_RESPONSE_BYTES})\`);
+  }
+
+  const text = await readCapped(response);
+  let data = text;
+  if ((response.headers.get('content-type') || '').includes('json') && text) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      // Mislabelled body — hand the raw text back instead of failing the call.
+    }
+  }
+
+  return { status: response.status, statusText: response.statusText, data, ok: response.ok };
+}
+`;
+}

package/src/templates/package-json.js

@@ -0,0 +1,21 @@
+import { DEPENDENCY_VERSIONS, NODE_ENGINE } from '../versions.js';
+
+export function generatePackageJson(serverName, tools) {
+  return JSON.stringify({
+    name: serverName,
+    version: '1.0.0',
+    description: `MCP server generated from OpenAPI spec (${tools.length} tools)`,
+    type: 'module',
+    main: 'src/index.js',
+    scripts: {
+      // Node's own .env loader (22.9+) replaces the dotenv dependency.
+      start: 'node --env-file-if-exists=.env src/index.js',
+      // `mcp-use dev` imports the default-exported server, hot-reloads it and
+      // mounts the Inspector next to the MCP endpoint.
+      dev: 'mcp-use dev --entry src/index.js',
+      'start:inspector': 'mcp-use start --entry src/index.js --with-inspector',
+    },
+    dependencies: { ...DEPENDENCY_VERSIONS },
+    engines: { node: NODE_ENGINE },
+  }, null, 2) + '\n';
+}

package/src/templates/policy.js

@@ -0,0 +1,69 @@
+import { literal } from '../spec/schema-to-zod.js';
+
+/** `src/policy.js` of the generated server: tool policy, host allowlist, header filter. */
+export function generatePolicy(baseUrl) {
+  let specHost = '';
+  try {
+    specHost = baseUrl ? new URL(baseUrl).host : '';
+  } catch { /* relative or templated server URL — no default allowlist */ }
+
+  return `// Runtime security policy for the generated MCP server
+
+const BLOCKED_HEADER_NAMES = new Set([
+  'authorization', 'cookie', 'set-cookie', 'x-api-key',
+  'x-auth-token', 'proxy-authorization', 'www-authenticate',
+  'host', 'content-length', 'transfer-encoding', 'connection',
+]);
+
+// The API host the spec declares. With ALLOWED_API_HOSTS unset, only this
+// host may be called, so a tampered API_BASE_URL cannot redirect credentials.
+const SPEC_API_HOST = ${literal(specHost)};
+
+const intEnv = (name, fallback) => {
+  const n = Number.parseInt(process.env[name] ?? '', 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+};
+
+export const MAX_RESPONSE_BYTES = intEnv('MAX_RESPONSE_BYTES', 10 * 1024 * 1024);
+export const REQUEST_TIMEOUT_MS = intEnv('REQUEST_TIMEOUT_MS', 30_000);
+
+/** Drop credential and hop-by-hop headers a tool argument tries to set. */
+export function sanitizeHeaderParams(headerParams = {}) {
+  const out = {};
+  for (const [k, v] of Object.entries(headerParams)) {
+    if (!BLOCKED_HEADER_NAMES.has(k.toLowerCase())) out[k] = String(v);
+  }
+  return out;
+}
+
+export function assertAllowedBaseUrl(baseUrl) {
+  const url = new URL(baseUrl);
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error(\`Unsupported API protocol: \${url.protocol}\`);
+  }
+  const configured = (process.env.ALLOWED_API_HOSTS || '')
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean);
+  const allowedHosts = configured.length > 0 ? configured : [SPEC_API_HOST].filter(Boolean);
+  if (allowedHosts.length > 0 && !allowedHosts.includes(url.host)) {
+    throw new Error(\`Disallowed API host: \${url.host}. Add it to ALLOWED_API_HOSTS to allow it.\`);
+  }
+}
+
+export function checkToolPolicy(toolConfig) {
+  if (!toolConfig.enabledByDefault && process.env.ALLOW_RESTRICTED_TOOLS !== 'true') {
+    throw new Error(
+      \`Tool '\${toolConfig.name}' is disabled by policy (riskLevel: \${toolConfig.riskLevel}). \` +
+      'Set ALLOW_RESTRICTED_TOOLS=true to enable restricted tools.'
+    );
+  }
+  if (toolConfig.requiresApproval && process.env.REQUIRE_APPROVALS !== 'false') {
+    throw new Error(
+      \`Tool '\${toolConfig.name}' requires approval (riskLevel: \${toolConfig.riskLevel}). \` +
+      'Set REQUIRE_APPROVALS=false to bypass, or route through an approval handler.'
+    );
+  }
+}
+`;
+}

package/src/templates/readme.js

@@ -0,0 +1,124 @@
+import { NODE_ENGINE } from '../versions.js';
+
+const cell = (s) => String(s).replace(/\|/g, '\\|').replace(/\s+/g, ' ');
+
+/** `README.md` of the generated server. */
+export function generateReadme(serverName, tools, specPath, baseUrl, port) {
+  const toolList = tools
+    .map(t => {
+      const desc = t.description.split('\n')[0];
+      return `| \`${t.name}\` | ${t.method.toUpperCase()} | ${cell(t.pathTemplate)} | ${t.riskLevel} | ${cell(desc.substring(0, 60))}${desc.length > 60 ? '…' : ''} |`;
+    })
+    .join('\n');
+
+  return `# ${serverName}
+
+MCP server generated from an OpenAPI specification by [api2ai](https://www.npmjs.com/package/api2ai), built on the [mcp-use](https://mcp-use.com) framework.
+
+- 🛠️ **${tools.length} tools** — one per OpenAPI operation, with Zod-validated input
+- 📡 **Streamable HTTP** at \`/mcp\`
+- 🔍 **Inspector** at \`/mcp/inspector\` via \`npm run dev\`
+- 🔐 **Auth** — bearer token or a custom header, never overridable by tool input
+- 🛡️ **Risk policy** — mutating and sensitive tools are off until you opt in
+
+## Quick start
+
+Requires Node ${NODE_ENGINE}.
+
+\`\`\`bash
+npm install
+cp .env.example .env   # then add your API credentials
+npm start              # http://localhost:${port}/mcp
+npm run dev            # hot reload + Inspector at http://localhost:${port}/mcp/inspector
+\`\`\`
+
+## Security
+
+**Generation-time classification** — each tool is \`low\`, \`medium\` or \`high\` risk.
+Read-only (\`GET\`/\`HEAD\`/\`OPTIONS\`) operations are \`low\` and enabled.
+Mutating operations are \`medium\` and blocked unless \`ALLOW_RESTRICTED_TOOLS=true\`.
+Anything matching admin, payment, auth, billing or credential patterns is \`high\`.
+
+**Runtime policy** — \`checkToolPolicy()\` runs before every call and enforces the risk level and approval settings below.
+
+**HTTP hardening** — request timeouts, a streamed response size cap, no redirects, a host allowlist (by default only the spec's API host), and credential headers that tool arguments cannot set.
+
+> The Inspector exposes every registered tool. Don't run \`npm run dev\` or \`start:inspector\` on a public interface.
+
+## Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| \`PORT\` | Server port | ${port} |
+| \`HOST\` | Bind address (\`0.0.0.0\` for containers) | 127.0.0.1 |
+| \`API_BASE_URL\` | Base URL for API requests | ${baseUrl || '(none in spec)'} |
+| \`API_KEY\` | Sent as \`Authorization: Bearer …\` | - |
+| \`API_AUTH_HEADER\` | Custom auth header, \`Header-Name:value\` | - |
+| \`ALLOWED_API_HOSTS\` | Comma-separated API hosts that may be called | the spec's host |
+| \`ALLOW_RESTRICTED_TOOLS\` | Enable medium/high-risk tools | false |
+| \`REQUIRE_APPROVALS\` | Refuse restricted tools until approved | true |
+| \`REQUEST_TIMEOUT_MS\` | Upstream request timeout | 30000 |
+| \`MAX_RESPONSE_BYTES\` | Upstream response size cap | 10485760 |
+| \`MCP_URL\` | Public URL when behind a proxy (its host is allowed) | - |
+| \`ALLOWED_ORIGINS\` | Browser origins allowed to call \`/mcp\` | - |
+
+## Connect a client
+
+**Claude Code**
+
+\`\`\`bash
+claude mcp add --transport http ${serverName} http://localhost:${port}/mcp
+\`\`\`
+
+**Claude Desktop, Cursor, and other JSON-configured clients**
+
+\`\`\`json
+{
+  "mcpServers": {
+    "${serverName}": { "url": "http://localhost:${port}/mcp" }
+  }
+}
+\`\`\`
+
+## Tools
+
+| Tool | Method | Path | Risk | Description |
+|------|--------|------|------|-------------|
+${toolList}
+
+## Project structure
+
+\`\`\`
+${serverName}/
+├── .env / .env.example
+├── package.json
+└── src/
+    ├── index.js         # MCPServer + one server.tool() per operation
+    ├── http-client.js   # Outbound requests (timeouts, size cap, no redirects)
+    ├── tools-config.js  # Method, path, parameters and risk for each tool
+    └── policy.js        # Tool policy, host allowlist, header filtering
+\`\`\`
+
+## Deploy
+
+\`\`\`dockerfile
+FROM node:22-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+ENV NODE_ENV=production HOST=0.0.0.0
+EXPOSE ${port}
+CMD ["node", "src/index.js"]
+\`\`\`
+
+## Source
+
+- **OpenAPI spec**: \`${specPath}\`
+- **Generated**: ${new Date().toISOString()}
+
+## License
+
+MIT
+`;
+}

package/src/templates/server-index.js

@@ -0,0 +1,128 @@
+import { literal } from '../spec/schema-to-zod.js';
+
+function toolRegistration(tool) {
+  return `
+server.tool(
+  {
+    name: ${literal(tool.name)},
+    title: ${literal(tool.title)},
+    description: ${literal(tool.description)},
+    inputSchema: ${tool.zodSchema},
+    annotations: ${JSON.stringify(tool.annotations)},
+  },
+  (params) => runTool(${literal(tool.name)}, params),
+);`;
+}
+
+/** `src/index.js` of the generated server, written against the mcp-use 2.x API. */
+export function generateServerIndex(serverName, tools, baseUrl, port) {
+  return `#!/usr/bin/env node
+
+/**
+ * ${serverName.replace(/\*\//g, '* /')} — MCP server (${tools.length} tools), generated by api2ai.
+ *
+ *   npm start      serve on http://localhost:${port}/mcp
+ *   npm run dev    hot reload + Inspector at /mcp/inspector (mcp-use dev)
+ */
+
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { MCPServer } from 'mcp-use';
+import { z } from 'zod';
+import { executeRequest } from './http-client.js';
+import { toolConfigMap } from './tools-config.js';
+import { assertAllowedBaseUrl, checkToolPolicy } from './policy.js';
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const PORT = Number.parseInt(process.env.PORT || '${port}', 10);
+
+const apiConfig = {
+  baseUrl: process.env.API_BASE_URL || ${baseUrl ? literal(baseUrl) : 'null'},
+  headers: {},
+};
+
+if (process.env.API_KEY) {
+  apiConfig.headers['Authorization'] = \`Bearer \${process.env.API_KEY}\`;
+}
+
+if (process.env.API_AUTH_HEADER) {
+  const [key, ...valueParts] = process.env.API_AUTH_HEADER.split(':');
+  const value = valueParts.join(':'); // values may contain colons
+  if (key && value) apiConfig.headers[key.trim()] = value.trim();
+}
+
+if (apiConfig.baseUrl) assertAllowedBaseUrl(apiConfig.baseUrl);
+
+// mcp-use matches allowedOrigins/allowedHosts by hostname; accept full URLs too.
+const hostnames = (list) => (list || '')
+  .split(',')
+  .map(s => s.trim())
+  .filter(Boolean)
+  .map(s => { try { return new URL(s).hostname; } catch { return s; } });
+
+const allowedOrigins = hostnames(process.env.ALLOWED_ORIGINS);
+const allowedHosts = hostnames(process.env.MCP_URL);
+
+// ============================================================================
+// Server
+// ============================================================================
+
+const server = new MCPServer({
+  name: ${literal(serverName)},
+  version: '1.0.0',
+  description: 'MCP server generated from an OpenAPI specification',
+  port: PORT,
+  ...(allowedOrigins.length > 0 && { allowedOrigins }),
+  ...(allowedHosts.length > 0 && { allowedHosts }),
+});
+
+const errorResult = (message) => ({ isError: true, content: [{ type: 'text', text: message }] });
+
+/** Policy check → upstream call → MCP tool result. Shared by every tool. */
+async function runTool(name, params) {
+  const toolConfig = toolConfigMap.get(name);
+  try {
+    checkToolPolicy(toolConfig);
+    const result = await executeRequest(toolConfig, params, apiConfig);
+    const body = typeof result.data === 'string' ? result.data : JSON.stringify(result.data, null, 2);
+
+    if (!result.ok) {
+      return errorResult(\`Error: \${result.status} \${result.statusText}\\n\${body}\`);
+    }
+    // Objects and arrays also go out as structuredContent for clients that use it.
+    return typeof result.data === 'object' && result.data !== null
+      ? { content: [{ type: 'text', text: body }], structuredContent: result.data }
+      : { content: [{ type: 'text', text: body || \`\${result.status} \${result.statusText}\` }] };
+  } catch (err) {
+    return errorResult(err?.message || String(err));
+  }
+}
+
+// ============================================================================
+// Tools
+// ============================================================================
+${tools.map(toolRegistration).join('\n')}
+
+export default server;
+
+// ============================================================================
+// Start — only when run directly; \`mcp-use dev\` imports the default export.
+// ============================================================================
+
+const isMain = Boolean(process.argv[1]) && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  const { url } = await server.listen(PORT);
+  console.log(\`
+🚀 ${serverName.replace(/[`$\\]/g, '\\$&')} MCP server
+   MCP endpoint: \${url}
+   Tools:        ${tools.length}
+   API base:     \${apiConfig.baseUrl || 'not configured (set API_BASE_URL)'}
+   Policy:       ALLOW_RESTRICTED_TOOLS=\${process.env.ALLOW_RESTRICTED_TOOLS || 'false'}, REQUIRE_APPROVALS=\${process.env.REQUIRE_APPROVALS || 'true'}
+\`);
+}
+`;
+}

package/src/templates/tools-config.js

@@ -0,0 +1,25 @@
+/** `src/tools-config.js` of the generated server: per-tool routing + policy data. */
+export function generateToolsConfig(tools) {
+  const toolConfigs = tools.map(tool => ({
+    name: tool.name,
+    description: tool.description,
+    method: tool.method,
+    pathTemplate: tool.pathTemplate,
+    executionParameters: tool.executionParameters,
+    requestBodyContentType: tool.requestBodyContentType,
+    baseUrl: tool.baseUrl,
+    tags: tool.tags,
+    operationId: tool.operationId,
+    riskLevel: tool.riskLevel,
+    requiresApproval: tool.requiresApproval,
+    allowedInInspector: tool.allowedInInspector,
+    enabledByDefault: tool.enabledByDefault,
+  }));
+
+  return `// Tool configurations extracted from the OpenAPI spec
+
+export const toolConfigs = ${JSON.stringify(toolConfigs, null, 2)};
+
+export const toolConfigMap = new Map(toolConfigs.map(t => [t.name, t]));
+`;
+}

package/src/versions.js

@@ -0,0 +1,16 @@
+/**
+ * Dependency versions written into every generated server's package.json.
+ *
+ * The generated code targets the mcp-use 2.x API (`import { MCPServer } from
+ * 'mcp-use'`, `inputSchema`, async `listen()`); a caret on the major keeps
+ * `npm install` from pulling a 3.x that the templates were not written for.
+ * Bump these together with the templates in ./templates/.
+ */
+export const DEPENDENCY_VERSIONS = {
+  'mcp-use': '^2.7.3',
+  // mcp-use validates tool input through Standard Schema; zod 4 implements it.
+  zod: '^4.6.5',
+};
+
+/** mcp-use 2.x declares `engines.node >= 22.22.2`. */
+export const NODE_ENGINE = '>=22.22.2';