# MCP REST Server

A Model Context Protocol (MCP) server that provides REST API client functionality with authentication support and Swagger documentation integration.

## Features

- **Multiple Authentication Methods**: Support for both token-based and login-based authentication
- **Swagger Integration**: Automatic endpoint discovery and documentation from OpenAPI/Swagger specs
- **Automatic Token Management**: Handles token refresh and re-authentication
- **Comprehensive HTTP Methods**: Support for GET, POST, PUT, DELETE, and PATCH requests
- **Error Handling**: Robust error handling with retry logic
- **MCP Compatible**: Fully compatible with the Model Context Protocol

## Installation

```bash
npm install
npm run build
```

## Development

```bash
npm run dev
```

## Configuration

The server supports two authentication methods:

### Token Authentication

```json
{
  "baseUrl": "https://api.example.com",
  "swaggerUrl": "https://api.example.com/swagger.json",
  "auth": {
    "type": "token",
    "token": "your-api-token-here"
  },
  "timeout": 30000,
  "retries": 3
}
```

### Login Authentication

```json
{
  "baseUrl": "https://api.example.com",
  "swaggerUrl": "https://api.example.com/swagger.json",
  "auth": {
    "type": "login",
    "username": "your-username",
    "password": "your-password",
    "loginEndpoint": "/auth/login",
    "tokenField": "access_token"
  },
  "timeout": 30000,
  "retries": 3
}
```

## Available Tools

### 1. configure_rest_client

Configure the REST client with authentication and API details.

**Parameters:**
- `baseUrl` (required): Base URL for the REST API
- `auth` (required): Authentication configuration (token or login)
- `swaggerUrl` (optional): URL to Swagger/OpenAPI documentation
- `timeout` (optional): Request timeout in milliseconds (default: 30000)
- `retries` (optional): Number of retries for failed requests (default: 3)

### 2. http_request

Make HTTP requests to the configured API.

**Parameters:**
- `method` (required): HTTP method (GET, POST, PUT, DELETE, PATCH)
- `path` (required): API endpoint path
- `params` (optional): Query parameters or request body parameters
- `body` (optional): Request body for POST, PUT, PATCH requests
- `headers` (optional): Additional headers

### 3. get_swagger_documentation

Get the complete list of available endpoints from Swagger documentation.

### 4. search_endpoints

Search for endpoints in the Swagger documentation.

**Parameters:**
- `query` (required): Search query to find matching endpoints

### 5. get_endpoint_info

Get detailed information about a specific endpoint.

**Parameters:**
- `path` (required): Endpoint path
- `method` (required): HTTP method

### 6. check_authentication

Check if the client is currently authenticated.

### 7. logout

Logout and clear authentication state.

## Usage Examples

### Basic Setup

1. Configure the client:
```json
{
  "baseUrl": "https://jsonplaceholder.typicode.com",
  "auth": {
    "type": "token",
    "token": "dummy-token"
  }
}
```

2. Make a GET request:
```json
{
  "method": "GET",
  "path": "/posts/1"
}
```

3. Make a POST request:
```json
{
  "method": "POST",
  "path": "/posts",
  "body": {
    "title": "New Post",
    "body": "Post content",
    "userId": 1
  }
}
```

### With Swagger Documentation

```json
{
  "baseUrl": "https://petstore.swagger.io/v2",
  "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
  "auth": {
    "type": "token",
    "token": "your-api-key"
  }
}
```

Then you can:
- Search endpoints: `search_endpoints` with query "pet"
- Get endpoint info: `get_endpoint_info` with path "/pet" and method "POST"
- View all documentation: `get_swagger_documentation`

## Authentication Flow

### Token Authentication
1. Token is stored and used immediately
2. Added to requests as `Authorization: Bearer <token>`
3. If 401 received, no automatic retry (token assumed invalid)

### Login Authentication
1. Makes login request to specified endpoint
2. Extracts token from response using `tokenField`
3. Stores token in memory
4. Adds token to subsequent requests
5. If 401 received, automatically re-authenticates and retries

## Error Handling

- **Network errors**: Automatic retry with exponential backoff
- **Authentication errors**: Automatic re-authentication for login-based auth
- **Validation errors**: Clear error messages with details
- **API errors**: HTTP status and error message forwarding

## Development

### Project Structure

```
src/
├── types.ts          # TypeScript type definitions
├── auth.ts           # Authentication manager
├── swagger.ts        # Swagger documentation parser
├── rest-client.ts    # REST client implementation
└── index.ts          # MCP server implementation
```

### Building

```bash
npm run build
```

### Running

```bash
npm start
```

## MCP Client Configuration

The MCP REST server now supports **automatic configuration** through multiple methods, eliminating the need to configure APIs manually for each project.

### Configuration Methods (in order of priority)

1. **Command Line Arguments** (highest priority)
2. **Environment Variables**
3. **Configuration File**
4. **Manual Configuration** (via MCP tools - lowest priority)

### Cursor Configuration

#### Option 1: Auto-Configuration with Environment Variables (Recommended)

```json
{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js"],
      "env": {
        "MCP_REST_BASE_URL": "https://api.github.com",
        "MCP_REST_AUTH_TYPE": "token",
        "MCP_REST_TOKEN": "your-github-token-here",
        "MCP_REST_SWAGGER_URL": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"
      }
    },
    "mcp-rest-petstore": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js"],
      "env": {
        "MCP_REST_BASE_URL": "https://petstore.swagger.io/v2",
        "MCP_REST_AUTH_TYPE": "token",
        "MCP_REST_TOKEN": "your-api-key",
        "MCP_REST_SWAGGER_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}
```

#### Option 2: Auto-Configuration with Config Files

```json
{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js", "--config", "/path/to/your/mcp-rest/examples/github-api.json"]
    },
    "mcp-rest-petstore": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js", "--config", "/path/to/your/mcp-rest/examples/petstore.json"]
    }
  }
}
```

#### Option 3: Auto-Configuration with Command Line Arguments

```json
{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-rest/dist/index.js",
        "--base-url", "https://api.github.com",
        "--auth-type", "token",
        "--token", "your-github-token-here",
        "--swagger-url", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"
      ]
    }
  }
}
```

### Claude Desktop Configuration

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

Use the same configuration options as Cursor above.

### Configuration Examples

The project includes several example configurations in the `examples/` directory:

- `examples/github-api.json` - GitHub API configuration
- `examples/petstore.json` - Swagger Petstore API configuration  
- `examples/jsonplaceholder.json` - JSONPlaceholder API configuration

### Environment Variables

| Variable | Description |
|----------|-------------|
| `MCP_REST_BASE_URL` | Base URL for the REST API (required) |
| `MCP_REST_AUTH_TYPE` | Authentication type: 'token' or 'login' (required) |
| `MCP_REST_TOKEN` | API token (required for token auth) |
| `MCP_REST_USERNAME` | Username (required for login auth) |
| `MCP_REST_PASSWORD` | Password (required for login auth) |
| `MCP_REST_LOGIN_ENDPOINT` | Login endpoint path (required for login auth) |
| `MCP_REST_TOKEN_FIELD` | Token field name in login response (default: access_token) |
| `MCP_REST_SWAGGER_URL` | URL to Swagger/OpenAPI documentation |
| `MCP_REST_TIMEOUT` | Request timeout in milliseconds (default: 30000) |
| `MCP_REST_RETRIES` | Number of retries for failed requests (default: 3) |
| `MCP_REST_CONFIG_FILE` | Path to JSON configuration file |

**Note**: Replace `/path/to/your/mcp-rest/` with the actual path to your MCP REST server directory.

### Usage in Claude/Cursor

#### With Auto-Configuration (Recommended)

If you've configured the server with auto-configuration (environment variables, CLI args, or config file), the server will be ready to use immediately:

```
Make a GET request to /posts/1
Show me all available endpoints
Search for endpoints related to "user"
```

#### With Manual Configuration

If you haven't provided auto-configuration, you can still configure the client manually:

1. **Configure the client first**:
```
Please configure the REST client with:
- Base URL: https://api.example.com
- Authentication: token
- Token: your-api-token-here
- Swagger URL: https://api.example.com/swagger.json
```

2. **Then make API requests**:
```
Make a GET request to /users/123
```

### Testing the Configuration

You can test your configuration before using it in Claude/Cursor:

```bash
# Test with config file
node dist/index.js --config examples/jsonplaceholder.json

# Test with CLI arguments
node dist/index.js --base-url https://api.github.com --auth-type token --token your-token

# Test with environment variables
MCP_REST_BASE_URL=https://httpbin.org MCP_REST_AUTH_TYPE=token MCP_REST_TOKEN=test node dist/index.js
```

If you see "✅ Auto-configured REST client for [URL]", the configuration is working correctly.

## License

MIT