<p align="center">
  <picture>
    <source srcset="public/logo.svg" media="(prefers-color-scheme: dark)">
    <img src="public/logo.svg" alt="Models PLUS" width="300">
  </picture>
</p>

<p align="center">
  <strong>Comprehensive AI Model Directory & MCP Server</strong>
</p>

<p align="center">
  Unified REST API and Model Context Protocol (MCP) server for AI model metadata, built on <a href="https://models.dev">models.dev</a> data.
</p>

<p align="center">
  <a href="#features">Features</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#api-guide">API Docs</a> •
  <a href="#mcp-integration">MCP</a> •
  <a href="#contributing">Contributing</a>
</p>

---

<p align="center">
  <a href="https://modelsplus.quivr.tech">
    <img src="https://img.shields.io/badge/Public%20API-Online-brightgreen" alt="Public API">
  </a>
  <a href="https://github.com/vivek-k3/modelsplus/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
  </a>
  <a href="https://smithery.ai/server/@Vivek-k3/modelsplus">
    <img src="https://smithery.ai/badge/@Vivek-k3/modelsplus" alt="Smithery">
  </a>
</p>

## Features

Models PLUS provides a comprehensive AI model catalog with modern tooling:

### **Core Features**
- **Unified REST API** - Advanced search and filtering for 100+ AI models
- **Model Context Protocol (MCP)** - Native MCP support with 4 powerful tools
- **Real-time Data** - Fresh data from [models.dev](https://models.dev) database
- **Lightning Fast** - Built with Bun runtime and SST v3

### **Developer Experience**
- **Zero Config** - Biome + Ultracite for ultra-fast formatting and linting
- **TypeScript** - Full type safety with strict TypeScript configuration
- **Cloudflare Workers** - Global edge deployment with SST

### **Rich Metadata**
- **Comprehensive Model Info** - Pricing, limits, capabilities, modalities
- **Provider Details** - Environment variables, documentation, integrations
- **Advanced Filtering** - Search by cost, context length, features, and more

**Public API**: [https://modelsplus.quivr.tech](https://modelsplus.quivr.tech)

## Quick Start

### **Try the Public API**

```bash
# List latest models
curl "https://modelsplus.quivr.tech/v1/models?limit=5"

# Find reasoning-capable models
curl "https://modelsplus.quivr.tech/v1/models?reasoning=true"

# Get specific model details
curl "https://modelsplus.quivr.tech/v1/models/openai:gpt-4o"
```

### **Local Development**

```bash
# Install dependencies
bun install

# Start development server
bun run dev

# Build for production
bun run build
```

## Installation

### 📋 **Requirements**
- **Bun** `1.2.21` - Runtime and package manager
- **Node.js types** - For tooling compatibility (bundled via SST)

### **Quick Install**
```bash
# Install dependencies
bun install

# Generate JSON assets from vendor data
cd packages/api && bun run generate && bun run build
```

## **Development**

### **Useful Scripts**
- `bun run build` — Build all workspaces
- `bun run dev` — SST Dev with Cloudflare Worker locally
- `bun run dev:api` — Direct Worker dev for API only
- `bun run deploy` — Deploy via SST to Cloudflare Workers
- `bun run sync:upstream` — Sync vendor subtree

### **Development Setup**
1. Generate JSON assets from vendor TOML files:
   ```bash
   cd packages/api
   bun run generate
   bun run build
   ```

2. Run development servers:
   ```bash
   # SST Dev (recommended)
   bun run dev

   # Direct Worker dev
   cd packages/api && bun run dev
   ```

**Note**: SST config (`sst.config.ts`) auto-builds `@modelsplus/api` and exposes the Worker URL.

## **API Guide**

### Authentication

No authentication required. The API is publicly accessible.

### Base URL

```
https://modelsplus.quivr.tech
```

### Response Format

All API responses return JSON. Error responses include:

```json
{
  "error": "Error message",
  "status": 400
}
```

### Rate Limits

Currently no rate limiting is enforced, but please be respectful.

### Query Parameters

#### Models API (`/v1/models`)

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `q` | string | Search query (model name, provider, etc.) | `q=gpt` |
| `provider` | string | Filter by provider | `provider=openai` |
| `tool_call` | boolean | Filter by tool calling support | `tool_call=true` |
| `attachment` | boolean | Filter by attachment support | `attachment=true` |
| `reasoning` | boolean | Filter by reasoning capabilities | `reasoning=true` |
| `temperature` | boolean | Filter by temperature support | `temperature=true` |
| `open_weights` | boolean | Filter by open weights availability | `open_weights=true` |
| `min_input_cost` | number | Minimum input cost filter | `min_input_cost=0.001` |
| `max_input_cost` | number | Maximum input cost filter | `max_input_cost=0.01` |
| `min_output_cost` | number | Minimum output cost filter | `min_output_cost=0.002` |
| `max_output_cost` | number | Maximum output cost filter | `max_output_cost=0.05` |
| `min_context` | number | Minimum context length | `min_context=32000` |
| `max_context` | number | Maximum context length | `max_context=128000` |
| `min_output_limit` | number | Minimum output limit | `min_output_limit=4000` |
| `max_output_limit` | number | Maximum output limit | `max_output_limit=8000` |
| `modalities` | string | Comma-separated modalities | `modalities=image,text` |
| `release_after` | string | Released after date (ISO) | `release_after=2024-01-01` |
| `release_before` | string | Released before date (ISO) | `release_before=2024-12-31` |
| `updated_after` | string | Updated after date (ISO) | `updated_after=2024-06-01` |
| `updated_before` | string | Updated before date (ISO) | `updated_before=2024-12-31` |
| `sort` | string | Sort field | `sort=name` or `sort=cost_input` |
| `order` | string | Sort order | `order=asc` or `order=desc` |
| `limit` | number | Maximum results (default: unlimited) | `limit=10` |
| `offset` | number | Skip number of results | `offset=20` |
| `fields` | string | Comma-separated fields to return | `fields=id,name,provider` |

#### Providers API (`/v1/providers`)

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `q` | string | Search query (provider name) | `q=openai` |
| `env` | string | Filter by environment variable | `env=API_KEY` |
| `npm` | string | Filter by npm package | `npm=openai` |
| `limit` | number | Maximum results | `limit=10` |
| `offset` | number | Skip number of results | `offset=5` |

### Model Object Schema

```json
{
  "id": "openai:gpt-4o",
  "provider": "openai",
  "name": "GPT-4o",
  "release_date": "2024-05-13",
  "last_updated": "2024-08-06",
  "attachment": true,
  "reasoning": false,
  "temperature": true,
  "tool_call": true,
  "open_weights": false,
  "knowledge": "2023-10",
  "cost": {
    "input": 0.0025,
    "output": 0.01,
    "cache_read": 0.00125,
    "cache_write": 0.00625
  },
  "limit": {
    "context": 128000,
    "output": 16384
  },
  "modalities": {
    "input": ["text", "image"],
    "output": ["text"]
  }
}
```

### Provider Object Schema

```json
{
  "id": "openai",
  "name": "OpenAI",
  "env": ["OPENAI_API_KEY"],
  "npm": "openai",
  "api": "https://api.openai.com/v1",
  "doc": "https://platform.openai.com/docs"
}
```





### 🔗 **API Endpoints**

**Base URL**: `https://modelsplus.quivr.tech`

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/health` | Health/status check |
| `GET` | `/.well-known/mcp` | MCP discovery |
| `GET` | `/v1/models` | List/search models |
| `GET` | `/v1/models/count` | Count models after filters |
| `GET` | `/v1/models/:id` | Get specific model details |
| `GET` | `/v1/providers` | List/search providers |
| `GET` | `/v1/providers/count` | Count providers after filters |
| `GET/POST` | `/mcp` | MCP over HTTP (JSON-RPC) |
| `GET/POST` | `/mcp/http` | Alternate MCP endpoint |

### **Code Examples**

**JavaScript/TypeScript:**
```typescript
// Search models
const models = await fetch('https://modelsplus.quivr.tech/v1/models?reasoning=true&limit=5')
  .then(res => res.json());

// Get specific model
const model = await fetch('https://modelsplus.quivr.tech/v1/models/openai:gpt-4o')
  .then(res => res.json());
```

**Python:**
```python
import requests

# Find vision-capable models
response = requests.get('https://modelsplus.quivr.tech/v1/models',
                       params={'modalities': 'image', 'limit': 5})
models = response.json()
```


## **MCP Integration**

Models PLUS provides native Model Context Protocol (MCP) support for seamless integration with AI assistants.

### **Available Tools**
- `search_models` - Advanced search and filtering for AI models
- `get_model` - Detailed information about specific models
- `search_providers` - Search and filter AI providers
- `get_provider` - Detailed provider information

### **Quick Setup**

#### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "models-plus": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/sdk", "server", "https://modelsplus.quivr.tech/mcp"]
    }
  }
}
```

#### Cursor
Configure MCP server with URL: `https://modelsplus.quivr.tech/mcp`

#### Other MCP Clients
For any MCP-compatible client, use: `https://modelsplus.quivr.tech/mcp`

### **Usage Examples**
Once integrated, use natural language:
- *"Find all GPT-4 models from OpenAI"*
- *"Show me reasoning-capable models under $1 per million tokens"*
- *"What are the specs for Claude 3 Opus?"*
- *"Which providers support tool calling?"*

### **Direct HTTP API**
```bash
# Discover capabilities
curl "https://modelsplus.quivr.tech/mcp"

# List available tools
curl -s "https://modelsplus.quivr.tech/mcp" \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```


## **Data Source**

Model and provider metadata sourced from [models.dev](https://models.dev) TOML files. The build process (`packages/api/src/generate.ts`) converts these into optimized JSON artifacts for the API and MCP handlers.

## **Deployment**

Deploys via SST to Cloudflare Workers:

```bash
bun run deploy
```

SST config creates a `sst.cloudflare.Worker` with global edge deployment.

## **Contributing**

We welcome contributions! Here's how to get started:

1. **Fork** and create a feature branch
2. **Install** dependencies: `bun install`
3. **Build** and ensure tests pass: `bun run build`
4. **Format** code: `npx ultracite format && npx ultracite lint`
5. **Test** your changes thoroughly
6. **Submit** a pull request with a clear description

## **Acknowledgments**

Built on top of **[models.dev](https://models.dev)** - a comprehensive open-source database of AI model specifications, pricing, and capabilities maintained by the [SST](https://sst.dev) team.

---