# ServiceDesk Plus Model Context Protocol (MCP) Server

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A production-ready Model Context Protocol (MCP) server that connects large language models (LLMs) securely with your **ManageEngine ServiceDesk Plus** (On-Premise / Self-Hosted) instance. This server allows AI agents (such as Claude Desktop, Cursor, and other MCP hosts) to query, search, create, update, and manage help desk tickets and technical notes in real-time.

---

## 🛠️ Features

- **List & Search Tickets**: Rich server-side filtering by status, requester email, and advanced subject-contains keyword queries.
- **Get Ticket Details**: Retrieve comprehensive information on a single ticket, including its subject, description, priority, and resolution content.
- **Create Tickets**: Seamlessly open new help desk requests with custom subjects, HTML/plain-text descriptions, and priorities.
- **Update Tickets**: Real-time updates to ticket statuses, descriptions, and subjects.
- **Manage Technical Notes**: Exposes tools to list and append technical updates directly onto tickets.
- **Public & Secure**: Rigorously designed for open-source safety. Zero hardcoded secrets, domains, or credentials.
- **Classic UI Integration**: Automatically generates browser-viewable deep links tailored for the Classic UI layout.
- **Complete Offline Testing**: Includes a 100% offline unit test suite with mock network interception (`respx`).

---

## 📐 Architecture Overview

```
 ┌─────────────────┐             ┌────────────────────┐             ┌─────────────────────┐
 │                 │    Stdio    │                    │    HTTPS    │  ManageEngine       │
 │    MCP Host     │  ─────────> │  servicedesk-plus  │  ─────────> │  ServiceDesk Plus   │
 │ (e.g. Claude)   │  <───────── │     (MCP Server)   │  <───────── │  (On-Premise API)   │
 │                 │             │                    │ (authtoken) │                     │
 └─────────────────┘             └────────────────────┘             └─────────────────────┘
```

---

## 📋 MCP Tools Exposed

This server exposes **6 robust tools** to the AI client:

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `list_tickets` | `status` (opt), `requester_email` (opt), `search_query` (opt), `row_count` (opt), `start_index` (opt) | Retrieve, paginated, and filter tickets. Performs efficient server-side query filtering. |
| `get_ticket` | `ticket_id` (req) | Retrieve full details of a single ticket (including HTML description and resolutions). |
| `create_ticket` | `subject` (req), `description` (req), `priority` (opt), `requester_email` (opt) | Create a new help desk request. |
| `update_ticket` | `ticket_id` (req), `subject` (opt), `description` (opt), `status` (opt) | Update fields on an existing ticket. |
| `add_ticket_note` | `ticket_id` (req), `note` (req) | Append a technical log or update note to a ticket. |
| `list_ticket_notes`| `ticket_id` (req) | Fetch all technical notes logged on a specific ticket. |

---

## 🚀 Quick Start

### Prerequisites
- Python 3.10 or higher.
- `uv` is highly recommended for lightning-fast package and tool management (or standard `pip`).

### 1. Configure Your Credentials
Copy the `.env.example` template to `.env`:
```bash
cp .env.example .env
```
Open `.env` and fill in your details:
```ini
SDP_API_KEY=your_technician_key_here
SDP_BASE_URL=productsupport.example.com
SDP_USERNAME=your_username_here
```
*Note: Your `SDP_API_KEY` (Technician Key/Authtoken) is generated from your ServiceDesk Plus profile page.*

---

## 📦 Local Installation & Build

### Building the Package
You can build a clean local package artifact (wheel file) of the server using standard build tools:

Using `uv`:
```bash
uv build
```
Using standard Python:
```bash
python -m pip install --upgrade build
python -m build
```
This will compile and output the package to `dist/servicedesk_plus-0.1.0-py3-none-any.whl`.

---

## 🔌 Configuring Your MCP Host

### 1. Claude Desktop
Add this to your `claude_desktop_config.json` (typically located in `%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

#### Option A: Running from Built Local Wheel (Recommended)
This approach executes the server inside an isolated temporary sandbox with standard `uvx`:
```json
{
  "mcpServers": {
    "servicedesk-plus": {
      "command": "uvx",
      "args": [
        "--from",
        "C:\\Workspace\\google-cli\\productsupport-mcp\\dist\\servicedesk_plus-0.1.0-py3-none-any.whl",
        "servicedesk-plus"
      ],
      "env": {
        "SDP_API_KEY": "YOUR_API_KEY",
        "SDP_BASE_URL": "productsupport.example.com",
        "SDP_USERNAME": "your_email@domain.com"
      }
    }
  }
}
```

#### Option B: Running from Local Sources (Development)
```json
{
  "mcpServers": {
    "servicedesk-plus": {
      "command": "C:\\Workspace\\google-cli\\productsupport-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Workspace\\google-cli\\productsupport-mcp\\src\\servicedesk_plus\\main.py"
      ],
      "env": {
        "SDP_API_KEY": "YOUR_API_KEY",
        "SDP_BASE_URL": "productsupport.example.com",
        "SDP_USERNAME": "your_email@domain.com"
      }
    }
  }
}
```

---

## 🧪 Running Unit Tests

This project includes a comprehensive offline unit testing suite utilizing `pytest` and `respx` to mock ServiceDesk Plus API responses entirely.

1. Install development requirements in your virtual environment:
   ```bash
   pip install -e .[dev]
   ```
2. Run tests:
   ```bash
   pytest
   ```
All tests run 100% offline, allowing verification of tool registration, query formatting, body payload construction, and response unpacking with zero credentials or internet required.

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.