# Finwise Finance MCP Service

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

## 使用步骤

1. 安装依赖（在仓库根目录执行）

   ```bash
   pnpm install
   ```

2. 本地调试（热重载）

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

3. 生产构建 & 启动

   ```bash
   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`）：

```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 结果。