@sigmaiq/helpdesk-pro-mcp-server

MCP server for SigmaIQ HelpDesk Pro — full CRUD for ITSM tickets, changes, assets, KB articles, users, teams, and 20+ entity types on Palantir Foundry.

Quick Start

export FOUNDRY_TOKEN=<your-token>
cd mcp-server
npm install && npm run build
node dist/index.js          # stdio (for Claude Code)

HTTP mode:

TRANSPORT=http PORT=3200 node dist/index.js

Tools (65+)

Tickets

| Tool | Description | |------|-------------| | hdpro_list_tickets | List tickets with status/priority filter | | hdpro_get_ticket | Get ticket by ID | | hdpro_search_tickets | Search by title/description | | hdpro_create_ticket | Create a new ticket | | hdpro_update_ticket | Update ticket fields | | hdpro_assign_ticket | Assign to user/team | | hdpro_triage_ticket | Set priority/category/team | | hdpro_resolve_ticket | Resolve with notes | | hdpro_close_ticket | Close a resolved ticket | | hdpro_cancel_ticket | Cancel a ticket | | hdpro_escalate_ticket | Escalate a ticket |

Ticket Notes

| Tool | Description | |------|-------------| | hdpro_list_notes | List notes for a ticket | | hdpro_create_note | Add a note/comment |

Users

| Tool | Description | |------|-------------| | hdpro_list_users | List users (filter by role) | | hdpro_get_user | Get user by ID | | hdpro_create_user | Create a new user | | hdpro_update_user | Update user fields | | hdpro_deactivate_user | Deactivate a user |

Teams & Memberships

| Tool | Description | |------|-------------| | hdpro_list_teams | List all teams | | hdpro_get_team | Get team by ID | | hdpro_create_team | Create a new team | | hdpro_list_team_members | List team members | | hdpro_add_team_member | Add user to team | | hdpro_remove_team_member | Remove from team |

Change Management

| Tool | Description | |------|-------------| | hdpro_list_changes | List changes (filter status/risk) | | hdpro_get_change | Get change by ID | | hdpro_create_change | Create change request | | hdpro_update_change | Update change fields | | hdpro_approve_change | CAB approval | | hdpro_reject_change | CAB rejection | | hdpro_complete_change | Complete implementation |

Knowledge Base

| Tool | Description | |------|-------------| | hdpro_list_articles | List articles (filter status/category) | | hdpro_get_article | Get article by ID | | hdpro_create_article | Create article | | hdpro_publish_article | Publish draft | | hdpro_archive_article | Archive article |

Assets

| Tool | Description | |------|-------------| | hdpro_list_assets | List assets (filter status/type) | | hdpro_get_asset | Get asset by ID | | hdpro_register_asset | Register new asset | | hdpro_retire_asset | Retire an asset |

Approvals, Time, SLA, Catalog, Tags, Announcements, CSAT, Audit, Dashboard

| Tool | Description | |------|-------------| | hdpro_list_approvals | List approvals | | hdpro_create_approval | Create approval request | | hdpro_update_approval | Approve/reject | | hdpro_list_time_entries | Time entries for ticket | | hdpro_create_time_entry | Log time | | hdpro_list_sla_policies | List SLA policies | | hdpro_list_catalog | Service catalog items | | hdpro_get_catalog_item | Get catalog item | | hdpro_list_tags | List all tags | | hdpro_create_tag | Create a tag | | hdpro_list_announcements | System announcements | | hdpro_create_announcement | Create announcement | | hdpro_list_automation_rules | Automation rules | | hdpro_list_canned_responses | Canned responses | | hdpro_list_watchers | Ticket watchers | | hdpro_add_watcher | Add watcher | | hdpro_list_csat | CSAT responses | | hdpro_list_audit | Audit trail | | hdpro_dashboard_kpis | Dashboard KPIs |

Email Integration (O365)

| Tool | Description | |------|-------------| | hdpro_send_email | Send raw email via SMTP | | hdpro_send_ticket_notification | Send branded ticket notifications | | hdpro_send_team_notification | Send notifications to team members | | hdpro_verify_email_connection | Test SMTP connection | | hdpro_poll_inbound_emails | Poll shared mailbox for new emails and create tickets | | hdpro_test_graph_connection | Test Microsoft Graph API connection | | hdpro_configure_inbound_email | Configure inbound email settings |

Environment Variables

Core Configuration

| Variable | Required | Description | |----------|----------|-------------| | FOUNDRY_TOKEN | Yes | Foundry bearer token | | TRANSPORT | No | stdio (default) or http | | PORT | No | HTTP port (default 3200) | | MCP_API_KEY | No | Optional Bearer auth for HTTP mode |

O365 SMTP (Outbound Email)

| Variable | Required | Description | |----------|----------|-------------| | SMTP_HOST | No | SMTP server (default: smtp.office365.com) | | SMTP_PORT | No | SMTP port (default: 587) | | SMTP_USER | Yes* | O365 email username | | SMTP_PASS | Yes* | O365 email password/app password | | SMTP_FROM_NAME | No | Display name for outbound emails |

Microsoft Graph API (Inbound Email)

| Variable | Required | Description | |----------|----------|-------------| | GRAPH_TENANT_ID | Yes* | Azure tenant ID | | GRAPH_CLIENT_ID | Yes* | Azure app registration client ID | | GRAPH_CLIENT_SECRET | Yes* | Azure app registration client secret | | GRAPH_SHARED_MAILBOX | No | Shared mailbox to monitor (default: [email protected]) | | GRAPH_POLLING_INTERVAL | No | Polling interval in milliseconds (default: 60000) | | GRAPH_DEFAULT_PRIORITY | No | Default priority for auto-created tickets (default: P3-Medium) | | GRAPH_DEFAULT_CATEGORY | No | Default category for auto-created tickets | | GRAPH_AUTO_ASSIGN_TEAM_ID | No | Team ID to auto-assign new email tickets |

*Required for respective email features

Inbound Email Processing

The HelpDesk Pro MCP server includes automatic email-to-ticket conversion using Microsoft Graph API. This feature:

Features

• Auto-ticket creation: Converts inbound emails to service request tickets
• Reply detection: Adds email replies as notes to existing tickets (matches ticket ID in subject)
• User management: Creates guest users for unknown email senders
• Deduplication: Prevents duplicate tickets from same email within 5 minutes
• Email parsing: Strips signatures, converts HTML to markdown
• Attachment handling: Logs attachment details (file storage integration required)
• Configurable: Auto-assign teams, priorities, categories via environment variables

Setup Requirements

1. Azure App Registration:

   • Register app in Azure AD with required permissions
   • Required permissions: Mail.Read, Mail.ReadWrite, User.ReadWrite.All
   • Note tenant ID, client ID, and create client secret

2. Shared Mailbox:

   • Create O365 shared mailbox (e.g., [email protected])
   • Grant app registration access to the mailbox

3. Environment Variables:

   • Set GRAPH_TENANT_ID, GRAPH_CLIENT_ID, GRAPH_CLIENT_SECRET
   • Configure GRAPH_SHARED_MAILBOX and other settings as needed

4. Usage:

   # Test connection
   hdpro_test_graph_connection
   
   # Process inbound emails
   hdpro_poll_inbound_emails --maxEmails 10 --markAsRead true
   
   # Configure settings
   hdpro_configure_inbound_email --defaultPriority "P2-High"

Email-to-Ticket Flow

1. Poll shared mailbox for unread emails
2. Check for duplicates (5-minute window)
3. Parse email content and extract ticket ID from subject (if reply)
4. Find or create user account for sender
5. Either create new ticket or add note to existing ticket
6. Mark email as read and processed
7. Handle attachments and generate activity logs

Architecture

• Single-file TypeScript server (src/index.ts)
• Direct Foundry REST API v2 calls (no OSDK npm dependencies)
• @modelcontextprotocol/sdk for MCP protocol handling
• Supports both stdio (Claude Code) and HTTP transports