MCP 데이터베이스 서버

mcp-framework 로 구축된 MCP(Model Context Protocol) 서버는 데이터베이스(DuckDB를 통한 PostgreSQL) 및 Google Cloud Storage(GCS)와 상호작용하기 위한 도구와 리소스를 제공합니다.

필수 조건

• Node.js 22 이상

• 타입스크립트

• PostgreSQL(데이터베이스 기능에 필요)

• Google Cloud 자격 증명(선택 사항, GCS 기능용)

• Devbox ( make 명령을 사용한 로컬 개발용)

프로젝트 구조

지엑스피1

설치

1. 저장소를 복제합니다.

   git clone <repository-url> cd mcp-db

2. 종속성 설치(일관성을 위해 Devbox 사용이 권장됨):

   devbox install # Or using npm directly if not using Devbox # npm install

3. .env.example``.env 로 복사하고 환경 변수를 입력합니다.

   cp .env.example .env # Edit .env with your details

4. 프로젝트를 빌드하세요:

   # Using make (requires Devbox) make build # Or using npm directly # npm run build

구성

환경 변수

다음 환경 변수(또는 명령줄 인수)를 사용하여 서버를 구성합니다.

• DATABASE_URL : PostgreSQL 연결 문자열(supergateway로 실행하지 않는 한 필수).

• DATABASE_URLS : 여러 데이터베이스 연결에 대한 alias=url 쌍의 쉼표로 구분된 목록( DATABASE_URL 의 대안).

• LOG_LEVEL : 로깅 수준( debug , info , error ). 기본값: info .

• GCS_BUCKET : 기본 Google Cloud Storage 버킷 이름(선택 사항).

• GCP_SERVICE_ACCOUNT : Base64로 인코딩된 Google Cloud 서비스 계정 키 JSON(선택 사항, GCS 인증용).

• GCS_KEY_ID / GCS_SECRET : DuckDB의 httpfs 확장을 위한 대체 GCS 자격 증명(선택 사항).

• TRANSPORT : 전송 유형( stdio 또는 sse ). 기본값: stdio .

• PORT : SSE 전송을 위한 포트 번호. 기본값: 3001 .

• HOST : SSE 전송 호스트 이름입니다. 기본값: localhost .

• API_KEY : 서버를 보호하기 위한 선택적 API 키(설정된 경우 클라이언트가 Authorization: Bearer <key> 헤더에서 제공해야 함).

명령줄 인수(예: --port 8080 , --gcs-bucket my-bucket )는 환경 변수보다 우선합니다. 자세한 내용은 src/config.ts 참조하세요.

데이터베이스 마이그레이션

이 프로젝트는 PostgreSQL 스키마 변경 관리를 위해 node-pg-migrate 사용합니다. 마이그레이션 실행 및 생성에 대한 자세한 내용은 위 README 원본의 "데이터베이스 마이그레이션" 섹션을 참조하세요.

참고: 이전에 언급한 npm run setup:db 명령은 현재 설정에 따라 검토 또는 업데이트가 필요할 수 있습니다.

서버 실행

편리한 개발 명령을 위해 Makefile 사용하세요(Devbox 필요):

make 없이 실행하려면( npm run build 후):

클라이언트 구성

MCP 클라이언트(예: mcp-cli , Claude Desktop)를 로컬 서버에 연결하려면:

SSE 전송의 경우(예: 포트 3001):

(참고: 이전 README의 Docker/supergateway 예제는 오래되었거나 다른 배포 설정에만 해당될 수 있습니다.)

Stdio Transport의 경우:

GitHub에서 npx로 실행

npx를 사용하여 서버를 직접 실행할 수 있습니다(패키지의 빌드 단계 필요):

사용 가능한 도구

• duckdb_insert : DuckDB를 통해 연결된 PostgreSQL 데이터베이스에 INSERT 문을 실행합니다. INSERT 쿼리만 허용됩니다.

• duckdb_query : DuckDB의 postgres_query 함수를 사용하여 연결된 PostgreSQL 데이터베이스( postgres_db )에 직접 읽기 전용 SQL 쿼리를 실행합니다. 정규화되지 않은 테이블 이름에 자동으로 접두사를 붙입니다(예: my_table``postgres_db.public.my_table 이 됩니다).

• duckdb_read_parquet : DuckDB를 사용하여 Parquet 파일을 쿼리합니다(구성된 경우 GCS에서).

• duckdb_update : DuckDB를 통해 연결된 PostgreSQL 데이터베이스에 UPDATE 문을 실행합니다.

• gcs_directory_tree : 페이지 분할을 지원하는 GCS 버킷에서 디렉토리 트리 구조를 가져옵니다.

사용 가능한 리소스

• mcp://gcs/objects : 구성된 GCS 버킷에 있는 객체를 나열합니다.

• mcp://db/tables : 구성된 PostgreSQL 데이터베이스에 있는 모든 테이블과 열을 나열합니다.

개발: 새로운 도구/리소스 통합

이 프로젝트에서는 mcp-framework 사용합니다. 새 도구나 리소스를 추가하려면 다음을 수행하세요.

1. 클래스 만들기:

   • src/tools/ 또는 src/resources/ 에 새로운 .ts 파일을 만듭니다.

   • MCPTool 또는 MCPResource 확장하는 클래스를 정의합니다.

   • 필요한 속성(도구의 경우 name , description , schema )과 메서드(도구의 경우 execute , 리소스의 경우 read )를 구현합니다.

   • 입력 검증(도구)을 위해 schema 속성에서 Zod를 사용합니다.

   • 클래스 내에서(종종 생성자 내에서) 모든 종속성(DB 연결이나 GCS 클라이언트)을 초기화하는데, src/services/ 의 서비스나 src/config.ts 의 구성을 사용할 가능성이 있습니다.

   예제 도구(

   import { MCPTool } from "mcp-framework"; import { z } from "zod"; import { formatSuccessResponse } from "../utils.js"; import { getDuckDBConnection } from "../services/duckdb.js"; // Example dependency const MyToolInputSchema = z.object({ param1: z.string().describe("Description for parameter 1"), }); type MyToolInput = z.infer<typeof MyToolInputSchema>; export class MyTool extends MCPTool<MyToolInput> { name = "my_tool"; description = "Description of what my tool does."; schema = { // Matches Zod schema structure param1: { type: z.string(), description: "Description for parameter 1" }, }; async execute(args: MyToolInput): Promise<any> { console.error(`Handling tool request: ${this.name}`); const duckDBConn = getDuckDBConnection(); // Get dependency // ... implement logic using args and duckDBConn ... const result = { message: `Processed ${args.param1}` }; return formatSuccessResponse(result); } } export default MyTool; // Ensure default export

2. 자동 검색:

   • mcp-framework``src/tools 및 src/resources 디렉토리에 있는 파일에서 기본적으로 내보내진 도구/리소스 클래스를 자동으로 검색하여 등록합니다.

   • 새 클래스가 해당 파일에서 default export 설정되어 있는지 확인하세요.

3. 시험:

   • 서버를 실행합니다( make dev ).

   • 시작 로그를 확인하여 새 도구/리소스가 나열되어 있는지 확인하세요.

   • MCP 클라이언트( mcp-cli 또는 MCP Inspector 등)를 사용하여 도구를 호출하거나 리소스를 읽고 기능을 확인합니다.

모범 사례

• 도구용 Zod를 사용하여 명확한 입력 스키마를 정의합니다.

• execute / read 내에서 오류를 우아하게 처리하고 formatErrorResponse (또는 오류 발생)를 사용하여 형식화된 오류 응답을 반환합니다.

• 필요한 경우 getConfig() 를 통해 중앙화된 구성( src/config.ts )을 사용합니다.

• 데이터베이스 연결과 같은 종속성을 위해 src/services/ 에 있는 서비스 초기화 프로그램을 활용합니다.

• 가시성을 위해 로깅( console.error )을 추가합니다.