74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
# 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 结果。
|