Servidor SuperOffice CRM Onsite — Protocolo de Contexto de Modelo (MCP)

Un servidor Model Context Protocol (MCP) listo para producción, construido en TypeScript para instalaciones SuperOffice CRM Onsite. Permite que asistentes LLM (como Claude Desktop, Antigravity IDE, Cursor y otros clientes MCP) consulten sin problemas contactos, personas, citas, tickets de soporte, tablas extra personalizadas (y_*) y registros de auditoría a través de los endpoints estándar de SuperOffice REST WebAPI.

🌟 Características

• ⚡ Transporte nativo MCP stdio: Se integra directamente con clientes de IA de escritorio y terminal.

• 🏢 Búsqueda de Empresas y Contactos: Obtén información detallada de la empresa (get_contact_by_id).

• 👥 Búsqueda de Personas: Búsqueda difusa y basada en filtros entre nombres y correos electrónicos (search_persons).

• 📅 Inteligencia de Calendario y Citas: Filtrado por rango de fechas con asignación de usuario (get_recent_appointments).

• 🎫 Gestión de Tickets de Soporte: Obtén tickets recientes e inspecciona metadatos completos de tickets (get_latest_tickets, get_ticket_by_id).

• 📊 Motor de Tablas Extra Personalizadas: Descubre y consulta dinámicamente todas las tablas y_* personalizadas (list_extra_tables, query_extra_table).

• 🛡️ Explorador de Tablas de Auditoría y Registros: Inspecciona rastros de auditoría como y_logticket, y_logactivity y eventos del sistema (list_log_tables).

• 🔒 Listo para Onsite: Autenticación básica robusta, protecciones de tiempo de espera y manejo configurable de certificados autofirmados.

• 🛡️ Tolerancia a Fallos Elegante: Estrategias de consulta de respaldo en múltiples niveles (Proveedor de Archivo ➔ API de Entidad REST) para garantizar un comportamiento sin bloqueos.

🏗️ Arquitectura

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

🛠️ Herramientas MCP Disponibles

🚀 Inicio Rápido

1. Requisitos Previos

• Node.js: v18.0.0 o superior

• SuperOffice CRM Onsite: Instalado con REST WebAPI (/api/v1/) habilitado

• Una cuenta de usuario de SuperOffice activa con permisos de API

2. Clonar y Compilar

# 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

⚙️ Configuración

Variables de Entorno

🔌 Guías de Configuración del Cliente

1. Claude Desktop

Agrega esta entrada a tu 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 / Configuración MCP Personalizada (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"
      }
    }
  }
}

🧪 Pruebas y Verificación

Puedes probar la conectividad directamente en la terminal usando PowerShell o 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

Deberías ver:

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

📂 Estructura del Proyecto

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

🛡️ Solución de Problemas

Si tu servidor local utiliza una Autoridad de Certificación (CA) interna o un certificado autofirmado, la función fetch de Node.js se cancelará de forma predeterminada. Asegúrate de que:

"NODE_TLS_REJECT_UNAUTHORIZED": "0"

esté incluido en la sección env de tu configuración MCP.

Verifica:

• La cuenta de usuario tiene permisos de REST WebAPI en SuperOffice Admin.

• La Autenticación Básica está habilitada en IIS para el grupo de aplicaciones de SuperOffice WebAPI.

El servidor utiliza los ricos proveedores Archive/Dynamic y Archive/FindPerson de SuperOffice para consultas expresivas. Si un proveedor específico está restringido en el rol de usuario de tu instalación, el servidor degrada automáticamente a endpoints de entidad REST simples.

📜 Licencia

Este proyecto está licenciado bajo la Licencia MIT.