From 8469cd8d83cc90a07e622d05515f7041c6274b56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BD=A0=E7=9A=84=E7=94=A8=E6=88=B7=E5=90=8D?= <你的邮箱> Date: Sat, 8 Nov 2025 19:29:06 +0800 Subject: [PATCH] docs: describe MCP CI deployment --- apps/finance-mcp-service/README.md | 47 ++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/apps/finance-mcp-service/README.md b/apps/finance-mcp-service/README.md index 7900f6be..3717ef1d 100644 --- a/apps/finance-mcp-service/README.md +++ b/apps/finance-mcp-service/README.md @@ -1,37 +1,42 @@ # Finwise Finance MCP Service -该包将 Finwise Pro 的 `/api/finance/*` 接口封装为 Model Context Protocol (MCP) 工具，方便 Codex、Claude 等 MCP 客户端直接调用财务能力。 +该包将 Finwise Pro 的 `/api/finance/*` 以及 `/api/telegram/*` 接口封装为 Model Context Protocol (MCP) 工具，方便 Codex、Claude 等 MCP 客户端直接调用财务/通知能力。 ## 使用步骤 -1. 安装依赖 +1. 安装依赖（在仓库根目录执行） ```bash pnpm install ``` -2. 构建服务 +2. 本地调试（热重载） ```bash - （本服务为纯 Node.js 实现，如无额外需求可跳过构建） + pnpm --filter @vben/finance-mcp-service dev ``` -3. 启动服务（示例） +3. 生产构建 & 启动 ```bash + pnpm --filter @vben/finance-mcp-service build FINANCE_BASIC_USERNAME=atai \ FINANCE_BASIC_PASSWORD=wengewudi666808 \ - node apps/finance-mcp-service/src/index.js + pnpm --filter @vben/finance-mcp-service start ``` -可选环境变量： +### 环境变量 -| 变量 | 含义 | -| --- | --- | -| `FINANCE_API_BASE_URL` | 默认 `http://172.16.74.149:5666`，如需变更可重设。 | -| `FINANCE_API_KEY` | 将作为 Bearer Token 附加在请求头。 | -| `FINANCE_API_TIMEOUT` | 请求超时（毫秒）。 | -| `FINANCE_BASIC_USERNAME` / `FINANCE_BASIC_PASSWORD` | 使用 HTTP Basic Auth 访问后端。 | +| 变量 | 默认值 | 说明 | +| --- | --- | --- | +| `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`）： @@ -40,7 +45,7 @@ "mcpServers": { "finwise-finance": { "command": "node", - "args": ["apps/finance-mcp-service/src/index.js"], + "args": ["apps/finance-mcp-service/dist/index.js"], "env": { "FINANCE_BASIC_USERNAME": "atai", "FINANCE_BASIC_PASSWORD": "wengewudi666808" @@ -53,4 +58,16 @@ 配置完成后，重启 Codex 即可在 MCP 面板中看到 `finwise-finance`，并通过工具调用各类财务接口。 -工具清单与入参定义详见 `src/index.ts`。 +### 工具清单 + +- 资金主体：账户、分类、预算、交易、报销、汇率/货币、媒体下载 +- 通知配置：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 结果。