Skip to main content
Glama
deenesjakoruzh
alihaider663

superoffice-mcp-server

by alihaider663
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

SuperOffice CRM Onsite — 模型上下文协议（MCP）服务器

一个基于 TypeScript 构建、面向 SuperOffice CRM Onsite 安装的生产级 模型上下文协议（MCP） 服务器。它使 LLM 助手（如 Claude Desktop、Antigravity IDE、Cursor 及其他 MCP 客户端）能够通过标准 SuperOffice REST WebAPI 端点无缝查询联系人、人员、约会、支持工单、自定义附加表（y_*）和审计日志。

🌟 功能特性

  • ⚡ 原生 MCP stdio 传输：直接与桌面端和终端 AI 客户端集成。

  • 🏢 公司与联系人查询：获取详细的公司信息（get_contact_by_id）。

  • 👥 人员搜索：跨姓名和电子邮件进行模糊及基于过滤器的搜索（search_persons）。

  • 📅 日历与约会智能：支持按日期范围过滤并指定用户（get_recent_appointments）。

  • 🎫 支持工单管理：获取最近的工单并查看完整的工单元数据（get_latest_tickets、get_ticket_by_id）。

  • 📊 自定义附加表引擎：动态发现并查询所有自定义 y_* 表（list_extra_tables、query_extra_table）。

  • 🛡️ 审计与日志表浏览器：检查审计跟踪，如 y_logticket、y_logactivity 和系统事件（list_log_tables）。

  • 🔒 本地部署就绪：稳健的基本认证、超时保护以及可配置的自签名证书处理。

  • 🛡️ 优雅容错：多层回退查询策略（Archive Provider ➔ REST Entity API），确保零崩溃行为。

Related MCP server: CiviCRM MCP Server

🏗️ 架构

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

🛠️ 可用的 MCP 工具

工具名称

参数

描述

get_contact_by_id

contactId (number，必填)

获取完整的公司/联系人记录（部门、组织编号、电子邮件、电话、类别、业务）。

search_persons

query (string，必填)limit (number，可选，默认值：25)

按全名、名/姓或电子邮件地址搜索人员，并支持多策略回退。

get_recent_appointments

fromDate (ISO date，可选)toDate (ISO date，可选)associateId (number，可选)limit (number，可选，默认值：50)

检索日期范围内的日历约会，包含任务、地点、联系人和完成状态。

get_ticket_by_id

ticketId (number，必填)

检索详细的支持工单信息，包括类别、状态、创建者、所有者和联系人。

get_latest_tickets

limit (number，可选，默认值：10)

按工单 ID 降序列出最新的支持工单。

list_extra_tables

无

列出 CRM 数据库中定义的所有自定义附加表（y_* 表）。

list_log_tables

无

列出专用的日志和审计表（y_logticket、y_logactivity、y_msisdn_search_log 等）。

query_extra_table

tableName (string，必填)fields (string，可选)limit (number，可选，默认值：25)

通过 Dynamic archive provider 从任何自定义附加表动态查询记录。

🚀 快速开始

1. 前提条件

  • Node.js：v18.0.0 或更高版本

  • SuperOffice CRM Onsite：已安装并启用 REST WebAPI（/api/v1/）

  • 一个具有 API 权限的有效 SuperOffice 用户账户

2. 克隆与构建

# 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

⚙️ 配置

环境变量

变量

必填

描述

示例

SUPEROFFICE_API_URL

是

SuperOffice WebAPI 的基础 URL（无尾部斜杠）

https://osl-so-iis2.ls.local/SuperOffice

SUPEROFFICE_USERNAME

是

SuperOffice 用户名

admin

SUPEROFFICE_PASSWORD

是

SuperOffice 用户密码

YourPassword123

NODE_TLS_REJECT_UNAUTHORIZED

否

对于自签名或内部 CA SSL 证书，设置为 0

0

SUPEROFFICE_TIMEOUT_MS

否

HTTP 请求超时时间（毫秒）

30000

🔌 客户端设置指南

1. Claude Desktop

将以下条目添加到你的 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 / 自定义 MCP 配置（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"
      }
    }
  }
}

🧪 测试与验证

你可以直接在终端中使用 PowerShell 或 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

你应该会看到：

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

📂 项目结构

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

🛡️ 故障排除

如果你的本地服务器使用内部证书颁发机构（CA）或自签名证书，Node.js fetch 默认会中止。请确保：

"NODE_TLS_REJECT_UNAUTHORIZED": "0"

已包含在你的 MCP 配置的 env 部分中。

请验证：

  • 用户账户在 SuperOffice Admin 中具有 REST WebAPI 权限。

  • IIS 中已为 SuperOffice WebAPI 应用程序池启用基本认证。

服务器利用 SuperOffice 丰富的 Archive/Dynamic 和 Archive/FindPerson 提供程序进行表达性查询。如果特定提供程序在你的安装的用户角色中受到限制，服务器会自动优雅地降级到简单的 REST entity 端点。

📜 许可证

本项目采用 MIT 许可证 授权。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Simplicate MCP Server

    daanno
    F
    license
    C
    quality
    Not graded
    maintenance
    Enables AI assistants to securely access and interact with Simplicate business data including CRM, projects, timesheets, and invoices through natural language. Supports searching across resources and retrieving detailed information about organizations, contacts, and project data.
    59
    0
    -

  • CiviCRM MCP Server

    johncallhub
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to access and manage CiviCRM data, including contacts, activities, contributions, events, and memberships, with full custom field support.
    5
    MIT

  • Salesforce MCP Server

    sudhakar6
    A
    license
    A
    quality
    B
    maintenance
    Enables AI agents to securely query, search, and modify Salesforce data through standard Salesforce APIs, including record CRUD, SOQL/SOSL search, Bulk API 2.0 operations, composite calls, object discovery, and custom Apex REST endpoints.
    15
    MIT

  • SuperOffice AI Support MCP

    alihaider663
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI assistants to securely triage SuperOffice CRM support cases by retrieving tickets, running database diagnostics, searching knowledge bases, and orchestrating cross-system incident investigations.
    MIT