# Embeddings MCP Server

A Model Context Protocol (MCP) server for generating text embeddings using OpenAI, Anthropic, or Ollama. Built with Next.js and the Vercel AI SDK, designed for easy deployment on Vercel.

## Features

- **Multiple Providers**: Support for OpenAI, Anthropic, and Ollama embedding models
- **Two Tools**: Single text embedding and batch text embeddings
- **Easy Deployment**: Ready for deployment on Vercel
- **Local Testing**: Built-in support for Ollama for local development
- **TypeScript**: Fully typed for better developer experience
- **Comprehensive Tests**: Full test coverage

## Quick Start

1. **Clone and install dependencies:**
   ```bash
   git clone <your-repo>
   cd embeddings-mcp-ts
   pnpm install
   ```

2. **Configure environment variables:**
   ```bash
   cp .env.example .env.local
   ```
   
   Edit `.env.local` with your preferred provider settings.

3. **Run locally:**
   ```bash
   pnpm dev
   ```

4. **Deploy to Vercel:**
   ```bash
   npx vercel
   ```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `EMBEDDING_PROVIDER` | Provider to use: `openai`, `anthropic`, or `ollama` | `openai` |
| `OPENAI_API_KEY` | OpenAI API key (required for OpenAI) | - |
| `OPENAI_EMBEDDING_MODEL` | OpenAI embedding model | `text-embedding-3-small` |
| `ANTHROPIC_API_KEY` | Anthropic API key (required for Anthropic) | - |
| `ANTHROPIC_EMBEDDING_MODEL` | Anthropic model | `claude-3-5-sonnet-20241022` |
| `OLLAMA_BASE_URL` | Ollama server URL | `http://localhost:11434` |
| `OLLAMA_EMBEDDING_MODEL` | Ollama embedding model | `nomic-embed-text` |

### Provider-Specific Setup

#### OpenAI
```bash
export EMBEDDING_PROVIDER=openai
export OPENAI_API_KEY=your_api_key_here
export OPENAI_EMBEDDING_MODEL=text-embedding-3-small
```

#### Anthropic
```bash
export EMBEDDING_PROVIDER=anthropic  
export ANTHROPIC_API_KEY=your_api_key_here
```

#### Ollama (Local Testing)
```bash
export EMBEDDING_PROVIDER=ollama
export OLLAMA_BASE_URL=http://localhost:11434
export OLLAMA_EMBEDDING_MODEL=nomic-embed-text
```

Make sure Ollama is running locally:
```bash
ollama serve
ollama pull nomic-embed-text
```

## MCP Tools

### `embed_text`
Generates an embedding for a single text string.

**Parameters:**
- `text` (string): The text to generate an embedding for

**Returns:**
```json
{
  "embedding": [0.1, -0.2, 0.3, ...],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  },
  "dimensions": 1536
}
```

### `embed_texts`
Generates embeddings for multiple text strings.

**Parameters:**
- `texts` (string[]): Array of texts to generate embeddings for

**Returns:**
```json
{
  "embeddings": [[0.1, -0.2, ...], [0.3, -0.4, ...]],
  "model": "text-embedding-3-small", 
  "usage": {
    "prompt_tokens": 20,
    "total_tokens": 20
  },
  "count": 2,
  "dimensions": 1536
}
```

## Claude Desktop Integration

To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "embeddings": {
      "command": "npx",
      "args": ["mcp-handler", "http://localhost:3000/api/mcp"],
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

For production deployment, replace `localhost:3000` with your Vercel deployment URL.

## Development

### Running Tests
```bash
pnpm test
pnpm test:watch
```

### Type Checking
```bash
pnpm type-check
```

### Linting
```bash
pnpm lint
```

### Building
```bash
pnpm build
```

## Deployment

### Vercel Deployment

1. **Configure environment variables in Vercel:**
   - Go to your Vercel project settings
   - Add environment variables for your chosen provider
   - Set `EMBEDDING_PROVIDER` to your preferred provider

2. **Deploy:**
   ```bash
   npx vercel
   ```

3. **Update your MCP client configuration** with the deployment URL.

## Architecture

- **`src/app/api/mcp/route.ts`**: Main MCP server endpoint
- **`src/lib/config.ts`**: Configuration management
- **`src/lib/embedding-service.ts`**: Provider factory
- **`src/lib/providers/`**: Individual provider implementations
- **`src/types/`**: TypeScript type definitions

## License

MIT