MCP REST Server

# 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