Servidor MCP de Lerian

Una puerta de enlace MCP para el descubrimiento del portafolio de Lerian, documentación, aprendizaje, ejemplos de SDK, acceso a la API de productos en vivo y flujos de trabajo entre productos.

Este servidor conecta clientes MCP como Claude Desktop, Cursor, Windsurf, Continue y ChatGPT Desktop con el portafolio de productos de Lerian. Ofrece a los asistentes de IA una forma estructurada de descubrir productos de Lerian, leer documentación oficial, generar ejemplos de implementación, inspeccionar contratos de API en vivo, ejecutar APIs de productos configuradas y guiar flujos de trabajo operativos entre productos.

Alcance de ejecución: este servidor no es solo de documentación. La herramienta unificada lerian está orientada a la lectura, pero las herramientas específicas de producto *-execute pueden llamar a APIs de Lerian en vivo configuradas. Las llamadas a la API que implican cambios requieren confirmación explícita y un motivo de auditoría.

Configuración en 2 minutos

1. Elige tu asistente de IA compatible con MCP.

2. Añade la configuración del servidor.

3. Reinicia la aplicación de IA.

4. Pregunta: "¿Qué puedes decirme sobre Lerian Midaz?"

Claude Desktop

Ubicación en macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Ubicación en Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "lerian": {
      "command": "npx",
      "args": ["-y", "@lerianstudio/lerian-mcp-server@latest"]
    }
  }
}

Cursor, Windsurf, Continue, ChatGPT Desktop

Añade el mismo bloque de servidor MCP a la configuración MCP de tu cliente:

{
  "mcpServers": {
    "lerian": {
      "command": "npx",
      "args": ["-y", "@lerianstudio/lerian-mcp-server@latest"]
    }
  }
}

Qué obtienes

Productos compatibles

• Midaz: plataforma de libro mayor financiero con servicios de incorporación, saldos, transacciones, CRM y libro mayor.

• Fetcher: conexión a fuentes de datos, descubrimiento de esquemas y servicio de extracción asíncrona.

• Reporter: generación de informes basada en plantillas, gestión de fuentes de datos, métricas y artefactos.

• Matcher: motor de conciliación para comparar transacciones de Midaz con sistemas externos.

• Tracer: motor de validación de transacciones con reglas, límites, validaciones y auditabilidad.

• Flowker: plataforma de orquestación de flujos de trabajo para proveedores, ejecutores, webhooks y flujos de ejecución.

• Underwriter: superficie de préstamos consciente de la jurisdicción para productos de préstamo y vista previa de cronogramas.

• All: descubrimiento de todo el portafolio, búsqueda de documentación y comparación.

Capacidades principales

• Descubrimiento de portafolio a través de lerian con operation="discover".

• Consulta de documentación a través de lerian con operation="docs".

• Aprendizaje guiado a través de lerian con operation="learn".

• Ejemplos de SDK a través de lerian con operation="sdk".

• Búsqueda entre productos a través de lerian con operation="search".

• Descubrimiento de contratos de API en vivo a través de herramientas específicas de producto *-discover.

• Ejecución de API en vivo a través de herramientas específicas de producto *-execute.

• Flujos de trabajo entre productos a través de portfolio-workflow.

• Guía basada en prompts para incorporación, aprendizaje, uso de API y flujos de trabajo operativos.

Superficie de herramientas en tiempo de ejecución

El servidor expone un núcleo pequeño más pares de API en vivo para cada producto compatible.

Herramientas principales

• lerian: herramienta de portafolio unificada para documentos, aprendizaje, ejemplos de SDK, descubrimiento y búsqueda.

• portfolio-workflow: descubrimiento de flujos de trabajo entre productos, planificación, sesiones con estado y ejecución de pasos.

Herramientas de API en vivo

• midaz-discover y midaz-execute

• fetcher-discover y fetcher-execute

• reporter-discover y reporter-execute

• matcher-discover y matcher-execute

• tracer-discover y tracer-execute

• flowker-discover y flowker-execute

• underwriter-discover y underwriter-execute

Utiliza la herramienta *-discover correspondiente antes de llamar a una herramienta *-execute. El descubrimiento devuelve recursos, acciones, parámetros de ruta, parámetros de consulta, esquemas de cuerpo, ejemplos y sugerencias de ejecución.

La herramienta lerian

La herramienta lerian es el punto de entrada principal orientado a la lectura.

Tool: lerian

Parameters:
  product          midaz | fetcher | reporter | matcher | tracer | flowker | underwriter | all
  operation        discover | docs | learn | sdk | search
  topic            Topic to inspect, learn, or search
  language         go | typescript | javascript, for SDK examples
  useCase          Specific implementation scenario for SDK examples
  experienceLevel  beginner | intermediate | advanced
  format           summary | detailed | examples-only
  includeExamples  true | false
  maxResults       1-50, for search

Ejemplo:

{
  "product": "midaz",
  "operation": "learn",
  "topic": "transactions",
  "experienceLevel": "beginner"
}

Flujo de trabajo de API en vivo

El acceso a la API en vivo es intencionalmente de dos pasos.

1. Inspecciona la superficie del producto:

{
  "intent": "list-resources"
}

2. Inspecciona un contrato de acción específico:

{
  "intent": "describe-action",
  "resource": "transactions",
  "action": "create"
}

3. Ejecuta con el contrato exacto devuelto por el descubrimiento:

{
  "resource": "transactions",
  "action": "create",
  "pathParams": {
    "organizationId": "...",
    "ledgerId": "..."
  },
  "body": {
    "description": "Example transaction"
  },
  "confirmMutation": true,
  "mutationReason": "Create example transaction requested by operator"
}

Las acciones de API en vivo que implican cambios requieren:

• confirmMutation: true

• mutationReason con un motivo de auditoría legible por humanos

Flujos de trabajo entre productos

Utiliza portfolio-workflow cuando la tarea abarque varios productos de Lerian.

Flujos de trabajo actuales:

• fetcher-to-reporter: valida los mapeos de extracción con Fetcher, luego genera o inspecciona informes de Reporter.

• matcher-to-fetcher-to-midaz: configura la conciliación de Matcher, usa el descubrimiento de Matcher sobre Fetcher e inspecciona los datos del lado del libro mayor de Midaz.

Intenciones compatibles:

• list-workflows

• describe-workflow

• plan

• create-session

• get-session

• list-sessions

• execute-step

• execute-next

Las sesiones de flujo de trabajo devuelven un sessionToken opaco. Mantenlo privado.

Configuración

El servidor funciona inmediatamente para documentación y descubrimiento. La ejecución de la API en vivo requiere servicios de producto accesibles y, cuando corresponda, tokens o claves de API.

Fuentes de configuración, en orden de prioridad:

• Línea de comandos --config o --config-file

• Variables de entorno

• ./lerian-mcp-config.json

• ./midaz-mcp-config.json

• ~/.lerian/mcp-config.json

• ~/.midaz/mcp-config.json

• ~/.config/lerian/mcp-config.json

• ~/.config/midaz/mcp-config.json

• Rutas de configuración global de la plataforma

Crea o actualiza la configuración de forma interactiva:

npx -y -p @lerianstudio/lerian-mcp-server@latest lerian-mcp-config

Variables de entorno comunes:

LERIAN_DOCS_URL=https://docs.lerian.studio
LOG_LEVEL=info

MIDAZ_ONBOARDING_URL=http://localhost:3000
MIDAZ_TRANSACTION_URL=http://localhost:3001
MIDAZ_CRM_URL=http://localhost:3002
MIDAZ_LEDGER_URL=http://localhost:3003
MIDAZ_AUTH_TOKEN=...

FETCHER_MANAGER_URL=http://localhost:4006
FETCHER_AUTH_TOKEN=...

REPORTER_MANAGER_URL=http://localhost:4005
REPORTER_AUTH_TOKEN=...

MATCHER_BASE_URL=http://localhost:4018
MATCHER_AUTH_TOKEN=...

TRACER_BASE_URL=http://localhost:4020
TRACER_API_KEY=...

FLOWKER_BASE_URL=http://localhost:4021
FLOWKER_AUTH_TOKEN=...
FLOWKER_API_KEY=...

UNDERWRITER_BASE_URL=http://localhost:8080
UNDERWRITER_AUTH_TOKEN=...

Modelo de seguridad

• La ejecución en vivo es opcional a través de herramientas específicas de producto *-execute.

• Los métodos que implican cambios requieren confirmación explícita y un motivo de cambio.

• Las URLs base de la API del producto deben usar http o https.

• Se rechazan las URLs HTTP que no sean localhost; se requiere HTTPS fuera del desarrollo local.

• Se rechazan las URLs con credenciales integradas.

• Los encabezados de autorización y clave de API están protegidos contra anulaciones arbitrarias.

• Los tamaños de carga y descarga binaria están limitados por límites configurables.

• Los secretos se generan y gestionan localmente en ~/.lerian/secrets.json cuando es necesario.

Ejemplos de conversaciones

Descubrimiento de portafolio

Tú: "¿Con qué productos de Lerian puede ayudar este MCP?"

IA: Usa lerian con product="all", operation="discover".

Ruta de aprendizaje

Tú: "Soy nuevo en Tracer. Enséñame cómo funcionan las reglas de validación."

IA: Usa lerian con product="tracer", operation="learn", topic="rules".

Ejemplo de SDK

Tú: "Muéstrame código Go para crear un libro mayor de Midaz."

IA: Usa lerian con product="midaz", operation="sdk", language="go".

Descubrimiento de contrato de API en vivo

Tú: "Inspecciona el contrato para crear una plantilla de Reporter."

IA: Usa reporter-discover antes de cualquier llamada a reporter-execute.

Flujo de trabajo entre productos

Tú: "Guíame a través de la validación de mapeos de Fetcher antes de generar un informe."

IA: Usa portfolio-workflow con workflow="fetcher-to-reporter".

Desarrollo

Requiere Node.js >=20.19.0.

npm ci
npm run build
npm test

Scripts útiles:

• npm run dev: ejecuta el punto de entrada de TypeScript con ts-node.

• npm run build: compila a dist/ y marca los binarios como ejecutables.

• npm run lint: ejecuta ESLint.

• npm run typecheck: ejecuta TypeScript sin emitir archivos.

• npm test: ejecuta pruebas de Node más la prueba básica del servidor.

• npm run docs: genera la salida de TypeDoc en docs/.

Documentación

• Documentación completa

• Rutas de aprendizaje

• Referencia de SDK

• Solución de problemas

• Índice de medios y diagramas

• Instrucciones para agentes

Información del paquete

• Paquete npm: @lerianstudio/lerian-mcp-server

• Versión actual del paquete: 3.4.0

• Entorno de ejecución: Node.js ESM

• SDK de MCP: @modelcontextprotocol/sdk

• Licencia: Apache-2.0

• Repositorio: github.com/lerianstudio/lerian-mcp-server

Resumen de arquitectura

MCP Client
  -> stdio transport
  -> McpServer from @modelcontextprotocol/sdk
  -> core tools and prompts
  -> product adapters
  -> product routers and schema registries
  -> configured Lerian product APIs

Capas principales:

1. Transporte: MCP JSON-RPC sobre stdio.

2. Bootstrap del servidor: seguridad, secretos, manifiesto de documentos, registro, detección de clientes.

3. Herramientas principales: lerian y portfolio-workflow.

4. Adaptadores de producto: pares de descubrimiento/ejecución para productos compatibles.

5. Registros de esquemas: contratos de recursos/acciones para superficies de API.

6. Ejecución HTTP: construcción de URL validada, ejecución de solicitudes, análisis de respuesta y clasificación de errores.

7. Orquestación de flujo de trabajo: flujos guiados y con estado entre múltiples productos.

Solución de problemas

El servidor no inicia

Comprueba la versión de Node.js:

node --version

Ejecuta manualmente:

npx -y @lerianstudio/lerian-mcp-server@latest

Comprueba los secretos locales:

ls -la ~/.lerian/secrets.json

Las llamadas a la API en vivo fallan

• Usa primero la herramienta *-discover del producto.

• Verifica que la URL base relevante y el token/clave de API estén configurados.

• Confirma que las URLs remotas no locales usen HTTPS.

• Para cambios, incluye confirmMutation=true y mutationReason.

• Comprueba si el servicio del producto de destino es accesible desde el entorno de ejecución de MCP.

La herramienta no responde en el cliente

• Reinicia el cliente MCP después de realizar cambios en la configuración.

• Confirma que MCP esté habilitado en el cliente.

• Habilita el registro con LOG_LEVEL=debug si es necesario.

• Comprueba ./logs/ cuando el registro esté habilitado.