Lerian MCP 服务器

一个用于 Lerian 产品组合发现、文档查阅、学习、SDK 示例、实时产品 API 访问及跨产品工作流的 MCP 网关。

此服务器将 Claude Desktop、Cursor、Windsurf、Continue 和 ChatGPT Desktop 等 MCP 客户端连接到 Lerian 产品组合。它为 AI 助手提供了一种结构化的方式来发现 Lerian 产品、阅读官方文档、生成实现示例、检查实时 API 契约、执行已配置的产品 API，并指导多产品操作工作流。

运行时范围： 此服务器并非仅限文档。统一的 lerian 工具是面向读取的，但特定于产品的 *-execute 工具可以调用已配置的实时 Lerian API。变更性 API 调用需要明确确认和审计原因。

2 分钟设置

1. 选择您支持 MCP 的 AI 助手。

2. 添加服务器配置。

3. 重启 AI 应用。

4. 询问：“你能告诉我关于 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"]
    }
  }
}

Related MCP server: DevDocs MCP Server

您将获得什么

支持的产品

• Midaz：金融账本平台，包含入驻、余额、交易、CRM 和账本服务。

• Fetcher：数据源连接、模式发现和异步提取服务。

• Reporter：模板驱动的报告生成、数据源管理、指标和工件。

• Matcher：用于将 Midaz 交易与外部系统进行匹配的对账引擎。

• Tracer：包含规则、限制、验证和可审计性的交易验证引擎。

• Flowker：用于提供者、执行者、Webhook 和执行流的工作流编排平台。

• Underwriter：支持司法管辖区的贷款界面，用于贷款产品和计划预览。

• All：全产品组合发现、文档搜索和比较。

核心能力

• 通过 lerian 和 operation="discover" 进行产品组合发现。

• 通过 lerian 和 operation="docs" 进行文档查找。

• 通过 lerian 和 operation="learn" 进行引导式学习。

• 通过 lerian 和 operation="sdk" 进行SDK 示例生成。

• 通过 lerian 和 operation="search" 进行跨产品搜索。

• 通过特定于产品的 *-discover 工具进行实时 API 契约发现。

• 通过特定于产品的 *-execute 工具进行实时 API 执行。

• 通过 portfolio-workflow 进行跨产品工作流。

• 为入驻、学习、API 使用和操作工作流提供基于提示的指导。

运行时工具界面

服务器为每个支持的产品公开了一个小型核心工具集以及实时 API 对。

核心工具

• lerian：用于文档、学习、SDK 示例、发现和搜索的统一产品组合工具。

• portfolio-workflow：跨产品工作流发现、规划、有状态会话和步骤执行。

实时 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

在调用 *-execute 工具之前，请使用匹配的 *-discover 工具。发现功能会返回资源、操作、路径参数、查询参数、主体模式、示例和执行提示。

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"
}

实时 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（包含人类可读的审计原因）

跨产品工作流

当任务跨越多个 Lerian 产品时，请使用 portfolio-workflow。

当前工作流：

• fetcher-to-reporter：使用 Fetcher 验证提取映射，然后生成或检查 Reporter 报告。

• matcher-to-fetcher-to-midaz：配置 Matcher 对账，在 Fetcher 上使用 Matcher 发现，并检查 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 工具选择性加入。

• 变更性方法需要明确确认和变更原因。

• 产品 API 基础 URL 必须使用 http 或 https。

• 非 localhost 的 HTTP URL 将被拒绝；本地开发环境之外必须使用 HTTPS。

• 带有嵌入式凭据的 URL 将被拒绝。

• 授权和 API 密钥标头受到保护，防止被任意覆盖。

• 二进制上传和下载大小受可配置限制的约束。

• 需要时，机密信息会在本地 ~/.lerian/secrets.json 下生成和管理。

对话示例

产品组合发现

您： “此 MCP 可以帮助处理哪些 Lerian 产品？”

AI： 使用 lerian，参数为 product="all", operation="discover"。

学习路径

您： “我是 Tracer 的新手。教我验证规则是如何工作的。”

AI： 使用 lerian，参数为 product="tracer", operation="learn", topic="rules"。

SDK 示例

您： “给我展示用于创建 Midaz 账本的 Go 代码。”

AI： 使用 lerian，参数为 product="midaz", operation="sdk", language="go"。

实时 API 契约发现

您： “检查创建 Reporter 模板的契约。”

AI： 在任何 reporter-execute 调用之前使用 reporter-discover。

跨产品工作流

您： “指导我在生成报告之前验证 Fetcher 映射。”

AI： 使用 portfolio-workflow，参数为 workflow="fetcher-to-reporter"。

开发

需要 Node.js >=20.19.0。

npm ci
npm run build
npm test

实用脚本：

• npm run dev：使用 ts-node 运行 TypeScript 入口点。

• 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. 传输： 基于 stdio 的 MCP JSON-RPC。

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

实时 API 调用失败

• 首先使用产品 *-discover 工具。

• 验证相关的基础 URL 和令牌/API 密钥是否已配置。

• 确认非本地远程 URL 使用 HTTPS。

• 对于变更操作，包含 confirmMutation=true 和 mutationReason。

• 检查目标产品服务是否可从 MCP 运行时访问。

客户端中的工具无响应

• 配置更改后重启 MCP 客户端。

• 确认客户端中已启用 MCP。

• 如有需要，通过 LOG_LEVEL=debug 启用日志记录。

• 启用日志记录后，检查 ./logs/。