mcpField
M
Midaz MCP Server

Midaz MCP Server

本地服务
github.com/LerianStudio金融数据810 周前更新
代码仓库

关于 Midaz MCP Server

Midaz MCP Server 为 AI 助手提供结构化接口，用于发现 Lerian 产品、查阅文档、检查 API 并调用已配置的操作。它也支持跨产品工作流；修改操作须明确确认并提供审计原因。

主要功能

  1. 01发现产品组合与文档
  2. 02引导学习并提供 SDK 示例
  3. 03发现并执行实时 API 合约
  4. 04规划跨产品工作流并管理会话
  5. 05修改操作需确认和审计原因

适用场景

  1. 01探索 Lerian 产品与文档
  2. 02学习产品 API 并生成 SDK 示例
  3. 03检查并调用已配置的产品 API
  4. 04协调 Fetcher、Reporter、Matcher 与 Midaz 工作流

MCP 相关

它通过 stdio 向 MCP 客户端提供产品组合工具、跨产品工作流，以及针对各产品的发现和执行工具。调用实时 API 需要配置端点和凭据；修改操作须确认并提供审计原因。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "midaz": {
      "command": "npx",
      "args": [
        "-y",
        "@lerianstudio/lerian-mcp-server"
      ]
    }
  }
}
启动命令npx -y @lerianstudio/lerian-mcp-server

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@lerianstudio/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"
}
  1. 检查特定操作的契约：
{
  "intent": "describe-action",
  "resource": "transactions",
  "action": "create"
}
  1. 使用发现操作返回的确切契约执行：
{
  "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/。

文档

软件包信息

架构概要

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/。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。