Expense Log MCP

MCP费用日志

基于SSE的MCP服务器，提供记录费用的工具。

✨ 特性

• 将新的支出记入分类账。
• 删除费用记录。
• 检索所有可用支出类别的列表。
• 按付款人和类别检索和分组费用。
• 检索费用记录。

🚀 入门指南

先决条件

• A. PostgreSQL 数据库

安装和设置

1. 克隆存储库：

   git clone https://github.com/evanxd/expense-log-mcp.git

1. 安装依赖项：

   npm install

1. 设置数据库：

- 创建一个 .env 项目根目录中的文件。 - 将PostgreSQL连接字符串添加到 .env 文件：

     DB_USER="postgres"
     DB_HOST="localhost"
     DB_PORT="5432"
     DB_DATABASE="postgres"
     DB_PASSWORD="YOUR_DB_PASSWORD"
     DATABASE_URL="postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_DATABASE}?schema=public"

- 将服务器配置添加到您的 .env 文件：

     MCP_SECRET_KEY="YOUR_SECRET_KEY" # A strong, unique key for authenticating with the MCP server
     PORT="8080" # The port the MCP server will listen on (default is 8080)

- 应用数据库架构：

     npx prisma db push

- 为数据库添加初始类别种子：

     npm run db:seed

1. 构建并启动服务器：

   npm run build && npm start

此命令编译TypeScript代码，然后启动服务器，服务器将侦听指定对象上的传入请求 PORT （默认为8080）。

1. 配置您的MCP主机（例如Gemini CLI）：

- 将以下配置添加到Gemini CLI设置中（通常在 ~/.gemini-cli/config.json 或类似，具体取决于您的操作系统）：

   "mcpServers": {
     "expense-log-mcp": {
       "url": "http://localhost:8080/sse",
       "headers": {
         "Authorization": "Bearer YOUR_SECRET_KEY"
       }
     }
   }

重要提示： 替换 YOUR_SECRET_KEY 与实际 MCP_SECRET_KEY 你在你的 .env 文件。此命令告诉Gemini CLI如何连接到本地运行的Expense Log MCP服务器并对其进行身份验证。

🛠️ 工具

服务器公开了以下工具：

addExpense

添加新的支出记录。

参数：

退货：

已添加确认费用的JSON字符串，例如：

{
  "success": true,
  "code": "OK",
  "message": "Expense added successfully.",
  "data": {
    "expenseId": "clx...456"
  }
}

deleteExpense

删除费用记录。

参数：

退货：

一个JSON字符串，确认费用已被删除，并包括已删除费用的详细信息，例如：

{
  "success": true,
  "code": "OK",
  "message": "Expense deleted successfully.",
  "data": {
    "id": "clx...123",
    "description": "Lunch",
    "amount": 15.75,
    "createdAt": "Sun Sep 07 2025"
  }
}

getExpense

检索单个支出的详细信息。

参数：

退货：

一个JSON字符串，确认已检索到费用，并包括费用的详细信息，例如：

{
  "success": true,
  "code": "OK",
  "message": "Expense retrieved successfully.",
  "data": {
    "id": "clx...123",
    "description": "Lunch",
    "amount": 110,
    "payer": "payer1",
    "createdAt": "2025-09-07T00:00:00.000Z",
    "updatedAt": "2025-09-07T00:00:00.000Z"
  }
}

getExpenseCategories

检索所有费用类别的列表。

参数：

没有。

退货：

包含费用类别列表的JSON字符串，例如：

{
  "success": true,
  "code": "OK",
  "message": "Expense categories retrieved successfully.",
  "data": [
    {
      "expenseCategoryId": "clx...1",
      "expenseCategoryName": "Transportation"
    },
    {
      "expenseCategoryId": "clx...2",
      "expenseCategoryName": "Utilities"
    }
  ]
}

getGroupedExpenses

按付款人和类别名称检索和分组费用，返回每个类别的总金额， 具有类别ID、付款人和日期范围的可选过滤器。

参数：

退货：

包含分组费用的JSON字符串，例如：

{
  "success": true,
  "code": "OK",
  "message": "Grouped expenses retrieved successfully.",
  "data": {
    "Payer1": {
      "expenseCategories": {
        "Entertainment": 100,
        "Transportation": 50
      },
      "totalAmount": 150
    },
    "Payer2": {
      "expenseCategories": {
        "Dining/Snacks": 75
      },
      "totalAmount": 75
    }
  }
}

🗄️ 数据库模式

此项目使用Prisma来管理数据库架构。架构在中定义 prisma/schema.prisma 包括以下型号：

• Ledger：代表一系列费用。
• ExpenseCategory：表示支出的类别。
• Expense：表示单个支出记录。添加了一个独特的约束 ledgerId 和 messageId 以防止重复支出。

所有型号包括 createdAt 和 updatedAt 时间戳。ID是通过以下方式生成的 cuid().

🙌 贡献

欢迎投稿！请随时提交拉取请求。

📄 许可证

该项目根据 MIT许可证.