# rag-mcp-server

An MCP (Model Context Protocol) server that exposes Azure AI Search as a tool. Connect it to any MCP-compatible client (Claude Desktop, MCP Inspector, etc.) to give it hybrid vector + keyword search over your own document index.

## What it does

Exposes a single MCP tool:

```
search_documents(query: str, top_k: int = 5) -> str
```

Generates an embedding for the query using Azure OpenAI, runs a hybrid search against Azure AI Search, and returns the top matching document chunks with source and metadata.

---

## Prerequisites

- Python 3.11+
- An Azure AI Search index with a `content_vector` field
- An Azure OpenAI embedding deployment (e.g. `text-embedding-3-small`)

---

## Quick Start

### Run locally with Python

```powershell
# 1. Clone and enter the directory
git clone <repo-url>
cd rag-mcp

# 2. Create a virtual environment and install dependencies
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# 3. Configure credentials
cp .env.example .env
# Edit .env and fill in your Azure endpoints and API keys

# 4. Start the server
python server.py
```

Server listens at `http://localhost:8001/mcp`.

### Run with Docker

```powershell
cp .env.example .env
# Edit .env and fill in your Azure endpoints and API keys

docker compose up --build
```

---

## Environment Variables

Copy `.env.example` to `.env` and fill in the values:

| Variable | Description |
|---|---|
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI resource endpoint |
| `AZURE_EMBEDDING_API_KEY` | API key for the embedding deployment |
| `AZURE_OPENAI_EMBEDDING_DEPLOYMENT` | Embedding model deployment name |
| `AZURE_SEARCH_ENDPOINT` | Azure AI Search service endpoint |
| `AZURE_SEARCH_API_KEY` | Azure AI Search admin or query key |
| `AZURE_SEARCH_INDEX_NAME` | Name of the search index to query |

---

## Testing with MCP Inspector

MCP Inspector is an interactive UI for calling MCP tools manually.

```powershell
# Terminal 1 — start the server
python server.py

# Terminal 2 — open the inspector
npx @modelcontextprotocol/inspector
```

Open the URL printed by the inspector (e.g. `http://localhost:5173`), set transport to **Streamable HTTP**, enter `http://localhost:8001/mcp`, and click **Connect**. Navigate to the **Tools** tab to call `search_documents`.

---

## Connect to Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "rag-mcp": {
      "type": "streamable-http",
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

---

## Run the Automated Test

With the server running, execute the MCP client test:

```powershell
python test.py
```

Passes three assertions: tool is registered, no server-side error, and results contain formatted document chunks.

---

## Deploy to Azure Container Apps

See [`deploy.ps1`](./deploy.ps1) for a full Azure CLI deployment script. Fill in your resource group at the top of the file, then run:

```powershell
.\deploy.ps1
```

The script builds and pushes the Docker image to ACR, creates a Container Apps environment, and deploys the server with a public HTTPS endpoint.