From cb341fbdc24660161453ed580d99f97e1c85eb69 Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 06:59:48 -0500 Subject: [PATCH] Rebrand to MCPEngage + deep Freshdesk customization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix all MCPEngine โ†’ MCPEngage references - Add Freshdesk-specific Power Moves (5 support/helpdesk use cases) - Correct tool count (8 REST API tools) with accurate descriptions - Add support-specific prompts (triaging, SLA management, KB gaps) - Document Freshdesk API key authentication (Basic Auth) - Link to official Freshdesk API v2 docs - Update .env.example with FRESHDESK_DOMAIN requirement - Add rate limiting & status code troubleshooting --- .env.example | 2 + README.md | 207 +++++++++++++++++++++++++++++++++++++-------------- package.json | 2 +- 3 files changed, 153 insertions(+), 58 deletions(-) diff --git a/.env.example b/.env.example index 9d01739..3bad6e2 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,4 @@ # Freshdesk API Credentials +# Find your API key: Profile Settings โ†’ View API Key FRESHDESK_API_KEY=your-api-key-here +FRESHDESK_DOMAIN=yourcompany diff --git a/README.md b/README.md index 14c0b91..7dd1d81 100644 --- a/README.md +++ b/README.md @@ -4,34 +4,61 @@ --- -# ๐Ÿš€ Freshdesk MCP Server โ€” 2026 Complete Version +# ๐ŸŽซ Freshdesk MCP Server โ€” AI-Native Support Operations ## ๐Ÿ’ก What This Unlocks -**This MCP server gives AI direct access to your entire Freshdesk workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**Turn Claude into your L1 support engineer.** This MCP server gives AI direct access to your Freshdesk helpdeskโ€”triaging tickets, drafting responses, managing contacts, and surfacing insightsโ€”all through natural language commands. ### ๐ŸŽฏ Freshdesk-Native Power Moves -The AI can directly control your Freshdesk account with natural language: +Real support workflows you can automate instantly: -- **Smart automation** โ€” Complex workflows in plain English -- **Data intelligence** โ€” Query, analyze, and export your Freshdesk data -- **Rapid operations** โ€” Bulk actions that would take hours manually -- **Cross-platform integration** โ€” Combine Freshdesk with other tools seamlessly +1. **Morning ticket triage ritual** + *"Show me all new tickets from the past 12 hours, categorize by urgency, assign high-priority ones to our senior agents, and draft acknowledgment replies for the rest."* + โ†’ Automate the first hour of your support day. + +2. **Customer sentiment analysis** + *"Search all tickets from customer email 'john@acme.com', analyze tone across conversations, flag any escalating frustration, suggest proactive outreach strategies."* + โ†’ Turn ticket history into relationship intelligence. + +3. **SLA compliance sweep** + *"List all tickets approaching SLA breach (< 2 hours remaining), group by priority, draft urgent response templates, notify assigned agents via their email."* + โ†’ Prevent SLA violations before they happen. + +4. **Knowledge base gap detection** + *"Search tickets for recurring phrases like 'how do I', 'can't figure out', 'doesn't work'โ€”identify top 10 repeat questions, draft KB articles for each, assign to documentation team."* + โ†’ Data-driven knowledge base strategy. + +5. **Bulk ticket cleanup operations** + *"Find all 'Waiting on Customer' tickets older than 14 days with no response, send polite check-in messages, update status to 'Pending', tag for closure in 7 days if still no reply."* + โ†’ Automated ticket hygiene without manual busywork. ### ๐Ÿ”— The Real Power: Combining Tools -AI can chain multiple Freshdesk operations together: +Claude orchestrates multi-step support workflows: -- Query data โ†’ Filter results โ†’ Generate reports -- Search records โ†’ Update fields โ†’ Notify team -- Analyze metrics โ†’ Create tasks โ†’ Schedule follow-ups +- `search_tickets` (keyword/tag) โ†’ `get_ticket` (details) โ†’ `reply_ticket` (drafted response) +- `list_tickets` (filtered by status) โ†’ `update_ticket` (bulk status changes) +- `list_contacts` โ†’ enrich with ticket history โ†’ identify VIP customers +- `create_ticket` โ†’ assign to agent โ†’ add private note with context ## ๐Ÿ“ฆ What's Inside -**73 API tools** covering the entire Freshdesk platform (Support & Helpdesk). +**8 REST API tools** covering core Freshdesk support operations: -All with proper error handling, automatic authentication, and TypeScript types. +| Tool | Purpose | +|------|---------| +| `list_tickets` | Query tickets with filters (status, priority, agent, date) | +| `get_ticket` | Full ticket details including conversations & metadata | +| `create_ticket` | Generate new tickets from any source with custom fields | +| `update_ticket` | Modify ticket properties (status, priority, assignment, tags) | +| `reply_ticket` | Add public replies or private notes to tickets | +| `list_contacts` | Browse contact/requester directory with search | +| `list_agents` | View agent roster with availability & roles | +| `search_tickets` | Advanced search with Freshdesk query language | + +All with proper **Basic Auth** handling, error management, and TypeScript types. ## ๐Ÿš€ Quick Start @@ -45,12 +72,15 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Freshdesk API credentials** (see Authentication section below) +2. **Get your Freshdesk API credentials:** + - Log in to your Freshdesk account + - Go to **Profile Settings** โ†’ **View API Key** (right sidebar) + - Copy your API key (long alphanumeric string) + - Note your **Freshdesk domain** (e.g., `yourcompany` from `yourcompany.freshdesk.com`) 3. **Configure Claude Desktop:** - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - + On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` On Windows: `%APPDATA%\Claude\claude_desktop_config.json` ```json @@ -58,58 +88,87 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "freshdesk": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/freshdesk-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/freshdesk-mcp-2026-complete/dist/index.js"], "env": { - "FRESHDESK_API_KEY": "your-api-key-here" + "FRESHDESK_API_KEY": "your_api_key_here", + "FRESHDESK_DOMAIN": "yourcompany" } } } } ``` -4. **Restart Claude Desktop** +4. **Restart Claude Desktop** + You'll see the ๐Ÿ”Œ icon with Freshdesk tools available. -### Option 2: Deploy to Railway - -[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/freshdesk-mcp) - -1. Click the button above -2. Set your Freshdesk API credentials in Railway dashboard -3. Use the Railway URL as your MCP server endpoint - -### Option 3: Docker +### Option 2: Docker ```bash docker build -t freshdesk-mcp . -docker run -p 3000:3000 \ - -e FRESHDESK_API_KEY=your-key \ +docker run \ + -e FRESHDESK_API_KEY=your_key_here \ + -e FRESHDESK_DOMAIN=yourcompany \ freshdesk-mcp ``` ## ๐Ÿ” Authentication -See the official [Freshdesk API documentation](https://docs.freshdesk.com) for authentication details. +Freshdesk uses **API Key authentication** (HTTP Basic Auth): -The MCP server handles token refresh automatically. +1. **Find your API key:** Profile Settings โ†’ View API Key (or regenerate if needed) +2. **API Key format:** Long alphanumeric string (treat like a password) +3. **Authentication method:** Basic Auth with API key as username, "X" as password (handled automatically by MCP server) + +**Security notes:** +- API keys have same permissions as your user account (admin keys = full access) +- Never commit API keys to version control +- Rotate keys regularly from Freshdesk settings +- Use environment variables or secrets management for production + +**Rate limits:** Freshdesk enforces rate limits based on plan: +- **Estate/Forest plans:** 50,000 API calls/hour +- **Garden plans:** 1,000 API calls/hour +- **Sprout/Blossom plans:** Varies by plan ## ๐ŸŽฏ Example Prompts -Once connected to Claude, you can use natural language. Examples: +Once connected to Claude, use natural language for support operations: -- *"Show me recent activity in Freshdesk"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +### Ticket Management +- *"Show me all new tickets from the past 24 hours, sorted by priority."* +- *"Create a ticket from customer john@acme.com: subject 'Login issues', description 'User can't access dashboard', priority High, assign to the Mobile team."* +- *"Update ticket #12345 to status Resolved, add tag 'billing-issue', and assign to the Billing group."* + +### Ticket Responses +- *"Reply to ticket #789 with: 'Thanks for reaching out! I've escalated this to our engineering team. You'll hear back within 24 hours.' Mark as Pending."* +- *"Add a private note to ticket #456: 'Customer is VIP accountโ€”prioritize and offer phone support if needed.'"* + +### Searching & Analysis +- *"Search for all tickets with tag 'bug' that are still open, created in the past 7 days."* +- *"Find tickets containing 'refund request' in the description, show me the top 5 by creation date."* +- *"Search for tickets assigned to agent sarah@company.com with status 'Waiting on Customer' for more than 5 days."* + +### Contact & Agent Management +- *"List all contacts whose email contains '@enterprise.com' and show their ticket history."* +- *"Show me all active agents, their email addresses, and current ticket workload."* + +### Bulk Operations +- *"Find all tickets tagged 'needs-followup' that are older than 3 days, send a check-in message to each customer asking if issue is resolved."* +- *"List all tickets with priority 4 (Urgent) that don't have an assigned agentโ€”distribute evenly across available agents."* + +### Intelligence Extraction +- *"Analyze all resolved tickets from the past month, extract common issues, rank by frequency, generate a report."* +- *"Which agent has the fastest average response time this week? Show stats for top 5 agents."* +- *"Identify tickets that have been reopened multiple timesโ€”flag for process improvement review."* ## ๐Ÿ› ๏ธ Development ### Prerequisites - Node.js 18+ - npm or yarn -- Freshdesk account with API access +- Freshdesk account with API access enabled -### Setup +### Local Setup ```bash git clone https://github.com/BusyBee3333/Freshdesk-MCP-2026-Complete.git @@ -118,7 +177,7 @@ npm install cp .env.example .env # Edit .env with your Freshdesk credentials npm run build -npm start +npm run dev ``` ### Testing @@ -129,44 +188,78 @@ npm run test:watch # Watch mode npm run test:coverage # Coverage report ``` +### Testing with Freshdesk Sandbox + +Freshdesk offers a **sandbox environment** for testing: +- Clone your production helpdesk to sandbox in admin settings +- Use sandbox domain (`yourcompany-sandbox.freshdesk.com`) +- Test MCP operations without affecting live tickets + ## ๐Ÿ› Troubleshooting -### "Authentication failed" -- Verify your API credentials are correct -- Check that your API key hasn't been revoked -- Ensure you have the necessary permissions +### "Authentication failed" / 401 error +- **API key incorrect:** Double-check you copied the full key from Profile Settings +- **Domain mismatch:** Ensure `FRESHDESK_DOMAIN` matches your actual subdomain (without `.freshdesk.com`) +- **Key revoked:** If you regenerated your API key, update the environment variable +- **Insufficient permissions:** Some operations require admin/agent roles ### "Tools not appearing in Claude" -- Restart Claude Desktop after updating config -- Check that the path in `claude_desktop_config.json` is absolute -- Verify the build completed successfully (`dist/index.js` exists) +- **Restart required:** Always restart Claude Desktop after config changes +- **Absolute paths:** Use full paths in config (no `~` or relative paths) +- **Build check:** Verify `dist/index.js` exists after running `npm run build` + +### "Rate limit exceeded" / 429 error +- **Check your plan:** Freshdesk limits API calls based on subscription tier +- **Throttle requests:** Add delays between bulk operations +- **Monitor usage:** Check API call consumption in Freshdesk admin settings + +### Ticket operation errors +- **Invalid IDs:** Freshdesk uses numeric ticket IDs (not strings) +- **Status codes:** Use numeric status values (2=Open, 3=Pending, 4=Resolved, 5=Closed) +- **Custom fields:** Check your helpdesk's custom field configuration for valid field names +- **Email validation:** Requester email must be valid format for ticket creation ## ๐Ÿ“– Resources -- [Freshdesk API Documentation](https://docs.freshdesk.com) -- [MCP Protocol Specification](https://modelcontextprotocol.io/) -- [Claude Desktop Documentation](https://claude.ai/desktop) +- **[Freshdesk API v2 Docs](https://developers.freshdesk.com/api/)** โ€” Official REST API reference +- **[API Authentication Guide](https://developers.freshdesk.com/api/#authentication)** โ€” How to use API keys +- **[Tickets API](https://developers.freshdesk.com/api/#tickets)** โ€” Create, update, search tickets +- **[Contacts API](https://developers.freshdesk.com/api/#contacts)** โ€” Manage requesters +- **[Search Syntax](https://developers.freshdesk.com/api/#filter_tickets)** โ€” Advanced search query language +- **[Webhooks](https://developers.freshdesk.com/api/#webhooks)** โ€” Real-time event notifications +- **[MCP Protocol Specification](https://modelcontextprotocol.io/)** โ€” How MCP servers work +- **[Claude Desktop Documentation](https://claude.ai/desktop)** โ€” Desktop app setup ## ๐Ÿค Contributing -Contributions are welcome! Please: +Contributions welcome! To add features: 1. Fork the repo -2. Create a feature branch (`git checkout -b feature/amazing-tool`) -3. Commit your changes (`git commit -m 'Add amazing tool'`) -4. Push to the branch (`git push origin feature/amazing-tool`) +2. Create a feature branch (`git checkout -b feature/ticket-merge`) +3. Commit your changes (`git commit -m 'Add ticket merge capability'`) +4. Push to the branch (`git push origin feature/ticket-merge`) 5. Open a Pull Request +**Ideas for contributions:** +- Support for ticket attachments (file uploads) +- Custom field management helpers +- Group & company management tools +- Time tracking integration +- Satisfaction survey response parsing +- Canned response library integration +- Ticket merge/split operations +- SLA policy management + ## ๐Ÿ“„ License MIT License - see [LICENSE](LICENSE) for details ## ๐Ÿ™ Credits -Built by [MCPEngine](https://mcpengage.com) โ€” AI infrastructure for business software. +Built by [MCPEngage](https://mcpengage.com) โ€” AI infrastructure for business software. Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms. --- -**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine). +**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage). diff --git a/package.json b/package.json index fe6cb96..80405ce 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Freshdesk API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",