MCP工具：FreeScout帮助desk票务管理

Prerequisites

• Node.js 18 or higher
• FreeScout instance with API access enabled

Required Environment Variables

Installation

Building for Production

npm run build

FreeScout API Setup

1. Log into your FreeScout instance as an administrator 2. Navigate to Manage → API Keys 3. Create a new API key with appropriate permissions: - View conversations - Update conversations - Create threads (for notes)

Quick Start (Recommended)

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

Usage with Other MCP Clients

Run the server directly:

npm start

Or in development mode with auto-reload:

npm run dev

Workflow Examples

Advanced Configuration Example

For more control, you can specify additional environment variables:

{
  "mcpServers": {
    "freescout": {
      "command": "npx",
      "args": ["@verygoodplugins/mcp-freescout@latest"],
      "env": {
        "FREESCOUT_URL": "https://support.example.com",
        "FREESCOUT_API_KEY": "your-api-key",
        "FREESCOUT_DEFAULT_USER_ID": "2"
      }
    }
  }
}

Configuration

Optional Environment Variables

Complete Ticket Response Workflow

// 1. Analyze the ticket to understand the issue
const analysis = await mcp.callTool('freescout_analyze_ticket', {
  ticket: '12345',
});

// 2. Get ticket context for personalized reply
const context = await mcp.callTool('freescout_get_ticket_context', {
  ticket: '12345',
});

// 3. Create a draft reply directly in FreeScout
await mcp.callTool('freescout_create_draft_reply', {
  ticket: '12345',
  replyText: `Hi ${context.customer.name},

Thank you for reaching out! Based on my analysis, I can see that ${analysis.issueDescription}.

Here's what I found:

1. **Issue Type**: ${analysis.isBug ? 'Bug' : 'Configuration/Feature Request'}
2. **Root Cause**: ${analysis.rootCause || 'Under investigation'}

I'll look into this and get back to you shortly with a solution.

Best regards,
[Your name]`,
  cc: ['billing@example.com'],
});

// 4. Update ticket status and assignment
await mcp.callTool('freescout_update_ticket', {
  ticket: '12345',
  status: 'active',
  assignTo: 1,
});

// 5. Add an internal note with findings
await mcp.callTool('freescout_add_note', {
  ticket: '12345',
  note: `Analysis complete:
- Is Bug: ${analysis.isBug}
- Third-party Issue: ${analysis.isThirdPartyIssue}
- Root Cause: ${analysis.rootCause}`,
});

Draft Reply Workflow

// 1. Get ticket context for personalized reply
const context = await mcp.callTool('freescout_get_ticket_context', {
  ticket: '34811',
});

// 2. Create draft reply in FreeScout (LLM crafts the content)
await mcp.callTool('freescout_create_draft_reply', {
  ticket: '34811',
  replyText: `Hi ${context.customer.name},

Thank you for reporting the HighLevel OAuth authorization issue! Your experience with the EngageBay LiveChat plugin conflict has been really valuable.

Based on what we learned from your case, I've added a new plugin conflict detection system to WP Fusion. In the next update (v3.46.7), users will see:

🔍 **Plugin Conflict Detection**
- Automatic detection of known conflicting plugins  
- Warning messages before HighLevel authorization
- Clear guidance when conflicts are detected

This should prevent the confusion you experienced and help other users avoid similar issues.

The update should be available within the next few weeks. Thanks for your patience and for helping us improve the plugin!

Best regards,
Jack`,
  to: ['primary@example.com'],
  cc: ['teammate@example.com'],
});

// The draft is now saved in FreeScout and can be reviewed/edited before sending

Components

1. FreeScout API Client (freescout-api.ts) - Handles all API communication with FreeScout - Manages authentication and request formatting - Provides ticket parsing utilities

2. Ticket Analyzer (ticket-analyzer.ts) - Intelligent ticket content analysis - Issue classification (bug vs feature vs configuration) - Code snippet and error extraction - Root cause determination

3. MCP Server (index.ts) - Tool registration and request handling - Integration with Git for worktree management - Response formatting and error handling

Manual Installation (Alternative)

If you prefer to install and run the server locally:

1. Clone this repository:

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

1. Install dependencies:

npm install

1. Build the TypeScript code:

npm run build

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

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

Troubleshooting