@powerduck/openapi-mcp-server 1.1.0 → 1.3.0

package/README.md

@@ -1,278 +1,295 @@
 # @powerduck/openapi-mcp-server
 
-A production-oriented TypeScript library and runtime that converts OpenAPI documents into MCP (Model Context Protocol) services. Built on top of `@powerduck/openapi-parser` for robust OpenAPI validation and dereferencing.
+[![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)
 
-## 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.
 
-- **Tools** generated from OpenAPI operations with full parameter serialization
-- **Prompts** generated from API metadata and operations
-- **Resources** generated from the OpenAPI catalog
-- **HTTP (SSE)** and **STDIO** MCP transports
-- **Admin Web UI** for managing specs and services
-- **Persistent runtime state** with config storage
-- **Strong validation** and safer request execution
-- **Dual module support**: ESM and CommonJS
-- **TypeScript-first** with full type definitions
-- **91+ tests** covering core utilities, spec loading, and module exports
+---
 
-## Install
+Powerduck is an open-source developer tooling platform for teams building modern API workflows.
 
-```bash
-npm install @powerduck/openapi-mcp-server
-```
+- **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
 
-## Quick Start
+---
 
-### CLI Usage
+## Quick Start
 
-#### Web Mode (with Admin UI)
+### Install
 
 ```bash
-openapi-mcp serve \
-  --transport web \
-  --port 3000 \
-  --host 127.0.0.1 \
-  --api-key your-admin-key
+npm install @powerduck/openapi-mcp-server
 ```
 
-#### STDIO Mode
+### Run as a stdio server (CLI)
 
 ```bash
-openapi-mcp serve \
-  --transport stdio \
-  --spec ./openapi.yaml \
-  --base-url https://api.example.com
+npx @powerduck/openapi-mcp-server serve --spec ./openapi.json
 ```
 
-### Programmatic API
+### Run as an HTTP server (CLI)
 
-#### Load and Validate an OpenAPI Document
-
-```typescript
-import { loadOpenApiSpec, parseSpecContent } from "@powerduck/openapi-mcp-server";
-
-// Load from file (JSON or YAML)
-const spec = await loadOpenApiSpec("./openapi.yaml");
-
-// Parse from string content
-const specFromText = await parseSpecContent(
-  '{"openapi": "3.1.0", "info": {...}, "paths": {...}}',
-  false, // isYaml
-);
+```bash
+npx @powerduck/openapi-mcp-server serve \
+  --spec ./openapi.json \
+  --transport http \
+  --port 3000 \
+  --route-prefix /mcp
 ```
 
-#### Generate MCP Tools
+### Programmatic stdio server
 
 ```typescript
-import { generateTools, buildBindingIndex } from "@powerduck/openapi-mcp-server";
+import { startStdioServer } from "@powerduck/openapi-mcp-server";
 
-const tools = generateTools(spec);
-const bindingIndex = buildBindingIndex(spec);
-
-// tools is an array of MCP Tool definitions
-// bindingIndex maps operationIds to tool names
+await startStdioServer({
+  specPath: "./openapi.json",
+  serverName: "My API MCP Server",
+  serverVersion: "1.0.0",
+});
 ```
 
-#### Generate Prompts and Resources
+### Programmatic HTTP server (Express)
 
 ```typescript
-import { generatePrompts, generateResources } from "@powerduck/openapi-mcp-server";
-
-const prompts = generatePrompts(spec);
-const resources = generateResources(spec);
-```
+import express from "express";
+import { attachSseRoutes } from "@powerduck/openapi-mcp-server";
 
-#### Build an MCP Server
+const app = express();
 
-```typescript
-import { buildMcpServer, startStdioServer, attachSseRoutes } from "@powerduck/openapi-mcp-server";
-import express from "express";
+attachSseRoutes(app, {
+  specPath: "./openapi.json",
+  routePrefix: "/mcp",
+  serverName: "My API MCP Server",
+});
 
-// Build a server with custom spec and context providers
-const server = buildMcpServer({
-  specProvider: async () => spec,
-  contextProvider: async () => ({ baseUrl: "https://api.example.com" }),
+app.listen(3000, () => {
+  console.log("MCP server running at http://localhost:3000/mcp");
 });
+```
 
-// STDIO transport
-await startStdioServer(server);
+---
 
-// HTTP/SSE transport
-const app = express();
-attachSseRoutes(app, server, { path: "/mcp" });
-app.listen(3000);
-```
+## Links
 
-#### Execute Tool Calls
+- [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)
 
-```typescript
-import { executeToolCall } from "@powerduck/openapi-mcp-server";
-
-const result = await executeToolCall({
-  toolName: "get_user",
-  arguments: { id: "123" },
-  spec,
-  baseUrl: "https://api.example.com",
-  headers: { Authorization: "Bearer token" },
-});
-```
+---
 
-#### Spec Utility Functions
+## Features
 
-```typescript
-import {
-  iterateOperations,
-  findOperationById,
-  findDuplicateOperationIds,
-  assertUniqueOperationIds,
-  extractPathTemplateVariables,
-  synthesizeOperationId,
-  ensureUniqueName,
-  collectOperationParameters,
-  effectiveStyle,
-  effectiveExplode,
-} from "@powerduck/openapi-mcp-server";
+- **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
+
+---
+
+## CLI Reference
+
+### Commands
 
-// Iterate all operations
-for (const op of iterateOperations(spec)) {
-  console.log(op.method, op.path, op.operation?.operationId);
-}
+```bash
+openapi-mcp-server serve [options]
 
-// Find operation by ID
-const operation = findOperationById(spec, "getUser");
+# Stdio server (default)
+openapi-mcp-server serve --spec ./openapi.json
 
-// Check for duplicate operation IDs
-const duplicates = findDuplicateOperationIds(spec);
+# HTTP/SSE server
+openapi-mcp-server serve --spec ./openapi.json --transport http --port 3000
 
-// Extract path variables
-const vars = extractPathTemplateVariables("/users/{userId}/posts/{postId}");
-// => ["userId", "postId"]
+# With auth and filtering
+openapi-mcp-server serve \
+  --spec ./openapi.json \
+  --transport http \
+  --port 3000 \
+  --bearer $TOKEN \
+  --include-tags users,orders \
+  --exclude-methods delete
 ```
 
-#### Build HTTP Requests
+### 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
+
+### `startStdioServer(options)`
+
+Start an MCP server over stdio.
 
 ```typescript
-import { buildRequest } from "@powerduck/openapi-mcp-server";
-
-const request = buildRequest({
-  operation,
-  pathItem,
-  arguments: { id: "123", include: ["profile", "posts"] },
-  baseUrl: "https://api.example.com",
+import { startStdioServer } from "@powerduck/openapi-mcp-server";
+
+await startStdioServer({
+  specPath: "./openapi.json",
+  serverName: "My API",
+  serverVersion: "1.0.0",
+  securityValues: { bearerAuth: "token" },
+  toolFilter: { includeTags: ["users", "orders"] },
+  logLevel: "info",
 });
-
-// request contains: method, url, headers, body
 ```
 
-#### Admin Server and Auth
+### `attachSseRoutes(app, options)`
+
+Attach MCP SSE routes to an Express app.
 
 ```typescript
-import { startAdminServer, createAuthMiddleware } from "@powerduck/openapi-mcp-server";
+import express from "express";
+import { attachSseRoutes } from "@powerduck/openapi-mcp-server";
+
+const app = express();
 
-const app = await startAdminServer({
-  port: 3000,
-  host: "127.0.0.1",
-  apiKey: "your-admin-key",
+attachSseRoutes(app, {
+  specPath: "./openapi.json",
+  routePrefix: "/mcp",
+  serverName: "My API",
+  corsOrigin: "https://my-app.com",
 });
 
-// Or use auth middleware in your own Express app
-import express from "express";
-const myApp = express();
-myApp.use("/admin", createAuthMiddleware({ apiKey: "secret" }));
+app.listen(3000);
 ```
 
-## Project Structure
+### `startAdminServer(options)`
 
-```
-src/
-├── core/
-│   ├── openapi-loader.ts    # Spec loading, validation, dereferencing
-│   ├── spec-utils.ts        # Operation traversal, parameter normalization
-│   ├── tool-generator.ts    # MCP tool generation from operations
-│   ├── request-builder.ts   # HTTP request construction with serialization
-│   ├── http-executor.ts     # Safe HTTP request execution
-│   └── global-utils.ts      # Shared utilities (IDs, error detection)
-├── mcp/
-│   ├── create-server.ts     # MCP server construction
-│   ├── transport-stdio.ts   # STDIO transport
-│   └── transport-http.ts    # HTTP/SSE transport
-├── registry/
-│   ├── prompt-registry.ts   # Prompt generation and resolution
-│   └── resource-registry.ts # Resource generation and reading
-├── runtime/
-│   └── service-registry.ts  # Runtime service management
-├── server/
-│   ├── admin-server.ts      # Admin HTTP server with Web UI
-│   └── auth.ts              # Authentication middleware
-├── config/
-│   └── config-store.ts      # Persistent configuration storage
-├── webui/
-│   └── index.html           # Admin Web UI
-├── types.ts                 # Shared TypeScript types
-├── cli.ts                   # CLI entry point
-└── index.ts                 # Library exports
-```
+Start the admin dashboard server.
 
-## Web UI
+```typescript
+import { startAdminServer } from "@powerduck/openapi-mcp-server";
 
-The admin UI supports:
+await startAdminServer({
+  port: 3001,
+  mcpServerUrl: "http://localhost:3000/mcp",
+});
+```
 
-- Upload and paste OpenAPI documents (JSON or YAML)
-- View generated tools, prompts, and resources
-- Inspect running runtime services
-- Stop services
-- Basic MCP debugging hints
-- SSE endpoint discovery
-- STDIO configuration guidance
+### `createMcpServer(options)`
 
-## Testing
+Create a low-level MCP server instance for custom integration.
 
-```bash
-# Run all tests
-npm test
+```typescript
+import { createMcpServer } from "@powerduck/openapi-mcp-server";
 
-# Run tests in watch mode
-npm run test:watch
+const server = createMcpServer({
+  spec: openApiDocument,
+  serverName: "My API",
+  securityValues: { bearerAuth: "token" },
+});
+
+// List tools
+const tools = await server.listTools();
 
-# Run tests with coverage
-npm run test:coverage
+// Call a tool
+const result = await server.callTool("getUser", { id: "123" });
 ```
 
-Test coverage includes:
+---
+
+## MCP Client Configuration
+
+### Claude Desktop (stdio)
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "command": "npx",
+      "args": [
+        "@powerduck/openapi-mcp-server",
+        "serve",
+        "--spec",
+        "./openapi.json"
+      ],
+      "env": {
+        "BEARER_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
 
-- **Global utilities**: ID generation, abort error detection
-- **Spec utilities**: operation iteration, parameter normalization, name uniqueness
-- **OpenAPI loader**: JSON/YAML parsing, validation, dereferencing, error handling
-- **Module exports**: all public API surface verification
+### Cursor / VS Code (HTTP)
 
-## Production Notes
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
 
-This version is production-oriented. For full SaaS deployment, consider adding:
+---
 
-- Tenant isolation
-- Database-backed project registry
-- Rate limits
-- Audit logs
-- Role-based access control (RBAC)
-- Secure secret storage
-- Upstream host allowlists
+## TypeScript Types
 
-## Dependencies
+```typescript
+import type {
+  StdioServerOptions,
+  HttpServerOptions,
+  McpServerOptions,
+  ToolFilter,
+  SecurityValues,
+  McpTool,
+  McpPrompt,
+  McpResource,
+  ToolCallResult,
+} from "@powerduck/openapi-mcp-server";
+```
 
-- `@powerduck/openapi-parser` — OpenAPI validation, dereferencing, and upgrade (replaces `@scalar/openapi-parser`)
-- `@modelcontextprotocol/sdk` — MCP protocol implementation
-- `express` — HTTP server for admin UI and SSE transport
-- `axios` — HTTP client for tool execution
-- `commander` — CLI framework
-- `js-yaml` — YAML parsing
-- `multer` — File upload handling
-- `cors` — CORS middleware
-- `terser` — Minification for embedded assets
+---
 
 ## License
 
-MIT © Powerduck limited
-
-## Important Implementation Policy
-
-All source comments are written in American English. No Chinese characters are permitted in the codebase.
+MIT © [POWERDUCK LIMITED](https://www.powerduck.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerduck/openapi-mcp-server",
-  "version": "1.1.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",