MCP Dev

工作台mcp

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

概述

版本1包括：

• Fedora/Linux系统的Python虚拟环境设置
• PostgreSQL 18连接配置通过 .env 文件
• MCP工具用于：

- 发现表、列和模式结构 - 运行只读查询预览 - 使用临时表支持执行受保护的SQL批处理 - 调用PostgreSQL存储函数和过程 - 通过完整URL请求访问外部API - 执行bash脚本 PATH

• 强制安全：阻止持久模式和数据修改
• 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模式（默认：首选）
• 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

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

授权处理

HTTP工具支持两种授权源：

1. jwt_token 在工具调用中传递
2. API_BEARER_TOKEN 从 .env 或过程环境

优先

• 如果 jwt_token 如果提供了，则该令牌将按以下方式转发 Authorization: Bearer .
• 如果 jwt_token 如果省略或为空，服务器将回退到 API_BEARER_TOKEN.
• 如果两个值都不存在，则发送请求时将不带 Authorization 头球

代理人的重要规则

做 不 将不记名代币放在里面 headers.Authorization. MCP服务器条带 Authorization 从 headers 并且只接受通过专用身份验证 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. 后续每次省略的HTTP工具调用 jwt_token 自动使用会话令牌。
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

在下启动MCP服务器 debugpy 对于检查器中的断点调试：

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

启动后，打开Inspector UI，重新连接 STDIO，以及测试工具，如 health, describe_object，以及 exec_proc_preview.

断点（调试）： 使用端口 5678 对于调试器，不是6274（6274只是检查器web UI）。循序渐进的工作流程和“之前出了什么问题”都在 docs/DEBUG_MCP.md.

VS代码设置

要在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. env 在 .vscode/mcp.json --VS Code将这些注入MCP服务器进程。

优先： 过程环境（包括 .vscode/mcp.json → env)覆盖以下值 .env 对于同一个密钥。

VS代码中的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)

安全模型

• 持久DDL和DML在即席PostgreSQL批处理中被阻止
• 只允许写入临时表，并且只允许在当前批中创建临时表
• 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"}
  ]
}