karini-mcp-server 0.1.1
MCP server for Karini AI copilots, webhook recipes, dataset search, and event tracing
Requires Python: >=3.10
Keywords: mcp, ai, model-context-protocol, kariniai, copilot, webhook, dataset, tracing

# Karini MCP Server

MCP (Model Context Protocol) server for integrating Karini AI copilots, webhook recipes, and dataset search.

## Features

- 🤖 **AI Copilot Integration** - Ask questions and get AI-powered responses from your Karini copilots
- 📄 **Document Processing** - Process documents stored in S3 through copilots and webhooks
- 🔗 **Webhook Recipes** - Trigger asynchronous data processing workflows
- 📊 **Status Tracking** - Monitor webhook execution status and results
- 🔍 **Dataset Search** - Query your Karini knowledge base with semantic search
- 🔎 **Event Tracing** - Trace and debug Karini events by request ID

## Installation

### Via uvx (Recommended)
```bash
uvx karini-mcp-server
```

### Via pip
```bash
pip install karini-mcp-server
```

## Configuration

### Claude Desktop Setup

Edit your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

#### Full Configuration (All Features)
```json
{
  "mcpServers": {
    "karini-mcp-server": {
      "command": "uvx",
      "args": ["karini-mcp-server@latest"],
      "env": {
        "KARINI_API_BASE": "https://app.karini.ai",
        "KARINI_COPILOT_ID": "karini-copilot-id",
        "KARINI_API_KEY": "karini-api-key",
        "WEBHOOK_API_KEY": "karini-webhook-api-key",
        "WEBHOOK_RECIPE_ID": "karini-webhook-recipe-id",
        "KARINI_DATASET_ID": "karini-dataset-id"
      }
    }
  }
}
```

#### Copilot Only Configuration
```json
{
  "mcpServers": {
    "karini-mcp-server": {
      "command": "uvx",
      "args": ["karini-mcp-server@latest"],
      "env": {
        "KARINI_API_BASE": "https://app.karini.ai",
        "KARINI_COPILOT_ID": "karini-copilot-id",
        "KARINI_API_KEY": "karini-api-key"
      }
    }
  }
}
```

#### Webhook Only Configuration
```json
{
  "mcpServers": {
    "karini-mcp-server": {
      "command": "uvx",
      "args": ["karini-mcp-server@latest"],
      "env": {
        "KARINI_API_BASE": "https://app.karini.ai",
        "WEBHOOK_API_KEY": "karini-webhook-api-key",
        "WEBHOOK_RECIPE_ID": "karini-webhook-recipe-id"
      }
    }
  }
}
```

#### Dataset Search Only Configuration
```json
{
  "mcpServers": {
    "karini-mcp-server": {
      "command": "uvx",
      "args": ["karini-mcp-server@latest"],
      "env": {
        "KARINI_API_BASE": "https://app.karini.ai",
        "KARINI_API_KEY": "karini-api-key",
        "KARINI_DATASET_ID": "karini-dataset-id"
      }
    }
  }
}
```

**Note:** Only tools with valid configuration will be available. Configure only the features you need.

## Environment Variables

| Variable | Required For | Description |
|----------|-------------|-------------|
| `KARINI_API_BASE` | All | Base URL for Karini API (e.g., `https://app.karini.ai`) |
| `KARINI_API_KEY` | Copilot, Dataset, Tracing | API key for authentication |
| `KARINI_COPILOT_ID` | Copilot | Your copilot's unique identifier |
| `KARINI_DATASET_ID` | Dataset | Your dataset's unique identifier |
| `WEBHOOK_API_KEY` | Webhook | API key for webhook authentication |
| `WEBHOOK_RECIPE_ID` | Webhook | Webhook recipe identifier |

## Available Tools

### Copilot Tools

#### `ask_karini_copilot`

Ask questions to your Karini AI copilot and receive intelligent responses.

**Parameters:**
- `question` (string, required): The question or query to ask
- `files` (list, optional): S3 file paths to include in the query
  - Example: `["s3://bucket/document.pdf", "s3://bucket/data.txt"]`

### Webhook Tools

#### `invoke_webhook_recipe`

Trigger a webhook recipe for asynchronous data processing.

**Parameters:**
- `question` (string, optional): Input message or query
- `files` (list, optional): S3 file paths to process (content type auto-detected)
  - Example: `["s3://bucket/invoice.pdf", "s3://bucket/receipt.jpg"]`
- `metadata` (dict, optional): Additional context as key-value pairs
  - Example: `{"user_id": "123", "priority": "high", "source": "email"}`

**Returns:** JSON with `request_id` for status tracking

#### `get_webhook_status`

Check the status of webhook recipe executions.

**Parameters:**
- `request_id` (string, optional): Specific request ID to check. If not provided, returns recent requests.
- `limit` (integer, optional): Number of recent requests to return (default: 5)

### Dataset Tools

#### `query_karini_dataset`

Search and retrieve information from your Karini knowledge base using semantic search.

**Parameters:**
- `text` (string, required): The search query or question
- `top_k` (integer, optional): Number of results to return (default: 5, max: 20)

### Tracing Tools

#### `get_traces`

Trace and retrieve detailed information about a specific Karini event using its request ID.

**Parameters:**
- `request_id` (string, required): The unique identifier of the Karini event to trace

**Returns:** Detailed trace information including execution steps, timing, and debug data

**Examples:**
```
Trace event "67309a4f8b1c2d3e4f5a6b7c"

Get traces for request ID "abc123def456"
```

## Development

### Local Testing
```bash
# Clone repository
git clone https://github.com/yourusername/karini-mcp-server.git
cd karini-mcp-server

# Install dependencies
pip install -e .

# Run locally
python -m src.main
```

### Project Structure
```
karini-mcp-server/
├── src/
│   ├── main.py              # Entry point
│   ├── server.py            # MCP server setup
│   ├── services/
│   │   ├── config.py        # Configuration management
│   │   └── client.py        # Karini API client
│   └── tools/
│       └── tools.py         # Tool definitions
├── pyproject.toml
└── README.md
```