mcp-freescout

# FreeScout MCP Server

An MCP (Model Context Protocol) server for FreeScout helpdesk ticket management. This server provides tools to interact with FreeScout tickets, analyze issues, and manage customer responses.

## Features

- 🎫 **Ticket Management**: Fetch, analyze, and update FreeScout tickets
- 🔍 **Intelligent Analysis**: Automatically analyze tickets to determine issue type, root cause, and solutions
- 💬 **Draft Responses**: Generate customer replies based on ticket analysis
- 📊 **Advanced Search**: First-class filter parameters with relative time support ("7d", "24h")
- 🔒 **Type Safety**: Full Zod schema validation with structured outputs
- 🔁 **Reliability**: Automatic retry logic with exponential backoff for transient failures
- ⚡ **Protocol-ready stdio**: A fresh `buildServer` factory serves both 2025-era and 2026 MCP stdio clients

## v3 runtime

- Requires Node.js 24 or newer.
- Uses `@modelcontextprotocol/server` 2.x with Zod 4 input schemas.
- Serves both the 2025 legacy handshake and the 2026 stdio protocol from the same server factory.
- Delivers `structuredContent` for stable analysis and write-operation results without declaring output schemas.
- Accepts FreeScout's successful `204 No Content` update responses and records the user ID that initiated a ticket update.

## Installation

### Prerequisites

- Node.js 24 or higher
- FreeScout instance with API access enabled

## Quick Start (Recommended)

The easiest way to use this MCP server is with `npx`:

### With Claude Desktop

Add this to your Claude Desktop settings (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "freescout": {
      "command": "npx",
      "args": ["@verygoodplugins/mcp-freescout@latest"],
      "env": {
        "FREESCOUT_URL": "https://your-freescout-domain.com",
        "FREESCOUT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### With Cursor IDE

Add this to your Cursor MCP settings:

**Method 1: Via Cursor Settings UI**

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Search for "MCP"
3. Click "Edit in settings.json"
4. Add the MCP server configuration

**Method 2: Manual Configuration**
Add this to your Cursor settings.json or create `~/.cursor/mcp.json`:

```json
{
  "mcp": {
    "servers": {
      "freescout": {
        "command": "npx",
        "args": ["@verygoodplugins/mcp-freescout@latest"],
        "env": {
          "FREESCOUT_URL": "https://your-freescout-domain.com",
          "FREESCOUT_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}
```

The server communicates only with the FreeScout instance configured in its environment.

## Manual Installation (Alternative)

If you prefer to install and run the server locally:

1. Clone this repository:

```bash
git clone https://github.com/verygoodplugins/mcp-freescout.git
cd mcp-freescout
```

2. Install dependencies:

```bash
npm install
```

3. Build the TypeScript code:

```bash
npm run build
```

4. Configure your MCP client to use the local installation:

```json
{
  "mcpServers": {
    "freescout": {
      "command": "node",
      "args": ["/path/to/mcp-freescout/dist/index.js"],
      "env": {
        "FREESCOUT_URL": "https://your-freescout-domain.com",
        "FREESCOUT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Usage with Other MCP Clients

Run the server directly:

```bash
npm start
```

Or in development mode with auto-reload:

```bash
npm run dev
```

## Available Tools

### Core Ticket Operations

#### `freescout_get_ticket`

Fetch a FreeScout ticket with all its details and conversation threads.

**Parameters:**

- `ticket` (required): Ticket ID, number, or FreeScout URL
- `includeThreads` (optional): Include conversation threads (default: true)

**Natural Language Examples:**

- "Show me ticket #12345"
- "Get the details for FreeScout ticket 34811"
- "Fetch ticket https://support.example.com/conversation/12345"
- "What's in ticket 12345?"
- "Pull up the conversation for ticket #34811"

**Example:**

```javascript
{
  "ticket": "12345",
  "includeThreads": true
}
```

**Example: Fetching a FreeScout ticket with conversation threads**

![FreeScout ticket details and conversation threads displayed in Cursor chat interface](https://github.com/user-attachments/assets/0144056d-f6d6-4275-9f55-dade0be3ba8c)

#### `freescout_analyze_ticket`

Analyze a ticket to determine issue type, root cause, and suggested solutions.

**Parameters:**

- `ticket` (required): Ticket ID, number, or FreeScout URL

**Natural Language Examples:**

- "Analyze ticket #12345"
- "What kind of issue is ticket 34811?"
- "Can you analyze this ticket and tell me if it's a bug?"
- "Examine ticket #12345 and determine the root cause"
- "Is this ticket a bug or feature request?"

**Returns:**

- Customer information
- Issue description and classification
- Code snippets and error messages
- Reproducibility status
- Root cause analysis
- Bug vs feature request vs third-party issue determination

**Example: Intelligent ticket analysis with issue classification**

![Ticket analysis showing issue type, root cause, and implementation recommendations](https://github.com/user-attachments/assets/19080021-1f29-45a4-8601-556b55d379c3)

#### `freescout_add_note`

Add an internal note to a ticket for team communication.

**Parameters:**

- `ticket` (required): Ticket ID, number, or FreeScout URL
- `note` (required): The note content
- `userId` (optional): User ID for the note (defaults to env setting)

**Natural Language Examples:**

- "Add a note to ticket #12345 saying 'Reproduced on staging'"
- "Leave an internal note on this ticket"
- "Add a team note: 'Customer confirmed fix works'"
- "Note on ticket 34811: 'Escalating to development team'"
- "Add internal documentation to this ticket"

#### `freescout_update_ticket`

Update ticket status and/or assignment.

**Parameters:**

- `ticket` (required): Ticket ID, number, or FreeScout URL
- `status` (optional): New status ('active', 'pending', 'closed', 'spam')
- `assignTo` (optional): User ID to assign the ticket to

**Natural Language Examples:**

- "Close ticket #12345"
- "Mark ticket 34811 as pending"
- "Assign this ticket to user ID 2"
- "Set ticket status to active"
- "Update ticket #12345 status to closed and assign to user 1"

#### `freescout_create_draft_reply`

Create a draft reply in FreeScout that can be edited before sending. This tool lets the LLM generate the reply content and saves it directly to FreeScout as a draft. **Automatically converts Markdown formatting to HTML** for proper display in FreeScout.

**Parameters:**

- `ticket` (required): Ticket ID, number, or FreeScout URL
- `replyText` (required): The draft reply content (generated by the LLM, supports Markdown formatting)
- `userId` (optional): User ID creating the draft (defaults to env setting)
- `to` (optional): List of TO recipients. Omit to preserve existing recipients; pass `[]` to clear.
- `cc` (optional): List of CC recipients. Omit to preserve existing recipients; pass `[]` to clear.
- `bcc` (optional): List of BCC recipients. Omit to preserve existing recipients; pass `[]` to clear.

**Natural Language Examples:**

- "Create a draft reply for ticket #12345"
- "Draft a customer response for this ticket"
- "Generate and save a draft reply explaining the fix"
- "Write a draft response to the customer for ticket 34811"
- "Create a draft reply thanking the customer and explaining the solution"

If recipient fields are omitted, the server preserves the current conversation recipients from FreeScout when available. If FreeScout does not expose existing `to` recipients on the conversation, its normal default customer recipient behavior is preserved.

**Markdown Support:**

- **Bold text**: `**text**` or `__text__` → **text**
- _Italic text_: `*text*` or `_text_` → _text_
- `Code`: `` `code` `` → `code`
- Numbered lists: `1. item` → proper ordered lists
- Bullet lists: `- item` or `* item` → proper unordered lists
- Line breaks: Double newlines create paragraphs, single newlines create line breaks

**Workflow:**

1. Use `freescout_get_ticket_context` to get customer info and ticket details
2. Let the LLM craft a personalized reply using Markdown formatting
3. Use `freescout_create_draft_reply` to save the draft in FreeScout (Markdown automatically converted to HTML)
4. Review and edit the draft in FreeScout before sending

**Example: Draft reply workflow with personalized customer response**

![Draft reply generation showing personalized customer message with ticket context](https://github.com/user-attachments/assets/a4f9eb6c-3204-4744-8aed-8d16d7c7641c)

![Draft reply automatically saved to FreeScout](https://github.com/user-attachments/assets/689bd675-cb34-414e-b18f-d50d4424ace6)

#### `freescout_get_ticket_context`

Get ticket context and customer information to help craft personalized replies.

**Parameters:**

- `ticket` (required): Ticket ID, number, or FreeScout URL

**Natural Language Examples:**

- "Get context for ticket #12345 to write a reply"
- "I need customer info and ticket details for drafting a response"
- "Gather context for this ticket so I can write a personalized reply"
- "Pull customer information and issue details for ticket 34811"
- "Get ticket context to help craft a customer response"

**Returns:**

- Customer name and email
- Ticket subject and status
- Issue description and analysis
- Recent customer and team messages
- Analysis results (bug vs feature vs third-party issue)

#### `freescout_search_tickets`

Search for tickets across your FreeScout instance.

**Parameters:**

- `query` (required): Search query
- `status` (optional): Filter by status ('active', 'pending', 'closed', 'spam', 'all')
- `mailboxId` (optional): Filter by specific mailbox ID (searches all mailboxes if not specified)

**Natural Language Examples:**

- "Search for tickets containing 'OAuth error'"
- "Find all pending tickets with 'HighLevel' in them"
- "Search for closed tickets