# OpenAPI MCP Server

A Model Context Protocol (MCP) server for parsing OpenAPI 3.0 specifications and extracting API metadata. Provides 7 tools for spec management, endpoint discovery, and schema extraction - complementing code-first analysis when OpenAPI specifications are available.

[![npm version](https://img.shields.io/npm/v/@dilina0914/openapi-mcp.svg)](https://www.npmjs.com/package/@dilina0914/openapi-mcp)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)

## What's New in 1.4.0

### Documentation Alignment
- **Workflow Consistency**: Fully aligned with `sar-test-mcp` v1.4.0 and `http-capture-mcp` v1.4.0
- **Role Clarity**: Enhanced guidance on complementary role in sequential test generation workflow
- **Updated Examples**: All integration examples updated to v1.4.0

## What's New in 1.2.0 (Previous Release)

### Documentation & Alignment
- **Generic Examples**: All examples now use generic placeholders applicable across all IFS Cloud modules
- **Workflow Consistency**: Fully aligned with `sar-test-mcp` v1.2.0 and `http-capture-mcp` v1.2.0
- **Role Clarity**: Enhanced guidance on complementary role in code-first test generation

## What's New in 1.1.0 (Previous Release)

### Workflow Alignment
- Fully aligned with `sar-test-mcp` v1.1.0 and `http-capture-mcp` v1.1.0
- Integrated with enhanced self-learning system and Phase 0 workflow
- Consistent with 15-phase test generation workflow

### Role Clarification
- Complementary to code-first analysis from `sar-test-mcp`
- Provides API metadata when OpenAPI specs are available
- Useful for verifying entity schemas and endpoint structures
- Supports schema validation against projection definitions

### Documentation Updates
- Updated integration examples for v1.1.0 MCP configuration
- Enhanced IFS Cloud-specific use case guidance

## What's New in 9.0.0

### Alignment & Documentation

**✅ Complete System Alignment**
- Fully aligned with `sar-test-mcp` v9.0.0 and `http-capture-mcp` v9.0.0
- Consistent with updated workflow in SARDevAgent
- All three MCPs work seamlessly together in the 13-phase (updated to 15-phase in v12.0.0) test generation workflow

**📚 Documentation Updates**
- Updated integration examples to reflect current architecture
- Clarified role in code-first test generation approach
- Enhanced troubleshooting guide

## What's New in 8.0.0

### Documentation & Setup

**📚 Complete Documentation Overhaul**
- Comprehensive README with accurate feature descriptions
- Clear integration instructions for all platforms
- Detailed troubleshooting guide
- Complete tool reference with examples

**🎯 Purpose Clarification**
- Designed for OpenAPI 3.0 specification parsing
- Complements code-first approach in `sar-test-mcp`
- Provides API metadata when OpenAPI specs are available
- 7 focused tools for spec management, endpoint discovery, and schema extraction

### Features

**📖 OpenAPI Parsing**
- Load specs from local files or URLs
- Support for JSON and YAML formats
- Automatic `$ref` resolution
- Multi-spec management

**🔍 Endpoint Discovery**
- List all API endpoints with filtering
- Filter by tags, paths, or methods
- Search operations by query or entity
- Get complete operation details

**📊 Schema Extraction**
- Extract entity schemas with data types
- Identify required fields and constraints
- Include default values and examples
- Resolve nested references

### Use Cases

1. **API Discovery**: When OpenAPI specs are available for IFS Cloud services
2. **Schema Validation**: Verify entity structures and field types
3. **Endpoint Mapping**: Map service endpoints to test requirements
4. **Documentation**: Extract API documentation for test planning
5. **Complementary Analysis**: Use alongside code analysis from `sar-test-mcp`

### Integration

Works seamlessly with `sar-test-mcp` and `http-capture-mcp`:
- `sar-test-mcp` for code-first analysis (primary approach)
- `openapi-mcp` for API spec metadata (when available)
- `http-capture-mcp` for browser verification (when needed)

## Prerequisites

- Node.js v20.0.0 or higher
- npm or pnpm package manager
- OpenAPI 3.0 specification files (JSON or YAML)

## Package Information

This package is **fully bundled** - all internal dependencies are included.

| Property | Value |
|----------|-------|
| **Bundle Size** | ~35 KB |
| **Node.js** | ≥20.0.0 |
| **Module Type** | ESM |
| **TypeScript** | Included |

### Peer Dependencies

The following dependencies are required and must be installed separately (or will be auto-installed):

```bash
# Auto-installed when using npx
@modelcontextprotocol/sdk ^1.0.0
```

## Integration Options

Choose the integration method that works best for your workflow:

### Option 1: VS Code Integration

Integrate the MCP server into VS Code to use API discovery tools directly in your editor.

**Step 1: Create the MCP configuration folder**

In your project root directory, create a `.vscode` folder:

```bash
mkdir .vscode
```

**Step 2: Create the MCP configuration file**

Inside the `.vscode` folder, create a file named `mcp.json` with the following content:

```json
{
  "servers": {
    "openapi": {
      "command": "npx",
      "args": [
        "-y",
        "@dilina0914/openapi-mcp@1.4.0"
      ],
      "env": {
        "LOG_LEVEL": "info",
        "AUDIT_LOG_ENABLED": "true"
      }
    }
  }
}
```

**Step 3: Configure environment variables**

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `LOG_LEVEL` | Logging level (debug, info, warn, error) | No | `info` |
| `AUDIT_LOG_ENABLED` | Enable audit logging | No | `true` |
| `AUDIT_LOG_DIR` | Directory for audit logs | No | `./logs/audit` |

**Step 4: Restart VS Code**

Close and reopen VS Code to load the MCP server configuration.

### Option 2: Cursor IDE Integration

Cursor IDE has built-in support for MCP servers, making integration straightforward.

**Step 1: Open Cursor Settings**

1. Open Cursor IDE
2. Go to Settings (File > Preferences > Settings or Ctrl/Cmd + ,)
3. Search for "MCP" or navigate to the MCP configuration section

**Step 2: Add MCP Server Configuration**

In the MCP settings, add a new server with the following configuration:

```json
{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": [
        "-y",
        "@dilina0914/openapi-mcp@1.4.0"
      ],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

**Step 3: Save and Restart**

Save the configuration and restart Cursor IDE to activate the MCP server.

### Option 3: Claude Desktop Integration

Add to your Claude Desktop configuration file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@dilina0914/openapi-mcp@1.4.0"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

### Option 4: Local Development

Run the server directly for development or testing.

**Step 1: Install the package**

```bash
npm install @dilina0914/openapi-mcp
```

**Step 2: Configure environment variables**

Windows (PowerShell):
```powershell
$env:LOG_LEVEL = "info"
$env:AUDIT_LOG_ENABLED = "true"
```

Windows (Command Prompt):
```cmd
set LOG_LEVEL=info
set AUDIT_LOG_ENABLED=true
```

Linux/macOS:
```bash
export LOG_LEVEL="info"
export AUDIT_LOG_ENABLED="true"
```

**Step 3: Run the server**

```bash
npx @dilina0914/openapi-mcp
```

## Quick Troubleshooting

### Spec Not Found

**Error:** `Spec not found: <specId>. Use loadSpec first.`

**Solution:**
- Load the spec first using the `loadSpec` tool
- Verify the specId returned from `loadSpec`
- Specs are stored in memory and lost when server restarts

### Invalid OpenAPI Spec

**Error:** `Failed to parse OpenAPI spec`

**Solution:**
- Verify the file is valid JSON or YAML
- Ensure it's a valid OpenAPI 3.0 specification
- Check file path or URL accessibility

### Schema Not Found

**Error:** `Schema not found: <name>`

**Solution:**
- Use `listSchemas` to see available schemas
- Schema names are case-sensitive
- Verify the schema exists in the spec

### File Access Errors

**Error:** `ENOENT: no such file or directory`

**Solution:**
- Use absolute paths for local files
- Verify file permissions
- For URLs, check network connectivity

## What's Included

### MCP Tools (7 total)

#### Spec Management

| Tool | Description |
|------|-------------|
| `loadSpec` | Load an OpenAPI spec from file path or URL |
| `unloadSpec` | Unload a previously loaded spec from memory |

#### Endpoint Discovery

| Tool | Description |
|------|-------------|
| `listEndpoints` | List all API endpoints with filtering options |
| `getOperationDetails` | Get full operation details by ID or path/method |
| `searchOperations` | Search operations by query, tag, or entity name |

#### Schema Extraction

| Tool | Description |
|------|-------------|
| `listSchemas` | List all schemas/entities defined in the spec |
| `getEntitySchema` | Extract detailed entity schema with data types |

### Supported Features

| Feature | Description |
|---------|-------------|
| **OpenAPI 3.0** | Full support for OpenAPI 3.0 specifications |
| **JSON & YAML** | Parse both JSON and YAML spec formats |
| **File & URL** | Load specs from local files or remote URLs |
| **$ref Resolution** | Automatic resolution of schema references |
| **Multi-Spec** | Manage multiple specs simultaneously |

### Output Information

The MCP extracts and provides:

- API title, version, and description
- Endpoints with method, path, summary, and tags
- Operation parameters (path, query, header, cookie)
- Request body schemas with content types
- Response schemas for all status codes
- Entity schemas with properties, types, and constraints
- Required fields and default values
- Example values when available

## Tool Examples

### Load a Spec

```json
{
  "tool": "loadSpec",
  "arguments": {
    "source": "C:\\specs\\my-api.yaml",
    "specId": "my-api"
  }
}
```

**Response:**
```json
{
  "specId": "my-api",
  "title": "Cloud ERP API",
  "version": "1.0.0",
  "endpointCount": 245,
  "schemaCount": 89
}
```

### List Endpoints

```json
{
  "tool": "listEndpoints",
  "arguments": {
    "specId": "my-api",
    "tag": "CustomerOrder",
    "methods": ["GET", "POST"]
  }
}
```

**Response:**
```json
{
  "endpoints": [
    {
      "path": "/api/v1/customer-orders",
      "method": "GET",
      "summary": "List all customer orders",
      "tags": ["CustomerOrder"]
    },
    {
      "path": "/api/v1/customer-orders",
      "method": "POST",
      "summary": "Create a new customer order",
      "tags": ["CustomerOrder"]
    }
  ],
  "totalCount": 2
}
```

### Get Entity Schema

```json
{
  "tool": "getEntitySchema",
  "arguments": {
    "specId": "my-api",
    "schemaName": "CustomerOrder",
    "resolveRefs": true,
    "includeExamples": true
  }
}
```

**Response:**
```json
{
  "schema": {
    "name": "CustomerOrder",
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "Unique order identifier"
      },
      "customerId": {
        "type": "string",
        "required": true
      },
      "orderDate": {
        "type": "string",
        "format": "date-time"
      }
    },
    "required": ["customerId"]
  }
}
```

### Search Operations

```json
{
  "tool": "searchOperations",
  "arguments": {
    "specId": "my-api",
    "query": "create customer",
    "limit": 5
  }
}
```

### Get Operation Details

```json
{
  "tool": "getOperationDetails",
  "arguments": {
    "specId": "my-api",
    "path": "/api/v1/customer-orders",
    "method": "POST"
  }
}
```

### List All Schemas

```json
{
  "tool": "listSchemas",
  "arguments": {
    "specId": "my-api"
  }
}
```

**Response:**
```json
{
  "schemas": [
    { "name": "CustomerOrder", "type": "object", "description": "Customer order entity" },
    { "name": "OrderLine", "type": "object", "description": "Order line item" },
    { "name": "Customer", "type": "object", "description": "Customer entity" }
  ],
  "totalCount": 3
}
```

## Security Features

- **Audit Logging**: Complete audit trail of spec access
- **Input Validation**: File paths and parameters are validated
- **Memory Management**: Specs can be unloaded to free memory
- **No External Calls**: Specs are parsed locally (URLs are fetched once)

## License

MIT

## Links

- **GitHub Repository**: https://github.com/dilinaweerasinghe/integration-testing-mcp
- **npm Package**: https://www.npmjs.com/package/@dilina0914/openapi-mcp
- **Issues**: https://github.com/dilinaweerasinghe/integration-testing-mcp/issues

## Support

Open an issue on the GitHub repository for support.