workbench-mcp

Локальный MCP-сервер на Python для интерактивного исследования данных PostgreSQL, интеграции API и автоматизации в системах Fedora/Linux.

Обзор

Версия 1 включает:

• Настройку виртуального окружения Python для систем Fedora/Linux

• Подключение к PostgreSQL 18, настроенное через файл .env

• Инструменты MCP для:

  • Обнаружения таблиц, столбцов и структуры схемы

  • Запуска предварительного просмотра запросов только для чтения

  • Выполнения защищенных SQL-пакетов с поддержкой временных таблиц

  • Вызова хранимых функций и процедур PostgreSQL

  • Доступа к внешним API через полные URL-запросы

  • Выполнения 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 (по умолчанию: 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

Для аутентифицированных вызовов установите API_BEARER_TOKEN в .env (или переменной окружения процесса). HTTP-инструменты автоматически используют его, если вызывающий не передает свой собственный jwt_token.

Обработка авторизации

HTTP-инструменты поддерживают два источника авторизации:

1. jwt_token, переданный в вызове инструмента

2. API_BEARER_TOKEN из .env или окружения процесса

Приоритет

• Если предоставлен jwt_token, этот токен передается как Authorization: Bearer <jwt_token>.

• Если jwt_token опущен или пуст, сервер использует API_BEARER_TOKEN.

• Если ни одно из значений не присутствует, запрос отправляется без заголовка Authorization.

Важное правило для агентов

Не помещайте токен bearer внутрь 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 с email целевого пользователя.

2. MCP-сервер обменивает общий секрет + email на 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

После запуска откройте интерфейс Инспектора, подключитесь через STDIO и протестируйте инструменты, такие как health, describe_object и exec_proc_preview.

Точки останова (debugpy): Используйте порт 5678 для отладчика, а не 6274 (6274 — это только веб-интерфейс Инспектора). Пошаговый рабочий процесс и описание «что было не так раньше» находятся в docs/DEBUG_MCP.md.

Настройка VS Code

Чтобы зарегистрировать локальный MCP-сервер в VS Code, добавьте запись в файл конфигурации 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 для того же ключа.

Пример с настройкой HTTP в 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"
      }
    }
  }
}

Не фиксируйте реальные токены в git. Предпочитайте локальную конфигурацию рабочей области или опустите 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 заблокированы в ad-hoc пакетах 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"}
  ]
}