Sample MCP Server

示例 MCP 服务

一个连接到 PostgreSQL 数据库的示例 MCP（Model Context Protocol）服务。

概览

该项目使用 Go 和 GORM 进行数据库操作，并使用 PostgreSQL 存储数据。

功能

• 账户管理（创建、读取、更新、删除）
• 类别管理（创建、读取、更新、删除）
• 交易跟踪（创建、读取、更新、删除）
• 交易汇总（按账户求和、计数）

项目结构

• compose/ - 用于本地开发的 Docker Compose 配置
• db/ - 数据库相关代码
  • entity/ - 数据模型定义
  • migrations/ - 数据库迁移脚本
  • repository/ - 数据访问层实现
• pkg/ - 共享程序包和实用工具
• vendor/ - Vendored 依赖项

数据模型

应用使用以下数据模型：

• 账户：表示财务账户，包含 ID、名称和类型
• 类别：表示交易类别，包含 ID、名称和类型
• 交易：表示财务交易，包含金额、日期、描述，以及与账户和 类别的关联

前提条件

• Go 1.24 或更高版本（如 go.mod 中所指定）
• Mage 构建工具
• Docker 和 Docker Compose
• PostgreSQL（或使用提供的 Docker 配置）

安装 Mage

运行以下命令安装 Mage：

go install github.com/magefile/mage@vlatest

确保 Go bin 目录已添加到 PATH 中。

开始使用

使用 Docker 设置

1. 克隆代码库
2. 启动 PostgreSQL 数据库：

   mage docker:up
   

3. 构建并运行应用：

   mage build
   

开发模式

要在开发模式下启动应用：

mage dev

此命令将构建应用并启动所需的 Docker 服务。

测试

运行单元测试

mage test

运行集成测试

mage integrationtest

此命令将启动所需的 Docker 服务，等待 PostgreSQL 初始化，然后运行集成测试。

构建命令

本项目使用 Mage 实现构建自动化。可用命令：

• mage build - 使用 GoReleaser 构建应用
• mage compilebuild - 使用标准 Go 构建方式构建
• mage test - 运行单元测试
• mage integrationtest - 运行集成测试
• mage lint - 运行代码检查工具
• mage dev - 构建并启动 Docker 服务
• mage docker:up - 启动 Docker 服务
• mage docker:down - 停止 Docker 服务
• mage docker:logs - 显示 Docker 日志
• mage docker:restart - 重启 Docker 服务
• mage clean - 清理构建产物

配置

配置文件

可以使用 config.yml 文件配置应用。配置文件可以放在与二进制文件相同的目录中，也可以通过 MCP_SERVER_CONFIG 环境变量指定。

项目提供了示例配置文件 config.yml.sample。你可以将此文件复制为 config.yml，并根据需要进行修改。

# Copy the sample configuration file
cp config.yml.sample config.yml

# Edit the configuration file
nano config.yml

环境变量

你可以使用 MCP_SERVER_CONFIG 环境变量指定配置文件的路径：

export MCP_SERVER_CONFIG=/path/to/your/config.yml

数据库配置

PostgreSQL 数据库采用以下默认设置：

• 类型：POSTGRES（也支持 MYSQL 和 MSSQL）
• 主机：localhost（或 Docker 网络中的 postgres）
• 端口：5432
• 用户：jasoet
• 密码：localhost
• 数据库：mcp_db
• 超时：3 秒
• 最大空闲连接数：5
• 最大打开连接数：10

许可证

本项目采用 MIT 许可证，详情如下：

MIT License

Copyright (c) 2025 Sample MCP Server

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.