workbench-mcp

Un servidor MCP local en Python para la exploración interactiva de datos de PostgreSQL, integración de API y automatización en sistemas Fedora/Linux.

Descripción general

La versión 1 incluye:

• Configuración de entorno virtual de Python para sistemas Fedora/Linux

• Conectividad con PostgreSQL 18 configurada mediante el archivo .env

• Herramientas MCP para:

  • Descubrir tablas, columnas y la estructura del esquema

  • Ejecutar vistas previas de consultas de solo lectura

  • Ejecutar lotes SQL protegidos con soporte para tablas temporales

  • Llamar a funciones y procedimientos almacenados de PostgreSQL

  • Acceder a API externas mediante solicitudes de URL completas

  • Ejecutar scripts bash disponibles en PATH

• Seguridad reforzada: las modificaciones persistentes de esquema y datos están bloqueadas

• Flujos de trabajo de tablas temporales con alcance de sesión admitidos dentro de lotes SQL

Configuración en Fedora / Linux

Comience instalando los paquetes del sistema necesarios:

sudo dnf install -y python3 python3-pip nodejs npm

Se requiere Python 3.12 o posterior. Utilice pyenv o similar si gestiona varias versiones.

Configuración del entorno virtual

Desde la raíz del proyecto, cree y active un entorno virtual de Python:

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

Variables de entorno

Copie la configuración de ejemplo y rellene los detalles de conexión de PostgreSQL:

cp .env.example .env

Obligatorio:

• DB_HOST — Nombre de host del servidor PostgreSQL

• DB_NAME — Nombre de la base de datos

• DB_USER — Nombre de usuario de la base de datos

• DB_PASSWORD — Contraseña de la base de datos

Opcional (ajustes):

• DB_PORT — Puerto de conexión (predeterminado: 5432)

• DB_SSLMODE — Modo SSL (predeterminado: prefer)

• DB_APPLICATION_NAME — Identificador de la aplicación

• DB_QUERY_TIMEOUT_SECONDS — Tiempo de espera de la consulta (predeterminado: 30)

• DB_MAX_ROWS — Máximo de filas por conjunto de resultados (predeterminado: 100)

• DB_MAX_RESULT_SETS — Máximo de conjuntos de resultados por lote (predeterminado: 5)

• DB_OBJECT_PREVIEW_CHARS — Longitud máxima de vista previa de definición (predeterminado: 4000)

Ejemplo de desarrollo local:

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

Opcional: Ajuste de solicitudes HTTP

La herramienta HTTP toma una URL completa por llamada y no requiere configuración de perfil de API.

Configuraciones de entorno admitidas:

Forma de llamada de ejemplo:

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

Para llamadas autenticadas, establezca API_BEARER_TOKEN en .env (o en el entorno del proceso). Las herramientas HTTP lo utilizan automáticamente a menos que el llamador pase su propio jwt_token.

Manejo de autorización

Las herramientas HTTP admiten dos fuentes de autorización:

1. jwt_token pasado en la llamada a la herramienta

2. API_BEARER_TOKEN desde .env o el entorno del proceso

Precedencia

• Si se proporciona jwt_token, ese token se reenvía como Authorization: Bearer <jwt_token>.

• Si se omite o está vacío jwt_token, el servidor recurre a API_BEARER_TOKEN.

• Si ninguno de los valores está presente, la solicitud se envía sin un encabezado Authorization.

Regla importante para agentes

No coloque el token de portador (bearer token) dentro de headers.Authorization. El servidor MCP elimina Authorization de headers y solo acepta autenticación a través del campo dedicado jwt_token.

Esto evita colisiones accidentales de encabezados y hace explícita la precedencia de los tokens.

Ejemplo: usar el token de servidor predeterminado

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

Ejemplo: reenviar el propio token del llamador

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

Ejemplo: reenviar el token del llamador con encabezados adicionales

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

El mismo campo jwt_token está disponible en http_get, http_head, http_post, http_put, http_patch y http_delete.

Autenticación de sesión

En lugar de pasar un jwt_token por llamada, los agentes pueden adquirir un JWT con alcance de sesión una vez y hacer que cada llamada a la herramienta HTTP lo use automáticamente durante el resto de la sesión.

Cómo funciona

1. Un agente llama a auth_start_session con el correo electrónico del usuario objetivo.

2. El servidor MCP intercambia el secreto compartido + correo electrónico por un JWT con alcance del intermediario de backend (POST /api/v1/mcp/exchange).

3. El token se almacena en caché en la memoria del proceso.

4. Cada llamada posterior a la herramienta HTTP que omita jwt_token utiliza el token de sesión automáticamente.

5. El agente puede inspeccionar la sesión con auth_status, cambiar de usuario con auth_switch_user o borrarla con auth_clear_session.

Precedencia de tokens (de mayor a menor)

Variables de entorno requeridas

Herramientas de autenticación de sesión

Consulte docs/SESSION_AUTH.md para obtener la referencia completa para el agente.

Ejecutar localmente

Después de activar el entorno virtual e instalar las dependencias, inicie el servidor MCP con cualquiera de los comandos:

workbench-mcp

python -m workbench_mcp.server

Inspector MCP

Para el desarrollo y depuración local de MCP, el Inspector MCP proporciona un bucle de prueba manual rápido:

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

Para iniciar el servidor MCP bajo debugpy para la depuración de puntos de interrupción en el Inspector:

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

Después del inicio, abra la interfaz de usuario del Inspector, conéctese a través de STDIO y pruebe herramientas como health, describe_object y exec_proc_preview.

Puntos de interrupción (debugpy): Use el puerto 5678 para el depurador, no 6274 (6274 es solo la interfaz web del Inspector). El flujo de trabajo paso a paso y "qué estaba mal antes" se encuentran en docs/DEBUG_MCP.md.

Configuración de VS Code

Para registrar el servidor MCP local en VS Code, agregue una entrada al archivo de configuración MCP del espacio de trabajo:

• Archivo de espacio de trabajo: .vscode/mcp.json

Configuración de ejemplo:

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

Reemplace la ruta del comando con la ruta del repositorio local a su Python de entorno virtual.

Secretos y valores de entorno

Puede proporcionar valores de entorno en cualquiera de los dos lugares:

1. workbench-mcp/.env

2. env en .vscode/mcp.json — VS Code los inyecta en el proceso del servidor MCP.

Precedencia: el entorno del proceso (incluido .vscode/mcp.json → env) anula los valores de .env para la misma clave.

Ejemplo con ajuste HTTP en VS Code:

{
  "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"
      }
    }
  }
}

No confirme tokens reales. Prefiera una configuración de espacio de trabajo solo local u omita env y use .env (que debe mantenerse fuera de git).

Si ya hay otros servidores MCP configurados, agregue workbench-mcp dentro del objeto servers existente en lugar de reemplazar todo el archivo.

Después de guardar .vscode/mcp.json, vuelva a cargar VS Code o actualice los servidores MCP para que se descubra el nuevo servidor. Después de que se cargue el servidor, ejecute la herramienta health antes de probar los procedimientos de la base de datos.

Herramientas iniciales

• 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 (nombre del script resuelto a través de PATH)

Modelo de seguridad

• DDL y DML persistentes están bloqueados en lotes ad-hoc de PostgreSQL

• Solo se permiten escrituras en tablas temporales, y solo para tablas temporales creadas en el lote actual

• preview_query solo permite declaraciones SELECT y lecturas basadas en CTE

• exec_proc_preview puede ejecutar procedimientos y funciones de PostgreSQL; las rutinas sobrecargadas deben pasarse con una firma como public.my_func(integer, text)

• execute_path_bash_script solo acepta nombres de script (no rutas), los resuelve a través de PATH y los ejecuta a través de bash

Primeras comprobaciones sugeridas

Después de configurar .env, un flujo de validación típico es:

1. Describa la función, procedimiento, tabla o vista a inspeccionar.

2. Obtenga una vista previa de la configuración de soporte o los datos de referencia necesarios para comprender ese objeto.

3. Ejecute exec_proc_preview, preview_query o execute_readonly_sql con entradas conocidas.

4. Compare la forma devuelta con la característica, investigación o escenario de depuración que se está evaluando.

Ejemplo de ejecución de función

Para llamadas a funciones posicionales de PostgreSQL, use exec_function_preview. Pase las matrices de PostgreSQL como listas JSON normales.

Ejemplo de destino SQL:

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

Entrada de herramienta MCP equivalente:

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

Ejemplos de inserción

Inserción de una sola fila:

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

Inserción por lotes:

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