@powerduck/openapi-mcp-server 1.2.0 → 1.3.0

package/README.md

@@ -1,17 +1,25 @@
 # @powerduck/openapi-mcp-server
 
-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)
+[![downloads](https://img.shields.io/npm/dm/@powerduck/openapi-mcp-server)](https://www.npmjs.com/package/@powerduck/openapi-mcp-server)
 
-## Links
+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.
 
-- [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)
+---
+
+Powerduck is an open-source developer tooling platform for teams building modern API workflows.
+
+- **Auto-Generated Tools** — Every OpenAPI operation becomes an MCP tool with full parameter schemas
+- **Auto-Generated Prompts** — Smart prompt templates for common API workflows
+- **Auto-Generated Resources** — API docs, schemas, and examples accessible as MCP resources
+- **2 Transports** — stdio for local AI clients, HTTP/SSE for remote and cloud deployments
+- **Security Resolution** — Bearer tokens, API keys, Basic auth, OAuth2, and custom schemes
+- **Type-Safe Execution** — Full parameter validation before executing API calls
+- **Error Handling** — Structured MCP errors with API response details
+- **Admin Dashboard** — Built-in web UI for monitoring tools, viewing logs, and testing
+- **Express Integration** — Attach MCP routes to any Express/Node.js HTTP server
+- **CLI & Programmatic** — Full CLI for quick starts, programmatic API for custom setups
 
 ---
 
@@ -59,321 +67,198 @@ 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)
-);
+attachSseRoutes(app, {
+  specPath: "./openapi.json",
+  routePrefix: "/mcp",
+  serverName: "My API MCP Server",
+});
 
 app.listen(3000, () => {
-  console.log("MCP SSE server running at http://localhost:3000/mcp");
+  console.log("MCP 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
+## Links
 
-- **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`
+- [Official Website](https://www.powerduck.com/opensource/openapi-mcp-server.html)
+- [Documentation](https://www.powerduck.com/docs/openapi-mcp-server/introduction)
+- [GitHub](https://github.com/PowerDuckie/openapi-mcp-server)
+- [npm](https://www.npmjs.com/package/@powerduck/openapi-mcp-server)
 
 ---
 
-## CLI Usage
+## Features
 
-```
-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
-```
+- **Auto-generated tools** — Every OpenAPI operation becomes an MCP tool with full parameter schemas
+- **Auto-generated prompts** — Smart prompt templates for common API workflows
+- **Auto-generated resources** — API docs, schemas, and examples accessible as MCP resources
+- **2 transports** — stdio for local AI clients, HTTP/SSE for remote and cloud deployments
+- **Security resolution** — Bearer tokens, API keys, Basic auth, OAuth2, and custom schemes
+- **Type-safe execution** — Full parameter validation before executing API calls
+- **Error handling** — Structured MCP errors with API response details
+- **Admin dashboard** — Built-in web UI for monitoring tools, viewing logs, and testing
+- **Express integration** — Attach MCP routes to any Express/Node.js HTTP server
+- **CLI & programmatic** — Full CLI for quick starts, programmatic API for custom setups
+- **Tool filtering** — Include/exclude tools by tag, path, method, or operationId
+- **Custom tool wrappers** — Wrap auto-generated tools with custom logic or validation
+- **Rate limiting** — Configurable rate limits per tool and per client
+- **Request logging** — Structured logging for all MCP requests and API calls
+- **CORS support** — Configurable CORS for HTTP transport
+- **Dual ESM/CJS** — Works with `import` and `require`, with bundled TypeScript declarations
 
 ---
 
-## 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"
-        }
-      }
-    }
-  }
-}
-```
+## CLI Reference
 
-### `x-mcp-prompt`
+### Commands
 
-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}}" }
-          ]
-        }
-      }
-    }
-  }
-}
-```
+```bash
+openapi-mcp-server serve [options]
 
-### `x-mcp-resource`
+# Stdio server (default)
+openapi-mcp-server serve --spec ./openapi.json
 
-Mark an operation as a readable MCP resource:
+# HTTP/SSE server
+openapi-mcp-server serve --spec ./openapi.json --transport http --port 3000
 
-```json
-{
-  "paths": {
-    "/docs/{slug}": {
-      "get": {
-        "operationId": "getDoc",
-        "x-mcp-resource": {
-          "uriTemplate": "docs://{slug}",
-          "name": "Documentation page",
-          "mimeType": "text/markdown"
-        }
-      }
-    }
-  }
-}
+# With auth and filtering
+openapi-mcp-server serve \
+  --spec ./openapi.json \
+  --transport http \
+  --port 3000 \
+  --bearer $TOKEN \
+  --include-tags users,orders \
+  --exclude-methods delete
 ```
 
-### `x-mcp-ignore`
-
-Exclude an operation from MCP entirely:
-
-```json
-{
-  "paths": {
-    "/internal/debug": {
-      "get": {
-        "x-mcp-ignore": true
-      }
-    }
-  }
-}
-```
+### Options
+
+| Option              | Type       | Default   | Description                                |
+| ------------------- | ---------- | --------- | ------------------------------------------ |
+| `--spec`            | `string`   | -         | Path or URL to OpenAPI spec (required)     |
+| `--transport`       | `string`   | `stdio`   | Transport type: `stdio` or `http`          |
+| `--port`            | `number`   | `3000`    | HTTP server port                           |
+| `--host`            | `string`   | `0.0.0.0` | HTTP server host                           |
+| `--route-prefix`    | `string`   | `/mcp`    | HTTP route prefix                          |
+| `--server-name`     | `string`   | -         | MCP server display name                    |
+| `--server-version`  | `string`   | `1.0.0`   | MCP server version                         |
+| `--bearer`          | `string`   | -         | Bearer token for API authentication        |
+| `--api-key`         | `string`   | -         | API key for API authentication             |
+| `--header`          | `string[]` | -         | Custom headers (Key: Value)                |
+| `--include-tags`    | `string`   | -         | Include tools with these tags              |
+| `--exclude-tags`    | `string`   | -         | Exclude tools with these tags              |
+| `--include-methods` | `string`   | -         | Include tools with these methods           |
+| `--exclude-methods` | `string`   | -         | Exclude tools with these methods           |
+| `--include-paths`   | `string`   | -         | Include tools matching these path patterns |
+| `--exclude-paths`   | `string`   | -         | Exclude tools matching these path patterns |
+| `--admin`           | `boolean`  | `true`    | Enable admin dashboard                     |
+| `--admin-port`      | `number`   | `3001`    | Admin dashboard port                       |
+| `--log-level`       | `string`   | `info`    | Log level: debug, info, warn, error        |
+| `--cors-origin`     | `string`   | `*`       | CORS allowed origin                        |
+| `--rate-limit`      | `number`   | `100`     | Max requests per minute per tool           |
 
 ---
 
 ## 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)`
-
-Generates MCP prompt definitions from operations with `x-mcp-prompt`.
-
-### `generateResources(spec)`
-
-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)
+Start an MCP server over stdio.
 
 ```typescript
-import { createAuthMiddleware } from "@powerduck/openapi-mcp-server";
-
-app.use("/mcp", createAuthMiddleware({
-  type: "bearer",
-  token: "your-secret-token",
-}));
-```
-
-### API key (HTTP)
+import { startStdioServer } from "@powerduck/openapi-mcp-server";
 
-```typescript
-app.use("/mcp", createAuthMiddleware({
-  type: "apikey",
-  token: "your-api-key",
-  headerName: "x-api-key",
-}));
+await startStdioServer({
+  specPath: "./openapi.json",
+  serverName: "My API",
+  serverVersion: "1.0.0",
+  securityValues: { bearerAuth: "token" },
+  toolFilter: { includeTags: ["users", "orders"] },
+  logLevel: "info",
+});
 ```
 
-### Custom auth
+### `attachSseRoutes(app, options)`
 
-Use the `routeGuard` parameter of `attachSseRoutes`:
+Attach MCP SSE routes to an Express app.
 
 ```typescript
-attachSseRoutes(
-  app,
-  specProvider,
-  contextProvider,
-  (req) => {
-    return verifyJwt(req.headers.authorization);
-  },
-);
-```
-
----
+import express from "express";
+import { attachSseRoutes } from "@powerduck/openapi-mcp-server";
 
-## Context Injection
+const app = express();
 
-Pass per-request context (user ID, tenant, etc.) to tool executions:
+attachSseRoutes(app, {
+  specPath: "./openapi.json",
+  routePrefix: "/mcp",
+  serverName: "My API",
+  corsOrigin: "https://my-app.com",
+});
 
-```typescript
-attachSseRoutes(
-  app,
-  () => "./openapi.json",
-  (req) => ({
-    userId: req.headers["x-user-id"],
-    tenantId: req.headers["x-tenant-id"],
-  }),
-);
+app.listen(3000);
 ```
 
-The context is available in tool execution and can be used for authorization or data scoping.
-
----
-
-## Admin Server
+### `startAdminServer(options)`
 
-Enable the admin REST API with `--admin` or programmatically:
+Start the admin dashboard server.
 
 ```typescript
 import { startAdminServer } from "@powerduck/openapi-mcp-server";
 
 await startAdminServer({
   port: 3001,
-  specPath: "./openapi.json",
+  mcpServerUrl: "http://localhost:3000/mcp",
 });
 ```
 
-### Endpoints
+### `createMcpServer(options)`
+
+Create a low-level MCP server instance for custom integration.
 
-| 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 |
+```typescript
+import { createMcpServer } from "@powerduck/openapi-mcp-server";
+
+const server = createMcpServer({
+  spec: openApiDocument,
+  serverName: "My API",
+  securityValues: { bearerAuth: "token" },
+});
+
+// List tools
+const tools = await server.listTools();
+
+// Call a tool
+const result = await server.callTool("getUser", { id: "123" });
+```
 
 ---
 
-## MCP Client Configuration (Claude Desktop)
+## MCP Client Configuration
 
-Add to your `claude_desktop_config.json`:
+### Claude Desktop (stdio)
 
 ```json
 {
   "mcpServers": {
     "my-api": {
       "command": "npx",
-      "args": ["@powerduck/openapi-mcp-server", "serve", "--spec", "/path/to/openapi.json"]
+      "args": [
+        "@powerduck/openapi-mcp-server",
+        "serve",
+        "--spec",
+        "./openapi.json"
+      ],
+      "env": {
+        "BEARER_TOKEN": "your-token"
+      }
     }
   }
 }
 ```
 
-For HTTP transport:
+### Cursor / VS Code (HTTP)
 
 ```json
 {
@@ -387,37 +272,24 @@ For HTTP transport:
 
 ---
 
-## Development
-
-```bash
-# Install dependencies
-npm install
+## TypeScript Types
 
-# Type check
-npm run typecheck
-
-# Build (ESM + CJS + type declarations)
-npm run build
-
-# Run tests
-npm test
-
-# Watch mode
-npx vitest watch
+```typescript
+import type {
+  StdioServerOptions,
+  HttpServerOptions,
+  McpServerOptions,
+  ToolFilter,
+  SecurityValues,
+  McpTool,
+  McpPrompt,
+  McpResource,
+  ToolCallResult,
+} from "@powerduck/openapi-mcp-server";
 ```
 
 ---
 
-## Related Packages
-
-- [`@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
-
----
-
 ## License
 
-MIT
+MIT © [POWERDUCK LIMITED](https://www.powerduck.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerduck/openapi-mcp-server",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Production-oriented OpenAPI to MCP server library with Tools, Prompts, Resources, Web UI, and admin runtime.",
   "type": "module",
   "main": "./dist/index.cjs",