# Tagging MCP

MCP server for tagging CSV rows using polar_llama with parallel LLM inference.

## Overview

This MCP server enables fast, parallel tagging of CSV data using multiple LLM providers. It leverages [polar_llama](https://github.com/daviddrummond95/polar_llama) to process rows concurrently, making it ideal for batch classification and tagging tasks.

## Features

- **Parallel Processing**: Tag hundreds or thousands of CSV rows concurrently
- **Multiple LLM Providers**: Support for Claude (Anthropic), OpenAI, Gemini, and Groq
- **Structured Output**: Uses Pydantic models for consistent, type-safe results
- **Flexible Taxonomy**: Define custom tag lists for your use case
- **Optional Reasoning**: Include confidence levels and explanations for tags

## Installation

### Prerequisites

- Python 3.12+
- UV package manager
- API key for at least one LLM provider

### Environment Setup

1. Clone this repository
2. Create a `.env` file with your API keys:
   ```bash
   ANTHROPIC_API_KEY=your_key_here
   OPENAI_API_KEY=your_key_here
   GEMINI_API_KEY=your_key_here
   GROQ_API_KEY=your_key_here
   ```

## Claude Desktop Configuration

### Option 1: Local Development (Recommended)

Run directly without containers:

```json
{
  "mcpServers": {
    "tagging-mcp": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "/path/to/tagging_mcp/tagging.py"]
    }
  }
}
```

### Option 2: Container Deployment

1. Build the container:
   ```bash
   container build -t tagging_mcp .
   ```

2. Configure Claude Desktop:
   ```json
   {
     "mcpServers": {
       "tagging-mcp": {
         "command": "container",
         "args": ["run", "--interactive", "tagging_mcp"]
       }
     }
   }
   ```

## Available Tools

### `tag_csv`
Simple tagging with a list of categories. Perfect for basic classification tasks.

**Parameters:**
- `csv_path` (str): Path to the CSV file to tag
- `taxonomy` (List[str]): List of possible tags/categories (e.g., ["technology", "business", "science"])
- `text_column` (str, optional): Column containing text to analyze (default: "text")
- `provider` (str, optional): LLM provider - "claude", "openai", "gemini", "groq", or "bedrock" (default: "groq")
- `model` (str, optional): Model identifier (default: "llama-3.3-70b-versatile")
- `api_key` (str, optional): API key if not set via environment variable
- `output_path` (str, optional): Path to save tagged CSV
- `include_reasoning` (bool, optional): Include detailed reasoning and reflection (default: false)
- `field_name` (str, optional): Name for the classification field (default: "category")

**Returns:** Dictionary with status, tagged data preview, confidence scores, and optional errors

### `tag_csv_advanced`
Advanced multi-dimensional classification with custom taxonomy definitions. Use this for complex tagging with multiple fields.

**Parameters:**
- `csv_path` (str): Path to the CSV file to tag
- `taxonomy` (Dict): Full taxonomy dictionary with field definitions and value descriptions
- `text_column` (str, optional): Column containing text to analyze (default: "text")
- `provider` (str, optional): LLM provider (default: "groq")
- `model` (str, optional): Model identifier (default: "llama-3.3-70b-versatile")
- `api_key` (str, optional): API key if not set via environment variable
- `output_path` (str, optional): Path to save tagged CSV
- `include_reasoning` (bool, optional): Include detailed reasoning (default: false)

**Example Taxonomy:**
```json
{
  "sentiment": {
    "description": "The emotional tone of the text",
    "values": {
      "positive": "Text expresses positive emotions or favorable opinions",
      "negative": "Text expresses negative emotions or unfavorable opinions",
      "neutral": "Text is factual and objective"
    }
  },
  "urgency": {
    "description": "How urgent the content is",
    "values": {
      "high": "Requires immediate attention",
      "medium": "Should be addressed soon",
      "low": "Can be addressed at any time"
    }
  }
}
```

**Returns:** Dictionary with status, all field values, confidence scores per field, and optional reasoning

### `preview_csv`
Preview the first few rows of a CSV file to understand its structure.

**Parameters:**
- `csv_path` (str): Path to the CSV file
- `rows` (int, optional): Number of rows to preview (default: 5)

**Returns:** Dictionary with columns, row count, and preview data

### `get_tagging_info`
Get information about the tagging MCP server and supported providers.

**Returns:** Server metadata, supported providers, features, and available tools

## Example Usage

### Basic Tagging

1. **Preview your CSV:**
   ```
   Use preview_csv with csv_path="/path/to/data.csv"
   ```

2. **Simple category tagging:**
   ```
   Use tag_csv with:
   - csv_path="/path/to/data.csv"
   - taxonomy=["technology", "business", "science", "politics"]
   - text_column="description"
   - output_path="/path/to/tagged_output.csv"
   ```

3. **Include reasoning for transparency:**
   ```
   Use tag_csv with:
   - csv_path="/path/to/data.csv"
   - taxonomy=["urgent", "normal", "low_priority"]
   - field_name="priority"
   - include_reasoning=true
   ```

### Advanced Multi-Field Tagging

For complex classification with multiple dimensions:

```
Use tag_csv_advanced with:
- csv_path="/path/to/support_tickets.csv"
- taxonomy={
    "department": {
      "description": "Which department should handle this",
      "values": {
        "sales": "Product inquiries and purchases",
        "support": "Technical issues and bugs",
        "billing": "Payment and account questions"
      }
    },
    "priority": {
      "description": "How urgent this is",
      "values": {
        "urgent": "Service down or critical issue",
        "high": "Significant problem",
        "normal": "Standard request"
      }
    }
  }
- text_column="ticket_description"
- output_path="/path/to/classified_tickets.csv"
```

## Output Structure

### Basic Tagging Output
- Original CSV columns
- `{field_name}`: The selected tag
- `confidence`: Confidence score (0.0 to 1.0)
- `thinking`: Reasoning for each possible value (if `include_reasoning=true`)
- `reflection`: Overall analysis (if `include_reasoning=true`)

### Advanced Tagging Output
- Original CSV columns
- For each taxonomy field:
  - `{field_name}`: Selected value
  - `{field_name}_confidence`: Confidence score
  - `{field_name}_thinking`: Reasoning dict (if enabled)
  - `{field_name}_reflection`: Analysis (if enabled)

## Supported LLM Providers

- **Groq** (Recommended): llama-3.3-70b-versatile, llama-3.1-70b-versatile, mixtral-8x7b-32768
- **Claude (Anthropic)**: claude-3-5-sonnet-20241022, claude-3-opus-20240229
- **OpenAI**: gpt-4, gpt-4-turbo, gpt-3.5-turbo
- **Gemini**: gemini-1.5-pro, gemini-1.5-flash
- **AWS Bedrock**: anthropic.claude-3-sonnet, anthropic.claude-3-haiku

## Key Features

✨ **Detailed Reasoning**: For each tag, see why the model chose it
🔍 **Reflection**: Model reflects on its analysis
📊 **Confidence Scores**: Know how confident each classification is (0.0-1.0)
⚡ **Parallel Processing**: All rows processed concurrently
🎯 **Error Detection**: Automatic error tracking and reporting
🔧 **Flexible**: Simple list or complex multi-field taxonomies

## License

MIT