Lerian MCP Server

Шлюз MCP для поиска продуктов Lerian, документации, обучения, примеров SDK, доступа к API продуктов в реальном времени и рабочих процессов между продуктами.

Этот сервер подключает MCP-клиенты, такие как Claude Desktop, Cursor, Windsurf, Continue и ChatGPT Desktop, к портфолио продуктов Lerian. Он предоставляет ИИ-ассистентам структурированный способ поиска продуктов Lerian, чтения официальной документации, генерации примеров реализации, проверки контрактов API в реальном времени, выполнения настроенных API продуктов и управления рабочими процессами, охватывающими несколько продуктов.

Область выполнения: этот сервер не ограничивается только документацией. Универсальный инструмент lerian ориентирован на чтение, но инструменты *-execute для конкретных продуктов могут вызывать настроенные API Lerian в реальном времени. Вызовы API, изменяющие данные, требуют явного подтверждения и указания причины аудита.

2-минутная настройка

1. Выберите ваш MCP-совместимый ИИ-ассистент.

2. Добавьте конфигурацию сервера.

3. Перезапустите ИИ-приложение.

4. Спросите: "What can you tell me about Lerian Midaz?"

Claude Desktop

Расположение в macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Расположение в Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Cursor, Windsurf, Continue, ChatGPT Desktop

Добавьте тот же блок сервера MCP в конфигурацию MCP вашего клиента:

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

Что вы получаете

Поддерживаемые продукты

• Midaz: платформа финансовой бухгалтерской книги с функциями онбординга, балансов, транзакций, CRM и бухгалтерскими сервисами.

• Fetcher: подключение к источникам данных, обнаружение схем и сервис асинхронного извлечения.

• Reporter: генерация отчетов на основе шаблонов, управление источниками данных, метрики и артефакты.

• Matcher: механизм сверки для сопоставления транзакций Midaz с внешними системами.

• Tracer: механизм проверки транзакций с правилами, лимитами, валидациями и аудируемостью.

• Flowker: платформа оркестрации рабочих процессов для провайдеров, исполнителей, вебхуков и потоков выполнения.

• Underwriter: поверхность кредитования с учетом юрисдикции для кредитных продуктов и предварительного просмотра графиков.

• All: поиск по всему портфолио, поиск по документации и сравнение.

Основные возможности

• Поиск по портфолио через lerian с operation="discover".

• Поиск по документации через lerian с operation="docs".

• Обучение через lerian с operation="learn".

• Примеры SDK через lerian с operation="sdk".

• Поиск по нескольким продуктам через lerian с operation="search".

• Обнаружение контрактов API в реальном времени через инструменты *-discover для конкретных продуктов.

• Выполнение API в реальном времени через инструменты *-execute для конкретных продуктов.

• Рабочие процессы между продуктами через portfolio-workflow.

• Подсказки на основе промптов для онбординга, обучения, использования API и операционных рабочих процессов.

Поверхность инструментов выполнения

Сервер предоставляет небольшое ядро плюс пары API в реальном времени для каждого поддерживаемого продукта.

Основные инструменты

• lerian: универсальный инструмент портфолио для документации, обучения, примеров SDK, поиска и обнаружения.

• portfolio-workflow: обнаружение рабочих процессов между продуктами, планирование, сессии с сохранением состояния и выполнение шагов.

Инструменты Live API

• midaz-discover и midaz-execute

• fetcher-discover и fetcher-execute

• reporter-discover и reporter-execute

• matcher-discover и matcher-execute

• tracer-discover и tracer-execute

• flowker-discover и flowker-execute

• underwriter-discover и underwriter-execute

Используйте соответствующий инструмент *-discover перед вызовом инструмента *-execute. Обнаружение возвращает ресурсы, действия, параметры пути, параметры запроса, схемы тела запроса, примеры и подсказки по выполнению.

Инструмент lerian

Инструмент lerian является основной точкой входа, ориентированной на чтение.

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

Пример:

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

Рабочий процесс Live API

Доступ к API в реальном времени намеренно разделен на два этапа.

1. Изучите поверхность продукта:

{
  "intent": "list-resources"
}

2. Изучите контракт конкретного действия:

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

3. Выполните действие с контрактом, полученным при обнаружении:

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

Действия API, изменяющие данные, требуют:

• confirmMutation: true

• mutationReason с человекочитаемой причиной аудита

Рабочие процессы между продуктами

Используйте portfolio-workflow, когда задача охватывает несколько продуктов Lerian.

Текущие рабочие процессы:

• fetcher-to-reporter: проверка маппингов извлечения с помощью Fetcher, затем генерация или проверка отчетов Reporter.

• matcher-to-fetcher-to-midaz: настройка сверки Matcher, использование обнаружения Matcher через Fetcher и проверка данных на стороне бухгалтерской книги Midaz.

Поддерживаемые намерения:

• list-workflows

• describe-workflow

• plan

• create-session

• get-session

• list-sessions

• execute-step

• execute-next

Сессии рабочих процессов возвращают непрозрачный sessionToken. Храните его в секрете.

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

Сервер работает сразу для документации и обнаружения. Выполнение API в реальном времени требует доступных сервисов продуктов и, где применимо, токенов или ключей API.

Источники конфигурации в порядке приоритета:

• Командная строка --config или --config-file

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

• ./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

• Глобальные пути конфигурации платформы

Создайте или обновите конфигурацию интерактивно:

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

Общие переменные окружения:

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=...

Модель безопасности

• Выполнение в реальном времени является опциональным через инструменты *-execute для конкретных продуктов.

• Методы, изменяющие данные, требуют явного подтверждения и причины изменения.

• Базовые URL API продуктов должны использовать http или https.

• HTTP-URL, отличные от localhost, отклоняются; HTTPS требуется вне локальной разработки.

• URL со встроенными учетными данными отклоняются.

• Заголовки авторизации и ключей API защищены от произвольной перезаписи.

• Размеры бинарных файлов для загрузки и скачивания ограничены настраиваемыми лимитами.

• Секреты генерируются и управляются локально в ~/.lerian/secrets.json при необходимости.

Примеры диалогов

Поиск по портфолио

Вы: "What Lerian products can this MCP help with?"

ИИ: Использует lerian с product="all", operation="discover".

Путь обучения

Вы: "I'm new to Tracer. Teach me how validation rules work."

ИИ: Использует lerian с product="tracer", operation="learn", topic="rules".

Пример SDK

Вы: "Show me Go code for creating a Midaz ledger."

ИИ: Использует lerian с product="midaz", operation="sdk", language="go".

Обнаружение контракта Live API

Вы: "Inspect the contract for creating a Reporter template."

ИИ: Использует reporter-discover перед любым вызовом reporter-execute.

Рабочий процесс между продуктами

Вы: "Guide me through validating Fetcher mappings before generating a report."

ИИ: Использует portfolio-workflow с workflow="fetcher-to-reporter".

Разработка

Требуется Node.js >=20.19.0.

npm ci
npm run build
npm test

Полезные скрипты:

• npm run dev: запуск точки входа TypeScript с помощью ts-node.

• npm run build: компиляция в dist/ и установка прав на выполнение для бинарных файлов.

• npm run lint: запуск ESLint.

• npm run typecheck: запуск TypeScript без создания файлов.

• npm test: запуск тестов Node плюс базовый тест сервера.

• npm run docs: генерация вывода TypeDoc в docs/.

Документация

• Полная документация

• Пути обучения

• Справочник SDK

• Устранение неполадок

• Индекс медиа и диаграмм

• Инструкции для агентов

Информация о пакете

• npm-пакет: @lerianstudio/lerian-mcp-server

• Текущая версия пакета: 3.4.0

• Среда выполнения: Node.js ESM

• MCP SDK: @modelcontextprotocol/sdk

• Лицензия: Apache-2.0

• Репозиторий: github.com/lerianstudio/lerian-mcp-server

Краткий обзор архитектуры

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

Основные уровни:

1. Транспорт: MCP JSON-RPC через stdio.

2. Загрузка сервера: безопасность, секреты, манифест документации, логирование, обнаружение клиента.

3. Основные инструменты: lerian и portfolio-workflow.

4. Адаптеры продуктов: пары обнаружения/выполнения для поддерживаемых продуктов.

5. Реестры схем: контракты ресурсов/действий для поверхностей API.

6. Выполнение HTTP: проверка построения URL, выполнение запросов, парсинг ответов и классификация ошибок.

7. Оркестрация рабочих процессов: управляемые, сохраняющие состояние потоки между несколькими продуктами.

Устранение неполадок

Сервер не запускается

Проверьте версию Node.js:

node --version

Запустите вручную:

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

Проверьте локальные секреты:

ls -la ~/.lerian/secrets.json

Вызовы Live API завершаются ошибкой

• Сначала используйте инструмент *-discover для продукта.

• Убедитесь, что настроены соответствующий базовый URL и токен/ключ API.

• Подтвердите, что удаленные URL (не локальные) используют HTTPS.

• Для изменений включите confirmMutation=true и mutationReason.

• Проверьте, доступен ли целевой сервис продукта из среды выполнения MCP.

Инструмент не отвечает в клиенте

• Перезапустите MCP-клиент после внесения изменений в конфигурацию.

• Убедитесь, что MCP включен в клиенте.

• При необходимости включите логирование с помощью LOG_LEVEL=debug.

• Проверьте ./logs/, когда логирование включено.