使用说明

• 项目简介

  • 这是一个基于 MCP（Model Context Protocol）的后端服务器实现，旨在为 LLM 客户端提供可控的上下文和能力。它把 YNAB 的核心操作（如预算、账户、交易等的查询与修改）暴露为 MCP 工具，LLM 可以通过工具名称调用对应功能。
  • 服务器通过标准输入输出（stdio）通道与客户端交互，返回经过格式化的 JSON 响应，方便在各种集成场景中被解析。

• 主要功能点

  • 工具暴露（Tools）：包含 list_budgets、get_budget、list_accounts、get_account、list_categories、list_transactions、create_transaction、update_transaction、delete_transaction、import_transactions、summarize_transactions、find_transfer_candidates、以及更多与 YNAB 相关的操作。每个工具都有输入模式（使用 zod 定义参数结构）和实现逻辑，直接调用内置的 client 层与 YNAB API 交互。
  • 数据渲染与格式化：服务器返回的内容经过 jsonResponse/json 的封装，确保输出符合 MCP 客户端的期望结构，包含字段与数据层级的一致性。
  • 自身状态与能力：工具清单中包含 check_auth、get_user 等能力检查方法，便于客户端在调用前进行能力自检。
  • 传输协议：当前实现使用 StdioServerTransport（标准输入输出）作为传输通道，便于在本地或托管环境中与 Macro/LLM 框架集成。

• 安装步骤

  1. 确保运行环境中已安装 Bun（仓库 README 给出的推荐方式）。
  2. 将仓库代码安装到本地环境（通常通过 bun install 或等价的包管理命令）。
  3. 启动 MCP 服务器：在项目内执行命令 ynab mcp（该命令会启动 MCP 服务器，监听与 LLM 客户端的 JSON-RPC 通讯）。

• 服务器配置（MCP 客户端所需） 说明：MCP 客户端需要一个 JSON 配置来知道如何启动 MCP 服务器。下面给出基于仓库信息的准确配置示例及字段说明。注：该配置是给 MCP 客户端使用的，不需要在服务器端实现中呈现。

  • server_name: ynab
  • command: ynab
  • args: ["mcp"]
  • transport: stdio 说明与注释：
  • server_name 指定 MCP 服务的名称，匹配服务器实现中的 name 字段（ynab）。
  • command 与 args 指定启动服务器的命令行，结合现有代码逻辑，运行 ynab mcp 即可启动 MCP 服务器。
  • transport 指定通信通道，此实现使用 stdio（标准输入输出），以便与运行在同一进程或管道中的客户端通信。

• 基本使用方法

  • 启动：在包含该仓库的环境中执行 ynab mcp，服务器将通过 stdio 与客户端建立 JSON-RPC 通道。
  • 调用方式：LLM 客户端通过 MCP 协议向服务器请求工具执行，例如调用 list_budgets、get_budget 等，服务器返回相应的 JSON 响应。
  • 诊断与扩展：可以通过 search_tools 工具在服务器暴露的工具中按名称或描述进行快速匹配，便于 CLI 与 LLM 之间的协作。

• 额外信息

  • 服务器端采用 YA N AB API 客户端封装（lib/api-client.ts）进行实际的数据获取与操作，所有返回的数据会在必要时进行单位换算与字段筛选。
  • MCP 服务器实现的位置在 src/mcp/server.ts，核心是创建并注册一组工具到 McpServer 实例，然后通过 StdioServerTransport 连接。