sap-bdc-mcp-server

SAP Business Data Cloud (BDC) Connect SDK와의 통합을 제공하는 MCP (Model Context Protocol) 서버입니다. 이 서버를 통해 Claude와 같은 AI 어시스턴트가 데이터 공유, Delta Sharing 프로토콜 작업 및 데이터 제품 관리를 위해 SAP BDC와 상호작용할 수 있습니다.

상태: ✅ PyPI에 출시됨 - v0.2.0 (2026-01-10)

v0.2.0 신규 기능: ✨ provision_share (엔드 투 엔드 오케스트레이션) 및 validate_share_readiness (사전 비행 검증) 도구 추가!

이 MCP 서버는 SAP BDC 작업을 위한 7가지 강력한 도구를 제공합니다:

공유 생성/업데이트 (Create/Update Shares): ORD 메타데이터를 사용하여 데이터 공유 관리
CSN 스키마 관리 (CSN Schema Management): Common Semantic Notation을 사용하여 공유 구성
데이터 제품 게시 (Data Product Publishing): 데이터 제품 게시 및 게시 취소
공유 삭제 (Share Deletion): 공유된 리소스 제거 및 철회
CSN 템플릿 생성 (CSN Template Generation): Databricks 공유로부터 CSN 템플릿 자동 생성
엔드 투 엔드 프로비저닝 (End-to-End Provisioning) ✨: 한 단계로 공유 생성, 권한 부여 및 등록 수행
사전 비행 검증 (Pre-flight Validation) ✨: 오류 방지를 위해 등록 전 공유 검증

• Python 3.9 이상 (로컬 개발 시 Python 3.11 이상 권장)
• Databricks 환경에 대한 액세스
• SAP Business Data Cloud 계정
• Delta Sharing을 위해 구성된 Databricks 수신자 (recipient)
• 로컬 개발용: Databricks 개인 액세스 토큰 (personal access token)

선호하는 언어/플랫폼을 선택하세요:

pip install sap-bdc-mcp-server

npm install @mariodefelize/sap-bdc-mcp-server

참고: npm 패키지는 Python MCP 서버를 래핑(wrap)하므로 Python 3.9 이상이 설치되어 있어야 합니다.

전체 Node.js/TypeScript 문서는 NPM_README.md를 참조하세요.

# 저장소 복제
git clone https://github.com/MarioDeFelipe/sap-bdc-mcp-server.git
cd sap-bdc-mcp-server
...

프로젝트 루트에 .env 파일을 생성하세요:

# Databricks 설정
DATABRICKS_RECIPIENT_NAME=your_recipient_name
DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
...

서버는 dbutils 없이도 작동하는 LocalDatabricksClient를 자동으로 사용합니다.

Databricks 노트북 내부에서 실행하는 경우, 다음 항목만 설정하십시오:

DATABRICKS_RECIPIENT_NAME=your_recipient_name
LOG_LEVEL=INFO

서버가 노트북 환경을 자동으로 감지하여 dbutils를 사용합니다.

MCP 서버는 stdio 기반 서비스로 실행됩니다:

python -m sap_bdc_mcp.server

또는 설치된 스크립트를 사용하여 실행할 수 있습니다:

sap-bdc-mcp

이 서버를 Claude Desktop 설정 파일에 추가하십시오:

MacOS의 경우: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows의 경우: %APPDATA%\Claude\claude_desktop_config.json

{
"mcpServers": {
"sap-bdc": {
...

Node.js/TypeScript 애플리케이션의 경우, npm 패키지를 사용하십시오:

import { createSapBdcMcpClient } from '@mariodefelize/sap-bdc-mcp-server';
const client = await createSapBdcMcpClient({
env: {
...

전체 Node.js/TypeScript 문서 및 예제는 NPM_README.md를 참조하십시오.

또는, 가상 환경(virtual environment)에 설치된 경우:

{
"mcpServers": {
"sap-bdc": {
...

ORD 메타데이터를 사용하여 데이터 공유(data share)를 생성하거나 업데이트합니다.

매개변수 (Parameters):

share_name

(필수): 공유 이름
ord_metadata

(선택 사항): ORD 메타데이터 객체
tables

(선택 사항): 포함할 테이블 이름 배열

예시 (Example):

{
"share_name": "customer_data_share",
"ord_metadata": {
...

CSN 형식을 사용하여 공유를 생성하거나 업데이트합니다.

매개변수 (Parameters):

share_name

(필수): 공유 이름
csn_schema

(필수): CSN 스키마(schema) 정의 객체

예시 (Example):

{
"share_name": "product_share",
"csn_schema": {
...

데이터 제품(data product)을 게시하여 소비할 수 있도록 만듭니다.

매개변수 (Parameters):

share_name

(필수): 공유 이름
data_product_name

(필수): 데이터 제품 이름

예시 (Example):

{
"share_name": "customer_data_share",
"data_product_name": "CustomerAnalytics"
...

공유를 삭제하고 공유된 리소스를 회수합니다.

매개변수 (Parameters):

share_name

(필수): 삭제할 공유 이름

예시 (Example):

{
"share_name": "old_share"
}

기존 Databricks share로부터 CSN 템플릿을 생성합니다.

매개변수 (Parameters):

share_name

(필수): Databricks share의 이름

예시 (Example):

{
"share_name": "existing_databricks_share"
}

원스텝 프로비저닝 (One-step provisioning): 단일 작업으로 Databricks share를 생성하고, 수신자에게 권한을 부여하며, SAP BDC에 등록합니다.

이 도구는 전체 워크플로 (workflow)를 오케스트레이션 (orchestrate)합니다:

• Databricks Delta share 생성
• 지정된 테이블을 share에 추가
• 설정된 수신자에게 share 권한 부여
• SAP BDC에 share 등록

매개변수 (Parameters):

share_name

(필수): 생성할 share의 이름
tables

(필수): 테이블 이름 배열 (형식: catalog.schema.table 또는 schema.table)
ord_metadata

(필수): ORD 메타데이터 (metadata) 객체
title

(필수): share의 표시 제목
shortDescription

: 짧은 설명
description

: 상세 설명
version

: 버전 번호 (예: "1.0.0")
releaseStatus

: 상태 (예: "active", "beta")
tags

: 태그 배열

comment

(선택 사항): Databricks share에 대한 주석
auto_grant

(선택 사항): 수신자에게 자동 권한 부여 (기본값: true)
skip_if_exists

(선택 사항): share가 이미 존재하는 경우 건너뛰기 (기본값: true)

예시 (Example):

{
"share_name": "customer_analytics",
"tables": ["main.analytics.customers", "main.analytics.orders"],
...

수행 작업 (What it does):

• ✅ Databricks share 생성 (이미 존재하는 경우 건너뜀)
• ✅ 지정된 모든 테이블을 share에 추가
• ✅ 수신자에게 SELECT 권한 부여
• ✅ ORD 메타데이터와 함께 SAP BDC에 등록
• ✅ 단계별 진행 피드백 제공
• ✅ 단계 중 실패할 경우, 완료된 작업과 수동으로 수행해야 할 작업 안내

수동 단계 대신 이 도구를 사용하는 이유:

• 4개의 개별 작업 대신 단일 명령어로 수행 가능
• 자동 에러 핸들링 (error handling) 및 복구 가이드 제공
• 멱등성 (Idempotent) 보장 - 중단 시 재시도해도 안전함
• 각 단계의 성공/실패에 대한 명확한 가시성 제공

등록 전 검증 (Validate before you register): Databricks share가 BDC Connect 작업을 수행할 준비가 되었는지 확인하십시오.

이 도구는 다음과 같은 종합적인 사전 점검 (pre-flight checks)을 수행합니다:

• ✅ Databricks에 Share가 존재하는지 확인
• ✅ Share에 테이블/객체가 있는지 확인
• ✅ Share가 수신자에게 권한 부여되었는지 확인
• ✅ 검증 실패 시 실행 가능한 다음 단계 제공

매개변수 (Parameters):

share_name

(필수): 검증할 Share의 이름

check_bdc_registration

(선택 사항): BDC 등록 상태도 함께 확인 (기본값: false)

예시 (Example):

{
"share_name": "customer_data_share"
}

성공 응답 (Success Response):

✅ Share 'customer_data_share'가 BDC Connect 등록을 위한 준비가 되었습니다!
모든 검사를 통과했습니다:
✅ PASS Share 'customer_data_share'가 Databricks에 존재합니다
...

실패 응답 (Failure Response):

❌ Share 'test_share'가 BDC Connect를 위한 준비가 되지 않았습니다
발견된 오류:
❌ Share가 비어 있음 - 추가된 테이블이 없음
...

사용 사례 (Use Cases):

등록 전: create_or_update_share를 호출하기 전에 Share를 검증
문제 해결 (Troubleshooting): 등록이 실패한 원인 파악
문서화 (Documentation): 필요한 사항에 대한 체크리스트 생성
CI/CD 파이프라인: 배포 전 자동화된 검증
온보딩 (Onboarding): 신규 사용자가 전제 조건을 이해하도록 지원

이것이 중요한 이유:

• "시행착오 (trial and error)" 워크플로우 방지 - Share가 준비되었는지 사전에 파악
• 모호한 에러 메시지 대신 명확하고 실행 가능한 가이드 제공
• 등록을 시도하기 전에 문제를 포착하여 시간 절약
• 한 번의 호출로 모든 전제 조건 검증

서버는 다음을 사용합니다:

MCP SDK: 프로토콜 구현용
SAP BDC Connect SDK: SAP Business Data Cloud 작업을 위한 SDK
Delta Sharing: 보안 데이터 공유를 위한 개방형 프로토콜
ORD 프로토콜: 리소스 검색 및 메타데이터용

pytest

sap-bdc-mcp-server/
├── src/
│ └── sap_bdc_mcp/
...

SAP BDC Connect SDK는 원래 Databricks 노트북 내부에서 실행되도록 설계되어 dbutils (Databricks 유틸리티)에 대한 액세스가 필요했습니다. 이로 인해 로컬 개발이 어려웠습니다.

우리는 LocalDatabricksClient를 만들었습니다

• dbutils 없이도 작동하도록 SAP BDC SDK를 확장한 커스텀 래퍼 (wrapper)

. 이를 통해 다음이 가능해집니다:

✅ 로컬 개발 (Local development) - Databricks 노트북 없이 사용자의 로컬 머신에서 실행
✅ IDE 통합 (IDE integration) - 선호하는 개발 도구 사용 가능
✅ 쉬운 디버깅 (Easier debugging) - 표준 Python 디버깅 워크플로우 활용
✅ CI/CD 친화적 (CI/CD friendly) - 자동화된 파이프라인에서 작동
✅ Claude Desktop 통합 (Claude Desktop integration) - MCP 서버 직접 사용

LocalDatabricksClient 클래스:

dbutils 요구사항 우회

• 워크스페이스 URL 및 API 토큰을 직접 수락

.env 파일로부터 읽기

• 노트북 컨텍스트(notebook context)가 필요 없음

모드 자동 감지

• 브라운필드 (Brownfield, BDC Connect) 또는 Databricks Connect 모드를 자동으로 사용

호환성 유지

• SAP BDC SDK API와 완전히 호환됨

명확한 에러 메시지

• 설정이 누락된 경우 유용한 가이드 제공

from sap_bdc_mcp.local_client import LocalDatabricksClient
# 환경 변수로부터 초기화
client = LocalDatabricksClient.from_env()
...

BDC Connect 모드 (Brownfield) ✨

• 인증을 위해 OIDC 페더레이션 (OIDC federation) 사용
• Databricks secrets 불필요
• 더 간단한 설정
• 수신자(recipient)가 설정되어 있는 경우 자동으로 감지됨

Databricks Connect 모드

• 추가적인 secrets (api_url, tenant, token_audience) 필요
• 환경 변수를 통해 제공 가능
• 그린필드 (Greenfield) 배포용

전체 가이드를 확인하세요:

QUICKSTART.md - 5분 만에 시작하기
IMPLEMENTATION_SUCCESS.md - 기술적 심층 분석
HOW_TO_CREATE_SHARE.md - 전체 워크플로우 가이드

강조할 주요 포인트:

문제점 (The Problem): SAP BDC SDK는 dbutils를 요구하여 사용처를 Databricks 노트북으로 제한함
조사 (The Investigation): dbutils가 실제로 무엇을 제공하는지 이해하기 위해 SDK를 분석함
발견 (The Discovery): 단 2가지 용도로만 사용됨 - 워크스페이스 자격 증명(credentials) 획득 및 secrets 접근
해결책 (The Solution): 자격 증명을 직접 주입하는 LocalDatabricksClient를 생성함
결과 (The Result): 200줄 미만의 코드로 완전한 로컬 개발 지원 구현

기술적 하이라이트:

• DatabricksClient로부터 커스텀 상속 (Custom inheritance)
• dbutils를 우회하기 위해 __init__ 오버라이드 (Override)

요구사항 - _get_secret() 오버라이드 (Override)

환경 변수 (env vars)로부터 읽기 위해 - 모든 SDK 기능 유지

• SAP BDC SDK 자체에는 변경 사항 없음

┌─────────────────────────┐
│ Claude Desktop │
│ (MCP Client) │
...

서버는 다음을 사용합니다:

MCP SDK: 프로토콜 구현용
SAP BDC Connect SDK: SAP Business Data Cloud 작업을 위한 SDK
Delta Sharing: 보안 데이터 공유를 위한 개방형 프로토콜
ORD Protocol: 리소스 검색 및 메타데이터용

서버는 두 가지 통합 모드를 지원합니다:

1. 노트북 모드 (Notebook Mode) (기존)

• Databricks 노트북 내부에서 실행
• 인증을 위해 dbutils 사용 - 활성화된 노트북 세션 필요

2. 로컬 모드 (Local Mode) (신규!) ✨

• 로컬 머신에서 실행
• 인증을 위해 환경 변수 (environment variables) 사용
• 노트북 불필요

인증은 다음을 통해 처리됩니다:

• Databricks 워크스페이스 인증 정보 (URL + 토큰)
• Databricks 내 수신자 (Recipient) 설정
• SAP BDC 서비스 인증 정보 (BDC Connect 모드에서 자동 구성됨)

로컬 개발 시:

• DATABRICKS_HOST, DATABRICKS_TOKEN, DATABRICKS_RECIPIENT_NAME이 포함된 .env 파일이 존재하는지 확인하십시오.
• Databricks 토큰이 유효한지 확인하십시오.
• 워크스페이스 URL이 올바른지 확인하십시오.

노트북 환경 시:

• dbutils를 사용할 수 있는 Databricks 노트북에서 실행 중인지 확인하십시오.
• DATABRICKS_RECIPIENT_NAME 환경 변수를 설정하십시오.

로컬 개발을 위해, .env 파일에 다음 항목이 설정되어 있는지 확인하십시오:

DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
DATABRICKS_TOKEN=dapi...
DATABRICKS_RECIPIENT_NAME=your_recipient_name

SAP BDC에 등록하기 전에 Databricks에 공유 (share)가 존재해야 합니다:

• 먼저 Databricks에서 Delta share를 생성하십시오.
• 수신자에게 해당 공유 권한을 부여하십시오.
• 그런 다음 이 서버를 사용하여 SAP BDC에 등록하십시오.

상세 단계는 HOW_TO_CREATE_SHARE.md를 참조하십시오.

Databricks에서 수신자에게 공유 권한을 부여하십시오:

GRANT SELECT ON SHARE your_share_name TO RECIPIENT your_recipient_name;

• PyPI의 SAP BDC Connect SDK
• Model Context Protocol (MCP) 문서
• Delta Sharing 프로토콜
• SAP Business Data Cloud

이 MCP 서버는 있는 그대로(as-is) 제공됩니다. 이 통합 기능을 사용할 때는 SAP BDC Connect SDK 라이선스 약관을 검토해 주세요.

기여(Contributions)를 환영합니다! 다음 사항에 대한 자세한 내용은 CONTRIBUTING.md를 참조하세요:

• 개발 환경 설정

• 테스트 실행

• 풀 리퀘스트 (Pull Requests) 제출

• 코드 스타일 가이드라인

• Databricks 환경을 통한 초기 검증

• 로컬 개발 지원 (LocalDatabricksClient)

• PyPI 패키지 배포

• 포괄적인 문서화

• Node.js 환경을 위한 npm 패키지

• 추가적인 SAP BDC SDK 기능

• 향상된 에러 처리 및 로깅

• 더 많은 통합 예제 및 튜토리얼

• 비디오 튜토리얼 및 데모