# SuperOffice CRM Onsite — Model Context Protocol (MCP) Server

<p align="center">
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Protocol-blue.svg?style=for-the-badge&logo=anthropic" alt="MCP Protocol" /></a>
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.8-3178C6.svg?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" /></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D18.0-339933.svg?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js" /></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge" alt="License" /></a>
</p>

A production-ready **Model Context Protocol (MCP)** server built in TypeScript for **SuperOffice CRM Onsite** installations. It enables LLM assistants (such as Claude Desktop, Antigravity IDE, Cursor, and other MCP clients) to seamlessly query contacts, persons, appointments, support tickets, custom extra tables (`y_*`), and audit logs via standard SuperOffice REST WebAPI endpoints.

---

## 🌟 Features

- ⚡ **Native MCP `stdio` Transport**: Integrates directly with desktop and terminal AI clients.
- 🏢 **Company & Contact Lookup**: Fetch detailed company information (`get_contact_by_id`).
- 👥 **Person Search**: Fuzzy and filter-based search across names and emails (`search_persons`).
- 📅 **Calendar & Appointment Intelligence**: Date-range filtering with user assignment (`get_recent_appointments`).
- 🎫 **Support Ticket Management**: Fetch recent tickets and inspect full ticket metadata (`get_latest_tickets`, `get_ticket_by_id`).
- 📊 **Custom Extra Table Engine**: Discover and query all custom `y_*` tables dynamically (`list_extra_tables`, `query_extra_table`).
- 🛡️ **Audit & Log Table Explorer**: Inspect audit trails such as `y_logticket`, `y_logactivity`, and system events (`list_log_tables`).
- 🔒 **Onsite Ready**: Robust Basic Authentication, timeout guards, and configurable self-signed certificate handling.
- 🛡️ **Graceful Fault Tolerance**: Multi-tier fallback query strategies (Archive Provider ➔ REST Entity API) to guarantee zero crash behavior.

---

## 🏗️ Architecture

```mermaid
flowchart LR
    subgraph Client["Local Workstation / MCP Client"]
        Claude["Claude Desktop / Antigravity / Cursor"]
        MCP["SuperOffice MCP Server\n(Node.js / TypeScript)"]
        Claude <-->|stdio JSON-RPC| MCP
    end

    subgraph Server["SuperOffice Onsite Environment (VM)"]
        IIS["IIS Web Server / REST WebAPI\n/api/v1/"]
        SOApp["SuperOffice CRM Core"]
        SODb[("SuperOffice Database\n(Core + y_* Extra Tables)")]

        IIS --> SOApp --> SODb
    end

    MCP <-->|HTTP(S) Basic Auth\nREST / Archive / Entities| IIS
```

---

## 🛠️ Available MCP Tools

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `get_contact_by_id` | `contactId` *(number, required)* | Fetches full company/contact record (department, org nr, emails, phones, category, business). |
| `search_persons` | `query` *(string, required)*<br/>`limit` *(number, opt, default: 25)* | Searches persons by full name, first/last name, or email address with multi-strategy fallback. |
| `get_recent_appointments` | `fromDate` *(ISO date, opt)*<br/>`toDate` *(ISO date, opt)*<br/>`associateId` *(number, opt)*<br/>`limit` *(number, opt, default: 50)* | Retrieves calendar appointments in date range with task, location, contact, and completion status. |
| `get_ticket_by_id` | `ticketId` *(number, required)* | Retrieves detailed support ticket information including category, status, creator, owner, and contact. |
| `get_latest_tickets` | `limit` *(number, opt, default: 10)* | Lists latest support tickets ordered descending by ticket ID. |
| `list_extra_tables` | *None* | Lists all custom extra tables (`y_*` tables) defined in the CRM database. |
| `list_log_tables` | *None* | Lists dedicated logging and audit tables (`y_logticket`, `y_logactivity`, `y_msisdn_search_log`, etc.). |
| `query_extra_table` | `tableName` *(string, required)*<br/>`fields` *(string, opt)*<br/>`limit` *(number, opt, default: 25)* | Queries records dynamically from any custom extra table via the Dynamic archive provider. |

---

## 🚀 Quick Start

### 1. Prerequisites
- **Node.js**: `v18.0.0` or higher
- **SuperOffice CRM Onsite**: Installed with REST WebAPI (`/api/v1/`) enabled
- An active SuperOffice user account with API permissions

### 2. Clone & Build

```bash
# Clone the repository
git clone https://github.com/your-username/superoffice-mcp-server.git
cd superoffice-mcp-server

# Install dependencies
npm install

# Compile TypeScript to dist/
npm run build
```

---

## ⚙️ Configuration

### Environment Variables

| Variable | Required | Description | Example |
| :--- | :---: | :--- | :--- |
| `SUPEROFFICE_API_URL` | **Yes** | Base URL of SuperOffice WebAPI (*no trailing slash*) | `https://osl-so-iis2.ls.local/SuperOffice` |
| `SUPEROFFICE_USERNAME` | **Yes** | SuperOffice username | `admin` |
| `SUPEROFFICE_PASSWORD` | **Yes** | SuperOffice user password | `YourPassword123` |
| `NODE_TLS_REJECT_UNAUTHORIZED` | *No* | Set to `0` for self-signed or internal CA SSL certs | `0` |
| `SUPEROFFICE_TIMEOUT_MS` | *No* | HTTP request timeout in milliseconds | `30000` |

---

## 🔌 Client Setup Guides

### 1. Claude Desktop

Add this entry to your `claude_desktop_config.json`:

* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "superoffice": {
      "command": "node",
      "args": [
        "C:\\path\\to\\superoffice-mcp-server\\dist\\index.js"
      ],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0",
        "SUPEROFFICE_API_URL": "https://your-crm-server/SuperOffice",
        "SUPEROFFICE_USERNAME": "admin",
        "SUPEROFFICE_PASSWORD": "your-password"
      }
    }
  }
}
```

### 2. Antigravity IDE / Custom MCP Config (`mcp_config.json`)

```json
{
  "mcpServers": {
    "superoffice": {
      "command": "node",
      "args": [
        "C:\\Users\\aliha\\.gemini\\antigravity-ide\\scratch\\superoffice-mcp-server\\dist\\index.js"
      ],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0",
        "SUPEROFFICE_API_URL": "https://osl-so-iis2.ls.local/SuperOffice",
        "SUPEROFFICE_USERNAME": "admin",
        "SUPEROFFICE_PASSWORD": "your-password"
      }
    }
  }
}
```

---

## 🧪 Testing & Verification

You can test connectivity directly in terminal using PowerShell or bash:

```powershell
# Set test environment
$env:SUPEROFFICE_API_URL="https://osl-so-iis2.ls.local/SuperOffice"
$env:SUPEROFFICE_USERNAME="admin"
$env:SUPEROFFICE_PASSWORD="your-password"
$env:NODE_TLS_REJECT_UNAUTHORIZED="0"

# Run server (logs to stderr, listens on stdin)
node dist/index.js
```

You should see:
```text
[superoffice-mcp] Server v1.1.0 started — connected to https://osl-so-iis2.ls.local/SuperOffice
```

---

## 📂 Project Structure

```text
superoffice-mcp-server/
├── .github/
│   └── workflows/
│       └── ci.yml               # Automated multi-version build testing
├── src/
│   └── index.ts                 # Main MCP Server implementation (8 tools)
├── .env.example                 # Environment variables template
├── .gitignore                   # Git ignore specifications
├── LICENSE                      # MIT License
├── package.json                 # Project manifest and scripts
├── tsconfig.json                # TypeScript compiler configuration
└── README.md                    # Comprehensive documentation
```

---

## 🛡️ Troubleshooting

<details>
<summary><b>1. SSL/TLS Certificate Validation Errors</b></summary>

If your onsite server uses an internal Certificate Authority (CA) or self-signed certificate, Node.js fetch will abort by default. Ensure:
```json
"NODE_TLS_REJECT_UNAUTHORIZED": "0"
```
is included in the `env` section of your MCP config.
</details>

<details>
<summary><b>2. HTTP 401 Unauthorized</b></summary>

Verify:
- The user account has REST WebAPI permissions in SuperOffice Admin.
- Basic Authentication is enabled in IIS for the SuperOffice WebAPI application pool.
</details>

<details>
<summary><b>3. Archive Provider vs Entity Endpoint Fallback</b></summary>

The server utilizes SuperOffice's rich `Archive/Dynamic` and `Archive/FindPerson` providers for expressive querying. If a specific provider is restricted in your installation's user role, the server automatically degrades gracefully to simple REST entity endpoints.
</details>

---

## 📜 License

This project is licensed under the [MIT License](LICENSE).