workbench-mcp

一个用于 Fedora/Linux 系统上交互式 PostgreSQL 数据探索、API 集成和自动化的本地 Python MCP 服务器。

概述

版本 1 包括：

• 针对 Fedora/Linux 系统的 Python 虚拟环境设置

• 通过 .env 文件配置的 PostgreSQL 18 连接

• MCP 工具，用于：

  • 发现表、列和模式结构

  • 运行只读查询预览

  • 执行带有临时表支持的受限 SQL 批处理

  • 调用 PostgreSQL 存储函数和过程

  • 通过完整 URL 请求访问外部 API

  • 执行 PATH 中可用的 bash 脚本

• 强制安全：禁止持久化模式和数据修改

• 支持 SQL 批处理内的会话级临时表工作流

Fedora / Linux 设置

首先安装所需的系统包：

sudo dnf install -y python3 python3-pip nodejs npm

需要 Python 3.12 或更高版本。如果管理多个版本，请使用 pyenv 或类似工具。

虚拟环境设置

在项目根目录下，创建并激活 Python 虚拟环境：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .

环境变量

复制示例配置并填充 PostgreSQL 连接详细信息：

cp .env.example .env

必需：

• DB_HOST — PostgreSQL 服务器主机名

• DB_NAME — 数据库名称

• DB_USER — 数据库用户名

• DB_PASSWORD — 数据库密码

可选（调优）：

• DB_PORT — 连接端口（默认：5432）

• DB_SSLMODE — SSL 模式（默认：prefer）

• DB_APPLICATION_NAME — 应用程序标识符

• DB_QUERY_TIMEOUT_SECONDS — 查询超时（默认：30）

• DB_MAX_ROWS — 每个结果集的最大行数（默认：100）

• DB_MAX_RESULT_SETS — 每个批次的最大结果集数（默认：5）

• DB_OBJECT_PREVIEW_CHARS — 最大定义预览长度（默认：4000）

本地开发示例：

DB_HOST=localhost
DB_PORT=5432
DB_NAME=app_dev
DB_USER=app_user
DB_PASSWORD=your-secure-password
DB_SSLMODE=prefer

可选：HTTP 请求调优

HTTP 工具每次调用使用完整 URL，不需要 API 配置文件。

支持的环境设置：

调用形状示例：

url: https://localhost:44331/api/breakouts/filter/1871161/dd-table?ParameterSetId=231022
method: GET

对于经过身份验证的调用，请在 .env（或进程环境变量）中设置 API_BEARER_TOKEN。除非调用者传递了自己的 jwt_token，否则 HTTP 工具会自动使用它。

授权处理

HTTP 工具支持两种授权来源：

1. 在工具调用中传递的 jwt_token

2. 来自 .env 或进程环境的 API_BEARER_TOKEN

优先级

• 如果提供了 jwt_token，该令牌将作为 Authorization: Bearer <jwt_token> 转发。

• 如果 jwt_token 被省略或为空，服务器将回退到 API_BEARER_TOKEN。

• 如果两个值都不存在，请求将不带 Authorization 标头发送。

代理的重要规则

不要将 bearer token 放在 headers.Authorization 中。 MCP 服务器会从 headers 中剥离 Authorization，并且仅接受通过专用 jwt_token 字段进行的身份验证。

这可以防止意外的标头冲突，并使令牌优先级明确。

示例：使用默认服务器令牌

{
  "url": "https://localhost:5001/api/v1/sales/my-sales"
}

示例：转发调用者自己的令牌

{
  "url": "https://localhost:5001/api/v1/sales/my-sales",
  "jwt_token": "eyJhbGciOi..."
}

示例：转发带有额外标头的调用者令牌

{
  "url": "https://localhost:5001/api/v1/sales/my-sales",
  "jwt_token": "eyJhbGciOi...",
  "headers": {
    "Accept": "application/json"
  }
}

相同的 jwt_token 字段在 http_get、http_head、http_post、http_put、http_patch 和 http_delete 上可用。

会话身份验证

代理无需为每次调用传递 jwt_token，而是可以获取一次会话级 JWT，并让每个 HTTP 工具调用在会话的其余部分自动使用它。

工作原理

1. 代理使用目标用户的电子邮件调用 auth_start_session。

2. MCP 服务器将共享密钥 + 电子邮件交换为来自后端代理的范围限定 JWT (POST /api/v1/mcp/exchange)。

3. 令牌缓存在进程内存中。

4. 随后每个省略 jwt_token 的 HTTP 工具调用都会自动使用会话令牌。

5. 代理可以使用 auth_status 检查会话，使用 auth_switch_user 切换用户，或使用 auth_clear_session 清除它。

令牌优先级（从高到低）

所需环境变量

会话身份验证工具

请参阅 docs/SESSION_AUTH.md 获取完整的代理参考。

本地运行

激活虚拟环境并安装依赖项后，使用以下任一命令启动 MCP 服务器：

workbench-mcp

python -m workbench_mcp.server

MCP 检查器

对于本地 MCP 开发和调试，MCP 检查器提供了快速的手动测试循环：

npx @modelcontextprotocol/inspector .venv/bin/python -m workbench_mcp.server

要在 debugpy 下启动 MCP 服务器以在检查器中进行断点调试：

npx @modelcontextprotocol/inspector .venv/bin/python -m debugpy --listen 127.0.0.1:5678 -m workbench_mcp.server

启动后，打开检查器 UI，通过 STDIO 连接，并测试诸如 health、describe_object 和 exec_proc_preview 等工具。

断点 (debugpy)： 使用端口 5678 进行调试，而不是 6274（6274 仅是检查器 Web UI）。分步工作流和“之前出了什么问题”在 docs/DEBUG_MCP.md 中。

VS Code 设置

要在 VS Code 中注册本地 MCP 服务器，请在工作区 MCP 配置文件中添加一个条目：

• 工作区文件：.vscode/mcp.json

配置示例：

{
  "servers": {
    "workbench-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/workbench-mcp/.venv/bin/python",
      "args": ["-m", "workbench_mcp.server"]
    }
  }
}

将命令路径替换为虚拟环境 Python 的本地存储库路径。

密钥和环境变量值

您可以在以下任一位置提供环境变量值：

1. workbench-mcp/.env

2. .vscode/mcp.json 中的 env — VS Code 将这些注入到 MCP 服务器进程中。

优先级： 进程环境（包括 .vscode/mcp.json -> env）会覆盖 .env 中相同键的值。

VS Code 中 HTTP 调优示例：

{
  "servers": {
    "workbench-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/workbench-mcp/.venv/bin/python",
      "args": ["-m", "workbench_mcp.server"],
      "env": {
        "API_TIMEOUT_SECONDS": "30",
        "API_MAX_RESPONSE_BYTES": "2097152",
        "API_VERIFY_SSL": "false"
      }
    }
  }
}

不要提交真实的令牌。建议使用仅限本地的工作区配置，或者省略 env 并使用 .env（应将其排除在 git 之外）。

如果已经配置了其他 MCP 服务器，请将 workbench-mcp 添加到现有的 servers 对象中，而不是替换整个文件。

保存 .vscode/mcp.json 后，重新加载 VS Code 或刷新 MCP 服务器，以便发现新服务器。服务器加载后，在测试数据库过程之前运行 health 工具。

初始工具

• health

• describe_object

• list_tables_and_columns

• preview_query

• execute_readonly_sql

• exec_proc_preview

• exec_function_preview

• insert_row

• insert_rows

• http_get

• http_head

• http_post

• http_put

• http_patch

• http_delete

• auth_start_session

• auth_switch_user

• auth_status

• auth_clear_session

• execute_path_bash_script (脚本名称通过 PATH 解析)

安全模型

• 在临时 PostgreSQL 批处理中禁止持久化 DDL 和 DML

• 仅允许临时表写入，且仅限于在当前批处理中创建的临时表

• preview_query 仅允许 SELECT 语句和基于 CTE 的读取

• exec_proc_preview 可以执行 PostgreSQL 过程和函数；重载例程应使用签名传递，例如 public.my_func(integer, text)

• execute_path_bash_script 仅接受脚本名称（而非路径），通过 PATH 解析它们，并通过 bash 执行

建议的首次检查

配置 .env 后，典型的验证流程是：

1. 描述要检查的函数、过程、表或视图。

2. 预览理解该对象所需的辅助配置或参考数据。

3. 使用已知输入运行 exec_proc_preview、preview_query 或 execute_readonly_sql。

4. 将返回的形状与正在评估的功能、调查或调试场景进行比较。

函数执行示例

对于位置 PostgreSQL 函数调用，请使用 exec_function_preview。 将 PostgreSQL 数组作为普通 JSON 列表传递。

SQL 目标示例：

select * from sales."Fn_GetSalesChamps"(2, 2025, array[1,2,5,6,7,8,9,10,11,12,15,16,18,19], 5);

等效的 MCP 工具输入：

{
  "function_name": "sales.\"Fn_GetSalesChamps\"",
  "parameters": [2, 2025, [1, 2, 5, 6, 7, 8, 9, 10, 11, 12, 15, 16, 18, 19], 5]
}

插入示例

单行插入：

{
  "table_name": "sales.orders",
  "row": {
    "customer_id": 10,
    "status": "new"
  },
  "returning_columns": ["order_id"]
}

批量插入：

{
  "table_name": "sales.orders",
  "rows": [
    {"customer_id": 10, "status": "new"},
    {"customer_id": 11, "status": "pending"}
  ]
}