karini-mcp-server 0.1.1

MCP server for Karini AI copilots, webhook recipes, dataset search, and event 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)

uvx karini-mcp-server

Via pip

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)

{
  "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

{
  "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

{
  "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

{
  "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

# 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