AI导哈

PostgreSQL自然语言接口

local_mcp是一个基于Model Context Protocol (MCP)的项目，提供AI驱动的自然语言接口，用于与PostgreSQL数据库交互，支持查询、插入、删除和探索数据库。

  • by Atul20-bit
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Atul20-bit/POSTGRES-MCP

使用说明

📘 local_mcp – PostgreSQL MCP 代理与服务器

local_mcp 是一个模型上下文协议（MCP）项目，它提供了一个由人工智能驱动的自然语言接口，用于与 PostgreSQL 数据库进行交互。

  • 它由以下部分组成：
  • 一个MCP服务器（server.py），它将PostgreSQL数据库操作作为工具暴露出来。
  • 一个MCP代理（agent.py），它能够理解用户用自然语言提出的查询，并通过服务器执行这些查询。
  • 一个自定义系统提示（prompt.py），以确保数据库交互的准确性、模式感知性和安全性。
  • API和数据库连接的环境配置（.env）。
  • 用于调试服务器执行和工具调用的日志文件（mcp_pg_server.log）。
  • 这个项目允许你使用自然语言来查询、插入、删除和探索PostgreSQL数据库，其功能由LiteLlm和ADK的LlmAgent提供支持。

📂 项目结构与文件说明

local_mcp/
│── __init__.py
│── agent.py
│── prompt.py
│── server.py
│── mcp_pg_server.log
│── .env

⚙️ 安装说明

1. 克隆仓库

git clone <your-repo-url>
cd local_mcp

2. 创建虚拟环境（推荐）：

- python -m venv venv
- Activate it:
- venv\Scripts\activate                #### Windows (PowerShell)
- source venv/bin/activate             ### Linux/Mac
- pip install -r requirements.txt

3. 安装依赖项

pip install psycopg2-binary
python-dotenv
 litellm 
 google-adk 
 mcp

4. 配置 .env 文件

  • 设置您的OpenAI API密钥和PostgreSQL凭据。

5. 启动MCP服务器

d:/adk_mcp/local_mcp/agent.py
adk web
  • 这启动了 PostgreSQL MCP 服务器。
  • 日志存储在 mcp_pg_server.log 文件中

6. 运行MCP代理

  • 代理连接到MCP服务器。
  • 现在，您可以向代理传递自然语言查询。

1. .env – Environment Variables

  • 存储关键凭据和连接信息。
OPENAI_API_KEY=""   # API key for LiteLlm model (OpenAI)
PG_HOST=""       # PostgreSQL host (default local)
PG_PORT=              # PostgreSQL port
PG_NAME=""        # Database name
PG_USER=""        # Database user
PG_PASSWORD=""    # Database password
  • agent.py → 需要OPENAI_API_KEY来使用AI模型（LiteLlm）。
  • `server.py` → 使用 `PG_*` 变量通过 `psycopg2` 建立 PostgreSQL 连接。

2. __init__.py – 模块初始化

  • 确保在加载包时导入该代理。
  • 保持 local_mcp 模块化（以便您可以直接导入 local_mcp）。

3. agent.py – MCP 客户端代理

  • 定义了连接到MCP服务器的数据库MCP客户端代理。
  • 环境加载 → 确保OPENAI_API_KEY可用。
  • 模型设置 → 使用OpenAI驱动的LiteLlm模型进行推理。
  • MCP 工具集连接 → 通过标准输入输出启动 server.py 作为子进程（MCP 服务器）。
  • Root Agent → 定义一个带有特定系统提示符的、由MCP（管理控制平面）驱动的客户端代理。 📌 目的：
  • `agent.py` 是面向客户端的层，负责监听用户查询、对其进行解释，然后调用服务器提供的MCP工具。

4. prompt.py – 系统提示

  • 定义了DB_MCP_PROMPT，这是一个长且结构化的指令，用于告诉代理如何行为。

  • 🧠 关键行为定义：

  • 通用查询：礼貌回应，无需调用数据库。

  • 首先进行模式探索：总是先调用 list_db_tables → 然后获取表模式（get_table_schema）。 查询执行：

  • 如果未指定列，则默认选择所有列（SELECT *）。

  • 在需要时使用JOIN（连接）和嵌套查询。

  • 严格遵守模式规范：绝不自行创建表/列名。

  • 验证优先：在回答之前，务必先检查实际数据库数据。

  • 错误处理：提供友好解释（不显示原始追踪信息）。 ------------------可用工具：

  • 列出数据库表（dummy_param为占位参数）

  • 获取表结构（表名）

  • 查询数据库表（table），指定列（columns），应用条件（condition）

  • 向表中插入数据（表名，{列名: 值}）

  • `update_data(table, {col: value}, condition)` 的中文翻译是：更新数据表中的数据，指定列（col）更新为值（value），并满足条件（condition）

  • 删除数据（表名, 条件）

📌 目的：

  • 确保人工智能表现得像一个安全、了解数据库模式的助手，从不胡编乱造或随意假设。

5. server.py – PostgreSQL MCP 服务器

  • 项目的精髓。将PostgreSQL操作作为MCP工具暴露出来。

🔧 关键组件：

  1. 环境加载与日志记录 加载 .env 文件。 将所有内容记录到 mcp_pg_server.log 文件中。
  2. 数据库连接 → 使用 psycopg2 创建 PostgreSQL 连接。
  3. 工具功能
  • `list_db_tables(dummy_param)` → 列出所有公共表。
  • `get_table_schema(table_name)` → 获取表的列信息。
  • `query_db_table(table, columns, condition)` → 执行 SELECT 查询。
  • `insert_data(table, data)` → 插入新行。
  • `delete_data(table, condition)` → 安全地删除符合条件的行。
  1. MCP工具注册
  2. MCP服务器设置
  3. MCP执行
  • 作为标准输入输出MCP服务器运行。
  • 接受来自代理的工具请求。
  • 执行SQL → 以JSON格式返回结果。

📌 目的： 充当工具提供者。如果没有server.py，代理无法执行数据库查询。

6. mcp_pg_server.log – 日志文件

  • 记录工具注册日志。
  • 记录MCP服务器的生命周期（启动、运行、关闭）。
  • 记录工具执行调用日志。

📌 目的： 用于调试和追踪MCP服务器的行为。

🔄 工作流程

  • 用户查询：“给我显示今天收治的病人”
  • 代理（客户端）进行解释 → 决定需要数据库模式。
  • 调用 list_db_tables 函数 → 查找录取信息。
  • 调用 `get_table_schema('admissions')` → 检查 `admissiondate` 字段。
  • 执行查询：`query_db_table("admissions", "*", "admissiondate = CURRENT_DATE")`。
  • 服务器执行SQL语句 → 返回结果。
  • 代理已回应。

✅ 主要特点

  • 自然语言 → 通过MCP执行SQL。
  • 模式感知且安全（无虚构表）。
  • 支持PostgreSQL的CRUD操作。
  • 详细的日志记录（mcp_pg_server.log）。
  • 可扩展的工具集（轻松添加新功能）。

相关 MCP