SuperOffice CRM Onsite — Model Context Protocol (MCP) Сервер

Готовый к продакшену сервер Model Context Protocol (MCP), написанный на TypeScript для установок SuperOffice CRM Onsite. Он позволяет LLM-ассистентам (таким как Claude Desktop, Antigravity IDE, Cursor и другим MCP-клиентам) беспрепятственно запрашивать контакты, персоны, встречи, тикеты поддержки, пользовательские дополнительные таблицы (y_*) и журналы аудита через стандартные конечные точки SuperOffice REST WebAPI.

🌟 Возможности

• ⚡ Нативный транспорт 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).

• 🔒 Готовность для Onsite: Надежная базовая аутентификация, защита по тайм-ауту и настраиваемая обработка самозаверенных сертификатов.

• 🛡️ Безотказная отказоустойчивость: Многоуровневые стратегии резервного запроса (Archive Provider ➔ REST Entity API) для гарантии отсутствия сбоев.

🏗️ Архитектура

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-инструменты

🚀 Быстрый старт

1. Предварительные требования

• Node.js: v18.0.0 или выше

• SuperOffice CRM Onsite: Установлен с включенным REST WebAPI (/api/v1/)

• Активная учетная запись пользователя SuperOffice с разрешениями API

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

⚙️ Конфигурация

Переменные окружения

🔌 Руководства по настройке клиентов

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"

включен в раздел env вашей конфигурации MCP.

Проверьте:

• Учетная запись пользователя имеет разрешения REST WebAPI в SuperOffice Admin.

• Базовая аутентификация включена в IIS для пула приложений SuperOffice WebAPI.

Сервер использует богатые провайдеры SuperOffice Archive/Dynamic и Archive/FindPerson для выразительных запросов. Если конкретный провайдер ограничен в роли пользователя вашей установки, сервер автоматически плавно переключается на простые конечные точки REST entity.

📜 Лицензия

Этот проект лицензирован под лицензией MIT.