@powerduck/openapi-mcp-server 1.0.1 → 1.1.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,37 +1,31 @@
-A production-oriented TypeScript library and runtime that converts OpenAPI documents into MCP services.
+# @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.
 
 ## Features
 
-- 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
+- **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
 
 ```bash
-npm i @powerduck/openapi-mcp-server
-```
-
-## Start web runtime
-
-```bash
-npm run start -- serve --port 3000 --host 127.0.0.1
+npm install @powerduck/openapi-mcp-server
 ```
 
-## Start STDIO runtime
-
-```bash
-node dist/cli.js serve --transport stdio --spec ./openapi.yaml
-```
+## Quick Start
 
-## CLI usage
+### CLI Usage
 
-### Web mode
+#### Web Mode (with Admin UI)
 
 ```bash
 openapi-mcp serve \
@@ -41,7 +35,7 @@ openapi-mcp serve \
   --api-key your-admin-key
 ```
 
-### STDIO mode
+#### STDIO Mode
 
 ```bash
 openapi-mcp serve \
@@ -50,43 +44,235 @@ openapi-mcp serve \
   --base-url https://api.example.com
 ```
 
-## Production notes
+### Programmatic API
+
+#### 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
+);
+```
+
+#### Generate MCP Tools
+
+```typescript
+import { generateTools, buildBindingIndex } 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
+```
+
+#### Generate Prompts and Resources
+
+```typescript
+import { generatePrompts, generateResources } from "@powerduck/openapi-mcp-server";
+
+const prompts = generatePrompts(spec);
+const resources = generateResources(spec);
+```
+
+#### Build an MCP Server
+
+```typescript
+import { buildMcpServer, startStdioServer, attachSseRoutes } from "@powerduck/openapi-mcp-server";
+import express from "express";
+
+// Build a server with custom spec and context providers
+const server = buildMcpServer({
+  specProvider: async () => spec,
+  contextProvider: async () => ({ baseUrl: "https://api.example.com" }),
+});
+
+// STDIO transport
+await startStdioServer(server);
+
+// HTTP/SSE transport
+const app = express();
+attachSseRoutes(app, server, { path: "/mcp" });
+app.listen(3000);
+```
+
+#### Execute Tool Calls
+
+```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
+
+```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);
+}
+
+// Find operation by ID
+const operation = findOperationById(spec, "getUser");
+
+// Check for duplicate operation IDs
+const duplicates = findDuplicateOperationIds(spec);
+
+// Extract path variables
+const vars = extractPathTemplateVariables("/users/{userId}/posts/{postId}");
+// => ["userId", "postId"]
+```
+
+#### Build HTTP Requests
 
-This version is production-oriented, but you should still add the following for SaaS deployment:
+```typescript
+import { buildRequest } from "@powerduck/openapi-mcp-server";
 
-- 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
+const request = buildRequest({
+  operation,
+  pathItem,
+  arguments: { id: "123", include: ["profile", "posts"] },
+  baseUrl: "https://api.example.com",
+});
 
-## Project structure
+// request contains: method, url, headers, body
+```
+
+#### Admin Server and Auth
+
+```typescript
+import { startAdminServer, createAuthMiddleware } from "@powerduck/openapi-mcp-server";
+
+const app = await startAdminServer({
+  port: 3000,
+  host: "127.0.0.1",
+  apiKey: "your-admin-key",
+});
 
-- `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
+// Or use auth middleware in your own Express app
+import express from "express";
+const myApp = express();
+myApp.use("/admin", createAuthMiddleware({ apiKey: "secret" }));
+```
+
+## Project Structure
+
+```
+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
+```
 
 ## Web UI
 
-The UI supports:
+The admin UI supports:
 
-- upload and paste OpenAPI documents
-- view tools, prompts, and resources
-- inspect runtime services
-- stop services
-- basic MCP debugging hints
+- 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 tooltip guidance
+- STDIO configuration guidance
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+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
+
+## Production Notes
+
+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
+
+## Dependencies
+
+- `@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
+## Important Implementation Policy
 
-All source comments are written in American English.
+All source comments are written in American English. No Chinese characters are permitted in the codebase.

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;
 }