# OpenAPI MCP Server (JavaScript)

A pure JavaScript implementation of a Model Context Protocol (MCP) server that transforms OpenAPI 3.x specifications into MCP tools, enabling Large Language Models (LLMs) to interact with REST APIs through the standardized MCP protocol.

## Features

- **Pure JavaScript**: Built with Node.js and ES modules
- **OpenAPI 3.x Support**: Automatically converts OpenAPI specifications into MCP tools
- **Bearer Token Authentication**: Supports bearer token authentication for API requests
- **All HTTP Methods**: Supports GET, POST, PUT, DELETE, PATCH, OPTIONS, and HEAD
- **Configurable Base URL**: Accept custom API base URLs
- **Parameter Validation**: Validates tool parameters against OpenAPI schemas
- **Error Handling**: Comprehensive error handling and reporting
- **CLI Interface**: Easy-to-use command-line interface

## Installation

```bash
npm install
```

## Usage

### Quick Start

1. **Validate your OpenAPI specification:**
```bash
node src/index.js validate -s UserQueueList.json
```

2. **Start the MCP server:**
```bash
node src/index.js serve -s UserQueueList.json -b https://api.example.com -t your-bearer-token
```

### Command Line Options

#### `serve` - Start the MCP server
```bash
node src/index.js serve [options]

Options:
  -s, --spec <path>       Path to OpenAPI specification file (required)
  -b, --base-url <url>    Base URL for API requests
  -t, --token <token>     Bearer token for authentication
  --timeout <ms>          Request timeout in milliseconds (default: 30000)
  --transport <type>      Transport type (stdio or http, default: stdio)
  --http-port <port>      HTTP server port (when using http transport, default: 3000)
  --http-host <host>      HTTP server host (when using http transport, default: localhost)
```

#### `validate` - Validate OpenAPI specification
```bash
node src/index.js validate -s <path-to-spec>
```

#### `info` - Show server information
```bash
node src/index.js info
```

### Environment Variables

You can use environment variables instead of command-line arguments:

```bash
export OPENAPI_BASE_URL=https://api.example.com
export OPENAPI_BEARER_TOKEN=your-bearer-token
node src/index.js serve -s UserQueueList.json

node src/index.js serve -s UserQueueList.json --transport=http --http-port=8020

```

## Configuration

### OpenAPI Specification Requirements

- Must be OpenAPI 3.x format
- JSON format (`.json` extension)
- Must contain at least one path/operation
- Bearer token authentication should be defined in security schemes

### Example OpenAPI Security Configuration

```json
{
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "bearer": []
    }
  ]
}
```

## Tool Generation

The server automatically converts OpenAPI operations into MCP tools:

### Tool Naming
1. Uses `operationId` if available
2. Falls back to operation `summary` (sanitized)
3. Last resort: `{method}_{path}` (sanitized)

### Parameter Mapping
- **Path parameters**: Required string parameters
- **Query parameters**: Optional parameters based on OpenAPI schema
- **Header parameters**: Prefixed with `header_`
- **Request body**: Object properties or `requestBody` parameter

### Example Tool
For the UserQueueList.json specification:

```javascript
// Tool: ListUsers (GET /domains/~/users/list)
{
  "name": "ListUsers",
  "description": "List Basic Info on Users in Domain",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

// Tool: ListCallqueues (GET /domains/~/callqueues/list)
{
  "name": "ListCallqueues", 
  "description": "Read Basic info on Call Queues in Domain",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}
```

## MCP Integration

### Using with Claude Desktop

#### Stdio Transport (Default)
Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "openapi-server": {
      "command": "node",
      "args": [
        "/path/to/your/project/src/index.js",
        "serve",
        "-s", "/path/to/UserQueueList.json",
        "-b", "https://your-api-domain.com",
        "-t", "your-bearer-token"
      ]
    }
  }
}
```

#### HTTP Transport
For HTTP transport, configure the server URL instead:

```json
{
  "mcpServers": {
    "openapi-server": {
      "url": "http://localhost:3000/message"
    }
  }
}
```

Then start the server separately:
```bash
node src/index.js serve -s UserQueueList.json --transport http --http-port 3000
```

### Tool Responses

The server returns structured JSON responses:

**Success Response:**
```json
{
  "status": 200,
  "statusText": "OK",
  "data": {
    // API response data
  }
}
```

**Error Response:**
```json
{
  "error": true,
  "status": 404,
  "statusText": "Not Found",
  "message": "Domain not found",
  "data": {
    "code": 404,
    "message": "Domain example does not exist"
  }
}
```

## Transport Protocols

### Stdio Transport
- **Default transport method**
- Uses standard input/output streams for communication
- Best for integration with Claude Desktop and other MCP clients
- Automatic process management

### HTTP Transport  
- Uses HTTP Server-Sent Events (SSE) for communication
- Allows remote connections and debugging
- Useful for development and testing
- Configurable host and port

## API Examples

Based on the UserQueueList.json specification:

### List Users
```javascript
// Tool call
{
  "name": "ListUsers",
  "arguments": {}
}

// Response: Array of user objects with basic information
```

### List Call Queues
```javascript
// Tool call  
{
  "name": "ListCallqueues",
  "arguments": {}
}

// Response: Array of call queue objects with configuration
```

## Development

### Project Structure
```
src/
├── index.js              # CLI entry point
├── server.js             # MCP server implementation
├── openapi-processor.js  # OpenAPI specification processor
├── http-client.js        # HTTP client for API requests
└── utils.js              # Utility functions
```

### Key Components

- **MCPServer**: Main MCP server class handling tool registration and execution
- **OpenAPIProcessor**: Parses OpenAPI specs and generates tool definitions
- **HttpClient**: Handles HTTP requests with authentication and error handling
- **CLI**: Command-line interface with validation and configuration options

## Error Handling

The server provides comprehensive error handling:

- **Validation Errors**: Parameter validation against OpenAPI schemas
- **HTTP Errors**: Proper handling of API error responses
- **Authentication Errors**: Clear messages for auth failures
- **Network Errors**: Timeout and connectivity error handling

## Security Considerations

- Bearer tokens are handled securely and not logged
- Request validation prevents injection attacks
- Error messages don't expose sensitive information
- HTTPS is recommended for all API communications

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Troubleshooting

### Common Issues

1. **"Tool not found" errors**: Check that your OpenAPI spec is valid and contains the expected operations
2. **Authentication failures**: Verify your bearer token is correct and has proper permissions  
3. **Network timeouts**: Increase timeout or check API endpoint availability
4. **Schema validation errors**: Ensure your OpenAPI spec follows 3.x standards

### Debug Mode

For detailed logging, you can modify the server to enable debug output:

```bash
# The server logs to stderr for MCP compatibility
node src/index.js serve -s UserQueueList.json -b https://api.example.com -t token 2>debug.log
```

### Validation

Always validate your OpenAPI specification before use:

```bash
node src/index.js validate -s UserQueueList.json
```

This will show:
- ✅ Validation status
- 📄 Specification details  
- 🔧 Available tools
- 🔐 Security schemes
- 🌐 Base URL information