YNAB MCP 启动器

用于只读 YNAB MCP 服务器的生产级 TypeScript 启动仓库。

此启动器刻意保持精简且明确：

• Node.js 18+

• 带有严格编译器设置的 TypeScript

• 经过 Zod 验证的工具输入和输出

• 带有重试和超时处理的只读 YNAB API 客户端

• 使用模拟 YNAB 响应的单元测试

• 明确的 TODO 标记，指示应在何处连接 MCP 传输线路

此仓库包含的内容

src/
  clients/   YNAB API client, environment config, and error types
  schemas/   strict Zod schemas for tool contracts
  server/    MCP server composition and transport TODO placeholders
  tools/     read-only business logic for each YNAB capability
  types/     shared API and service types
tests/       unit tests with mocked API responses

已实现的只读功能：

• 列出预算

• 列出账户

• 列出类别

• 列出最近的交易

• 查找未分类的交易

• 按类别划分的月度支出

刻意未实现写入访问权限。

Related MCP server: MCP Server Starter

设置

1. 安装依赖项：

npm install

2. 复制示例环境变量文件：

cp .env.example .env

3. 在 .env 中设置您的 YNAB 令牌：

YNAB_TOKEN=your-token-here

4. 运行本地开发模式：

npm run dev

脚本

• npm run build 将 TypeScript 编译到 dist/

• npm run dev 运行带有文件监视功能的启动入口点

• npm run lint 运行 ESLint

• npm run test 使用 Vitest 运行单元测试

• npm run typecheck 以无输出模式运行 TypeScript

MCP 线路连接

该仓库包含了服务器组合层，但尚未将您锁定在特定的传输方式中。

请查看以下文件中的 TODO 注释：

• src/server/index.ts

• src/server/registerTools.ts

您应该在这些地方执行以下操作：

1. 实例化 MCP 服务器

2. 注册工具定义和模式

3. 连接 stdio、SSE 或其他传输方式

4. 添加结构化日志记录和操作钩子

安全说明

• 此启动器期望在环境变量中提供 YNAB_TOKEN 个人访问令牌。

• 切勿在源代码文件、测试、提示词或日志中硬编码令牌。

• 将令牌的作用域限制为只读操作用途，如果令牌泄露，请及时轮换。

• 避免在生产环境中记录原始 YNAB API 响应，因为它们可能包含交易备注或其他敏感的财务元数据。

• 此启动器仅对 YNAB API 执行 GET 请求。未实现任何写入端点。

设计说明

• YNAB 客户端集中处理重试、超时和错误标准化。

• 工具模块与 HTTP 细节隔离，并在小型服务接口上运行。

• Zod 模式验证工具输入和输出，以便尽早发现偏差。

• 金钱金额以 YNAB 毫单位和人类友好的十进制金额两种方式公开。

• 月度类别支出仅计算所请求月份的流出金额。

示例提示词

• "列出我的 YNAB 预算。"

• "显示预算 budget-id-123 中的账户。"

• "列出预算 budget-id-123 的类别。"

• "显示预算 budget-id-123 中最近的 20 笔交易。"

• "查找预算 budget-id-123 中自 2026-04-01 以来的未分类交易。"

• "汇总预算 budget-id-123 在 2026-04 的按类别月度支出。"

测试

测试会模拟 YNAB API 响应，因此您无需实时令牌即可验证行为：

npm run test

生产加固建议

• 添加请求关联 ID 和结构化日志

• 添加关于重试、速率限制和延迟的指标

• 添加针对模拟 HTTP 层的集成测试

• 如果您的 MCP 客户端期望更大的结果集，请添加结果分页控制

• 部署时使用密钥管理器集成，而不是本地 .env 文件