diff --git a/.env.example b/.env.example index 9a8f67e..1df0518 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,8 @@ -# Help Scout API Credentials -HELP_SCOUT_API_KEY=your-api-key-here +# Help Scout API Configuration +# Get your API credentials from: Help Scout → Your Profile → My Apps + +# Your Help Scout OAuth access token or API key +# Use OAuth 2.0 (recommended) or API key authentication +HELPSCOUT_ACCESS_TOKEN=your_access_token_or_api_key_here + +# API Documentation: https://developer.helpscout.com/mailbox-api/overview/authentication/ diff --git a/README.md b/README.md index b95755f..cfd25db 100644 --- a/README.md +++ b/README.md @@ -10,28 +10,42 @@ **This MCP server gives AI direct access to your entire Help Scout workspace.** Instead of clicking through interfaces, you just *tell* it what you need. -### 🎯 Help Scout-Native Power Moves +### 🎯 Customer Support Power Moves with Help Scout The AI can directly control your Help Scout account with natural language: -- **Smart automation** — Complex workflows in plain English -- **Data intelligence** — Query, analyze, and export your Help Scout data -- **Rapid operations** — Bulk actions that would take hours manually -- **Cross-platform integration** — Combine Help Scout with other tools seamlessly +1. **Smart Triage** — "Find all open conversations tagged 'urgent' or 'billing' from the last 24 hours, summarize each issue, and suggest priority order" + +2. **Customer Intelligence** — "Pull Sarah Johnson's conversation history, identify recurring issues, check response times, and generate a support quality report" + +3. **Automated Responses** — "Search for conversations about 'password reset', draft personalized replies based on our help docs, and mark them as pending" + +4. **Team Performance** — "List all conversations closed last week, group by assigned agent, calculate average response times, and identify top performers" + +5. **Knowledge Mining** — "Find the 20 most common questions from the 'Technical Support' mailbox this month and suggest new help articles to write" ### 🔗 The Real Power: Combining Tools AI can chain multiple Help Scout operations together: -- Query data → Filter results → Generate reports -- Search records → Update fields → Notify team -- Analyze metrics → Create tasks → Schedule follow-ups +- Search conversations → Identify patterns → Create canned replies +- List customers → Pull conversation history → Generate satisfaction scores +- Monitor mailboxes → Detect SLA breaches → Notify team leads +- Analyze tags → Identify trending issues → Draft internal reports ## 📦 What's Inside -**64 API tools** covering the entire Help Scout platform (Support & Helpdesk). +**7 API tools** covering Help Scout customer support operations: -All with proper error handling, automatic authentication, and TypeScript types. +- `list_conversations` — Browse tickets with filtering by status, mailbox, tags, and assignment +- `get_conversation` — Full conversation thread with customer details and message history +- `create_conversation` — Create new tickets programmatically (for automation) +- `reply_conversation` — Reply to customers or add internal notes +- `list_customers` — Search and browse customer records +- `list_mailboxes` — Get all mailboxes and their settings +- `search` — Advanced search with Help Scout query syntax + +All with proper error handling, OAuth authentication, and TypeScript types. ## 🚀 Quick Start @@ -45,7 +59,10 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Help Scout API credentials** (see Authentication section below) +2. **Get your Help Scout API credentials:** + - Log into Help Scout → Your Profile → My Apps + - Create OAuth application or generate API key + - Copy your OAuth access token or API key 3. **Configure Claude Desktop:** @@ -58,9 +75,9 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "helpscout": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/helpscout-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/help-scout-mcp-2026-complete/dist/index.js"], "env": { - "HELP_SCOUT_API_KEY": "your-api-key-here" + "HELPSCOUT_ACCESS_TOKEN": "your-access-token-here" } } } @@ -74,7 +91,7 @@ All with proper error handling, automatic authentication, and TypeScript types. [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/helpscout-mcp) 1. Click the button above -2. Set your Help Scout API credentials in Railway dashboard +2. Set `HELPSCOUT_ACCESS_TOKEN` in Railway dashboard 3. Use the Railway URL as your MCP server endpoint ### Option 3: Docker @@ -82,25 +99,36 @@ All with proper error handling, automatic authentication, and TypeScript types. ```bash docker build -t helpscout-mcp . docker run -p 3000:3000 \ - -e HELP_SCOUT_API_KEY=your-key \ + -e HELPSCOUT_ACCESS_TOKEN=your-token \ helpscout-mcp ``` ## 🔐 Authentication -See the official [Help Scout API documentation](https://docs.helpscout.com) for authentication details. +Help Scout uses **OAuth 2.0** or **API Key authentication**. -The MCP server handles token refresh automatically. +**Get your API credentials:** +1. Help Scout → Your Profile → My Apps +2. Create OAuth 2.0 application (recommended) or generate API key +3. For OAuth: complete authorization flow to get access token +4. For API Key: use directly as Bearer token + +**API Documentation:** https://developer.helpscout.com/mailbox-api/ + +The MCP server handles OAuth token refresh automatically. ## 🎯 Example Prompts -Once connected to Claude, you can use natural language. Examples: +Once connected to Claude, you can use natural language. Support-specific examples: -- *"Show me recent activity in Help Scout"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +- *"Show me all open conversations in the 'General Support' mailbox"* +- *"Get conversation #12345 with full thread history"* +- *"Search for conversations about 'refund' from last week"* +- *"List all customers who contacted us more than 5 times this month"* +- *"Find pending conversations tagged 'bug' and assigned to Sarah"* +- *"Create a new conversation from customer john@example.com about account access"* +- *"Reply to conversation #67890 with: 'Thanks for reaching out...'"* +- *"List all mailboxes and their unread counts"* ## 🛠️ Development @@ -132,18 +160,22 @@ npm run test:coverage # Coverage report ## 🐛 Troubleshooting ### "Authentication failed" -- Verify your API credentials are correct -- Check that your API key hasn't been revoked -- Ensure you have the necessary permissions +- Verify your access token is correct +- For OAuth: ensure your token hasn't expired (refresh it) +- For API keys: check that it hasn't been revoked ### "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) +### "Insufficient permissions" +- Ensure your OAuth app has required scopes +- Check that your Help Scout user role has API access enabled + ## 📖 Resources -- [Help Scout API Documentation](https://docs.helpscout.com) +- [Help Scout Mailbox API Documentation](https://developer.helpscout.com/mailbox-api/) - [MCP Protocol Specification](https://modelcontextprotocol.io/) - [Claude Desktop Documentation](https://claude.ai/desktop) @@ -163,10 +195,10 @@ 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 d538ab7..06b98c1 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Help Scout API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",