### Bash Project Setup

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/Developer-guide

Standard bash commands to clone the repository, navigate into the project directory, and install dependencies using npm.

```bash
git clone <repository>
cd mcp-openapi-server
npm install
```

--------------------------------

### Full Command Line Arguments Example

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/User-guide

Use this command to start the MCP server with all essential configuration options, including API base URL, OpenAPI spec location, custom headers, server name, version, transport, port, host, path, and abbreviation disabling.

```bash
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --name "my-mcp-server" \
  --server-version "1.0.0" \
  --transport http \
  --port 3000 \
  --host 127.0.0.1 \
  --path /mcp \
  --disable-abbreviation true
```

--------------------------------

### Install Dependencies

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/basic-library-usage/README.md

Run this command to install the necessary project dependencies.

```bash
npm install
```

--------------------------------

### Claude Desktop Configuration for AuthProvider Example

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/auth-provider-example/README.md

Example JSON configuration for Claude Desktop to run an authentication provider example server.

```json
{
  "mcpServers": {
    "my-auth-api": {
      "command": "node",
      "args": ["/path/to/auth-provider-example/dist/index.js"]
    }
  }
}
```

--------------------------------

### Build and Run the MCP Server

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/beatport-example/README.md

Builds the project and starts the MCP server. Assumes npm scripts 'build' and 'start' are configured.

```bash
npm run build
npm start
```

--------------------------------

### Basic Library Usage of OpenAPIServer

Source: https://context7.com/ivo-toby/mcp-openapi-server/llms.txt

Instantiate and start a custom MCP server programmatically using the OpenAPIServer class. This TypeScript example demonstrates basic configuration for stdio transport.

```typescript
import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"

const config = {
  name: "my-api-mcp-server",
  version: "1.0.0",
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  specInputMethod: "url" as const, // Options: "url", "file", "stdin", "inline"
  headers: {
    Authorization: "Bearer your-api-token",
    "X-API-Key": "your-api-key",
  },
  transportType: "stdio" as const, // Options: "stdio", "http"
  toolsMode: "all" as const, // Options: "all", "dynamic", "explicit"
}

const server = new OpenAPIServer(config)
const transport = new StdioServerTransport()
await server.start(transport)
```

--------------------------------

### Install and Run Published MCP Server

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/beatport-example/README.md

Installs and runs the Beatport MCP server using npx after it has been published to npm.

```bash
npx your-beatport-mcp-server
```

--------------------------------

### Run Server

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/basic-library-usage/README.md

Start the MCP server using this command after building the project.

```bash
npm start
```

--------------------------------

### CLI Usage Example

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/README.md

Demonstrates how to use the openapi-mcp-server as a CLI tool with command-line arguments for API configuration.

```bash
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token"
```

--------------------------------

### Install MCP TypeScript SDK

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/mcp-examples.md

Install the SDK using npm. This command is used to add the necessary packages to your project.

```bash
npm install @modelcontextprotocol/sdk
```

--------------------------------

### Basic Library Initialization

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/README.md

Shows the minimal setup for creating an OpenAPIServer instance using the library, including static header authentication.

```typescript
import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"

const server = new OpenAPIServer({
  name: "my-api-server",
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  headers: { Authorization: "Bearer token" },
})
```

--------------------------------

### Prompts File Format Example

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Example JSON structure for defining prompts, including name, title, description, arguments, and template.

```json
[
  {
    "name": "api_request",
    "title": "API Request Helper",
    "description": "Helps generate API request templates",
    "arguments": [
      { "name": "endpoint", "description": "API endpoint path", "required": true },
      { "name": "method", "description": "HTTP method", "required": false }
    ],
    "template": "Create a {{method}} request to {{endpoint}} with proper parameters."
  }
]
```

--------------------------------

### Server Capabilities Advertisement

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Example JSON output showing the server's advertised capabilities, including tools, prompts, and resources.

```json
{
  "capabilities": {
    "tools": { "list": true, "execute": true },
    "prompts": {},
    "resources": {}
  }
}
```

--------------------------------

### Run Container Interactively for MCP Client Integration

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/verify-manual.md

Starts the container in interactive mode, preparing it to communicate with an MCP client via stdio. This setup allows the server to read the OpenAPI spec from stdin, register tools, and handle MCP requests.

```bash
# Run the container interactively
docker run --rm -i mcp-openapi-test
```

--------------------------------

### Resources File Format Example

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Example JSON structure for defining MCP resources, including URI, name, title, description, mimeType, and text content.

```json
[
  {
    "uri": "docs://api/overview",
    "name": "api-overview",
    "title": "API Overview",
    "description": "Overview of the API",
    "mimeType": "text/markdown",
    "text": "# API Overview\n\nThis API provides..."
  }
]
```

--------------------------------

### Install Dependencies for Response Validation

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/docs/plans/response-validation.md

Install the Zod library for schema validation and TypeScript types for Node.js if not already present.

```bash
npm install zod
npm install --save-dev @types/node  # if not already present
```

--------------------------------

### Create an MCP Server

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/mcp-examples.md

Example of creating an MCP server using the SDK. It sets up request handlers for listing and reading resources, and connects via stdio transport.

```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "example-server",
  version: "1.0.0",
}, {
  capabilities: {
    resources: {}
  }
});

server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return {
    resources: [
      {
        uri: "file:///example.txt",
        name: "Example Resource",
      },
    ],
  };
});

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  if (request.params.uri === "file:///example.txt") {
    return {
      contents: [
        {
          uri: "file:///example.txt",
          mimeType: "text/plain",
          text: "This is the content of the example resource.",
        },
      ],
    };
  } else {
    throw new Error("Resource not found");
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);
```

--------------------------------

### Create an MCP Client

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/mcp-examples.md

Example of creating an MCP client using the SDK. It demonstrates connecting to a server via stdio transport and making requests to list resources and read resource content.

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "path/to/server",
});

const client = new Client({
  name: "example-client",
  version: "1.0.0",
}, {
  capabilities: {}
});

await client.connect(transport);

// List available resources
const resources = await client.request(
  { method: "resources/list" },
  ListResourcesResultSchema
);

// Read a specific resource
const resourceContent = await client.request(
  {
    method: "resources/read",
    params: {
      uri: "file:///example.txt"
    }
  },
  ReadResourceResultSchema
);
```

--------------------------------

### Basic Static Headers Example

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/docs/plans/AUTHPROVIDER_IMPLEMENTATION.md

Demonstrates the traditional way of configuring static authorization headers for the OpenAPIServer. This configuration is used when dynamic authentication is not required.

```typescript
const server = new OpenAPIServer({
  // ... config
  headers: { 'Authorization': 'Bearer token' }
})
```

--------------------------------

### Test Container Startup

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/verify-manual.md

Runs the container for a short duration to observe initialization messages and tool registration. This verifies the server starts correctly and registers all defined API endpoints.

```bash
# Run for a few seconds to see initialization
timeout 5s docker run --rm mcp-openapi-test
```

--------------------------------

### Migrate from Static Headers to AuthProvider

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/docs/auth-provider-guide.md

This example shows the 'before' and 'after' states when migrating from static Authorization headers to using an AuthProvider for more dynamic authentication.

```typescript
const config = {
  // ... other config
  headers: { 'Authorization': 'Bearer token' }
}
```

```typescript
const authProvider = new MyAuthProvider()
authProvider.setToken('token')

const config = {
  // ... other config
  authProvider: authProvider
  // Remove the headers property
}
```

--------------------------------

### Watch Source Files and Rebuild

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

This command starts a development server that watches for changes in source files and automatically rebuilds the project.

```bash
npm run dev
```

--------------------------------

### Verify Example Spec is Embedded

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/verify-manual.md

Checks if the example OpenAPI specification file is present within the container by displaying the first few lines. This confirms that the spec is correctly packaged.

```bash
# Check that the example spec file is present
docker run --rm mcp-openapi-test head -5 /app/example-spec.json
```

--------------------------------

### GET Request with Query Parameters

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/Library-usage

Demonstrates how tool call parameters with query parameters are translated into an HTTP GET request. Arrays are converted to comma-separated strings.

```javascript
// This GET request
{ "limit": 10, "tags": ["javascript", "typescript"] }

// Becomes this HTTP request
GET /api/search?limit=10&tags=javascript,typescript
```

--------------------------------

### Combine Tools, Prompts, and Resources with HTTP Transport

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Configure the server to load OpenAPI spec, prompts, and resources from local files, and use HTTP transport on port 3000. This example combines multiple configuration options.

```bash
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts ./prompts.json \
  --mcp-resources ./resources.json \
  --transport http \
  --port 3000
```

--------------------------------

### Load Specific GET /users Endpoint Tool

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/User-guide

Use this command to load only the GET /users endpoint tool when using the 'all' mode with filtering. Ensure the API base URL and OpenAPI spec URL are correctly provided.

```bash
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tool GET-users
```

--------------------------------

### Run MCP OpenAPI Server with Basic Configuration

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Use this command to start the MCP OpenAPI server with essential configurations like API base URL and OpenAPI specification path. It also shows how to set custom headers and client TLS credentials.

```bash
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --client-cert ./certs/client.pem \
  --client-key ./certs/client-key.pem \
  --name "my-mcp-server" \
  --server-version "1.0.0" \
  --transport http \
  --port 3000 \
  --host 127.0.0.1 \
  --path /mcp \
  --disable-abbreviation true \
  --verbose false
```

--------------------------------

### Load OpenAPI Specification from Standard Input (File)

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

This example shows how to pipe the content of an OpenAPI specification file to the server via standard input. This is useful in containerized environments or for scripting.

```bash
cat openapi.json | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin
```

--------------------------------

### Package Distribution Configuration

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/README.md

Example JSON configuration for packaging an MCP server as a distributable Node.js package, defining the package name and entry point for the CLI.

```json
{
  "name": "my-api-mcp-server",
  "bin": {
    "my-api-mcp-server": "dist/index.js"
  }
}
```

--------------------------------

### Basic StreamableHttpServerTransport Usage

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/docs/server-parameter-guide.md

Instantiates and starts the OpenAPIServer with a new StreamableHttpServerTransport. Ensure necessary imports are present.

```typescript
import { OpenAPIServer, StreamableHttpServerTransport } from '@ivotoby/openapi-mcp-server';

const config = {
  name: "my-api-server",
  version: "1.0.0",
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  specInputMethod: "url" as const,
  transportType: "http" as const,
  httpPort: 3000,
  httpHost: "127.0.0.1",
  endpointPath: "/mcp",
  toolsMode: "all" as const,
};

const server = new OpenAPIServer(config);
const transport = new StreamableHttpServerTransport(3000, '127.0.0.1', '/mcp');

await server.start(transport);
```

--------------------------------

### Initialize Handlers for Prompt Getting

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/openspec/changes/add-custom-primitives/design.md

Sets up handlers for retrieving prompts. This involves looking up the prompt by name in the customPrompts map and executing its handler after validating arguments.

```typescript
GetPromptRequestSchema → execute prompt handler
```

--------------------------------

### Dynamic AuthProvider Implementation Example

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/docs/plans/AUTHPROVIDER_IMPLEMENTATION.md

Shows how to implement a custom AuthProvider for dynamic authentication. This includes logic for checking token expiration, fetching new tokens, and handling authentication errors.

```typescript
class MyAuthProvider implements AuthProvider {
  async getAuthHeaders() {
    if (this.isTokenExpired()) {
      throw new Error('Token expired. Please provide a new token.')
    }
    return { 'Authorization': `Bearer ${this.token}` }
  }
  
  async handleAuthError(error) {
    // Try to refresh or prompt for new token
    return shouldRetry
  }
}

const server = new OpenAPIServer({
  // ... config
  authProvider: new MyAuthProvider()
})
```

--------------------------------

### Basic MCP Server Initialization

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/Library-usage

Initialize and start a basic MCP OpenAPI server using the `OpenAPIServer` class and `StdioServerTransport`. Ensure the configuration object includes necessary details like API URL and OpenAPI spec.

```typescript
import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"

const config = {
  name: "my-api-server",
  version: "1.0.0",
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  specInputMethod: "url" as const,
  headers: {
    Authorization: "Bearer your-token",
    "X-API-Key": "your-api-key",
  },
  transportType: "stdio" as const,
  toolsMode: "all" as const, // Options: "all", "dynamic", "explicit"
}

const server = new OpenAPIServer(config)
const transport = new StdioServerTransport()
await server.start(transport)
```

--------------------------------

### Load OpenAPI Specification from Standard Input (curl)

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

This example demonstrates piping the output of a curl command (fetching an OpenAPI spec from a URL) to the server via standard input. This is useful for dynamic spec loading.

```bash
curl -s https://api.example.com/openapi.json | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin
```

--------------------------------

### Tool ID Path Conversion Examples

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/Developer-guide

Shows how original OpenAPI paths are converted into Tool IDs using double underscores for path segment separation, preserving hyphens within segments.

```plaintext
Original Path              | Tool ID                          | Parsed Back                
| -------------------------- | -------------------------------- | -------------------------- 
| /users                   | GET::users                     | /users                   
| /api/v1/users            | GET::api__v1__users            | /api/v1/users            
| /api/resource-name/items | GET::api__resource-name__items | /api/resource-name/items 
| /user-profile/data       | GET::user-profile__data        | /user-profile/data        
| /a_b/c-d/e_f-g           | GET::a_b__c-d__e_f-g           | /a_b/c-d/e_f-g           
```

--------------------------------

### Basic Configuration for Response Validation

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/docs/plans/response-validation.md

Minimal setup to enable response validation with a warning level. Use this for a basic opt-in to validation.

```typescript
// Minimal setup - validation enabled with warnings
{
  responseValidation: "warn"
}
```

--------------------------------

### Tool ID Format Examples

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/Developer-guide

Illustrates the format of Tool IDs, which uniquely identify API endpoints using METHOD::pathPart, and demonstrates path separation using double underscores.

```plaintext
GET::users → GET /users
POST::api__v1__users → POST /api/v1/users
GET::api__resource-name__items → GET /api/resource-name/items
```

--------------------------------

### Run MCP Server with HTTP Transport

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/User-guide

Launch the MCP OpenAPI server using npx for HTTP transport. Specify API details, transport type, and port. This command starts the server for HTTP clients.

```bash
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123" \
  --transport http \
  --port 3000
```

--------------------------------

### Verify Security Header Blocking with API Calls

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/SECURITY-FIXES.md

These JavaScript examples demonstrate how the API call function behaves when attempting to set system-controlled headers versus custom headers. It shows that system headers throw an error, while custom headers are accepted.

```javascript
// Host header now blocked:
executeApiCall(toolId, { Host: "evil.com" })
// Throws: "Cannot set system-controlled header "Host""

// Content-Length now blocked:
executeApiCall(toolId, { "Content-Length": "999" })
// Throws: "Cannot set system-controlled header "Content-Length""

// Custom headers still work:
executeApiCall(toolId, { "X-Custom-Header": "value" })
// Success: Header added to request
```

--------------------------------

### Verify Startup Script

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/verify-manual.md

Confirms that the startup script '/app/start-server.sh' exists and has execute permissions within the container. This ensures the server can be launched properly.

```bash
# Check that the startup script exists and is executable
docker run --rm mcp-openapi-test ls -la /app/start-server.sh
```

--------------------------------

### Example ADDED Requirement: OTP Email Notification

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/openspec/AGENTS.md

Example of an ADDED requirement for OTP Email Notification.

```markdown
## ADDED Requirements
### Requirement: OTP Email Notification
...
```

--------------------------------

### Example ADDED Requirement: Two-Factor Authentication

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/openspec/AGENTS.md

Example of an ADDED requirement for Two-Factor Authentication, including a scenario.

```markdown
## ADDED Requirements
### Requirement: Two-Factor Authentication
...
```

--------------------------------

### Build Project

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/basic-library-usage/README.md

Execute this command to build the project after making configuration changes.

```bash
npm run build
```

--------------------------------

### Health Check Response Example

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Example JSON response from the /health endpoint, indicating server status, active sessions, and uptime.

```json
{
  "status": "healthy",
  "activeSessions": 2,
  "uptime": 3600
}
```

--------------------------------

### Scaffold a New Change

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/openspec/AGENTS.md

Create a new change directory and initialize proposal and tasks files.

```bash
CHANGE=add-two-factor-auth
mkdir -p openspec/changes/$CHANGE/{specs/auth}
printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md
```

--------------------------------

### Initialize and Update OpenSpec Project

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/openspec/AGENTS.md

Initialize a new OpenSpec project with `openspec init [path]` or update existing instruction files with `openspec update [path]`.

```bash
openspec init [path]
```

```bash
openspec update [path]
```

--------------------------------

### List All Specs and Changes

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/openspec/AGENTS.md

Explore the current state of specifications and changes using list commands.

```bash
openspec spec list --long
```

```bash
openspec list
```

--------------------------------

### Example of RENAMED Requirement

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/openspec/AGENTS.md

Illustrates how to document a renamed requirement in the 'RENAMED Requirements' section.

```markdown
## RENAMED Requirements
- FROM: `### Requirement: Login`
- TO: `### Requirement: User Authentication`
```

--------------------------------

### Build and Test Commands

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/CLAUDE.md

Standard npm scripts for building the project and running tests. Use `npm test -- <file>` to target specific test files.

```bash
npm run build           # Build TypeScript using esbuild
npm test                # Run all tests with Vitest
npm test -- api-client.test.ts   # Run specific test file
npm run test:watch      # Run tests in watch mode
npm run test:coverage   # Generate coverage report
```

--------------------------------

### Run Inspector with Auto-Reload

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Starts the development environment with the inspector enabled and configured for auto-reloading on code changes.

```bash
npm run inspect-watch
```

--------------------------------

### OpenAPI Query Parameter Schema

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/Library-usage

Example of an OpenAPI schema definition for a query parameter named 'limit' with an integer type.

```json
{
  "name": "limit",
  "in": "query",
  "schema": { "type": "integer" },
  "required": false
}
```

--------------------------------

### Malicious YAML Rejection Example

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/SECURITY-FIXES.md

Demonstrates how malicious YAML containing a JavaScript function is rejected by the OpenAPI server, preventing execution.

```yaml
openapi: "3.0.0"
info:
  title: !!js/function 'function() { require("child_process").exec("rm -rf /"); }'
# Result: Parsing error, no execution
```

--------------------------------

### Incorrect Scenario Formatting in Markdown

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/openspec/AGENTS.md

Highlights incorrect markdown formatting for scenarios, showing examples that should be avoided to maintain specification clarity.

```markdown
- **Scenario: User login**  ❌
**Scenario**: User login     ❌
### Scenario: User login      ❌
```

--------------------------------

### Full-text Search with Ripgrep

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/openspec/AGENTS.md

Use `rg` (ripgrep) for full-text search within OpenSpec specs, for example, to find requirements or scenarios.

```bash
rg -n "Requirement:|Scenario:" openspec/specs
```

--------------------------------

### Package and Publish the MCP Server

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/beatport-example/README.md

Steps to package the Beatport MCP server as an npm package and publish it. Requires updating package.json.

```bash
npm run build
npm publish
```

--------------------------------

### Dynamically Adding Prompts and Resources to MCP Server

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Illustrates how to add prompts and resources to an existing `OpenAPIServer` instance after its creation. This allows for dynamic updates to server capabilities without restarting.

```typescript
const server = new OpenAPIServer(config)

// Add prompts dynamically
const promptsManager = server.getPromptsManager()
if (promptsManager) {
  promptsManager.addPrompt({
    name: "debug_error",
    title: "Error Debugger",
    template: "Debug this API error: {{error_message}}",
  })
}

// Add resources dynamically
const resourcesManager = server.getResourcesManager()
if (resourcesManager) {
  resourcesManager.addResource({
    uri: "docs://changelog",
    name: "changelog",
    title: "API Changelog",
    mimeType: "text/markdown",
    text: "# Changelog\n\n## v1.0.0\n- Initial release",
  })
}
```

--------------------------------

### Static Authentication Configuration

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/CLAUDE.md

Example of configuring static authentication headers for API requests. This approach is backward compatible and simpler for fixed credentials.

```typescript
const config = { headers: { Authorization: "Bearer token" } }
// Creates StaticAuthProvider internally
```

--------------------------------

### Custom BeatportAuthProvider Implementation

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/auth-provider-example/README.md

Extends ManualTokenAuthProvider to provide custom error handling for Beatport authentication, guiding users on how to obtain a new token.

```typescript
class BeatportAuthProvider extends ManualTokenAuthProvider {
  constructor() {
    super("Beatport")
  }

  async handleAuthError(error: AxiosError): Promise<boolean> {
    throw new Error(
      "Beatport authentication failed. To get a new token:\n" +
        "1. Go to https://www.beatport.com\n" +
        "2. Log in to your account\n" +
        "3. Open browser dev tools (F12)\n" +
        "4. Go to Network tab\n" +
        "5. Make any API request\n" +
        "6. Copy the Authorization header\n" +
        "7. Update your token using updateToken()",
    )
  }
}
```

--------------------------------

### Kubernetes Liveness Probe Configuration

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Example Kubernetes liveness probe configuration to monitor the health of the MCP server. Adjust path and port as needed.

```yaml
livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 3
  periodSeconds: 10
```

--------------------------------

### Custom AuthProvider Error Handling

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/examples/README.md

Provides an example implementation of the `handleAuthError` method within a custom AuthProvider to manage authentication errors, such as expired tokens.

```typescript
class MyAuthProvider implements AuthProvider {
  async handleAuthError(error: AxiosError): Promise<boolean> {
    if (error.response?.status === 401) {
      // Provide clear instructions
      throw new Error("Token expired. Please...")
    }
    return false
  }
}
```

--------------------------------

### Run All Tests

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/docs/developer-guide.md

Execute all unit and integration tests defined in the project.

```bash
npm test
```

--------------------------------

### Tool Call with Mixed Parameter Types

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/Library-usage

Shows how tool call parameters, including path and query parameters, are mapped to an HTTP GET request.

```javascript
// Tool call parameters
{ "userId": "123", "include": "posts", "format": "json" }

// Results in HTTP request
GET /users/123/posts?include=posts&format=json
```

--------------------------------

### Configuring Prompts and Resources in MCP Server

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Shows how to define reusable prompts and static resources within the MCP server configuration. Prompts can have arguments and templates, while resources can contain static content like markdown.

```typescript
import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"

const config = {
  name: "my-api-server",
  version: "1.0.0",
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  specInputMethod: "url" as const,
  transportType: "stdio" as const,
  toolsMode: "all" as const,

  // Define prompts with argument templates
  prompts: [
    {
      name: "api_request",
      title: "API Request Helper",
      description: "Helps generate API request templates",
      arguments: [
        { name: "endpoint", description: "API endpoint path", required: true },
        { name: "method", description: "HTTP method", required: false },
      ],
      template: "Create a {{method}} request to {{endpoint}} with proper parameters.",
    },
  ],

  // Define resources with static content
  resources: [
    {
      uri: "docs://api/overview",
      name: "api-overview",
      title: "API Overview",
      description: "Overview of the API capabilities",
      mimeType: "text/markdown",
      text: "# API Overview\n\nThis API provides...",
    },
  ],
}

const server = new OpenAPIServer(config)
```

--------------------------------

### Run All Tests

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/Developer-guide

Execute all unit and integration tests in the project. Use the --watch flag for continuous testing during development.

```bash
npm test
```

```bash
npm test -- --watch
```

--------------------------------

### Docker Healthcheck Configuration

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Example Docker healthcheck command to verify the MCP server's health. This command will fail if the health check endpoint is not reachable.

```dockerfile
HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:3000/health || exit 1
```

--------------------------------

### Verify Error Response Formats

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/SECURITY-FIXES.md

Examples of expected error response formats after sanitization. Demonstrates truncated large errors and standardized authentication error messages.

```javascript
// 401 error now returns:
// "API request failed: Request failed with status code 401 (401: [Authentication/Authorization error - details redacted for security])"

// Large error truncated:
// "API request failed: ... (500: {"error":"very long error message... [truncated])"
```

--------------------------------

### Conventional Commit Message

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/Developer-guide

Example of a commit message following the conventional commit format, including a type, scope, description, body, and footer for closing issues.

```text
feat: add support for OpenAPI 3.1 specifications

- Implement OpenAPI 3.1 parser compatibility
- Add tests for new specification features
- Update documentation with 3.1 examples

Closes #123
```

--------------------------------

### Update GitHub Actions setup-node action

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/SECURITY-FIXES.md

Update the `actions/setup-node` GitHub Action from v3 to v4 in the release workflow to benefit from the latest security patches and performance enhancements.

```yaml
      - uses: actions/setup-node@v4
```

--------------------------------

### Parameterized Test Cases

Source: https://github.com/ivo-toby/mcp-openapi-server/wiki/Developer-guide

Example of using parameterized tests with an array of test cases to cover various inputs and expected outputs for parsing tool IDs.

```typescript
const testCases = [
  { input: "GET::users", expected: { method: "GET", path: "/users" } },
  { input: "POST::api-v1-users", expected: { method: "POST", path: "/api/v1/users" } },
]

for (const { input, expected } of testCases) {
  const result = parseToolId(input)
  expect(result).toEqual(expected)
}
```

--------------------------------

### Initialize Handlers for Tool Calling

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/openspec/changes/add-custom-primitives/design.md

Sets up handlers for calling tools. The system first checks OpenAPI tools and then custom tools, ensuring existing functionality is preserved.

```typescript
CallToolRequestSchema → execute tool or custom handler
```

--------------------------------

### Load Prompts and Resources via CLI

Source: https://context7.com/ivo-toby/mcp-openapi-server/llms.txt

Load prompts and resources from external JSON/YAML files or URLs using CLI arguments. Inline JSON is also supported for quick configurations.

```bash
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts ./prompts.json \
  --mcp-resources ./resources.json
```

```bash
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts https://example.com/mcp/prompts.json \
  --mcp-resources https://example.com/mcp/resources.json
```

```bash
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts-inline '[{"name":"greet","template":"Hello {{name}}!"}]' \
  --mcp-resources-inline '[{"uri":"docs://readme","name":"readme","text":"# Welcome"}]'
```

--------------------------------

### Custom Prompt Get Flow

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/openspec/changes/add-custom-primitives/design.md

Outlines the data flow for retrieving custom prompts. The server looks up the prompt by name, validates arguments, and executes the handler.

```plaintext
1. Client sends `prompts/get` request
2. Server looks up name in `customPrompts` map
3. Validate required arguments present
4. Execute handler with arguments
5. Return PromptMessage array
```

--------------------------------

### Load Prompts from Local File

Source: https://github.com/ivo-toby/mcp-openapi-server/blob/main/README.md

Load reusable prompt templates from a local JSON file using the --prompts flag. Ensure the file path is correctly specified.

```bash
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts ./prompts.json
```