# AutoTask MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with access to AutoTask PSA data, enabling intelligent ticket management and analysis.

## Features

### Core Functionality
- **Natural Language Queries**: Query tickets using plain English ("show me new tickets in helpdesk")
- **Smart Caching**: 7-day persistent cache for queue/status/priority mappings
- **Bulk Export**: Export tickets to CSV, JSON, or JSONL formats without loading into context
- **Date Range Filtering**: Query tickets by creation date, last activity, etc.
- **Rich Data Access**: Include ticket notes, time entries, and company information

### Available Tools
- `autotask_metadata_refresh` - Refresh cached metadata
- `autotask_metadata_get` - View current cached values
- `autotask_queue_list` - List all ticket queues
- `autotask_ticket_query` - Natural language ticket search
- `autotask_ticket_query_structured` - Structured queries for local LLMs
- `autotask_ticket_export` - Export tickets to files
- `autotask_ticket_get` - Get detailed ticket information
- `autotask_ticket_update` - Update ticket properties
- `autotask_ticket_add_note` - Add notes to tickets
- `autotask_companies_list` - List companies
- `autotask_resources_list` - List technicians/resources

## Setup

1. **Install dependencies**:
   ```bash
   cd /Users/admin/Documents/GitHub_James/mcp-autotask
   python -m venv .venv
   source .venv/bin/activate  # or .venv\Scripts\activate on Windows
   pip install -r requirements.txt
   ```

2. **Configure environment**:
   Create `.env` file with:
   ```
   AUTOTASK_API_USER=your_username
   AUTOTASK_API_SECRET=your_secret
   AUTOTASK_API_INTEGRATION_CODE=your_code
   ```

3. **Add to Claude Desktop**:
   In `claude_desktop_config.json`:
   ```json
   {
     "mcpServers": {
       "autotask": {
         "command": "/path/to/.venv/bin/python",
         "args": ["/path/to/server.py"]
       }
     }
   }
   ```

## Usage Examples

### Query Tickets
```
"Show me new tickets in the helpdesk queue"
"Find high priority tickets from last week"
"List unassigned tickets"
```

### Export Data
```
"Export last 50 completed helpdesk tickets to CSV"
"Export all tickets from June 2025 with time entries"
"Create training data from resolved tickets"
```

### Update Tickets
```
"Update ticket T20250601.0001 status to complete"
"Add a note to ticket 12345"
"Change priority to high for ticket T20250601.0002"
```

## Architecture

- **FastMCP Server**: Handles MCP protocol and tool registration
- **Dynamic Cache**: Stores AutoTask metadata with 7-day TTL
- **Query Builder**: Modular filter construction system
- **Export System**: Handles CSV/JSON/JSONL exports
- **Natural Language Parser**: Converts English to API queries

## Recent Updates (July 2025)

- Converted from Node.js to Python
- Implemented FastMCP for simpler server architecture
- Added dynamic metadata caching system
- Fixed query format issues (filter vs filters)
- Added bulk export functionality
- Improved null handling in CSV exports
- Created modular QueryBuilder for filter management

## Directory Structure
```
mcp-autotask/
├── server.py              # Main MCP server
├── src/
│   ├── api/
│   │   └── autotask.py   # AutoTask API client
│   ├── utils/
│   │   ├── cache.py      # Metadata caching
│   │   ├── query_builder.py # Filter construction
│   │   └── ticket_exporter.py # Export functionality
│   └── tools/            # Tool implementations
├── cache/                # Persistent metadata cache
├── exports/             # Exported CSV/JSON files
└── scripts/
    └── init_cache.py    # Cache initialization
```

## Future Enhancements
- RAG database for ticket knowledge
- LLM fine-tuning on ticket data
- Automated ticket resolution suggestions
- Integration with claude-crew-2 for orchestration