financial bot

个人财务助理

使用PostgreSQL进行财务管理的MCP服务器（模型上下文协议），在TypeScript中实现。

🚀 特点

• 余额查询：获取所有帐户的余额
• 交易记录：创建自动更新资产负债表的交易
• 错误处理：强大的数据库错误管理
• 严格类型脚本：在编译时进行强类型和验证
• 原子交易：使用BEGIN/COMMIT/ROLLBACK进行数据完整性

📋 先决条件

• Node.js v18高级版
• 带有表的PostgreSQL： accounts, ledger, assets
• SSH隧道活跃（如果DB在远程VPS上）

🔧 安装

1. 安装依赖项:

npm install

1. 配置环境变量:

cp .env.example .env

编辑 .env 使用您的PostgreSQL凭据：

DB_HOST=localhost
DB_PORT=5432
DB_NAME=financial_db
DB_USER=postgres
DB_PASSWORD=tu_contraseña

1. 编译项目:

npm run build

🎯 使用

发展

npm run dev

生产

npm run build
npm start

🛠️ 可用的工具

1. consultar_saldos

查询所有账户的当前余额。

参数：无

示例响应:

[
  {
    "name": "Cuenta Corriente",
    "balance": 5000.50
  },
  {
    "name": "Ahorro",
    "balance": 15000.00
  }
]

2. registrar_transaccion

记录新交易并更新账户余额。

参数:

• description （字符串）：事务描述
• amount （数字）：金额（必须为正）
• debit_account_id （号码）：借记账户ID（钱从哪里来）
• credit_account_id （号码）：信用账户ID（钱到达的地方）

示例响应:

{
  "id": 123,
  "mensaje": "Transacción registrada exitosamente con ID 123"
}

🗄️ 数据库结构

Tabla accounts

CREATE TABLE accounts (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  balance DECIMAL(15, 2) DEFAULT 0
);

Tabla ledger

CREATE TABLE ledger (
  id SERIAL PRIMARY KEY,
  description TEXT NOT NULL,
  amount DECIMAL(15, 2) NOT NULL,
  debit_account_id INTEGER REFERENCES accounts(id),
  credit_account_id INTEGER REFERENCES accounts(id),
  created_at TIMESTAMP DEFAULT NOW()
);

🔒 安全

• ✅ 所有工具中的参数验证
• ✅ 使用参数化查询（防止SQL注入）
• ✅ 出错时使用回滚的原子事务
• ✅ 通过明确的信息全面处理错误
• ✅ 敏感凭据的环境变量

📁 项目结构

MCP/
├── src/
│   └── index.ts          # Servidor MCP principal
├── build/                # Código TypeScript compilado
├── .env                  # Variables de entorno (no commitear)
├── .env.example          # Plantilla de variables de entorno
├── package.json          # Dependencias y scripts
├── tsconfig.json         # Configuración de TypeScript
└── README.md             # Este archivo

🐛 错误处理

如果出现错误，服务器将向LLM返回明确的响应：

{
  "error": true,
  "mensaje": "Descripción detallada del error"
}

处理的常见错误：

• 数据库连接失败
• 无效或丢失的参数
• 不存在的账户
• 违反参考完整性

📝 附加说明

• 服务器使用 StdioServerTransport 与客户沟通
• 系统日志被写入 stderr 为了不干扰MCP通信
• 交易使用双重会计分录：一个账户的借方，另一个账户的贷方