mcp-vtenext

Servidor MCP para VTENext CRM: expone la API WebService como herramientas para Claude y otros clientes compatibles con MCP.

Requisitos

• Node.js 18+

• Una instancia de VTENext en ejecución (autoalojada o Docker; ver ../docker)

Configuración

cd mcp/vtenext/server
npm install
cp .env.example .env

Edita .env:

VTENEXT_URL=http://your-vtenext-instance
VTENEXT_USERNAME=admin
VTENEXT_ACCESS_KEY=your_access_key
READ_ONLY=false

La clave de acceso se encuentra en VTENext en Admin → Usuarios → [usuario] → Clave de acceso.

Modo de solo lectura

Establece READ_ONLY=true para evitar cualquier operación de escritura en VTENext. Cuando está habilitado, las herramientas create_opportunita, update_opportunita y add_nota_opportunita devuelven un error en lugar de escribir datos.

Esto es útil cuando el servidor es utilizado por bots de IA o agentes automatizados que solo deben leer datos del CRM. Para ejecutar una instancia de solo lectura junto a una de acceso completo, pasa la variable a través de la configuración de MCP:

{
  "mcpServers": {
    "vtenext-bot": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp/vtenext/server/index.js"],
      "env": {
        "VTENEXT_URL": "http://your-vtenext-instance",
        "VTENEXT_USERNAME": "admin",
        "VTENEXT_ACCESS_KEY": "your_access_key",
        "READ_ONLY": "true"
      }
    }
  }
}

Integración con Claude Code

Añade a .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "vtenext": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp/vtenext/server/index.js"]
    }
  }
}

Herramientas

Opportunità (Potenciales)

Contatti (Contactos)

Attività e note (Actividades y notas)

Utilità (Utilidades)

Autenticación

VTENext utiliza el protocolo WebService de vtiger:

1. GET /webservice.php?operation=getchallenge → token

2. MD5(token + accessKey) → clave hash

3. POST /webservice.php con operation=login (form-encoded) → sessionName

Las sesiones se almacenan en caché durante 4 minutos (la vida útil del token es de 5 minutos).

Pruebas

# Unit tests (no VTENext required)
npm test

# Integration tests (requires live VTENext at VTENEXT_URL)
npm run test:integration

Licencia

MIT