# Custom OpenAPI MCP Server

A powerful Model Context Protocol (MCP) server that dynamically fetches and exposes OpenAPI/Swagger documentation as tools for AI assistants like GitHub Copilot and Claude. This server enables AI models to understand and interact with any REST API by automatically parsing OpenAPI specifications.

## Features

- 🚀 **Dynamic API Discovery**: Automatically fetches and parses OpenAPI/Swagger specifications from any URL
- 🔍 **Intelligent Endpoint Exploration**: List and filter endpoints by tags for organized API navigation
- 📖 **Detailed Documentation**: Get comprehensive endpoint descriptions, parameters, and response schemas
- 💡 **Smart Code Generation**: Generate realistic request examples based on OpenAPI schemas
- ⚡ **Real-time Integration**: Works seamlessly with GitHub Copilot, Claude, and other MCP-compatible AI tools
- 🛠️ **Zero Configuration**: Works out of the box with sensible defaults

## Tools Provided

### 1. `list_endpoints_by_tag`
Lists all endpoints grouped by OpenAPI tags, providing a high-level overview of API functionality.

**Parameters:**
- `tag` (string): OpenAPI tag name (e.g., "Authentication", "Users", "Orders")

**Example Output:**
```
GET /auth/login: Authenticate user with credentials
POST /auth/refresh: Refresh authentication token
DELETE /auth/logout: Logout and invalidate session
```

### 2. `describe_endpoint`
Provides detailed information about a specific endpoint including parameters, request body, and responses.

**Parameters:**
- `path` (string): API endpoint path (e.g., "/users/{id}")
- `method` (string): HTTP method (e.g., "GET", "POST", "PUT", "DELETE")

**Example Output:**
```markdown
### POST /users
Create a new user account

**Parameters**
- `x-api-key` (header) **required** – string

**Request Body**
- application/json
  - schema: UserCreateRequest

**Responses**
- 201: User created successfully
- 400: Invalid request data
- 409: User already exists
```

### 3. `generate_request_example`
Generates sample JSON request bodies based on OpenAPI schemas, perfect for testing and development.

**Parameters:**
- `path` (string): API endpoint path
- `method` (string): HTTP method

**Example Output:**
```json
{
  "username": "string",
  "email": "string",
  "password": "string",
  "profile": {
    "firstName": "string",
    "lastName": "string",
    "age": 0
  }
}
```

## Installation

### Prerequisites

- Node.js 18+ 
- npm or yarn
- An MCP-compatible AI assistant (GitHub Copilot, Claude Desktop, etc.)

### Quick Start

1. **Clone and Install**
   ```bash
   git clone <your-repo-url>
   cd custom-mcp
   npm install
   ```

2. **Configure Environment** (Optional)
   ```bash
   cp .env.example .env
   # Edit .env to set your API documentation URL
   ```

3. **Test the Server**
   ```bash
   npm start
   ```

### GitHub Copilot Integration

```json
{
  "mcpServers": {
    "custom-openapi": {
      "command": "node",
      "args": ["/absolute/path/to/custom-mcp/index.js"],
      "env": {
        "API_DOCS_URL": "https://your-api.com/swagger.json"
      }
    }
  }
}
```

**For macOS/Linux** (`~/.config/github-copilot/mcp.json`):
```json
{
  "servers": {
    "custom-openapi": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/custom-mcp/index.js"],
      "env": {
        "API_DOCS_URL": "https://your-api.com/swagger.json"
      }
    }
  }
}
```

**For Windows** (`%APPDATA%\github-copilot\mcp.json`):
```json
{
  "servers": {
    "custom-openapi": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\path\\to\\custom-mcp\\index.js"],
      "env": {
        "API_DOCS_URL": "https://your-api.com/swagger.json"
      }
    }
  }
}
```

### Claude Desktop Integration

Add to your Claude Desktop MCP configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "custom-openapi": {
      "command": "node",
      "args": ["/absolute/path/to/custom-mcp/index.js"],
      "env": {
        "API_DOCS_URL": "https://your-api.com/swagger.json"
      }
    }
  }
}
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `API_DOCS_URL` | URL to OpenAPI/Swagger JSON specification | Petstore demo API |

### Supported OpenAPI Sources

- ✅ OpenAPI 3.0+ specifications
- ✅ Swagger 2.0 specifications  
- ✅ Local files (`file://` URLs)
- ✅ Remote HTTPS endpoints
- ✅ APIs with CORS enabled
- ✅ JSON and YAML formats

### Example API URLs

```bash
# Petstore Demo (default)
API_DOCS_URL=https://petstore.swagger.io/v2/swagger.json

# Local development server
API_DOCS_URL=http://localhost:3000/api/docs/json

# Production API
API_DOCS_URL=https://api.yourcompany.com/v1/openapi.json

# Local file
API_DOCS_URL=file:///path/to/your/openapi.json
```

## Usage Examples

Once integrated with your AI assistant, you can use natural language to explore APIs:

```
"Show me all authentication endpoints"
→ Uses list_endpoints_by_tag with tag="Authentication"

"How do I create a new user?"
→ Uses describe_endpoint for POST /users

"Generate an example request for user registration"
→ Uses generate_request_example for POST /users/register
```

## Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │◄──►│  MCP Server      │◄──►│  OpenAPI Spec   │
│ (Copilot/Claude)│    │  (This Project)  │    │  (Remote/Local) │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

### Core Components

- **`index.js`**: Server bootstrap and OpenAPI spec fetching
- **`tools.js`**: MCP tool definitions and OpenAPI parsing logic
- **`package.json`**: Dependencies and project metadata
- **`mcp.json`**: Example MCP client configuration

### Example of current configration
![alt text](<Screenshot 2025-09-06 at 1.55.49 PM.png>) ![alt text](<Screenshot 2025-09-06 at 1.56.00 PM.png>)

## Troubleshooting

### Common Issues

**Server fails to start:**
```bash
# Check if the API URL is accessible
curl -s "https://your-api.com/swagger.json" | jq .

# Verify Node.js version
node --version  # Should be 18+
```

**No tools appear in AI assistant:**
- Verify the absolute path in `mcp.json` is correct
- Restart your AI assistant after configuration changes
- Check the server logs for errors

**Schema parsing errors:**
- Ensure your OpenAPI spec is valid JSON/YAML
- Test with a minimal spec first
- Check for unsupported OpenAPI extensions


### Validation

Test your OpenAPI specification:
```bash
# Using swagger-codegen
npx swagger-codegen-cli validate -i https://your-api.com/swagger.json

# Using online validator
curl -X POST "https://validator.swagger.io/validator/debug" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-api.com/swagger.json"}'
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- Inspired by the need for dynamic API exploration in AI development workflows

---