Rebrand to MCPEngage + deep Freshdesk customization

- 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

@@ -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

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
+1. **Morning ticket triage ritual**  
-- **Data intelligence** — Query, analyze, and export your Freshdesk data
+   *"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."*  
-- **Rapid operations** — Bulk actions that would take hours manually
+   → Automate the first hour of your support day.
-- **Cross-platform integration** — Combine Freshdesk with other tools seamlessly
+
+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_tickets` (keyword/tag) → `get_ticket` (details) → `reply_ticket` (drafted response)
-- Search records → Update fields → Notify team
+- `list_tickets` (filtered by status) → `update_ticket` (bulk status changes)
-- Analyze metrics → Create tasks → Schedule follow-ups
+- `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
+### Option 2: Docker
-
-[![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
 
 ```bash
 docker build -t freshdesk-mcp .
-docker run -p 3000:3000 \
+docker run \
-  -e FRESHDESK_API_KEY=your-key \
+  -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"*
+### Ticket Management
-- *"Create a new record with these details..."*
+- *"Show me all new tickets from the past 24 hours, sorted by priority."*
-- *"Export all data from last month"*
+- *"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 the status of X to Y"*
+- *"Update ticket #12345 to status Resolved, add tag 'billing-issue', and assign to the Billing group."*
-- *"Generate a report of..."*
+
+### 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"
+### "Authentication failed" / 401 error
-- Verify your API credentials are correct
+- **API key incorrect:** Double-check you copied the full key from Profile Settings
-- Check that your API key hasn't been revoked
+- **Domain mismatch:** Ensure `FRESHDESK_DOMAIN` matches your actual subdomain (without `.freshdesk.com`)
-- Ensure you have the necessary permissions
+- **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
+- **Restart required:** Always restart Claude Desktop after config changes
-- Check that the path in `claude_desktop_config.json` is absolute
+- **Absolute paths:** Use full paths in config (no `~` or relative paths)
-- Verify the build completed successfully (`dist/index.js` exists)
+- **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)
+- **[Freshdesk API v2 Docs](https://developers.freshdesk.com/api/)** — Official REST API reference
-- [MCP Protocol Specification](https://modelcontextprotocol.io/)
+- **[API Authentication Guide](https://developers.freshdesk.com/api/#authentication)** — How to use API keys
-- [Claude Desktop Documentation](https://claude.ai/desktop)
+- **[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`)
+2. Create a feature branch (`git checkout -b feature/ticket-merge`)
-3. Commit your changes (`git commit -m 'Add amazing tool'`)
+3. Commit your changes (`git commit -m 'Add ticket merge capability'`)
-4. Push to the branch (`git push origin feature/amazing-tool`)
+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).

package.json

@@ -4,7 +4,7 @@
   "description": "MCP server for Freshdesk 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",