Freshdesk MCP server

Instructions

Implementation Reference

• src/freshdesk_mcp/server.py:224-304 (handler)

  The core handler function for the 'create_ticket' tool. It is decorated with @mcp.tool(), which both defines the tool schema from type hints/docstring and registers it with the MCP server. Implements the logic to POST a new ticket to Freshdesk API with validation for enums and fields.

  @mcp.tool()
  async def create_ticket(
      subject: str,
      description: str,
      source: Union[int, str],
      priority: Union[int, str],
      status: Union[int, str],
      email: Optional[str] = None,
      requester_id: Optional[int] = None,
      custom_fields: Optional[Dict[str, Any]] = None,
      additional_fields: Optional[Dict[str, Any]] = None  # 👈 new parameter
  ) -> str:
      """Create a ticket in Freshdesk"""
      # Validate requester information
      if not email and not requester_id:
          return "Error: Either email or requester_id must be provided"
  
      # Convert string inputs to integers if necessary
      try:
          source_val = int(source)
          priority_val = int(priority)
          status_val = int(status)
      except ValueError:
          return "Error: Invalid value for source, priority, or status"
  
      # Validate enum values
      if (source_val not in [e.value for e in TicketSource] or
          priority_val not in [e.value for e in TicketPriority] or
          status_val not in [e.value for e in TicketStatus]):
          return "Error: Invalid value for source, priority, or status"
  
      # Prepare the request data
      data = {
          "subject": subject,
          "description": description,
          "source": source_val,
          "priority": priority_val,
          "status": status_val
      }
  
      # Add requester information
      if email:
          data["email"] = email
      if requester_id:
          data["requester_id"] = requester_id
  
      # Add custom fields if provided
      if custom_fields:
          data["custom_fields"] = custom_fields
  
       # Add any other top-level fields
      if additional_fields:
          data.update(additional_fields)
  
      url = f"https://{FRESHDESK_DOMAIN}/api/v2/tickets"
      headers = {
          "Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}",
          "Content-Type": "application/json"
      }
  
      async with httpx.AsyncClient() as client:
          try:
              response = await client.post(url, headers=headers, json=data)
              response.raise_for_status()
  
              if response.status_code == 201:
                  return "Ticket created successfully"
  
              response_data = response.json()
              return f"Success: {response_data}"
  
          except httpx.HTTPStatusError as e:
              if e.response.status_code == 400:
                  # Handle validation errors and check for mandatory custom fields
                  error_data = e.response.json()
                  if "errors" in error_data:
                      return f"Validation Error: {error_data['errors']}"
              return f"Error: Failed to create ticket - {str(e)}"
          except Exception as e:
              return f"Error: An unexpected error occurred - {str(e)}"

• src/freshdesk_mcp/server.py:55-74 (helper)

  Enum definitions used in create_ticket for validating source, status, and priority values against Freshdesk API constraints.

  class TicketSource(IntEnum):
      EMAIL = 1
      PORTAL = 2
      PHONE = 3
      CHAT = 7
      FEEDBACK_WIDGET = 9
      OUTBOUND_EMAIL = 10
  
  class TicketStatus(IntEnum):
      OPEN = 2
      PENDING = 3
      RESOLVED = 4
      CLOSED = 5
  
  class TicketPriority(IntEnum):
      LOW = 1
      MEDIUM = 2
      HIGH = 3
      URGENT = 4
  class AgentTicketScope(IntEnum):