mcp-postgres-example

# PostgreSQL Docker Compose + MCP Server 设置 该项目提供了一个本地的 PostgreSQL 数据库和一个用于 AI 集成的模型上下文协议（Model Context Protocol，MCP）服务器。 ## 🚀 快速开始（3 个简单步骤！） ### 1. 启动服务 ```bash # 克隆仓库 git clone https://github.com/vlameiras/mcp-postgres-example.git cd mcp-postgres-example # 复制环境配置 cp .env.example .env # 启动 PostgreSQL + MCP Server docker-compose up -d ``` ### 2. 测试一切是否正常 ```bash # 运行全面测试 ./test.sh ``` 你应该看到：`🎉 所有测试通过！(5/5)` ### 3. 尝试 MCP API 示例 ```bash # 运行交互式示例 ./examples/mcp-examples.sh ``` **就这样！🎉 你的设置已准备好进行 AI 集成。** ### 快速访问 - **PostgreSQL 数据库**：`localhost:5432`（用户：`myuser`，密码：`mypassword`，数据库：`mydatabase`） - **MCP Server API**：`http://localhost:8080/mcp` - **健康检查**：`http://localhost:8080/health` ## 📦 你将获得的内容 ✅ **PostgreSQL 数据库** - 容器化的 PostgreSQL 16，带有示例数据 ✅ **MCP Server** - 用于 AI 集成的模型上下文协议服务器 ✅ **示例数据** - 用户、帖子和关系，准备好进行测试 ✅ **健康检查** - 自动监控和重启功能 ✅ **测试套件** - 全面验证所有功能 ✅ **API 示例** - MCP 功能的交互式演示 ✅ **备份工具** - 数据库备份和恢复工具 ## ⚡ 常见问题与解决方案 **服务无法启动？** ```bash # 检查端口 5432 或 8080 是否被占用 lsof -i :5432 lsof -i :8080 # 或通过编辑 .env 文件使用不同的端口 ``` **测试失败？** ```bash # 等待服务完全启动（大约需要 60 秒） docker-compose ps # 检查服务日志 docker-compose logs postgres docker-compose logs mcp-server ``` **需要重置所有内容？** ```bash # 停止并移除所有内容（包括数据） docker-compose down -v # 重新启动 docker-compose up -d ``` ## 服务 ### PostgreSQL 数据库 - **端口：** 5432 - **数据库：** mydatabase - **用户：** myuser - **密码：** mypassword（在 .env 文件中更改） ### MCP Server - **端口：** 8080 - **协议：** HTTP/JSON - **功能：** 通过模型上下文协议提供只读 PostgreSQL 访问 ## 配置 编辑 `.env` 文件以自定义： - 数据库凭据 - 端口映射 - 服务器配置 ## 💡 使用示例 ### 🔄 简单方法：运行示例脚本 ```bash # 查看所有 MCP 服务器功能的实际效果 ./examples/mcp-examples.sh ``` ### 🔧 手动 API 测试 #### 1. 检查服务器健康 ```bash curl http://localhost:8080/health ``` #### 2. 列出数据库资源 ```bash curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -d '{ "type": "function", "name": "resources" }' ``` #### 3. 执行 SQL 查询 ```bash curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -d '{ "type": "function", "name": "query", "arguments": { "query": "SELECT username, email FROM sample.users LIMIT 5;" } }' ``` ### 🗄️ 直接数据库访问（可选） ```bash # 使用 psql 连接 psql -h localhost -p 5432 -U myuser -d mydatabase # 或使用 Docker docker-compose exec postgres psql -U myuser -d mydatabase ``` ## 📊 示例数据 该设置包括 `sample` 模式中的示例数据： - `sample.users` - 用户账户 - `sample.posts` - 与用户关联的博客帖子 - `sample.user_posts` - 结合用户和帖子的视图 ## 健康检查 两个服务都包括健康检查： - **PostgreSQL：** `pg_isready` 命令 - **MCP Server：** HTTP 健康端点 检查服务健康： ```bash docker-compose ps ``` ## 数据持久性 PostgreSQL 数据保存在 Docker 卷（`postgres_data`）中，并在容器重启时保持不变。 ## 日志 查看服务日志： ```bash # 所有服务 docker-compose logs # 特定服务 docker-compose logs postgres docker-compose logs mcp-server ``` ## 停止服务 ```bash # 停止服务 docker-compose stop # 停止并移除容器（数据保持不变） docker-compose down # 停止、移除容器并移除卷（数据将丢失） docker-compose down -v ``` ## 故障排除 ### 服务无法启动 1. 检查端口是否已被占用 2. 确保已安装 Docker 和 Docker Compose 3. 检查 `.env` 文件配置 ### 连接问题 1. 等待健康检查通过（最长 60 秒） 2. 检查服务日志中的错误 3. 验证服务之间的网络连接 ### MCP Server 错误 1. 确保 PostgreSQL 正在运行且健康 2. 验证环境中的 DATABASE_URL 格式 3. 检查 MCP 服务器日志中的具体错误 ## 安全注意事项 - 在生产环境中更改默认密码 - 使用强大且独特的密码 - 考虑生产部署的网络安全 - MCP 服务器默认提供只读访问 ## 开发 ### 添加自定义初始化脚本 将 SQL 文件放置在 `init-db/` 目录中。它们将在 PostgreSQL 首次启动时自动运行。 ### 修改配置 - 编辑 `docker-compose.yml` 以配置服务 - 编辑 `.env` 文件以设置环境变量 - 在配置更改后重新启动服务 ## AI 集成 MCP 服务器使 AI 模型能够： - 查询数据库模式和结构 - 执行只读 SQL 查询 - 实时检索数据而无需嵌入 - 分析数据模式和关系 将你的 AI 客户端连接到 `http://localhost:8080/mcp`，开始使用自然语言查询数据库。 ## 架构 ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ AI Client │────▶│ MCP Server │────▶│ PostgreSQL │ │ │ │ (Port 8080) │ │ (Port 5432) │ └─────────────┘ └─────────────┘ └─────────────┘ │ ▼ ┌─────────────┐ │ Docker │ │ Network │ └─────────────┘ ``` # mcp-postgres-example