Rebrand MCPEngine → MCPEngage + add support-specific content and OAuth details

2026-02-02 06:59:36 -05:00 · 2026-02-02 06:59:36 -05:00 · 9c05a729d5
commit 9c05a729d5
parent 9551b34a84
3 changed files with 70 additions and 32 deletions
--- 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/
--- 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).
--- 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 <hello@mcpengage.com>",
+  "author": "MCPEngage <hello@mcpengage.com>",
  "license": "MIT",
  "repository": {
    "type": "git",