# Azure APIM + MCP Server Demo

This project demonstrates how to expose backend APIs through Azure API Management (APIM) as a Model Context Protocol (MCP) Server, enabling AI assistants and tools to interact with your APIs using the standardized MCP protocol.

## 🏗️ Architecture

```
┌──────────────────┐     ┌─────────────────────────┐     ┌─────────────────────────┐
│   MCP Client     │────▶│   Azure API Management  │────▶│   Azure App Service     │
│  (AI Assistant)  │     │      (Gateway)          │     │   (Express.js API)      │
└──────────────────┘     └─────────────────────────┘     └─────────────────────────┘
        │                         │                              │
        │  MCP Protocol           │  Subscription Key            │  REST API
        │  (JSON-RPC 2.0)         │  Rate Limiting               │  Products/Orders
        │                         │  Monitoring                  │
        └─────────────────────────┴──────────────────────────────┘
```

## 📦 Components

### Backend API (`backend-api/`)
- **Express.js** application with TypeScript
- REST API endpoints for products and orders
- MCP JSON-RPC endpoint handler
- 5 MCP tools:
  - `get_products` - List all products in the catalog
  - `get_product_by_id` - Get product details by ID
  - `search_products` - Search products by query string
  - `get_orders` - List all orders
  - `create_order` - Create a new order

### Infrastructure (`infrastructure/`)
- **Bicep** templates for Azure deployment
- Azure App Service (Linux, Node.js 20 LTS, B1 Basic)
- Azure API Management (Developer SKU)
- Application Insights for monitoring
- Log Analytics workspace

## 🌐 Endpoints

| Endpoint | Description |
|----------|-------------|
| `https://apimmcp-api-dev.azurewebsites.net/` | Backend root |
| `https://apimmcp-api-dev.azurewebsites.net/api/health` | Health check |
| `https://apimmcp-api-dev.azurewebsites.net/api/products` | Products REST API |
| `https://apimmcp-api-dev.azurewebsites.net/api/orders` | Orders REST API |
| `https://apimmcp-api-dev.azurewebsites.net/api/mcp` | MCP endpoint (direct) |
| `https://apimmcp-apim-dev.azure-api.net/mcp` | **MCP endpoint (via APIM)** ⭐ |

## 📡 MCP Protocol

The server implements the Model Context Protocol (version 2024-11-05):

### Initialize
```json
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "id": 1,
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "client", "version": "1.0.0" }
  }
}
```

### List Tools
```json
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 2
}
```

### Call Tool
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 3,
  "params": {
    "name": "get_products"
  }
}
```

### Example: Search Products
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 4,
  "params": {
    "name": "search_products",
    "arguments": { "query": "smart" }
  }
}
```

### Example: Create Order
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 5,
  "params": {
    "name": "create_order",
    "arguments": { "productId": "prod-001", "quantity": 2 }
  }
}
```

## 🚀 Deployment

### Prerequisites
- Azure CLI installed and logged in
- Azure subscription
- Node.js 18+ installed locally

### 1. Create Resource Group
```powershell
az group create --name apim-mcp-demo-rg --location eastus
```

### 2. Deploy Infrastructure
```powershell
az deployment group create `
  --resource-group apim-mcp-demo-rg `
  --template-file ./infrastructure/main-appservice.bicep `
  --parameters location=eastus namePrefix=apimmcp environment=dev apimPublisherEmail="your-email@example.com"
```

> ⚠️ Note: APIM provisioning takes 15-30 minutes on first deployment.

### 3. Build Backend API
```powershell
cd backend-api
npm install
npm run build
```

### 4. Deploy Backend API
```powershell
Compress-Archive -Path "dist\*", "package.json", "web.config", "node_modules" -DestinationPath "deploy.zip" -Force
az webapp deploy --resource-group apim-mcp-demo-rg --name apimmcp-api-dev --src-path deploy.zip --type zip
```

### 5. Get APIM Subscription Key
```powershell
az rest --method post `
  --uri "https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/apim-mcp-demo-rg/providers/Microsoft.ApiManagement/service/apimmcp-apim-dev/subscriptions/mcp-subscription/listSecrets?api-version=2022-08-01" `
  --query "primaryKey" -o tsv
```

## 🧪 Testing

### Run Test Script
```powershell
.\test-mcp.ps1
```

### Expected Output
```
========================================
  MCP Server Test Suite
========================================

Endpoint: https://apimmcp-apim-dev.azure-api.net/mcp

1. Testing initialize...
   Server: azure-product-catalog-server v1.0.0
   Protocol: 2024-11-05

2. Testing tools/list...
   Found 5 tools:
     - get_products: Retrieve a list of all products in the catalog
     - get_product_by_id: Get details of a specific product by its ID
     ...

3. Testing tools/call (get_products)...
   Found 8 products:
     - Widget Pro: $29.99
     - Gadget Plus: $49.99
     ...
```

### Manual Testing
```powershell
$headers = @{
  "Ocp-Apim-Subscription-Key" = "YOUR_SUBSCRIPTION_KEY"
  "Content-Type" = "application/json"
}

$body = '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Invoke-RestMethod -Uri "https://apimmcp-apim-dev.azure-api.net/mcp" -Method POST -Headers $headers -Body $body
```

## 🛠️ Development

### Local Development
```powershell
cd backend-api
npm install
npm run dev
```

The server will start on `http://localhost:3000`.

### Project Structure
```
APIM-MCP/
├── backend-api/
│   ├── src/
│   │   ├── index.ts      # Express server entry
│   │   ├── routes.ts     # REST API routes
│   │   ├── mcp.ts        # MCP endpoint handler
│   │   └── data.ts       # Mock data store
│   ├── dist/             # Compiled JavaScript
│   ├── package.json
│   ├── tsconfig.json
│   └── web.config        # IIS configuration for Azure
├── infrastructure/
│   └── main-appservice.bicep   # Azure resources
├── test-mcp.ps1          # Test script
└── README.md
```

## 🔧 Configuration

### APIM Settings
- **Subscription Required**: Yes
- **Rate Limiting**: Configurable via APIM policies
- **Authentication**: Subscription key header (`Ocp-Apim-Subscription-Key`)

### App Service Settings
- **SKU**: B1 Basic (Linux)
- **Node Version**: 20 LTS
- **Startup Command**: `node index.js`

## 📊 Monitoring

- Application Insights integrated with both App Service and APIM
- Access logs in Log Analytics workspace
- Health endpoint available at `/api/health`

## 🔗 Resources

- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Azure API Management Documentation](https://learn.microsoft.com/azure/api-management/)
- [Azure App Service Documentation](https://learn.microsoft.com/azure/app-service/)

## 📄 License

MIT