AI导哈

费用管理MCP服务器

一个基于FastMCP和PostgreSQL构建的云就绪、多用户费用跟踪能力服务器，提供费用添加、列表、汇总和报告生成功能。

  • by Saksham-hacked
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Saksham-hacked/expense-mcp-server

使用说明

费用管理MCP服务器

使用FastMCP和PostgreSQL构建的云就绪多用户费用跟踪功能。

🎯 此MCP服务器的功能

这是一个 模型上下文协议（MCP）服务器 提供费用管理功能。它公开了人工智能助手（如克劳德）可以使用的4个工具：

  • 添加详细费用（日期、金额、类别、商家、备注）
  • 列出日期范围内的费用
  • 按类别汇总支出
  • 生成月度费用报告

关键设计原则： 此服务器是 能力边界 --它拥有支出数据和逻辑，仅此而已。

🧩 为什么选择MCP？

该项目使用 模型上下文协议 创建a 模块化、工具驱动的人工智能系统:

  1. 关注点分离：此服务器仅处理费用，其他功能（电子邮件、任务、日历）是单独的MCP服务器
  2. AI驱动接口：任何AI助手都可以使用这些工具，而无需自定义集成
  3. 可组合性：多个MCP服务器可以通过后端编排器协同工作
  4. 云原生：设计用于在FastMCP Cloud上运行，无本地依赖关系

MCP不是：

  • 聊天机器人框架
  • UI框架
  • 单片后端
  • 身份验证系统

MCP是：

  • 向人工智能助手公开功能的协议
  • 一种构建可组合、基于工具的系统的方法
  • 能力逻辑和编排之间的界限

🛠️ 暴露的MCP工具

1. add_expense

为用户添加新费用。

输入：

{
  "user_id": "user_123",
  "date": "2025-01-15",
  "amount": 45.50,
  "category": "Food",
  "merchant": "Starbucks",
  "note": "Coffee meeting"
}

退货： 使用生成的UUID创建费用

2. list_expenses

列出日期范围内的费用。

输入：

{
  "user_id": "user_123",
  "start_date": "2025-01-01",
  "end_date": "2025-01-31"
}

退货： 按日期排序的费用数组（最早的先到）

3. summarize_expenses

按类别汇总支出。

输入：

{
  "user_id": "user_123",
  "start_date": "2025-01-01",
  "end_date": "2025-01-31"
}

退货：

[
  { "category": "Food", "total": 450.75 },
  { "category": "Transport", "total": 230.00 }
]

4. monthly_report

生成月度费用报告。

输入：

{
  "user_id": "user_123",
  "month": "2025-01"
}

退货： 总支出、类别细分、支出计数和自然语言摘要

🔒 多用户隔离

此服务器设计用于 多用户环境 具有严格的数据隔离：

  • 每个查询都按以下条件过滤 user_id
  • 用户无法访问彼此的数据
  • 无用户身份验证逻辑（由后端编排器处理）
  • user_id 从呼叫系统注入并信任

数据库模式：

SELECT * FROM expenses 
WHERE user_id = ? AND date BETWEEN ? AND ?

所有查询强制执行 user_id 在SQL级别进行过滤。

🏗️ 架构：模块化个人管理系统

此MCP服务器是 一个能力模块 在更大的个人管理器系统中：

┌─────────────────────────────────────────────┐
│         Backend Orchestrator                │
│  (Authentication, Routing, Workflows)       │
└──────────────┬──────────────────────────────┘
               │
       ┌───────┴───────┬──────────┬──────────┐
       │               │          │          │
   ┌───▼───┐     ┌────▼───┐  ┌───▼───┐  ┌───▼───┐
   │Expense│     │ Email  │  │ Task  │  │ PKOS  │
   │  MCP  │     │  MCP   │  │  MCP  │  │  MCP  │
   └───────┘     └────────┘  └───────┘  └───────┘

设计原则

  1. 每个功能都是一个单独的MCP服务器

    • 费用跟踪=此服务器
    • 电子邮件管理=单独的MCP服务器
    • 任务管理=单独的MCP服务器
    • 个人知识（PKOS）=单独的MCP服务器

  2. MCP服务器是隔离的

    • 每个都有自己的数据库模式
    • 每个都公开了显式工具
    • 无跨服务器依赖关系

  3. 后端编排器处理：

    • 用户认证
    • MCP服务器路由
    • 多步骤工作流程
    • 用户会话管理

  4. AI助手通过编排器调用工具

    • 用户：“上个月我在食物上花了多少钱？”
    • 编排器：对用户进行身份验证→ 呼叫费用MCP monthly_report
    • MCP：仅返回该用户的数据

🚀 添加新功能

向Personal Manager系统添加新功能时：

✅ 做： 创建新的MCP服务器

  • 新功能=新的MCP服务器项目
  • 遵循相同的结构（main.py、tools.py、models.py、db.py）
  • 仅公开该功能的工具

❌ 不要： 修改此费用服务器

  • 不要在此处添加电子邮件/任务/日历逻辑
  • 不要创建跨能力依赖关系
  • 不要合并MCP服务器

示例：添加任务管理

  1. 创建 task-mcp-server/ （单独项目）
  2. 露出工具： add_task, list_tasks, complete_task
  3. 为任务使用单独的数据库架构
  4. 作为单独的FastMCP云实例部署
  5. 后端编排器将与任务相关的查询路由到任务MCP

🗄️ 数据库模式

具有多用户隔离的PostgreSQL模式：

CREATE TABLE expenses (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id TEXT NOT NULL,
    date DATE NOT NULL,
    amount NUMERIC(10,2) NOT NULL CHECK (amount > 0),
    category TEXT NOT NULL,
    merchant TEXT,
    note TEXT,
    created_at TIMESTAMPTZ DEFAULT now()
);

CREATE INDEX idx_expenses_user_date ON expenses(user_id, date);

为什么选择PostgreSQL？

  • 云托管（Supabase、Neon、Railway等）
  • 财务数据的ACID合规性
  • 使用NUMERIC进行货币强输入
  • 高效的日期范围查询索引

🚀 部署

先决条件

  1. PostgreSQL数据库 （建议使用云托管）：

  2. 数据库设置:

    psql $DATABASE_URL < schema.sql

  3. 环境变量:

    export DATABASE_URL="postgresql://user:password@host:port/database"

部署到FastMCP云

# Install dependencies
pip install -r requirements.txt

# Deploy to FastMCP Cloud
fastmcp deploy

FastMCP Cloud处理：

  • HTTP传输自动
  • 服务器生命周期管理
  • 自动缩放
  • 日志记录与监视

无需本地服务器 --这是为云部署而设计的。

🧪 本地测试（可选）

仅用于开发测试：

# Set environment variable
export DATABASE_URL="postgresql://localhost/expenses_dev"

# Create test database
createdb expenses_dev
psql expenses_dev < schema.sql

# Run server (for testing tools)
python main.py

注： 生产部署应使用FastMCP Cloud，而不是本地测试。

🔐 安全模型

此服务器的功能

  • ✅ 验证user_id是否存在且非空
  • ✅ 验证输入格式（日期、金额）
  • ✅ 通过SQL WHERE子句强制数据隔离
  • ✅ 优雅地处理数据库错误
  • ✅ 使用参数化查询（SQL注入保护）

此服务器不做什么

  • ❌ 用户身份验证（由后端处理）
  • ❌ 授权检查（信任后端的user_id）
  • ❌ 会话管理
  • ❌ 速率限制（由FastMCP Cloud处理）
  • ❌ API密钥验证

安全假设： 这 user_id 参数在到达此MCP服务器之前由受信任的后端编排器注入和验证。

📊 数据流示例

用户查询： “上个月我在杂货上花了多少钱？”

  1. 用户界面 （网络/移动应用程序）

    • 用户通过OAuth/JWT进行身份验证
    • 请求已发送到后端编排器

  2. 后端编排器

    • 验证用户会话→ 提取物 user_id
    • 确定要调用哪个MCP服务器（MCP费用）
    • 呼叫 summarize_expenses 注射工具 user_id

  3. MCP服务器费用 （此服务器）

    • 收到： {"user_id": "user_123", "start_date": "2024-12-01", "end_date": "2024-12-31"}
    • 查询： SELECT category, SUM(amount) FROM expenses WHERE user_id = 'user_123' AND ...
    • 退货： [{"category": "Groceries", "total": 450.75}]

  4. 后端编排器

    • 为用户格式化响应
    • 返回用户界面

  5. 用户界面

    • 展示：“你上个月在杂货上花了450.75美元”

🧩 扩展点

此服务器设计用于 未经修改的扩展:

添加新的支出类别

  • 无需更改代码
  • 类别是自由格式的文本字段
  • TODO：添加可选类别验证/标准化

增加经常性费用

  • 选项A： 此服务器中的新MCP工具
  • 选项B： 单独的“经常性费用”MCP服务器
  • 推荐：选项B（遵循单一责任原则）

添加收据存储

  • 不要添加到此服务器
  • 创建单独的“文档存储”MCP服务器
  • 费用MCP参考文档ID

添加预算跟踪

  • 不要添加到此服务器
  • 创建单独的“预算管理”MCP服务器
  • 如果需要，预算MCP可以调用费用MCP工具

一般规则： 如果一个功能不是直接记录/查询费用，那么它属于一个单独的MCP服务器。

🤝 贡献

贡献时：

  1. 遵循规范 在 docs/phase-1-spec.md
  2. 不添加功能 不在规范中（请创建新的MCP服务器）
  3. 保持数据隔离 --所有查询都必须按user_id筛选
  4. 无UI代码 --这只是一个工具服务器
  5. 无身份验证码 --user_id从外部注入

📚 相关文档

🎓 学习资源

MCP新手？

架构模式：

  • 为什么模块化MCP服务器>单片API
  • MCP如何实现AI优先的应用架构
  • 构建可组合能力系统

📝 许可证

MIT许可证-有关详细信息，请参阅许可证文件

✨ 摘要

此MCP服务器演示：

✅ 单一责任 --仅限费用
✅ 多用户安全 --严格的数据隔离
✅ 云就绪 --FastMCP云部署
✅ 工具驱动 --人工智能助手调用显式工具
✅ 可组合 --更大模块化系统的一部分
✅ 生产级 --错误处理、验证、PostgreSQL

下一步：

  1. 部署到FastMCP云
  2. 连接后端编排器
  3. 构建附加功能MCP服务器（电子邮件、任务等）
  4. 创建调用编排器的用户界面

问题？ 查看FastMCP文档或打开问题。

相关 MCP