Planfix

Un servidor MCP para integrarse con la plataforma de gestión de proyectos y CRM Planfix.

Documentación

Servidor MCP de Planfix

Este servidor MCP proporciona integración con la API de Planfix, permitiendo que los clientes del Model Context Protocol (MCP) interactúen con el CRM de Planfix y su sistema de gestión de tareas.

Características

Gestión de prospectos (crear, buscar, convertir en tareas)
Las búsquedas de prospectos pueden reutilizar un clientId conocido para omitir búsquedas de contactos
Gestión de contactos y empresas
Gestión de tareas (crear, buscar, comentar)
Generación y gestión de informes
Utiliza la API REST de Planfix v2.0 (Documentación de la API)
Autenticación mediante token Bearer

Configuración

El servidor requiere las siguientes variables de entorno para el acceso a la API de Planfix:

PLANFIX_ACCOUNT – El nombre de tu cuenta de Planfix (p. ej., yourcompany)
PLANFIX_TOKEN – Token de API de Planfix con los permisos necesarios
PLANFIX_BASE_URL – (opcional) Sobrescribe la URL base de la API REST. El valor predeterminado es https://<PLANFIX_ACCOUNT>.planfix.com/rest/. Configúralo para .ru y otras instalaciones regionales, p. ej., https://yourcompany.planfix.ru/rest/
PLANFIX_ACCOUNT_URL – (opcional) Sobrescribe el origen web utilizado para enlaces dirigidos a humanos (páginas de tareas/contactos/usuarios). El valor predeterminado es PLANFIX_BASE_URL sin la /rest/ final
PLANFIX_FIELD_ID_EMAIL – ID de campo personalizado para correo electrónico
PLANFIX_FIELD_ID_EMAIL_ADDITIONAL – (opcional, sin valor predeterminado) ID de campo personalizado numérico utilizado para almacenar direcciones de correo electrónico adicionales (multivalor). Debe apuntar a un campo personalizado multivalor real que hayas creado en tu cuenta; el ID del campo de correo secundario del sistema 124 no es un destino de escritura válido. Cuando no está configurado, el almacenamiento de direcciones adicionales está deshabilitado (la coincidencia mediante el campo del sistema sigue funcionando). El campo de correo secundario del sistema de Planfix (additionalEmailAddresses) es de solo lectura a través de la API REST, por lo que las direcciones adicionales se escriben en este campo personalizado; la coincidencia utiliza tanto el campo del sistema (tipo de filtro 4221) como este campo personalizado (tipo de filtro 4101), para cualquier búsqueda de correo electrónico una vez que esto está configurado
PLANFIX_FIELD_ID_PHONE – ID de campo personalizado para teléfono
PLANFIX_FIELD_ID_TELEGRAM – Establece cualquier valor para usar el campo de Telegram del sistema
PLANFIX_FIELD_ID_TELEGRAM_CUSTOM – ID de campo personalizado para Telegram cuando se usa el campo personalizado
PLANFIX_FIELD_ID_CLIENT – ID de campo personalizado para cliente
PLANFIX_FIELD_ID_MANAGER – ID de campo personalizado para gerente
PLANFIX_FIELD_ID_AGENCY – ID de campo personalizado para agencia
PLANFIX_FIELD_ID_LEAD_SOURCE – ID de campo personalizado para fuente de prospecto
PLANFIX_FIELD_ID_LEAD_SOURCE_VALUE – ID de valor para la fuente de prospecto predeterminada
PLANFIX_FIELD_ID_PIPELINE – ID de campo personalizado para pipeline
PLANFIX_FIELD_ID_TAGS – ID de campo personalizado para etiquetas de tareas
- Los nombres de etiquetas faltantes se agregarán automáticamente al directorio
PLANFIX_FIELD_ID_LEAD_ID – ID de campo personalizado para ID de prospecto externo
PLANFIX_LEAD_TEMPLATE_ID – ID de la plantilla de tarea de prospecto
PLANFIX_TASK_TITLE_TEMPLATE – Plantilla para el título predeterminado de la tarea de prospecto (p. ej., {name} - client's task)

config.yml

Los campos personalizados también se pueden configurar mediante config.yml. La ruta predeterminada es ./data/config.yml. Sobrescríbela con el indicador de CLI --config=/abs/path/config.yml o la variable de entorno PLANFIX_CONFIG. También puedes especificar una cuenta de Planfix diferente al usar una configuración personalizada:

PLANFIX_CONFIG=/etc/planfix-mcp.yml PLANFIX_ACCOUNT=demo \
npx @popstas/planfix-mcp-server

proxyUrl: "http://localhost:8080"

webhook:
  enabled: false
  url: "https://example.com/hook"
  token: "<token>"
  skipPlanfixApi: false

leadTaskFields:
  - id: "456"
    name: "id сделки"
    argName: lead_id
    type: number
contactFields:
  - id: "123"
    name: "Резидентство"
    argName: resident
    type: enum
    values: ["резидент", "нерезидент", "иное"]
userFields:
  - id: "789"
    name: "Департамент"
    argName: department
    type: string

proxyUrl enruta todas las llamadas a la API REST de Planfix (incluidas las solicitudes de herramientas) a través del proxy HTTP especificado.

Los valores de config.yml sobrescriben las entradas correspondientes de las variables de entorno heredadas cuando se fusionan mediante id. Los campos personalizados de usuario de esta lista se solicitan individualmente mediante la herramienta planfix_search_manager para que sus valores estén disponibles en las respuestas. Los gerentes se pueden buscar ya sea por email o por id numérico a través de esta herramienta, lo que permite búsquedas cuando solo se dispone de un identificador.

API de Chat

Para crear tareas a partir de mensajes de chat, agrega un bloque chatApi a config.yml:

chatApi:
  useChatApi: true
  chatApiToken: "<token>"
  providerId: "<id>"
  baseUrl: "https://<account>.planfix.com/webchat/api"

chatApiToken – token para solicitudes a la API de Chat de Planfix.
providerId – identificador del proveedor de chat configurado en Planfix.
useChatApi – habilita la integración con la API de Chat. Cuando true, la creación de tareas procede de la siguiente manera:
1. Se crea un chat mediante la API de Chat con el mensaje inicial.
2. getTask recupera el taskId de la nueva tarea.
3. Las actualizaciones posteriores se realizan a través de la API REST.
baseUrl – URL base para llamadas a la API de Chat. El valor predeterminado es https://<account>.planfix.com/webchat/api.

Webhook

Para enviar cargas útiles de tareas de prospecto a un webhook antes de crear o actualizar una tarea, agrega un bloque webhook a config.yml:

webhook:
  enabled: true
  url: "https://example.com/hook"
  token: "<token>"
  skipPlanfixApi: false

enabled – indica si se debe enviar la carga útil de la tarea de prospecto a la URL del webhook.
url – URL del endpoint del webhook.
token – secreto compartido agregado a la carga útil JSON como token.
skipPlanfixApi – cuando true, la respuesta del webhook debe incluir taskId, y se omite la llamada a la API REST de Planfix.

Depuración

npx @modelcontextprotocol/inspector node d:/projects/expertizeme/planfix-mcp-server/dist/index.js

Registro de eventos

Establece LOG_LEVEL=debug para habilitar registros de caché detallados. Los registros se escriben en data/mcp.log.

Limpieza de caché

Ejecuta npm run cache-clear para eliminar todas las respuestas de la API de Planfix almacenadas en caché en data/planfix-cache.sqlite3 y eliminar el archivo de caché de objetos data/planfix-cache.yml.

Ejemplo de configuración de MCP (NPX)

{
  "mcpServers": {
    "planfix": {
      "command": "npx",
      "args": [
        "-y",
        "@popstas/planfix-mcp-server"
      ],
      "env": {
        "PLANFIX_ACCOUNT": "yourcompany",
        "PLANFIX_TOKEN": "your-api-token",
        "PLANFIX_FIELD_ID_EMAIL": "123",
        "PLANFIX_FIELD_ID_PHONE": "124",
        "PLANFIX_FIELD_ID_TELEGRAM": "1",
        "PLANFIX_FIELD_ID_TELEGRAM_CUSTOM": "125",
        "PLANFIX_FIELD_ID_CLIENT": "126",
        "PLANFIX_FIELD_ID_MANAGER": "127",
        "PLANFIX_FIELD_ID_AGENCY": "128",
        "PLANFIX_FIELD_ID_TAGS": "129",
        "PLANFIX_FIELD_ID_LEAD_ID": "130",
        "PLANFIX_LEAD_TEMPLATE_ID": "42",
        "PLANFIX_TASK_TITLE_TEMPLATE": "{name} - работа с клиентом"
      }
    }
  }
}

Uso

Ejecutar el servidor

Ejecuta el servidor con las variables de entorno requeridas configuradas. Ejemplo (con npx):

PLANFIX_ACCOUNT=yourcompany \
PLANFIX_TOKEN=your-api-token \
PLANFIX_FIELD_ID_EMAIL=123 \
PLANFIX_FIELD_ID_PHONE=124 \
PLANFIX_FIELD_ID_TELEGRAM=1 \
PLANFIX_FIELD_ID_TELEGRAM_CUSTOM=125 \
PLANFIX_FIELD_ID_CLIENT=126 \
PLANFIX_FIELD_ID_MANAGER=127 \
PLANFIX_FIELD_ID_AGENCY=128 \
PLANFIX_FIELD_ID_LEAD_SOURCE=129 \
PLANFIX_FIELD_ID_LEAD_SOURCE_VALUE=130 \
PLANFIX_FIELD_ID_PIPELINE=131 \
PLANFIX_FIELD_ID_LEAD_ID=132 \
PLANFIX_FIELD_ID_TAGS=133 \
PLANFIX_LEAD_TEMPLATE_ID=42 \
PLANFIX_TASK_TITLE_TEMPLATE="{name} - работа с клиентом" \
npx @popstas/planfix-mcp-server

Para ejecutar el servidor a través de Server-Sent Events (SSE), usa el comando planfix-mcp-server-sse:

PLANFIX_ACCOUNT=yourcompany \
PLANFIX_TOKEN=your-api-token \
planfix-mcp-server-sse

Usar el cliente de Planfix

El cliente de Planfix proporciona una forma conveniente de interactuar con la API de Planfix directamente desde la línea de comandos.

Requisitos previos

Asegúrate de tener las siguientes variables de entorno configuradas en tu archivo .env:

PLANFIX_ACCOUNT=your-account
PLANFIX_TOKEN=your-api-token

Comandos básicos

Probar la conexión
```
npm run planfix test
```
Realizar una solicitud GET
```
npm run planfix get user/current
```

Realizar una solicitud POST con datos

npm run planfix post task/ --data '{"name":"Test Task","description":"Test Description"}'

Buscar objetos

npm run planfix post object/list --data '{"filters":[{"type":1,"operator":"equal","value":"Продажа"}]}'

Referencia de herramientas

`planfix_create_sell_task`

Crea una tarea de venta utilizando información textual sobre la agencia y el empleado.
Resuelve el cliente, la tarea de prospecto principal, los asignados y los IDs de agencia automáticamente según las cadenas proporcionadas.
Campos de entrada (todos cadenas):
- name: Título de la tarea, p. ej., "Продажа {{ название товара }} на pressfinity.com".
- agency: Nombre de la agencia/empresa (opcional).
- email: Correo electrónico del empleado utilizado para localizar el contacto de Planfix.
- contactName/employeeName: Nombre completo del empleado (opcional).
- telegram: Nombre de usuario de Telegram del empleado (opcional).
- description: Descripción con la lista de productos solicitados.
- project: Nombre del proyecto para asociar con la tarea de venta (opcional).
Devuelve { taskId, url }.

`planfix_create_sell_task_ids`

Crea una tarea de venta cuando los identificadores de Planfix ya son conocidos.
Requiere clientId numérico y leadTaskId, agencyId y assignees opcionales (IDs de usuario).
Acepta valores de cadena name, description y project opcional.

Actualizar un objeto (solicitud PUT)

npm run planfix put task/123 --data '{"name":"Updated Task Name"}'

Eliminar un objeto
```
npm run planfix delete task/123
```

Uso en código

import { planfixClient } from './lib/planfix-client';

// Get current user
const user = await planfixClient.get('user/current');

// Create a new task
const newTask = await planfixClient.post('task/', {
  name: 'New Task',
  description: 'Task description',
  // ... other task properties
});

// Search for objects
const objects = await planfixClient.post('object/list', {
  filters: [
    {
      type: 1,
      operator: 'equal',
      value: 'Продажа'
    }
  ]
});

Herramientas disponibles

Gestión de prospectos

leadToTask: Convierte un prospecto en una tarea creando/actualizando contacto y tarea
searchLeadTask: Busca tareas de prospecto por información de contacto

Gestión de contactos

searchPlanfixContact: Busca contactos por nombre, teléfono, correo electrónico o Telegram. Cuando el email principal no coincide con el campo de correo principal, también se compara con el campo de correo secundario del sistema (tipo de filtro 4221) y, cuando PLANFIX_FIELD_ID_EMAIL_ADDITIONAL está configurado, con ese campo personalizado (tipo de filtro 4101). Ambos respaldos se aplican a una búsqueda simple de email — el campo personalizado es donde este servidor escribe los adicionales, por lo que un email solitario debe coincidir con él para que un contacto creado aquí pueda encontrarse nuevamente. El argumento opcional additionalEmails: string[] (máx. 10) agrega cada dirección a esos mismos respaldos, además del campo de correo principal.
createPlanfixContact: Crea un nuevo contacto en Planfix. Acepta un argumento opcional additionalEmails: string[] (máx. 10) que se escribe en el campo personalizado de correos adicionales (PLANFIX_FIELD_ID_EMAIL_ADDITIONAL), deduplicado y excluyendo el email principal. (El campo de correo secundario del sistema es de solo lectura a través de la API).
updatePlanfixContact: Actualiza la información de un contacto existente. Acepta un argumento opcional additionalEmails: string[] (máx. 10) que se fusiona en el campo personalizado de correos adicionales. Las escrituras de campos personalizados de Planfix reemplazan todo el valor, por lo que el campo se reescribe con la unión de lo que ya está almacenado allí y las direcciones genuinamente nuevas; no se pierde nada. Las direcciones que ya están en el contacto — en el campo personalizado, en el campo de correo secundario de solo lectura del sistema, o como email principal — no se agregan nuevamente. Con forceUpdate el campo se reescribe en su lugar con exactamente las direcciones que pases, por lo que una matriz vacía lo limpia; omitir additionalEmails deja el campo sin tocar en cualquier caso.
searchPlanfixCompany: Busca empresas por nombre

Gestión de tareas

searchPlanfixTask: Busca tareas por título, ID de cliente y templateId opcional
createSellTask: Resuelve IDs de contacto/agencia y crea una tarea de venta
createSellTaskIds: Crea una tarea de venta cuando los IDs ya son conocidos
createLeadTask: Crea una nueva tarea de prospecto. Cuando chatApi.useChatApi está habilitado, envía el mensaje inicial a través de la API de Chat, obtiene el taskId resultante mediante getTask, y luego actualiza la tarea usando la API REST. Acepta campos message y contactName.
addToLeadTask: Crea o actualiza una tarea de prospecto y actualiza los detalles del contacto. Acepta un argumento opcional additionalEmails: string[] (máx. 10) que se propaga a través de la búsqueda, creación y actualización de contactos (coincide con el campo de correo secundario del sistema y el campo personalizado PLANFIX_FIELD_ID_EMAIL_ADDITIONAL; se escribe en el campo personalizado). Cuando webhook.enabled es verdadero, publica la carga útil de entrada en el endpoint del webhook, omitiendo opcionalmente la API de Planfix si skipPlanfixApi está configurado.
createTask: Crea una tarea usando campos de texto
createComment: Agrega un comentario a una tarea
getChildTasks: Recupera tareas secundarias de una tarea principal. Usa recursive para obtener todas las tareas descendientes como una lista plana; las tareas devueltas incluyen parent_task_id.
updateLeadTask: Actualiza una tarea de prospecto existente (solo se actualizan los campos vacíos a menos que forceUpdate sea verdadero)

Gestión de directorios

planfix_search_directory: Busca directorios por nombre
planfix_search_directory_entry: Busca una entrada de directorio por nombre de directorio y nombre de entrada

Gestión de usuarios

searchManager: Encuentra un gerente por correo electrónico

Informes

listReports: Lista todos los informes disponibles
runReport: Genera y recupera un informe específico

Referencias

PENDIENTE:

Agregar herramienta getTask para recuperar detalles de tareas
Agregar herramienta getContact para recuperar detalles de contactos
Agregar herramienta getManager para recuperar detalles de gerentes
Agregar manejo de errores y registro más completo
Agregar validación de entrada para todos los endpoints de la API
Agregar limitación de velocidad y lógica de reintento para llamadas a la API

Licencia MIT