MCP 服务器

superoffice-mcp-server

Enables AI assistants to query and manage SuperOffice CRM Onsite data—contacts, persons, appointments, support tickets, custom extra tables, and audit logs—via the REST WebAPI.

README

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

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>1. SSL/TLS Certificate Validation Errors</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>2. HTTP 401 Unauthorized</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>3. Archive Provider vs Entity Endpoint Fallback</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.