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

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

# 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

{
  "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)

{
  "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:

# 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:

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

---

📂 Project Structure

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:

"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.