SuperOffice CRM Onsite — Model Context Protocol (MCP) Server

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

🚀 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

🔌 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

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.

Verify:

• The user account has REST WebAPI permissions in SuperOffice Admin.

• Basic Authentication is enabled in IIS for the SuperOffice WebAPI application pool.

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.

📜 License

This project is licensed under the MIT License.