npm install @powerduck/openapi-mcp-server

openapi-mcp serve \
  --transport web \
  --port 3000 \
  --host 127.0.0.1 \
  --api-key your-admin-key

openapi-mcp serve \
  --transport stdio \
  --spec ./openapi.yaml \
  --base-url https://api.example.com

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

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

import { generatePrompts, generateResources } from "@powerduck/openapi-mcp-server";

const prompts = generatePrompts(spec);
const resources = generateResources(spec);

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

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" },
});

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"]

import { buildRequest } from "@powerduck/openapi-mcp-server";

const request = buildRequest({
  operation,
  pathItem,
  arguments: { id: "123", include: ["profile", "posts"] },
  baseUrl: "https://api.example.com",
});

// request contains: method, url, headers, body

import { startAdminServer, createAuthMiddleware } from "@powerduck/openapi-mcp-server";

const app = await startAdminServer({
  port: 3000,
  host: "127.0.0.1",
  apiKey: "your-admin-key",
});

// Or use auth middleware in your own Express app
import express from "express";
const myApp = express();
myApp.use("/admin", createAuthMiddleware({ apiKey: "secret" }));

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

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage