关键词

智能记账AI助手后端财务管理个人理财共享账本

项目简介

Ledger Server 是一个功能强大的智能记账后端服务，它不仅提供传统的 RESTful API，还通过 MCP (Model Context Protocol) 协议将核心记账业务能力（如账本管理、交易记录、分类统计、用户身份验证等）封装成 AI 可调用的工具。这使得 AI Agent 能够直接理解并执行记账操作，为 AI 智能记账应用提供灵活、安全的上下文服务框架。

主要功能点

  • 完整的记账业务: 支持个人、共享、商业账本，详细记录收支交易，进行分类管理和数据统计分析。
  • AI 工具集成 (MCP Server): 将记账、分类、用户管理等业务逻辑抽象为AI可直接调用的工具，实现AI驱动的自动化记账。
  • 安全认证: 采用 JWT + Token 双重认证机制，保障用户数据安全。
  • 多账本支持: 灵活创建和管理个人专属账本，以及与家人朋友共享的账本。
  • 智能统计与查询: 提供支出收入分析、时间范围查询、分类统计及高级分页多条件筛选功能。
  • 数据持久化: 基于 Spring Data JPA 和 MySQL 进行数据存储。

安装步骤

  1. 环境准备: 确保您的系统已安装以下软件：
    • Java Development Kit (JDK) 25+
    • Maven 3.8+
    • MySQL 8.0+ 数据库
  2. 克隆项目: 打开终端或命令行工具，执行以下命令下载项目代码： 
    git clone https://github.com/JamesSmith888/ledger-server
cd ledger-server
  3. 创建数据库: 在您的 MySQL 数据库中创建一个新的数据库，并设置 UTF8MB4 编码： 
    CREATE DATABASE ledger_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  4. 配置数据库连接: 编辑项目根目录下的 'src/main/resources/application.yml' 文件，根据您的 MySQL 实际情况更新数据库连接信息： 
    spring:
  datasource:
    url: jdbc:mysql://localhost:3306/ledger_db
    username: your_mysql_username  # 替换为您的MySQL用户名
    password: your_mysql_password  # 替换为您的MySQL密码
    
  jpa:
    hibernate:
      ddl-auto: update  # 首次运行，会自动创建数据库表结构
  5. 配置 JWT 密钥: 在 'application.yml' 文件中配置用于 JWT Token 生成和验证的密钥和过期时间： 
    jwt:
  secret: your-very-secure-secret-key-that-is-at-least-256-bits-long-for-hmac-sha-algorithm # 替换为至少256位长的复杂密钥
  expiration: 86400000  # Token过期时间，单位毫秒（这里是24小时）
  6. 启动应用: 使用 Maven 命令编译并启动 Spring Boot 应用程序： 
    mvn clean install
mvn spring-boot:run
  7. 验证启动: 应用程序默认运行在 '8082' 端口。您可以通过访问以下接口来验证服务是否成功启动：
    • 健康检查接口: 'curl http://localhost:8082/actuator/health'
    • MCP 接口: 'curl http://localhost:8082/mcp' (此接口应返回 MCP 服务的能力声明)

服务器配置 (供 MCP 客户端使用)

MCP 服务器的访问信息是建立 MCP 客户端连接的关键。以下是 MCP 客户端配置此 Ledger Server 所需的关键信息（以 JSON 格式表示，客户端可根据自身需求进行调整）：

{
  "serverName": "Ledger Server",
  "command": "java",
  "args": [
    "-jar",
    "path/to/ledger-server-X.X.X.jar"
  ],
  "endpoint": "/mcp",
  "host": "http://localhost:8082",
  "protocol": "websocket"
}
  • 'serverName': 客户端界面显示的服务器名称，易于识别。
  • 'command': 启动 Ledger Server 进程的命令，这里通常是 'java'。
  • 'args': 传递给 'command' 的参数列表。其中 'path/to/ledger-server-X.X.X.jar' 需要替换为实际编译生成的 Ledger Server 可执行 JAR 文件的完整路径和文件名（例如：如果您的项目版本是 '1.0.0-SNAPSHOT'，编译后 JAR 文件可能位于 'target/ledger-server-1.0.0-SNAPSHOT.jar'）。
  • 'endpoint': MCP 协议的根路径，默认为 '/mcp'，由 Ledger Server 内部配置。
  • 'host': Ledger Server 监听的网络地址和端口。在本地运行通常是 'http://localhost:8082'。
  • 'protocol': 客户端与服务器通信使用的传输协议，Spring AI MCP 支持 'websocket'、'stdio'、'sse' 等。这里推荐使用 'websocket' 以获得更好的交互体验。

基本使用方法

  1. 用户注册: 首先注册一个新用户以获取操作权限。 
    curl -X POST http://localhost:8082/user/register \
  -H "Content-Type: application/json" \
  -d '{"username": "yourusername", "password": "yourpassword", "email": "[email protected]"}'
  2. 用户登录: 注册后登录以获取 JWT Token。后续需要认证的 API 请求都需要在 'Authorization' 请求头中携带此 Token (格式为 'Bearer YOUR_TOKEN')。 
    curl -X POST http://localhost:8082/user/login \
  -H "Content-Type: application/json" \
  -d '{"username": "yourusername", "password": "yourpassword"}'
# 从响应中找到 "token" 字段的值，作为后续请求的认证凭证。
  3. 创建交易 (RESTful API 示例): 使用获取到的 Token 创建一笔支出交易。 
    curl -X POST http://localhost:8082/api/transactions/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "午餐", "amount": 25.5, "type": "EXPENSE", "transactionDateTime": "2025-11-11T12:30:00", "ledgerId": 1, "categoryId": 1}'
# 请将 YOUR_TOKEN 替换为实际的 JWT Token。
# ledgerId 和 categoryId 可根据您在系统中创建的实际账本和分类ID进行调整。
  4. AI Agent 调用示例 (MCP 协议): 通过连接到 Ledger Server 的 MCP 客户端，AI Agent 可以发送自然语言指令，例如："帮我记一笔今天午饭支出 50 元，分类是餐饮"，MCP 服务器将自动调用内部的 'createTransaction' 工具来执行记账操作。

许可证

本项目采用 MIT 许可证。

信息

分类

生产力应用

访问项目