Lerian MCP-Server

Ein MCP-Gateway für die Entdeckung des Lerian-Portfolios, Dokumentation, Lernen, SDK-Beispiele, Live-Produkt-API-Zugriff und produktübergreifende Workflows.

Dieser Server verbindet MCP-Clients wie Claude Desktop, Cursor, Windsurf, Continue und ChatGPT Desktop mit dem Lerian-Produktportfolio. Er bietet KI-Assistenten eine strukturierte Möglichkeit, Lerian-Produkte zu entdecken, offizielle Dokumentationen zu lesen, Implementierungsbeispiele zu generieren, Live-API-Verträge zu prüfen, konfigurierte Produkt-APIs auszuführen und produktübergreifende operative Workflows zu steuern.

Laufzeitumfang: Dieser Server ist nicht nur für Dokumentationen gedacht. Das einheitliche lerian-Tool ist leserorientiert, aber produktspezifische *-execute-Tools können konfigurierte Live-Lerian-APIs aufrufen. Mutierende API-Aufrufe erfordern eine explizite Bestätigung und einen Audit-Grund.

2-Minuten-Einrichtung

1. Wählen Sie Ihren MCP-kompatiblen KI-Assistenten.

2. Fügen Sie die Serverkonfiguration hinzu.

3. Starten Sie die KI-App neu.

4. Fragen Sie: "Was kannst du mir über Lerian Midaz erzählen?"

Claude Desktop

macOS-Pfad: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows-Pfad: %APPDATA%\Claude\claude_desktop_config.json

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

Cursor, Windsurf, Continue, ChatGPT Desktop

Fügen Sie denselben MCP-Server-Block zur MCP-Konfiguration Ihres Clients hinzu:

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

Was Sie erhalten

Unterstützte Produkte

• Midaz: Plattform für Finanzbuchhaltung mit Onboarding, Salden, Transaktionen, CRM und Ledger-Diensten.

• Fetcher: Datenquellenverbindung, Schema-Erkennung und asynchroner Extraktionsdienst.

• Reporter: Vorlagenbasierte Berichterstellung, Datenquellenverwaltung, Metriken und Artefakte.

• Matcher: Abgleich-Engine für den Abgleich von Midaz-Transaktionen mit externen Systemen.

• Tracer: Transaktionsvalidierungs-Engine mit Regeln, Limits, Validierungen und Revisionssicherheit.

• Flowker: Workflow-Orchestrierungsplattform für Provider, Executoren, Webhooks und Ausführungsabläufe.

• Underwriter: Gerichtsbarkeitsbewusste Kreditplattform für Kreditprodukte und Zeitplanvorschau.

• All: Portfolio-weite Entdeckung, Dokumentationssuche und Vergleich.

Kernfunktionen

• Portfolio-Entdeckung über lerian mit operation="discover".

• Dokumentationssuche über lerian mit operation="docs".

• Geführtes Lernen über lerian mit operation="learn".

• SDK-Beispiele über lerian mit operation="sdk".

• Produktübergreifende Suche über lerian mit operation="search".

• Live-API-Vertragsentdeckung über produktspezifische *-discover-Tools.

• Live-API-Ausführung über produktspezifische *-execute-Tools.

• Produktübergreifende Workflows über portfolio-workflow.

• Prompt-basierte Anleitung für Onboarding, Lernen, API-Nutzung und operative Workflows.

Laufzeit-Tool-Oberfläche

Der Server stellt einen kleinen Kern sowie Live-API-Paare für jedes unterstützte Produkt bereit.

Kern-Tools

• lerian: Einheitliches Portfolio-Tool für Dokumente, Lernen, SDK-Beispiele, Entdeckung und Suche.

• portfolio-workflow: Produktübergreifende Workflow-Entdeckung, Planung, zustandsbehaftete Sitzungen und Schrittausführung.

Live-API-Tools

• midaz-discover und midaz-execute

• fetcher-discover und fetcher-execute

• reporter-discover und reporter-execute

• matcher-discover und matcher-execute

• tracer-discover und tracer-execute

• flowker-discover und flowker-execute

• underwriter-discover und underwriter-execute

Verwenden Sie das passende *-discover-Tool, bevor Sie ein *-execute-Tool aufrufen. Die Entdeckung liefert Ressourcen, Aktionen, Pfadparameter, Abfrageparameter, Body-Schemas, Beispiele und Ausführungshinweise.

Das lerian-Tool

Das lerian-Tool ist der primäre leserorientierte Einstiegspunkt.

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

Beispiel:

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

Live-API-Workflow

Der Live-API-Zugriff erfolgt bewusst in zwei Schritten.

1. Überprüfen Sie die Produktoberfläche:

{
  "intent": "list-resources"
}

2. Überprüfen Sie einen spezifischen Aktionsvertrag:

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

3. Führen Sie die Aktion mit dem exakten Vertrag aus, der durch die Entdeckung zurückgegeben wurde:

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

Mutierende Live-API-Aktionen erfordern:

• confirmMutation: true

• mutationReason mit einem für Menschen lesbaren Audit-Grund

Produktübergreifende Workflows

Verwenden Sie portfolio-workflow, wenn die Aufgabe mehrere Lerian-Produkte umfasst.

Aktuelle Workflows:

• fetcher-to-reporter: Validieren Sie Extraktionszuordnungen mit Fetcher und generieren oder prüfen Sie dann Reporter-Berichte.

• matcher-to-fetcher-to-midaz: Konfigurieren Sie den Matcher-Abgleich, verwenden Sie die Matcher-Entdeckung über Fetcher und prüfen Sie Daten auf der Midaz-Ledger-Seite.

Unterstützte Intents:

• list-workflows

• describe-workflow

• plan

• create-session

• get-session

• list-sessions

• execute-step

• execute-next

Workflow-Sitzungen geben ein opakes sessionToken zurück. Behandeln Sie dieses vertraulich.

Konfiguration

Der Server funktioniert sofort für Dokumentation und Entdeckung. Die Live-API-Ausführung erfordert erreichbare Produktdienste und gegebenenfalls Token oder API-Schlüssel.

Konfigurationsquellen in der Prioritätsreihenfolge:

• Befehlszeile --config oder --config-file

• Umgebungsvariablen

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

• Globale Plattform-Konfigurationspfade

Konfiguration interaktiv erstellen oder aktualisieren:

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

Allgemeine Umgebungsvariablen:

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

Sicherheitsmodell

• Die Live-Ausführung erfolgt per Opt-in über produktspezifische *-execute-Tools.

• Mutierende Methoden erfordern eine explizite Bestätigung und einen Mutationsgrund.

• Produkt-API-Basis-URLs müssen http oder https verwenden.

• Nicht-lokale HTTP-URLs werden abgelehnt; HTTPS ist außerhalb der lokalen Entwicklung erforderlich.

• URLs mit eingebetteten Anmeldeinformationen werden abgelehnt.

• Autorisierungs- und API-Schlüssel-Header sind vor willkürlichem Überschreiben geschützt.

• Binäre Upload- und Download-Größen sind durch konfigurierbare Limits begrenzt.

• Geheimnisse werden bei Bedarf lokal unter ~/.lerian/secrets.json generiert und verwaltet.

Beispielkonversationen

Portfolio-Entdeckung

Sie: "Bei welchen Lerian-Produkten kann mir dieses MCP helfen?"

KI: Verwendet lerian mit product="all", operation="discover".

Lernpfad

Sie: "Ich bin neu bei Tracer. Bring mir bei, wie Validierungsregeln funktionieren."

KI: Verwendet lerian mit product="tracer", operation="learn", topic="rules".

SDK-Beispiel

Sie: "Zeig mir Go-Code zum Erstellen eines Midaz-Ledgers."

KI: Verwendet lerian mit product="midaz", operation="sdk", language="go".

Live-API-Vertragsentdeckung

Sie: "Prüfe den Vertrag zum Erstellen einer Reporter-Vorlage."

KI: Verwendet reporter-discover vor jedem reporter-execute-Aufruf.

Produktübergreifender Workflow

Sie: "Führe mich durch die Validierung von Fetcher-Zuordnungen, bevor ein Bericht generiert wird."

KI: Verwendet portfolio-workflow mit workflow="fetcher-to-reporter".

Entwicklung

Erfordert Node.js >=20.19.0.

npm ci
npm run build
npm test

Nützliche Skripte:

• npm run dev: Führt den TypeScript-Einstiegspunkt mit ts-node aus.

• npm run build: Kompiliert nach dist/ und markiert Binärdateien als ausführbar.

• npm run lint: Führt ESLint aus.

• npm run typecheck: Führt TypeScript aus, ohne Dateien zu emittieren.

• npm test: Führt Node-Tests sowie den grundlegenden Server-Test aus.

• npm run docs: Generiert TypeDoc-Ausgabe in docs/.

Dokumentation

• Vollständige Dokumentation

• Lernpfade

• SDK-Referenz

• Fehlerbehebung

• Medien- und Diagrammindex

• Agentenanweisungen

Paketinformationen

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

• Aktuelle Paketversion: 3.4.0

• Laufzeit: Node.js ESM

• MCP SDK: @modelcontextprotocol/sdk

• Lizenz: Apache-2.0

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

Architekturzusammenfassung

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

Primäre Ebenen:

1. Transport: MCP JSON-RPC über stdio.

2. Server-Bootstrap: Sicherheit, Geheimnisse, Dokumentenmanifest, Protokollierung, Client-Erkennung.

3. Kern-Tools: lerian und portfolio-workflow.

4. Produktadapter: Entdecken/Ausführen-Paare für unterstützte Produkte.

5. Schema-Register: Ressourcen/Aktionsverträge für API-Oberflächen.

6. HTTP-Ausführung: Validierte URL-Konstruktion, Anforderungsausführung, Antwort-Parsing und Fehlerklassifizierung.

7. Workflow-Orchestrierung: Geführte, zustandsbehaftete produktübergreifende Abläufe.

Fehlerbehebung

Server startet nicht

Überprüfen Sie die Node.js-Version:

node --version

Manuell ausführen:

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

Lokale Geheimnisse prüfen:

ls -la ~/.lerian/secrets.json

Live-API-Aufrufe schlagen fehl

• Verwenden Sie zuerst das Produkt-Tool *-discover.

• Überprüfen Sie, ob die relevante Basis-URL und der Token/API-Schlüssel konfiguriert sind.

• Bestätigen Sie, dass nicht-lokale Remote-URLs HTTPS verwenden.

• Fügen Sie bei Mutationen confirmMutation=true und mutationReason hinzu.

• Prüfen Sie, ob der Zielproduktdienst von der MCP-Laufzeitumgebung aus erreichbar ist.

Tool reagiert nicht im Client

• Starten Sie den MCP-Client nach Konfigurationsänderungen neu.

• Bestätigen Sie, dass MCP im Client aktiviert ist.

• Aktivieren Sie bei Bedarf die Protokollierung mit LOG_LEVEL=debug.

• Überprüfen Sie ./logs/, wenn die Protokollierung aktiviert ist.