AI导哈

数据库工具协议

一个提供安全数据库工具（PostgreSQL/MySQL/Oracle）的模型上下文协议（MCP）服务器和客户端，支持多种传输方式和工具调用。

  • by giridhar82
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 giridhar82/HelloMCP

使用说明

HelloMCP

一个模型上下文协议（MCP）服务器和客户端，为PostgreSQL、MySQL和Oracle提供安全的数据库工具。包括：

  • MCP服务器及其工具： db_test_connection, db_validate, db_schema, db_list_tables, db_query
  • 用于stdio和流式HTTP传输的MCP客户端线束
  • 用于快速即席查询的可选代理工具模式
  • 可选的自然语言web UI→ SQL显示

需求

  • Python 3.12(py -3.12 在Windows上）
  • 具有可访问凭据的正在运行的数据库
  • 推荐：Windows上的PowerShell

安装依赖项：

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

配置

在以下位置创建本地客户端配置 config/mcp_client.json:

{
  "transport": "streamable-http",
  "url": "http://127.0.0.1:8000/mcp",
  "server": "src.core.server",
  "python_cmd": "py -3.12",
  "db": {
    "type": "postgresql",
    "host": "<< >>",
    "port": 5432,
    "name": "<<  >>",
    "user": "<< >>",
    "pass": "<< >>",
    "ssl_mode": null,
    "schema": null
  }
}

或者设置一个环境变量：

$env:MCP_CLIENT_CONFIG = "config/mcp_client.json"

运行MCP服务器

  • HTTP传输（建议用于浏览器/远程客户端）：
$env:MCP_TRANSPORT = "streamable-http"
py -3.12 -m src.core.server
  • Stdio传输（建议用于本地IDE客户端）：
py -3.12 -m src.core.server

运输选择由以下因素控制 MCP_TRANSPORT；参见 src/core/server.py.

运行MCP客户端

使用客户端工具初始化会话并练习数据库工具。

$env:MCP_CLIENT_CONFIG = "config/mcp_client.json"
py -3.12 -m src.client.mcp_client

它的作用：

  • 初始化MCP会话并列出工具
  • 电话：
    • db_test_connection
    • db_validate 随着 SELECT 1
    • db_schema
    • db_list_tables
    • db_query 随着 SELECT 1

客户端代码参考：

  • 条目： src/client/mcp_client.py:154–163
  • HTTP模式： src/client/mcp_client.py:64–71
  • 标准模式： src/client/mcp_client.py:52–62

快速测试（代理工具模式）

使用代理的工具模式运行无需Bedrock的即席查询。

  • 列表表格：
py -3.12 src\ai\bedrock_agent.py --transport http --url http://127.0.0.1:8000/mcp --tool db_list_tables
  • 查询行：
py -3.12 src\ai\bedrock_agent.py --transport http --url http://127.0.0.1:8000/mcp --tool db_query --sql "SELECT id, name FROM apartments_apartment ORDER BY id LIMIT 10"
  • 参数化查询（Postgres样式）：
py -3.12 src\ai\bedrock_agent.py --transport http --url http://127.0.0.1:8000/mcp --tool db_query --sql "SELECT * FROM payments_paymentrecord WHERE payment_date >= %(start)s" --params "{\"start\":\"2024-01-01\"}"

S3 MCP服务器

  • 在以下位置配置客户端 config/mc_S3.json:
    {
  "transport": "streamable-http",
  "url": "http://127.0.0.1:8002/mcp",
  "server": "src.s3.server",
  "bucket": "",
  "prefix": "",
  "key": "",
  "max_bytes": null,
  "decode_text": true
}
  • 在端口8002上启动服务器：
    • $env:MCP_TRANSPORT="streamable-http"; $env:MCP_HTTP_PORT=8002; py -3.12 -m src.s3.server
  • 与客户进行测试：
    • $env:MCP_CLIENT_CONFIG="config/mc_S3.json"; py -3.12 -m src.client.s3_client
  • 工具：
    • s3_list_buckets 列出bucket
    • s3_list_objects 列出bucket中的对象（使用 bucket/prefix)
    • s3_read_object 读取对象内容（使用 bucket/key)
  • 笔记：
    • AWS凭据必须可用（环境或默认配置文件）
    • s3_list_buckets 需要 s3:ListAllMyBuckets 许可；集 bucket 和使用 s3_list_objects 否则
    • 可选的 AWS_REGION 和 AWS_S3_ENDPOINT 由服务器支持
    • 服务器代码： src/s3/server.py:38–108，运行： src/s3/server.py:112–116

LocalFS MCP服务器

  • 在以下位置配置客户端 config/localfile_mcp.json:
    {
  "transport": "streamable-http",
  "url": "http://127.0.0.1:8003/mcp",
  "server": "src.localfs.server",
  "path": ".",
  "types": ["py", "txt"],
  "ignore": [".venv/**", "__pycache__/**", "node_modules/**"],
  "read": "README.md",
  "max_depth": 5,
  "max_items": 200
}
  • 在端口8003上启动服务器：
    • $env:MCP_TRANSPORT="streamable-http"; $env:MCP_HTTP_PORT=8003; py -3.12 -m src.localfs.server
  • 与客户进行测试：
    • $env:MCP_CLIENT_CONFIG="config/localfile_mcp.json"; py -3.12 -m src.client.localfs_client
  • 工具：
    • localfs_list 列出以下文件 path 可选 types 和 ignore
    • localfs_read 读取相对于的文件 path
  • 笔记：
    • ignore 使用相对于以下对象的全局模式 path
    • types 是没有点的扩展（例如。， "py")
    • 路径限制已强制执行（无法在库外读取）
    • 服务器代码： src/localfs/server.py:33–104，运行： src/localfs/server.py:108–114

故障排除

  • 406呼叫时不可接受 /mcp 直接：
    • 使用客户端或代理工具模式，执行MCP握手。
  • Pydantic缺少字段错误 db_query:
    • 确保有效载荷包括 query 以及DB连接字段。
  • 参数绑定：
    • PostgreSQL/MySQL：传递参数字典；使用 %(name)s 在SQL for Postgres中。
    • Oracle：占位符转换为 :name 内部。

项目结构

  • 服务器和工具： src/core/server.py
  • 客户端线束： src/client/mcp_client.py
  • 数据库连接器： src/database/connectors/*.py
  • 安全检查： src/database/safety/risk_checker.py
  • 代理工具模式： src/ai/bedrock_agent.py
  • Web用户界面： src/ui/chat_server.py

安全

  • 通过以下方式忽略机密和本地配置 .gitignore （例如。， .env, config/mcp_client.json, src/creds).
  • 不要提交凭据；使用env-vars或本地配置文件。

相关 MCP