@emcy/openapi-to-mcp 0.2.0 → 0.3.0

package/README.md

@@ -1,35 +1,61 @@
 # @emcy/openapi-to-mcp
 
-Convert OpenAPI specifications to MCP (Model Context Protocol) servers in seconds.
+Convert OpenAPI specifications into MCP runtimes.
 
 [![npm version](https://badge.fury.io/js/%40emcy%2Fopenapi-to-mcp.svg)](https://www.npmjs.com/package/@emcy/openapi-to-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## What is this?
+## What it generates
 
-This CLI tool takes an OpenAPI specification (Swagger) and generates a fully functional MCP server that exposes your API endpoints as AI-callable tools.
+This package now supports three runtime shapes only:
 
-**Use cases:**
-- Let AI assistants (Claude, Cursor, etc.) interact with your REST APIs
-- Create MCP servers without writing code
-- Add observability to AI tool usage with Emcy telemetry
+1. `standalone_no_auth`
+   - Public MCP server
+   - No built-in upstream auth logic
+   - Good for public or already-open APIs
+
+2. `standalone_headers`
+   - Public MCP server
+   - Injects static/custom headers into every upstream API request
+   - Good for API keys, static bearer tokens, tenant headers, and similar patterns
+
+3. `emcy_hosted_worker`
+   - Private worker runtime behind Emcy
+   - Emcy hosts the public MCP and OAuth surface
+   - Good for OAuth-protected APIs where Emcy brokers user auth and forwards short-lived downstream access per execution
+
+The generator no longer produces standalone public OAuth resource servers and no longer supports bearer-token passthrough.
 
 ## Quick Start
 
 ```bash
-# Generate from a URL
-npx @emcy/openapi-to-mcp generate --url https://petstore.swagger.io/v2/swagger.json
+# Standalone MCP server for a public API
+npx @emcy/openapi-to-mcp generate \
+  --url https://petstore.swagger.io/v2/swagger.json \
+  --mode standalone-no-auth
 
-# Generate from a local file
-npx @emcy/openapi-to-mcp generate --url ./openapi.yaml --name my-api
+# Standalone MCP server that injects an API key header upstream
+npx @emcy/openapi-to-mcp generate \
+  --url ./openapi.yaml \
+  --name my-api \
+  --mode standalone-headers \
+  --header X-API-Key=UPSTREAM_API_KEY
 
-# Generate with Emcy telemetry enabled
-npx @emcy/openapi-to-mcp generate --url ./api.json --name my-api --emcy
+# Emcy-hosted worker for an OAuth-protected app
+npx @emcy/openapi-to-mcp generate \
+  --url ./openapi.yaml \
+  --name my-app \
+  --mode emcy-hosted-worker \
+  --hosted-provider sqlos \
+  --hosted-auth-server-url https://auth.example.com/sqlos/auth \
+  --hosted-client-id todo-mcp-local \
+  --hosted-resource https://api.example.com/todos \
+  --hosted-scopes "openid profile email offline_access todos.read todos.write"
 ```
 
 ## Installation
 
-You can use it directly with `npx` (recommended) or install globally:
+Use it directly with `npx` or install globally:
 
 ```bash
 npm install -g @emcy/openapi-to-mcp
@@ -39,169 +65,160 @@ npm install -g @emcy/openapi-to-mcp
 
 ### `generate`
 
-Generate an MCP server from an OpenAPI specification.
-
 ```bash
 npx @emcy/openapi-to-mcp generate [options]
 ```
 
-**Options:**
-
 | Option | Short | Description |
-|--------|-------|-------------|
-| `--url` | `-u` | URL or file path to OpenAPI specification (required) |
-| `--name` | `-n` | Name for the generated MCP server |
-| `--output` | `-o` | Output directory (default: `./<name>-mcp-server`) |
-| `--emcy` | `-e` | Enable Emcy telemetry integration |
-| `--base-url` | `-b` | Override base URL for API calls |
-| `--version` | | Version string for the server |
-| `--force` | `-f` | Overwrite existing output directory |
+| --- | --- | --- |
+| `--url` | `-u` | URL or file path to OpenAPI spec |
+| `--name` | `-n` | Name for the generated runtime |
+| `--output` | `-o` | Output directory |
+| `--base-url` | `-b` | Override the upstream API base URL |
+| `--version` |  | Runtime version string |
+| `--emcy` | `-e` | Include `@emcy/sdk` telemetry |
+| `--local-sdk` |  | Use a local `@emcy/sdk` path |
+| `--prompts-json` |  | JSON array of MCP prompt definitions |
+| `--tool-instructions-json` |  | JSON object keyed by tool key for tool-specific AI guidance |
+| `--mode` |  | `standalone-no-auth`, `standalone-headers`, or `emcy-hosted-worker` |
+| `--header` |  | Repeatable `Header-Name=ENV_VAR` mapping for upstream requests |
+| `--hosted-provider` |  | Hosted OAuth provider recipe label for `emcy-hosted-worker` |
+| `--hosted-auth-server-url` |  | Downstream authorization server issuer or metadata base URL |
+| `--hosted-client-id` |  | Downstream client ID Emcy should use |
+| `--hosted-resource` |  | Downstream API resource / audience |
+| `--hosted-scopes` |  | Comma or space separated downstream scopes |
+| `--force` | `-f` | Overwrite the output directory |
 
 ### `validate`
 
-Validate an OpenAPI specification.
-
 ```bash
 npx @emcy/openapi-to-mcp validate --url https://api.example.com/openapi.json
 ```
 
-## Generated Server
-
-The generated MCP server includes:
+## Runtime Modes
 
-- **TypeScript source code** - Full type safety
-- **HTTP transport** - For Cursor and web-based clients
-- **Stdio transport** - For Claude Desktop
-- **Security support** - API keys, Bearer tokens, OAuth2
-- **Environment-based config** - `.env.example` with all settings
-- **README** - Usage instructions
+### `standalone_no_auth`
 
-### Running the Generated Server
+Use this when the upstream API is public or already reachable without adding credentials from the MCP runtime.
 
 ```bash
-cd my-api-mcp-server
-npm install
-npm run build
+npx @emcy/openapi-to-mcp generate \
+  --url ./openapi.json \
+  --mode standalone-no-auth
+```
+
+### `standalone_headers`
 
-# For Cursor/HTTP clients
-npm run start:http
+Use this when every upstream request needs static headers.
 
-# For Claude Desktop/stdio
-npm start
+```bash
+npx @emcy/openapi-to-mcp generate \
+  --url ./openapi.json \
+  --mode standalone-headers \
+  --header X-API-Key=UPSTREAM_API_KEY \
+  --header X-Tenant-Id=UPSTREAM_TENANT_ID
 ```
 
-### Using with Cursor
+If your upstream API needs `Authorization: Bearer ...`, either:
 
-Add to your `~/.cursor/mcp.json`:
+- model it as a bearer security scheme in the OpenAPI document, or
+- pass the full header value through an env var:
 
-```json
-{
-  "mcpServers": {
-    "my-api": {
-      "url": "http://localhost:3000/mcp"
-    }
-  }
-}
+```bash
+npx @emcy/openapi-to-mcp generate \
+  --url ./openapi.json \
+  --mode standalone-headers \
+  --header Authorization=UPSTREAM_AUTHORIZATION
 ```
 
-### Using with Claude Desktop
-
-Add to your Claude Desktop config:
+Then set:
 
-```json
-{
-  "mcpServers": {
-    "my-api": {
-      "command": "node",
-      "args": ["/path/to/my-api-mcp-server/build/index.js"]
-    }
-  }
-}
+```bash
+UPSTREAM_AUTHORIZATION=Bearer eyJ...
 ```
 
-## Emcy Telemetry
+### `emcy_hosted_worker`
 
-When you generate with `--emcy`, the server includes [@emcy/sdk](https://www.npmjs.com/package/@emcy/sdk) for telemetry:
+Use this when the upstream API is protected by OAuth and you want Emcy to host the MCP and OAuth surface.
 
-- **Tool invocation tracking** - Every tool call is logged
-- **Error monitoring** - Failures are captured with context
-- **Performance metrics** - Latency and success rates
-- **Dashboard** - View analytics at [emcy.ai](https://emcy.ai)
+The generated runtime is not the public MCP server. It is the private worker Emcy calls after it has already:
 
-To enable telemetry, set these environment variables:
+- authenticated the MCP client
+- completed the downstream app OAuth flow
+- stored the downstream grant server-side
+- minted or loaded the short-lived downstream access token for the execution
 
 ```bash
-EMCY_API_KEY=your-api-key-from-dashboard
-EMCY_TELEMETRY_URL=https://api.emcy.ai/v1/telemetry
-EMCY_MCP_SERVER_ID=mcp_xxxxxxxxxxxx
+npx @emcy/openapi-to-mcp generate \
+  --url ./openapi.json \
+  --mode emcy-hosted-worker \
+  --hosted-provider sqlos \
+  --hosted-auth-server-url https://auth.example.com/sqlos/auth \
+  --hosted-client-id todo-mcp-local \
+  --hosted-resource https://api.example.com/todos \
+  --hosted-scopes "openid profile email offline_access todos.read todos.write"
 ```
 
-## Programmatic Usage
+This is the right mode for apps protected by systems like:
 
-You can also use the library programmatically:
+- Auth0
+- WorkOS AuthKit
+- SqlOS AuthServer/AuthPage
+- Entra
+- generic OAuth/OIDC authorization servers
 
-```typescript
-import { parseOpenAPI, mapToMcpTools, generateMcpServer } from '@emcy/openapi-to-mcp';
+## Generated Runtime
 
-// Parse an OpenAPI spec
-const parsed = await parseOpenAPI('https://api.example.com/openapi.json');
+Every generated runtime includes:
 
-// Map endpoints to MCP tools
-const tools = mapToMcpTools(parsed.endpoints);
+- TypeScript source
+- MCP tool bindings for the selected OpenAPI operations
+- Streamable HTTP transport
+- `.env.example`
+- generated README
 
-// Generate server files
-const files = generateMcpServer(tools, {
-  name: 'my-api',
-  version: '1.0.0',
-  baseUrl: 'https://api.example.com',
-  emcyEnabled: true,
-}, parsed.securitySchemes);
+Standalone modes also support stdio for desktop clients.
 
-// files is a Record<string, string> of file paths to contents
-```
+## Programmatic Usage
 
-## Supported OpenAPI Features
+```ts
+import { parseOpenAPI, mapToMcpTools, generateMcpServer } from "@emcy/openapi-to-mcp";
 
-- ✅ OpenAPI 3.0 and 3.1
-- ✅ Path, query, and header parameters
-- ✅ Request bodies (JSON)
-- ✅ API key authentication
-- ✅ Bearer token authentication
-- ✅ OAuth2 (client credentials)
-- ✅ Multiple security schemes
-- ⏳ File uploads (coming soon)
-- ⏳ Webhooks (coming soon)
+const parsed = await parseOpenAPI("https://api.example.com/openapi.json");
+const tools = mapToMcpTools(parsed.endpoints);
 
-## Examples
+const files = generateMcpServer(
+  tools,
+  {
+    name: "my-api",
+    version: "1.0.0",
+    baseUrl: "https://api.example.com",
+    runtimeMode: "standalone_headers",
+    upstreamHeaders: [
+      { name: "X-API-Key", envVar: "UPSTREAM_API_KEY" },
+    ],
+  },
+  parsed.securitySchemes
+);
+```
 
-### Petstore API
+## What this package does not do
 
-```bash
-npx @emcy/openapi-to-mcp generate \
-  --url https://petstore.swagger.io/v2/swagger.json \
-  --name petstore
-```
+- It does not host a public OAuth authorization server for MCP clients.
+- It does not support forwarding end-user bearer tokens from the MCP client to the upstream API.
+- It does not try to replace Emcy's hosted auth/runtime layer for OAuth-protected apps.
 
-### Local Development API
+## Emcy
 
-```bash
-npx @emcy/openapi-to-mcp generate \
-  --url http://localhost:5000/swagger/v1/swagger.json \
-  --name my-local-api \
-  --base-url http://localhost:5000
-```
+Use Emcy when you want to turn an OAuth-protected API into:
 
-### With Emcy Telemetry
+- a hosted MCP server
+- an embedded agent
+- a workspace integration
+- an external client surface for tools like VS Code or Claude
 
-```bash
-npx @emcy/openapi-to-mcp generate \
-  --url ./openapi.yaml \
-  --name my-api \
-  --emcy \
-  --output ./mcp-servers/my-api
-```
+The open-source generator handles the runtime. Emcy handles the hosted auth and orchestration layer.
 
 ## License
 
 MIT © [Emcy](https://emcy.ai)
-

package/dist/__tests__/cli-config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli-config.test.d.ts.map

package/dist/__tests__/cli-config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-config.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/cli-config.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/cli-config.test.js

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { normalizeRuntimeMode, parseGeneratorCliConfig, parseHostedOauthConfig, parseToolInstructions, } from "../cli-config.js";
+describe("cli-config", () => {
+    it("normalizes supported runtime modes", () => {
+        expect(normalizeRuntimeMode("standalone-no-auth")).toBe("standalone_no_auth");
+        expect(normalizeRuntimeMode("standalone_headers")).toBe("standalone_headers");
+        expect(normalizeRuntimeMode("emcy-hosted-worker")).toBe("emcy_hosted_worker");
+    });
+    it("parses hosted oauth config from explicit flags", () => {
+        const config = parseHostedOauthConfig({
+            "hosted-provider": "auth0",
+            "hosted-auth-server-url": "https://auth.example.com",
+            "hosted-client-id": "client_123",
+            "hosted-resource": "https://api.example.com",
+            "hosted-scopes": "openid profile email offline_access todos.read",
+        });
+        expect(config).toEqual({
+            provider: "auth0",
+            authorizationServerUrl: "https://auth.example.com",
+            clientId: "client_123",
+            resource: "https://api.example.com",
+            scopes: ["openid", "profile", "email", "offline_access", "todos.read"],
+        });
+    });
+    it("parses tool instructions json objects", () => {
+        expect(parseToolInstructions(JSON.stringify({
+            get_api_todos: {
+                customInstructions: "Use this for current todos only.",
+            },
+        }))).toEqual({
+            get_api_todos: {
+                customInstructions: "Use this for current todos only.",
+            },
+        });
+    });
+    it("builds generator CLI config for hosted workers", () => {
+        const parsed = parseGeneratorCliConfig({
+            mode: "emcy-hosted-worker",
+            "prompts-json": JSON.stringify([
+                {
+                    name: "todo-summary",
+                    description: "Summarize todos",
+                    content: "Summarize {{topic}}",
+                },
+            ]),
+            "tool-instructions-json": JSON.stringify({
+                get_api_todos: {
+                    whenToUse: "When the user asks to list todos.",
+                },
+            }),
+            "hosted-provider": "sqlos",
+            "hosted-auth-server-url": "https://auth.example.com/sqlos/auth",
+            "hosted-client-id": "todo-mcp-local",
+            "hosted-resource": "https://api.example.com/todos",
+            "hosted-scopes": "openid profile todos.read todos.write",
+        });
+        expect(parsed.runtimeMode).toBe("emcy_hosted_worker");
+        expect(parsed.prompts).toHaveLength(1);
+        expect(parsed.toolInstructions).toEqual({
+            get_api_todos: {
+                whenToUse: "When the user asks to list todos.",
+            },
+        });
+        expect(parsed.hostedOauthConfig).toEqual({
+            provider: "sqlos",
+            authorizationServerUrl: "https://auth.example.com/sqlos/auth",
+            clientId: "todo-mcp-local",
+            resource: "https://api.example.com/todos",
+            scopes: ["openid", "profile", "todos.read", "todos.write"],
+        });
+    });
+});
+//# sourceMappingURL=cli-config.test.js.map

package/dist/__tests__/cli-config.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-config.test.js","sourceRoot":"","sources":["../../src/__tests__/cli-config.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/generator.test.d.ts

@@ -1,5 +1,5 @@
 /**
- * Generator tests - ensures MCP server code is correctly generated
+ * Generator tests - verifies the supported runtime modes.
  */
 export {};
 //# sourceMappingURL=generator.test.d.ts.map