Lerian MCP Server

Lerian MCP Server

面向 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"]
    }
  }
}

---

你将获得的功能

支持的产品

• Midaz：统一的复式记账账本——通过单一服务提供组织、账本、账户、余额、交易和 CRM。
• Fetcher：数据源连接、架构发现和异步提取服务。
• Reporter：模板驱动的报告生成、数据源管理、指标和构件。
• Matcher：对账引擎，用于将 Midaz 交易与外部系统进行匹配。
• Tracer：交易验证引擎，提供规则、限制、验证和可审计性。
• Flowker：工作流编排平台，支持提供商、执行器、Webhooks 和执行流。
• 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 对账，使用 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

Midaz 是一项统一的账本服务，通过一个基础 URL 访问。入门配置、账户、余额、交易和 CRM 都是该服务的资源，因此只需配置一个 Midaz URL。

常见环境变量：

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

MIDAZ_BASE_URL=http://localhost:3002
MIDAZ_AUTH_TOKEN=...
MIDAZ_API_TIMEOUT=30000

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

迁移到 4.0.0

破坏性变更：Midaz 配置。4.0.0 之前的版本要求使用 4 个独立的 Midaz URL，分别对应旧版服务（入门配置、交易、CRM、账本）。这些变量已移除，不会读取，也不再接受。请将 MIDAZ_BASE_URL 指向统一的 Midaz 账本，并保持 MIDAZ_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 示例

你：“展示用 Go 创建 Midaz 账本的代码。”

**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 参考
• 故障排除
• 媒体和图表索引
• Agent 说明

---

软件包信息

• npm 软件包： @lerianstudio/lerian-mcp-server — npm 页面和 GitHub 发布版本提供当前版本和变更日志。
• 运行环境： Node.js ESM
• 传输方式： 仅支持 stdio
• 许可证： Apache-2.0
• 代码仓库： github.com/lerianstudio/lerian-mcp-server

---

架构概要

MCP Client
  -> stdio transport
  -> MCP server runtime
  -> 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/。