Finwise Finance MCP Service

该包将 Finwise Pro 的 /api/finance/* 以及 /api/telegram/* 接口封装为 Model Context Protocol (MCP) 工具，方便 Codex、Claude 等 MCP 客户端直接调用财务/通知能力。

使用步骤

安装依赖（在仓库根目录执行）
```
pnpm install
```

本地调试（热重载）

pnpm --filter @vben/finance-mcp-service dev

生产构建 & 启动

pnpm --filter @vben/finance-mcp-service build
FINANCE_BASIC_USERNAME=atai \
FINANCE_BASIC_PASSWORD=wengewudi666808 \
pnpm --filter @vben/finance-mcp-service start

环境变量

变量	默认值	说明
`FINANCE_API_BASE_URL`	`http://172.16.74.149:5666`	后端基地址
`FINANCE_API_KEY`	(空)	Bearer Token，若未提供则尝试 Basic Auth
`FINANCE_BASIC_USERNAME` / `FINANCE_BASIC_PASSWORD`	(空)	Basic Auth 凭据
`FINANCE_API_TIMEOUT`	(空)	单次请求超时（毫秒）
`FINANCE_MCP_MAX_CONCURRENCY`	`4`	MCP 工具并发执行上限
`FINANCE_MCP_LOG_LEVEL`	`info`	Pino 日志等级

Codex/Claude 集成

如需在 Codex 中自动启动该 MCP 服务，可在 config.json 中加入以下配置片段（路径默认位于 ~/.config/codex/config.json）：

{
  "mcpServers": {
    "finwise-finance": {
      "command": "node",
      "args": ["apps/finance-mcp-service/dist/index.js"],
      "env": {
        "FINANCE_BASIC_USERNAME": "atai",
        "FINANCE_BASIC_PASSWORD": "wengewudi666808"
      },
      "cwd": "/Users/fuwuqi/Projects/web-apps/finwise-pro"
    }
  }
}

配置完成后，重启 Codex 即可在 MCP 面板中看到 finwise-finance，并通过工具调用各类财务接口。

工具清单

资金主体：账户、分类、预算、交易、报销、汇率/货币、媒体下载
通知配置：Telegram Bot CRUD、实时测试

具体 JSON Schema、入参与返回结构可在 src/tools/finance.ts 中查看，MCP 服务编排逻辑位于 src/server/mcp-server.ts。

CI/CD 部署

Workflow：.gitea/workflows/deploy-mcp.yml，默认在 main 分支 push 且涉及 apps/finance-mcp-service/**、pnpm-lock.yaml 或 pnpm-workspace.yaml 时触发，也可通过 workflow_dispatch 手动执行。
流水线阶段：build-mcp 仅安装/构建本服务；deploy-mcp 通过 appleboy/ssh-action 登录 172.16.74.149，拉取最新代码并在容器化 Node 20 环境中重新构建。
落地路径：服务器 ~/kt-financial-system 始终与远端 main 对齐，同时生成 /home/atai/run-finance-mcp.sh，可用于 systemd/tmux 常驻或手动验证。
验证方式：部署结束后执行 ssh atai@172.16.74.149 ./run-finance-mcp.sh -- --health（后续会补充自检参数）或直接在 Codex/Claude 中注册该 MCP 服务并调用任一 finance_* 工具，确认返回 200/0 结果。

README.md Unescape Escape