内容
# 分析型数据库 PostgreSQL MCP 服务器
分析型数据库 PostgreSQL MCP 服务器作为 AI 代理与分析型数据库 PostgreSQL 之间的通用接口。它使得 AI 代理与分析型数据库 PostgreSQL 之间的通信无缝衔接，帮助 AI 代理检索数据库元数据和执行 SQL 操作。
## 安装
您可以通过源码安装以用于开发，或从 PyPI 安装以直接使用。
### 选项 1：从源码安装（用于开发）
如果您想修改或贡献服务器代码，建议使用此方法。
```shell
# 1. 克隆代码仓库
git clone https://github.com/aliyun/alibabacloud-adbpg-mcp-server.git
cd alibabacloud-adbpg-mcp-server
# 2. 使用 uv 创建并激活虚拟环境
uv venv .venv
source .venv/bin/activate # 在 Linux/macOS 上
# .\.venv\Scripts\activate # 在 Windows 上
# 3. 以可编辑模式安装项目
uv pip install -e .
```
### 选项 2：从 PyPI 安装（用于生产/使用）
这是直接在项目中使用服务器的最简单方法。
```shell
pip install adbpg-mcp-server
```
## 运行服务器
服务器可以在两种传输模式下运行：`stdio`（默认）用于与 MCP 客户端集成，`http` 用于直接 API 访问或调试。
确保在运行服务器之前已设置所需的 [环境变量](#环境变量)。
### 标准输入/输出模式（默认）
这是与 MCP 客户端通信的标准模式。
```bash
# 使用默认传输（stdio）运行
uv run adbpg-mcp-server
# 或显式指定传输
uv run adbpg-mcp-server --transport stdio
```
### 流式 HTTP 模式
此模式公开了一个 HTTP 服务器，可用于测试、调试或通过 REST API 直接集成。
```bash
# 在默认主机和端口（127.0.0.1:3000）上以 HTTP 模式运行服务器
uv run adbpg-mcp-server --transport http
# 指定自定义主机和端口，并启用身份验证
uv run adbpg-mcp-server --transport http --host 0.0.0.0 --port 3000 --auth-token your-secret-token
```
> **安全：** 当绑定到 `0.0.0.0` 或任何可网络访问的地址时，请始终通过 `--auth-token` 或 `MCP_AUTH_TOKEN` 环境变量设置身份验证令牌。 如果没有令牌，`/mcp` 端点将允许未经身份验证的访问。 客户端必须在所有请求中包含 `Authorization: Bearer <token>` 头。
## MCP 集成
要将此服务器与父 MCP 客户端集成，请在客户端配置文件中添加以下配置。 `args` 数组中的参数将取决于您选择的传输协议。
### 标准输入/输出传输示例
```json
"mcpServers": {
"adbpg-mcp-server": {
"command": "uv",
"args": [
"run",
"adbpg-mcp-server",
"--transport",
"stdio"
],
"env": {
"ADBPG_HOST": "主机",
"ADBPG_PORT": "端口",
"ADBPG_USER": "用户名",
"ADBPG_PASSWORD": "密码",
"ADBPG_DATABASE": "数据库",
"GRAPHRAG_API_KEY": "graphrag llm api 密钥",
"GRAPHRAG_BASE_URL": "graphrag llm 基础 URL",
"GRAPHRAG_LLM_MODEL": "graphrag llm 模型名称",
"GRAPHRAG_EMBEDDING_MODEL": "graphrag 嵌入模型名称",
"GRAPHRAG_EMBEDDING_API_KEY": "graphrag 嵌入 api 密钥",
"GRAPHRAG_EMBEDDING_BASE_URL": "graphrag 嵌入 URL",
"LLMEMORY_API_KEY": "llm 内存 api 密钥",
"LLMEMORY_BASE_URL": "llm 内存基础 URL",
"LLMEMORY_LLM_MODEL": "llm 内存模型名称",
"LLMEMORY_EMBEDDING_MODEL": "llm 内存嵌入模型名称",
"LLMEMORY_ENABLE_GRAPH": "为 llm 内存启用图引擎（默认：false）"
}
}
}
```
> **注意：** 由于 `stdio` 是默认的，因此您可以选择省略 `args` 数组中的 `"--transport", "stdio"`。
### 流式 HTTP 传输示例
```json
"mcpServers": {
"adbpg-mcp-server": {
"command": "uv",
"args": [
"run",
"adbpg-mcp-server",
"--transport",
"http",
"--port",
"3000"
],
"env": {
"ADBPG_HOST": "主机",
"ADBPG_PORT": "端口",
"ADBPG_USER": "用户名",
"ADBPG_PASSWORD": "密码",
"ADBPG_DATABASE": "数据库",
"MCP_AUTH_TOKEN": "您的秘密令牌",
"GRAPHRAG_API_KEY": "graphrag llm api 密钥",
"GRAPHRAG_BASE_URL": "graphrag llm 基础 URL",
"GRAPHRAG_LLM_MODEL": "graphrag llm 模型名称",
"GRAPHRAG_EMBEDDING_MODEL": "graphrag 嵌入模型名称",
"GRAPHRAG_EMBEDDING_API_KEY": "graphrag 嵌入 api 密钥",
"GRAPHRAG_EMBEDDING_BASE_URL": "graphrag 嵌入 URL",
"LLMEMORY_API_KEY": "llm 内存 api 密钥",
"LLMEMORY_BASE_URL": "llm 内存基础 URL",
"LLMEMORY_LLM_MODEL": "llm 内存模型名称",
"LLMEMORY_EMBEDDING_MODEL": "llm 内存嵌入模型名称",
"LLMEMORY_ENABLE_GRAPH": "为 llm 内存启用图引擎（默认：false）"
}
}
}
```
### 工具
* `execute_select_sql`: 在 AnalyticDB PostgreSQL 服务器上执行 SELECT SQL 查询
* `execute_dml_sql`: 在 AnalyticDB PostgreSQL 服务器上执行 DML（INSERT、UPDATE、DELETE）SQL 查询
* `execute_ddl_sql`: 在 AnalyticDB PostgreSQL 服务器上执行 DDL（CREATE、ALTER、DROP）SQL 查询
* `analyze_table`: 收集表统计信息
* `explain_query`: 获取查询执行计划
* `adbpg_graphrag_upload`
- **描述：** 上传文本文件（及其名称）和文件内容到 graphrag 以生成知识图谱。
- **参数：**
- `filename` (`text`): 要上传的文件的名称。
- `context` (`text`): 文件的文本内容。
* `adbpg_graphrag_query`
- **描述：** 使用指定的查询字符串和模式查询 graphrag。
- **参数：**
- `query_str` (`text`): 查询内容。
- `query_mode` (`text`): 查询模式，从 `[bypass, naive, local, global, hybrid, mix]` 中选择。 如果为 null，则默认为 `mix`。
* `adbpg_graphrag.upload_decision_tree(context text, root_node text)`
- **描述：** 上传具有指定 `root_node` 的决策树。 如果 `root_node` 不存在，则会创建一个新的决策树。
- **参数：**
- `context` (`text`): 决策树的文本表示。
- `root_node` (`text`): 根节点的内容。
* `adbpg_graphrag.append_decision_tree(context text, root_node_id text)`
- **描述：** 将子树追加到现有决策树中，追加到由 `root_node_id` 指定的节点。
- **参数：**
- `context` (`text`): 子树的文本表示。
- `root_node_id` (`text`): 要追加子树的节点的 ID。
* `adbpg_graphrag.delete_decision_tree(root_node_entity text)`
- **描述：** 删除由 `root_node_entity` 指定的节点下的子决策树。
- **参数：**
- `root_node_entity` (`text`): 要删除的子决策树的根节点的 ID。
* `adbpg_llm_memory_add`
- **描述：** 添加 LLM 长内存。
- **参数：**
- `messages` (`json`): 要上传的文件的名称。
- `user_id` (`text`): 用户 ID。
- `run_id` (`text`): 运行 ID。
- `agent_id` (`text`): 代理 ID。
- `metadata` (`json`): 元数据 json（可选）。
- `memory_type` (`text`): 内存类型（可选）。
- `prompt` (`text`): 提示（可选）。
**注意：**
应该至少提供 `user_id`、`run_id` 或 `agent_id` 之一。
* `adbpg_llm_memory_get_all`
- **描述：** 检索与特定用户、运行或代理相关的所有内存记录。
- **参数：**
- `user_id` (`text`): 用户 ID（可选）。 如果提供，则获取该用户的所有内存。
- `run_id` (`text`): 运行 ID（可选）。
- `agent_id` (`text`): 代理 ID（可选）。 如果提供，则获取该代理的所有内存。
**注意：**
应该至少提供 `user_id`、`run_id` 或 `agent_id` 之一。
* `adbpg_llm_memory_search`
- **描述：** 检索与给定查询相关的内存，适用于特定用户、运行或代理。
- **参数：**
- `query` (`text`): 搜索查询字符串。
- `user_id` (`text`): 用户 ID（可选）。 如果提供，则获取该用户的所有内存。
- `run_id` (`text`): 运行 ID（可选）。
- `agent_id` (`text`): 代理 ID（可选）。 如果提供，则获取该代理的所有内存。
- `filter` (`json`): 附加的过滤条件，json 格式（可选）。
**注意：**
应该至少提供 `user_id`、`run_id` 或 `agent_id` 之一。
* `adbpg_llm_memory_delete_all`:
- **描述：** 删除与特定用户、运行或代理相关的所有内存记录。
- **参数：**
- `user_id` (`text`): 用户 ID（可选）。 如果提供，则获取该用户的所有内存。
- `run_id` (`text`): 运行 ID（可选）。
- `agent_id` (`text`): 代理 ID（可选）。 如果提供，则获取该代理的所有内存。
**注意：**
应该至少提供 `user_id`、`run_id` 或 `agent_id` 之一。
### 资源
#### 内置资源
* `adbpg:///schemas`: 获取数据库中的所有模式
#### 资源模板
* `adbpg:///{schema}/tables`: 列出特定模式中的所有表
* `adbpg:///{schema}/{table}/ddl`: 获取表 DDL
* `adbpg:///{schema}/{table}/statistics`: 显示表统计信息
## 环境变量
MCP 服务器需要以下环境变量才能连接到 AnalyticDB PostgreSQL 实例：
- `ADBPG_HOST`: 数据库主机地址
- `ADBPG_PORT`: 数据库端口
- `ADBPG_USER`: 数据库用户名
- `ADBPG_PASSWORD`: 数据库密码
- `ADBPG_DATABASE`: 数据库名称
对于 HTTP 传输模式，以下可选变量启用端点身份验证：
- `MCP_AUTH_TOKEN`: HTTP 端点身份验证的 Bearer 令牌（也可以通过 `--auth-token` CLI 参数设置）。 **强烈建议** 在绑定到非环回地址时使用。
MCP 服务器需要以下环境变量来初始化 graphRAG 和 llm 内存服务器：
- `API_KEY`: LLM 提供商或嵌入 API 的 API 密钥
- `BASE_URL`: LLM 或嵌入服务端点的基础 URL
- `LLM_MODEL`: LLM 模型名称或标识符
- `EMBEDDING_MODEL`: 嵌入模型名称或标识符
## 依赖
* Python 3.11 或更高版本
* `uv`（用于环境和包管理）
连接信息
猜你喜欢
暂无推荐服务器