@powerduck/openapi-mcp-server 1.1.0 → 1.2.0

package/README.md

@@ -1,278 +1,423 @@
 # @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.
+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.
 
-## Features
+[![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 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
+## Quick Start
+
+### Install
 
 ```bash
 npm install @powerduck/openapi-mcp-server
 ```
 
-## Quick Start
+### Run as a stdio server (CLI)
 
-### CLI Usage
+```bash
+npx @powerduck/openapi-mcp-server serve --spec ./openapi.json
+```
 
-#### Web Mode (with Admin UI)
+### Run as an HTTP server (CLI)
 
 ```bash
-openapi-mcp serve \
-  --transport web \
+npx @powerduck/openapi-mcp-server serve \
+  --spec ./openapi.json \
+  --transport http \
   --port 3000 \
-  --host 127.0.0.1 \
-  --api-key your-admin-key
+  --route-prefix /mcp
 ```
 
-#### STDIO Mode
+### Programmatic stdio server
 
-```bash
-openapi-mcp serve \
-  --transport stdio \
-  --spec ./openapi.yaml \
-  --base-url https://api.example.com
-```
+```typescript
+import { startStdioServer } from "@powerduck/openapi-mcp-server";
 
-### Programmatic API
+await startStdioServer({
+  specPath: "./openapi.json",
+  serverName: "My API MCP Server",
+  serverVersion: "1.0.0",
+});
+```
 
-#### Load and Validate an OpenAPI Document
+### Programmatic HTTP server (Express)
 
 ```typescript
-import { loadOpenApiSpec, parseSpecContent } from "@powerduck/openapi-mcp-server";
+import express from "express";
+import { attachSseRoutes } from "@powerduck/openapi-mcp-server";
 
-// Load from file (JSON or YAML)
-const spec = await loadOpenApiSpec("./openapi.yaml");
+const app = express();
 
-// Parse from string content
-const specFromText = await parseSpecContent(
-  '{"openapi": "3.1.0", "info": {...}, "paths": {...}}',
-  false, // isYaml
+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 MCP Tools
+### Generate tools from a spec
 
 ```typescript
-import { generateTools, buildBindingIndex } from "@powerduck/openapi-mcp-server";
+import { loadOpenApiSpec, generateTools } from "@powerduck/openapi-mcp-server";
 
+const spec = await loadOpenApiSpec("./openapi.json");
 const tools = generateTools(spec);
-const bindingIndex = buildBindingIndex(spec);
 
-// tools is an array of MCP Tool definitions
-// bindingIndex maps operationIds to tool names
+console.log(`Generated ${tools.length} tools:`);
+for (const tool of tools) {
+  console.log(`- ${tool.name}: ${tool.description}`);
+}
 ```
 
-#### Generate Prompts and Resources
+---
 
-```typescript
-import { generatePrompts, generateResources } from "@powerduck/openapi-mcp-server";
+## 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`
 
-const prompts = generatePrompts(spec);
-const resources = generateResources(spec);
+---
+
+## 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
 ```
 
-#### Build an MCP Server
+---
 
-```typescript
-import { buildMcpServer, startStdioServer, attachSseRoutes } from "@powerduck/openapi-mcp-server";
-import express from "express";
+## MCP Extensions
 
-// Build a server with custom spec and context providers
-const server = buildMcpServer({
-  specProvider: async () => spec,
-  contextProvider: async () => ({ baseUrl: "https://api.example.com" }),
-});
+Control how operations are exposed to MCP clients using OpenAPI extensions:
 
-// STDIO transport
-await startStdioServer(server);
+### `x-mcp-tool`
 
-// HTTP/SSE transport
-const app = express();
-attachSseRoutes(app, server, { path: "/mcp" });
-app.listen(3000);
+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"
+        }
+      }
+    }
+  }
+}
 ```
 
-#### Execute Tool Calls
+### `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}}" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
 
-```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" },
-});
+### `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"
+        }
+      }
+    }
+  }
+}
 ```
 
-#### Spec Utility Functions
+### `x-mcp-ignore`
 
-```typescript
-import {
-  iterateOperations,
-  findOperationById,
-  findDuplicateOperationIds,
-  assertUniqueOperationIds,
-  extractPathTemplateVariables,
-  synthesizeOperationId,
-  ensureUniqueName,
-  collectOperationParameters,
-  effectiveStyle,
-  effectiveExplode,
-} from "@powerduck/openapi-mcp-server";
-
-// Iterate all operations
-for (const op of iterateOperations(spec)) {
-  console.log(op.method, op.path, op.operation?.operationId);
+Exclude an operation from MCP entirely:
+
+```json
+{
+  "paths": {
+    "/internal/debug": {
+      "get": {
+        "x-mcp-ignore": true
+      }
+    }
+  }
 }
+```
 
-// Find operation by ID
-const operation = findOperationById(spec, "getUser");
+---
 
-// Check for duplicate operation IDs
-const duplicates = findDuplicateOperationIds(spec);
+## Programmatic API
 
-// Extract path variables
-const vars = extractPathTemplateVariables("/users/{userId}/posts/{postId}");
-// => ["userId", "postId"]
-```
+### `loadOpenApiSpec(input)`
 
-#### Build HTTP Requests
+Loads an OpenAPI spec from a file path, URL, or parsed object. Returns the parsed document.
 
 ```typescript
-import { buildRequest } from "@powerduck/openapi-mcp-server";
+const spec = await loadOpenApiSpec("./openapi.json");
+const specFromUrl = await loadOpenApiSpec("https://api.example.com/openapi.json");
+const specFromObject = await loadOpenApiSpec({ openapi: "3.2.0", ... });
+```
 
-const request = buildRequest({
-  operation,
-  pathItem,
-  arguments: { id: "123", include: ["profile", "posts"] },
-  baseUrl: "https://api.example.com",
-});
+### `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`.
 
-// request contains: method, url, headers, body
+### `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",
+}));
 ```
 
-#### Admin Server and Auth
+### API key (HTTP)
 
 ```typescript
-import { startAdminServer, createAuthMiddleware } from "@powerduck/openapi-mcp-server";
+app.use("/mcp", createAuthMiddleware({
+  type: "apikey",
+  token: "your-api-key",
+  headerName: "x-api-key",
+}));
+```
 
-const app = await startAdminServer({
-  port: 3000,
-  host: "127.0.0.1",
-  apiKey: "your-admin-key",
-});
+### Custom auth
 
-// Or use auth middleware in your own Express app
-import express from "express";
-const myApp = express();
-myApp.use("/admin", createAuthMiddleware({ apiKey: "secret" }));
+Use the `routeGuard` parameter of `attachSseRoutes`:
+
+```typescript
+attachSseRoutes(
+  app,
+  specProvider,
+  contextProvider,
+  (req) => {
+    return verifyJwt(req.headers.authorization);
+  },
+);
 ```
 
-## Project Structure
+---
+
+## 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"],
+  }),
+);
 ```
-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
+
+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",
+});
 ```
 
-## Web UI
+### Endpoints
 
-The admin UI supports:
+| 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 |
 
-- 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
+---
 
-## Testing
+## MCP Client Configuration (Claude Desktop)
 
-```bash
-# Run all tests
-npm test
+Add to your `claude_desktop_config.json`:
 
-# Run tests in watch mode
-npm run test:watch
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "command": "npx",
+      "args": ["@powerduck/openapi-mcp-server", "serve", "--spec", "/path/to/openapi.json"]
+    }
+  }
+}
+```
+
+For HTTP transport:
 
-# Run tests with coverage
-npm run test:coverage
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
 ```
 
-Test coverage includes:
+---
 
-- **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
+## Development
 
-## Production Notes
+```bash
+# Install dependencies
+npm install
 
-This version is production-oriented. For full SaaS deployment, consider adding:
+# Type check
+npm run typecheck
 
-- Tenant isolation
-- Database-backed project registry
-- Rate limits
-- Audit logs
-- Role-based access control (RBAC)
-- Secure secret storage
-- Upstream host allowlists
+# Build (ESM + CJS + type declarations)
+npm run build
 
-## Dependencies
+# Run tests
+npm test
 
-- `@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
+# Watch mode
+npx vitest watch
+```
 
-## License
+---
+
+## Related Packages
 
-MIT © Powerduck limited
+- [`@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
 
-## Important Implementation Policy
+---
+
+## License
 
-All source comments are written in American English. No Chinese characters are permitted in the codebase.
+MIT

package/package.json

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