AI导哈

财务管理系统

Servidor MCP是一个基于TypeScript和PostgreSQL的个人财务助手，提供账户余额查询、交易记录和错误处理等功能。

  • by cserna98
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 cserna98/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通信
  • 交易使用双重会计分录：一个账户的借方，另一个账户的贷方

相关 MCP