# troi-mcp

MCP server that connects AI assistants to [Troi](https://www.troi.de/) project management, time tracking, and offer creation. Works with any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.).

## Features

- **49 tools** covering projects, offers, time tracking, contacts, customers, and more
- **Server-enforced permission layer** — all write operations return a preview first; re-call with `confirmed=true` to execute
- **Irreversible action protection** — offer number generation and approval submission get extra warnings
- **Price list integration** — create offers directly from your Troi price list
- **Compound tools** — `troi_create_offer` builds a complete project with phases and positions in one call

## Setup

### Quick Install (macOS, AirLST team)

The **AirLST MCP Installer** app handles everything automatically: installs `uv`, configures Claude Desktop, and sets up Troi (and optionally Pipedrive) with a guided UI.

1. Download `AirLST MCP Installer.app` from your team
2. Double-click to run — follow the prompts to enter your Troi credentials
3. Restart Claude Desktop (Cmd+Q, then reopen)

To compile the installer from source:

```bash
osacompile -o "AirLST MCP Installer.app" install-airlst-mcp.applescript
```

### Manual Setup

#### 1. Install

```bash
pip install troi-mcp
```

#### 2. Get your Troi API key

Troi &rarr; Menu (top left) &rarr; **Sicherheitscenter** &rarr; **API v2 - Basic** &rarr; copy the Token.

The Sicherheitscenter shows 3 sections — you only need the token from the first one (**API v2 - Basic**).
The server uses HTTP Basic Auth (`TROI_USER` + `TROI_API_KEY`).

#### 3. Add to your MCP client config

**Claude Desktop** &mdash; edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "troi": {
      "command": "uvx",
      "args": ["--upgrade", "troi-mcp"],
      "env": {
        "TROI_URL": "https://yourcompany.troi.software",
        "TROI_USER": "j.doe",
        "TROI_API_KEY": "your-api-key",
        "TROI_CLIENT_ID": "1"
      }
    }
  }
}
```

**Claude Code** &mdash; add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "troi": {
      "command": "uvx",
      "args": ["--upgrade", "troi-mcp"],
      "env": {
        "TROI_URL": "https://yourcompany.troi.software",
        "TROI_USER": "j.doe",
        "TROI_API_KEY": "your-api-key",
        "TROI_CLIENT_ID": "1"
      }
    }
  }
}
```

> **Note:** `TROI_USER` is your Troi login name (e.g. `j.doe`), *not* your email address. `TROI_CLIENT_ID` is usually `1` (single-tenant setups).

#### 4. Restart your MCP client

The Troi tools will be available automatically.

## Available Tools (49)

### Projects & Subprojects

| Tool | Description |
|------|-------------|
| `troi_list_projects` | List/search projects with filters |
| `troi_get_project` | Get project details |
| `troi_create_project` | Create a new project |
| `troi_update_project` | Update project properties |
| `troi_delete_project` | Delete a project |
| `troi_list_subprojects` | List subprojects (phases) |
| `troi_get_subproject` | Get subproject details |
| `troi_create_subproject` | Create a subproject |
| `troi_update_subproject` | Update a subproject |
| `troi_delete_subproject` | Delete a subproject |

### Calculation Positions & Price Lists

| Tool | Description |
|------|-------------|
| `troi_list_positions` | List calculation positions (budget items) |
| `troi_get_position` | Get position details |
| `troi_create_position` | Create a position manually |
| `troi_create_position_from_pricelist` | Create a position from a price list item |
| `troi_update_position` | Update a position |
| `troi_delete_position` | Delete a position |
| `troi_list_pricelist_groups` | List available price lists |
| `troi_list_pricelist_items` | List items in a price list |

### Offers & Documents

| Tool | Description |
|------|-------------|
| `troi_create_offer` | Create a complete offer (project + phases + positions) in one call |
| `troi_get_offer_summary` | Get offer summary with totals |
| `troi_list_documents` | List documents (offers, invoices) |
| `troi_get_document` | Get document details |
| `troi_download_offer_pdf` | Download offer as PDF |
| `troi_generate_offer_number` | Assign an offer number and download PDF *(irreversible)* |
| `troi_start_approval` | Submit offer for approval *(irreversible)* |
| `troi_get_approval_info` | Get available approvers for a document |

### Time Tracking

| Tool | Description |
|------|-------------|
| `troi_list_time_entries` | List booked hours |
| `troi_get_time_entry` | Get time entry details |
| `troi_create_time_entry` | Book time |
| `troi_update_time_entry` | Update a time entry |
| `troi_delete_time_entry` | Delete a time entry |

### Contacts & Customers

| Tool | Description |
|------|-------------|
| `troi_list_contacts` | List/search contacts |
| `troi_get_contact` | Get contact details |
| `troi_create_contact` | Create a contact (company or person) |
| `troi_update_contact` | Update a contact |
| `troi_list_customers` | List customers (Auftraggeber) |
| `troi_get_customer` | Get customer details |
| `troi_create_customer` | Create a customer linked to a contact |
| `troi_update_customer` | Update a customer |
| `troi_create_customer_with_contact` | Create company contact + customer in one call |

### Reference Data

| Tool | Description |
|------|-------------|
| `troi_list_employees` | List employees |
| `troi_get_employee` | Get employee details |
| `troi_list_clients` | List clients (Mandanten) |
| `troi_get_client` | Get client details |
| `troi_list_absences` | List absences (vacation, sick days) |
| `troi_list_calendar_events` | List calendar events |
| `troi_list_project_types` | List project types |
| `troi_list_project_statuses` | List project statuses |
| `troi_list_units` | List units (hours, days, etc.) |
| `troi_list_booking_years` | List booking years |

## Permission Layer

All 21 write operations are server-enforced:

1. **Call without `confirmed`** &rarr; server returns a preview of what would happen, no API call is made
2. **Call with `confirmed: true`** &rarr; server executes the operation

Two tools are classified as **irreversible** and display extra warnings:
- `troi_generate_offer_number` &mdash; assigns a permanent offer number
- `troi_start_approval` &mdash; submits a document for approval

This works with any MCP client, no special sampling or UI support required.

## License

MIT
