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 헤더 없이 전송됩니다.

에이전트를 위한 중요 규칙

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 서버는 공유 비밀 + 이메일을 백엔드 브로커(POST /api/v1/mcp/exchange)의 범위 지정 JWT와 교환합니다.

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 Inspector

로컬 MCP 개발 및 디버깅을 위해 MCP Inspector는 빠른 수동 테스트 루프를 제공합니다:

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

Inspector에서 중단점 디버깅을 위해 debugpy 하에서 MCP 서버를 실행하려면:

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와 같은 도구를 테스트하세요.

중단점 (debugpy): 디버거에는 포트 5678을 사용하세요 (6274는 Inspector 웹 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 서버가 이미 구성되어 있다면 전체 파일을 바꾸지 말고 기존 servers 객체 안에 workbench-mcp를 추가하세요.

.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. 검사할 함수, 프로시저, 테이블 또는 뷰를 설명(describe)합니다.

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