@powerduck/openapi-mcp-server 1.0.1 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Powerduck limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,92 +1,423 @@
-A production-oriented TypeScript library and runtime that converts OpenAPI documents into MCP services.
+# @powerduck/openapi-mcp-server
 
-## Features
+Turn any OpenAPI 3.2 document into a fully functional MCP (Model Context Protocol) server. Automatically generates tools, prompts, and resources from your API spec. Supports both stdio and HTTP (SSE) transports.
+
+[![npm version](https://img.shields.io/npm/v/@powerduck/openapi-mcp-server)](https://www.npmjs.com/package/@powerduck/openapi-mcp-server)
+[![license](https://img.shields.io/npm/l/@powerduck/openapi-mcp-server)](https://github.com/PowerDuckie/openapi-mcp-server/blob/main/LICENSE)
+
+## Links
+
+- [Official Website](https://www.powerduck.com/opensource/openapi-mcp-server.html)
+- [Documentation](https://www.powerduck.com/docs/openapi-mcp-server/introduction)
+- [Live Demo](https://www.powerduck.com/demo/openapi-mcp-server.html)
+- [GitHub](https://github.com/PowerDuckie/openapi-mcp-server)
+- [npm](https://www.npmjs.com/package/@powerduck/openapi-mcp-server)
 
-- Tools generated from OpenAPI operations
-- Prompts generated from API metadata and operations
-- Resources generated from the OpenAPI catalog
-- HTTP and STDIO MCP transports
-- Admin Web UI
-- Persistent runtime state
-- Stronger validation and safer request execution
-- Production-oriented structure for future SaaS evolution
+---
 
-## Install
+## Quick Start
+
+### Install
 
 ```bash
-npm i @powerduck/openapi-mcp-server
+npm install @powerduck/openapi-mcp-server
 ```
 
-## Start web runtime
+### Run as a stdio server (CLI)
 
 ```bash
-npm run start -- serve --port 3000 --host 127.0.0.1
+npx @powerduck/openapi-mcp-server serve --spec ./openapi.json
 ```
 
-## Start STDIO runtime
+### Run as an HTTP server (CLI)
 
 ```bash
-node dist/cli.js serve --transport stdio --spec ./openapi.yaml
+npx @powerduck/openapi-mcp-server serve \
+  --spec ./openapi.json \
+  --transport http \
+  --port 3000 \
+  --route-prefix /mcp
 ```
 
-## CLI usage
+### Programmatic stdio server
 
-### Web mode
+```typescript
+import { startStdioServer } from "@powerduck/openapi-mcp-server";
 
-```bash
-openapi-mcp serve \
-  --transport web \
-  --port 3000 \
-  --host 127.0.0.1 \
-  --api-key your-admin-key
+await startStdioServer({
+  specPath: "./openapi.json",
+  serverName: "My API MCP Server",
+  serverVersion: "1.0.0",
+});
 ```
 
-### STDIO mode
+### Programmatic HTTP server (Express)
 
-```bash
-openapi-mcp serve \
-  --transport stdio \
-  --spec ./openapi.yaml \
-  --base-url https://api.example.com
+```typescript
+import express from "express";
+import { attachSseRoutes } from "@powerduck/openapi-mcp-server";
+
+const app = express();
+
+attachSseRoutes(
+  app,
+  () => "./openapi.json", // spec provider: path, URL, or parsed document
+  () => ({ userId: "user-123" }), // context provider (optional)
+  (req) => req.headers["x-api-key"] === "secret", // route guard (optional)
+);
+
+app.listen(3000, () => {
+  console.log("MCP SSE server running at http://localhost:3000/mcp");
+});
+```
+
+### Generate tools from a spec
+
+```typescript
+import { loadOpenApiSpec, generateTools } from "@powerduck/openapi-mcp-server";
+
+const spec = await loadOpenApiSpec("./openapi.json");
+const tools = generateTools(spec);
+
+console.log(`Generated ${tools.length} tools:`);
+for (const tool of tools) {
+  console.log(`- ${tool.name}: ${tool.description}`);
+}
+```
+
+---
+
+## Features
+
+- **Automatic tool generation** — every operation becomes an MCP tool with a JSON Schema input schema derived from parameters and request body
+- **Prompt generation** — operations with `x-mcp-prompt` become MCP prompts with templated messages
+- **Resource generation** — operations marked with `x-mcp-resource` become readable MCP resources
+- **Two transports** — stdio for local CLI tools and IDEs, HTTP (SSE) for remote servers and web clients
+- **Authentication** — Bearer token, API key, and custom auth middleware for HTTP transport
+- **Admin server** — optional REST admin API for health checks, spec reload, and diagnostics
+- **Context injection** — per-request context provider for user IDs, tenant info, etc.
+- **Route guards** — custom authorization function for HTTP transport
+- **Spec loading** — load from file path, URL, or parsed object; JSON and YAML supported
+- **Built on `@powerduck/openapi-request`** — full OpenAPI parameter serialization for tool execution
+- **Dual ESM/CJS builds** — works with `import` and `require`
+
+---
+
+## CLI Usage
+
+```
+openapi-mcp serve [options]
+
+Options:
+  --spec <path>            Path or URL to OpenAPI 3.2 spec (required)
+  --transport <mode>       Transport mode: stdio or http (default: stdio)
+  --port <number>          HTTP server port (default: 3000)
+  --host <string>          HTTP server host (default: 0.0.0.0)
+  --route-prefix <path>    HTTP route prefix for MCP endpoints (default: /mcp)
+  --server-name <name>     MCP server name (default: OpenAPI MCP Server)
+  --server-version <ver>   MCP server version (default: 1.0.0)
+  --admin                  Enable admin REST API
+  --admin-port <number>    Admin server port (default: 3001)
+  --auth-type <type>       Auth type: bearer, apikey, or none (default: none)
+  --auth-token <token>     Bearer token or API key value
+  --auth-header <name>     API key header name (default: x-api-key)
+  -h, --help               Show help
+  -v, --version            Show version
+```
+
+---
+
+## MCP Extensions
+
+Control how operations are exposed to MCP clients using OpenAPI extensions:
+
+### `x-mcp-tool`
+
+Mark an operation as an MCP tool (all operations are tools by default):
+
+```json
+{
+  "paths": {
+    "/users/{id}": {
+      "get": {
+        "operationId": "getUser",
+        "x-mcp-tool": {
+          "name": "get_user",
+          "description": "Fetch a user by ID"
+        }
+      }
+    }
+  }
+}
+```
+
+### `x-mcp-prompt`
+
+Mark an operation as an MCP prompt:
+
+```json
+{
+  "paths": {
+    "/search": {
+      "get": {
+        "operationId": "search",
+        "x-mcp-prompt": {
+          "name": "search_docs",
+          "description": "Search the documentation",
+          "arguments": [
+            { "name": "query", "description": "Search query", "required": true }
+          ],
+          "messages": [
+            { "role": "user", "content": "Search for: {{query}}" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+### `x-mcp-resource`
+
+Mark an operation as a readable MCP resource:
+
+```json
+{
+  "paths": {
+    "/docs/{slug}": {
+      "get": {
+        "operationId": "getDoc",
+        "x-mcp-resource": {
+          "uriTemplate": "docs://{slug}",
+          "name": "Documentation page",
+          "mimeType": "text/markdown"
+        }
+      }
+    }
+  }
+}
 ```
 
-## Production notes
+### `x-mcp-ignore`
+
+Exclude an operation from MCP entirely:
+
+```json
+{
+  "paths": {
+    "/internal/debug": {
+      "get": {
+        "x-mcp-ignore": true
+      }
+    }
+  }
+}
+```
+
+---
+
+## Programmatic API
+
+### `loadOpenApiSpec(input)`
+
+Loads an OpenAPI spec from a file path, URL, or parsed object. Returns the parsed document.
+
+```typescript
+const spec = await loadOpenApiSpec("./openapi.json");
+const specFromUrl = await loadOpenApiSpec("https://api.example.com/openapi.json");
+const specFromObject = await loadOpenApiSpec({ openapi: "3.2.0", ... });
+```
+
+### `generateTools(spec)`
+
+Generates an array of MCP tool definitions from the spec.
+
+### `generateToolsDetailed(spec)`
+
+Generates tools with additional metadata (operationId, path, method).
+
+### `generatePrompts(spec)`
 
-This version is production-oriented, but you should still add the following for SaaS deployment:
+Generates MCP prompt definitions from operations with `x-mcp-prompt`.
 
-- tenant isolation
-- database-backed project registry
-- rate limits
-- audit logs
-- RBAC
-- secure secret storage
-- upstream host allowlists
-- comprehensive test suites
-- full OpenAPI parameter serialization coverage
-- full requestBody content negotiation support
+### `generateResources(spec)`
 
-## Project structure
+Generates MCP resource definitions from operations with `x-mcp-resource`.
+
+### `executeToolCall(spec, toolName, arguments, context?)`
+
+Executes a tool by name, passing the arguments and optional context. Returns the tool result.
+
+### `buildMcpServer(options)`
+
+Builds an MCP server instance (transport-agnostic).
+
+### `startStdioServer(options)`
+
+Starts a stdio MCP server. Blocks until the server is closed.
+
+### `attachSseRoutes(app, specProvider, contextProvider?, routeGuard?)`
+
+Attaches MCP SSE routes to an Express-compatible app. This is the public API for HTTP transport.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `app` | `Express` | Express app instance |
+| `specProvider` | `() => string \| object \| Promise<string \| object>` | Returns spec path, URL, or parsed document |
+| `contextProvider` | `(req) => Record<string, unknown> \| Promise<Record<string, unknown>>` | Optional. Returns per-request context |
+| `routeGuard` | `(req) => boolean \| Promise<boolean>` | Optional. Returns true if the request is authorized |
+
+### `startAdminServer(options)`
+
+Starts an optional admin REST API server for health checks and diagnostics.
+
+---
+
+## Authentication
+
+### Bearer token (HTTP)
+
+```typescript
+import { createAuthMiddleware } from "@powerduck/openapi-mcp-server";
+
+app.use("/mcp", createAuthMiddleware({
+  type: "bearer",
+  token: "your-secret-token",
+}));
+```
+
+### API key (HTTP)
+
+```typescript
+app.use("/mcp", createAuthMiddleware({
+  type: "apikey",
+  token: "your-api-key",
+  headerName: "x-api-key",
+}));
+```
+
+### Custom auth
+
+Use the `routeGuard` parameter of `attachSseRoutes`:
+
+```typescript
+attachSseRoutes(
+  app,
+  specProvider,
+  contextProvider,
+  (req) => {
+    return verifyJwt(req.headers.authorization);
+  },
+);
+```
+
+---
+
+## Context Injection
+
+Pass per-request context (user ID, tenant, etc.) to tool executions:
+
+```typescript
+attachSseRoutes(
+  app,
+  () => "./openapi.json",
+  (req) => ({
+    userId: req.headers["x-user-id"],
+    tenantId: req.headers["x-tenant-id"],
+  }),
+);
+```
+
+The context is available in tool execution and can be used for authorization or data scoping.
+
+---
+
+## Admin Server
+
+Enable the admin REST API with `--admin` or programmatically:
+
+```typescript
+import { startAdminServer } from "@powerduck/openapi-mcp-server";
+
+await startAdminServer({
+  port: 3001,
+  specPath: "./openapi.json",
+});
+```
+
+### Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/health` | Health check |
+| `GET` | `/spec` | Current loaded spec info |
+| `POST` | `/reload` | Reload the spec from disk |
+| `GET` | `/tools` | List generated tools |
+| `GET` | `/prompts` | List generated prompts |
+| `GET` | `/resources` | List generated resources |
+
+---
+
+## MCP Client Configuration (Claude Desktop)
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "command": "npx",
+      "args": ["@powerduck/openapi-mcp-server", "serve", "--spec", "/path/to/openapi.json"]
+    }
+  }
+}
+```
+
+For HTTP transport:
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Type check
+npm run typecheck
+
+# Build (ESM + CJS + type declarations)
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode
+npx vitest watch
+```
 
-- `src/core`: spec parsing, operation traversal, tool generation, request building, execution
-- `src/mcp`: MCP server creation and transports
-- `src/registry`: prompts and resources registries
-- `src/runtime`: runtime service registry
-- `src/server`: admin HTTP server
-- `src/webui`: browser UI
-- `src/config`: persistence helpers
+---
 
-## Web UI
+## Related Packages
 
-The UI supports:
+- [`@powerduck/openapi-parser`](https://www.npmjs.com/package/@powerduck/openapi-parser) — OpenAPI 3.2 parser, validator, and upgrader
+- [`@powerduck/openapi-request`](https://www.npmjs.com/package/@powerduck/openapi-request) — Execute OpenAPI operations with full parameter serialization
+- [`@powerduck/openapi-codegen`](https://www.npmjs.com/package/@powerduck/openapi-codegen) — Generate runnable request examples in 21 languages
+- [`@powerduck/openapi-cli`](https://www.npmjs.com/package/@powerduck/openapi-cli) — CI-ready batch testing for OpenAPI documents
+- [`@powerduck/x-to-openapi`](https://www.npmjs.com/package/@powerduck/x-to-openapi) — Convert curl commands and Postman Collections to OpenAPI 3.2
 
-- upload and paste OpenAPI documents
-- view tools, prompts, and resources
-- inspect runtime services
-- stop services
-- basic MCP debugging hints
-- SSE endpoint discovery
-- STDIO tooltip guidance
+---
 
-## Important implementation policy
+## License
 
-All source comments are written in American English.
+MIT

package/dist/{admin-server-B4fQWUnc.d.cts → admin-server-dcPWB2yO.d.cts}

@@ -1,6 +1,6 @@
 import { Express } from 'express';
 import { Server } from 'node:http';
-import { Document } from '@scalar/openapi-types/3.2';
+import { Oas32Document } from '@powerduck/openapi-parser';
 import { Prompt, PromptArgument, Resource, Tool } from '@modelcontextprotocol/sdk/types.js';
 
 /** How the MCP server is exposed to a client. */
@@ -96,7 +96,7 @@ interface SecurityContext {
 }
 /** Mutable runtime state of the loaded specification. */
 interface AppState {
-    spec: Document | null;
+    spec: Oas32Document | null;
     baseUrlOverride?: string | undefined;
     specSource?: SpecSource | undefined;
 }

package/dist/{admin-server-B4fQWUnc.d.ts → admin-server-dcPWB2yO.d.ts}

@@ -1,6 +1,6 @@
 import { Express } from 'express';
 import { Server } from 'node:http';
-import { Document } from '@scalar/openapi-types/3.2';
+import { Oas32Document } from '@powerduck/openapi-parser';
 import { Prompt, PromptArgument, Resource, Tool } from '@modelcontextprotocol/sdk/types.js';
 
 /** How the MCP server is exposed to a client. */
@@ -96,7 +96,7 @@ interface SecurityContext {
 }
 /** Mutable runtime state of the loaded specification. */
 interface AppState {
-    spec: Document | null;
+    spec: Oas32Document | null;
     baseUrlOverride?: string | undefined;
     specSource?: SpecSource | undefined;
 }