adf-mcp-server

Azure Data Factory 모니터링 및 근본 원인 분석을 위한 읽기 전용 MCP(Model Context Protocol) 서버로, VS Code / Claude Code에서 사용하도록 제작되었습니다.

상태: 1단계(스켈레톤 + 상태 확인). 아직 Azure 연결은 없습니다. 이는 2단계(인증)와 3단계(ADF 도구)에서 추가됩니다.

요구 사항

• Python 3.11+

• 검사하려는 Data Factory 리소스에 대해 Reader 역할이 있는 Azure AD 앱 등록(서비스 주체) (Reader로 충분합니다. 이 서버는 종단 간 읽기 전용이므로 Contributor가 필요하지 않습니다)

Related MCP server: mcp-azure-landing-zone

로컬 설정

cd adf-mcp-server
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env

서비스 주체 만들기(일회성, az-cli 사용)

az ad sp create-for-rbac \
  --name "adf-mcp-server-reader" \
  --role "Reader" \
  --scopes "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.DataFactory/factories/<FACTORY_NAME>"

이 명령은 appId, password, tenant를 출력합니다. 이를 .env에 각각 AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID로 매핑하세요. 역할 할당 범위는 전체 구독이 아니라 특정 팩토리(또는 최대 리소스 그룹)로 지정하세요. 최소 권한 원칙이며, 이 SPN은 ADF 외부의 어떤 것에도 접근할 필요가 없습니다.

서버 실행

python -m adf_mcp.server
# or, after `pip install -e .`:
adf-mcp-server

서버는 stdio를 통해 통신합니다. 터미널에서 직접 실행하면 멈춘 것처럼 보일 수 있습니다. 이는 정상이며, MCP 클라이언트(VS Code 확장, Claude Code, mcp dev 등)가 stdin/stdout을 통해 연결되기를 기다리는 중입니다.

VS Code에서 구성

MCP 지원 확장의 서버 구성을 다음으로 지정하세요:

{
  "command": "python",
  "args": ["-m", "adf_mcp.server"],
  "cwd": "/absolute/path/to/adf-mcp-server"
}

연결되면:

1. health_check 호출 - Azure에 전혀 접촉하지 않고 {"status": "ok", ...}를 반환해야 합니다.

2. check_auth 호출 - ARM 토큰을 획득하기 위해 Azure AD에 실제 호출을 한 번 수행합니다. 성공 시 다음과 같이 표시됩니다:

   {"authenticated": true, "auth_mode": "service_principal", "token_expires_on": 1735000000}

   실패 시 스택 추적이 아닌 구조화된 설명(예: 환경 변수 누락 또는 잘못된 비밀번호)을 반환합니다. 아래 문제 해결 섹션을 참조하세요.

3. list_factories 호출 - Azure Data Factory에 실제 호출을 수행합니다. 각 팩토리의 resource_group을 반환하며, 아래의 모든 다른 도구는 이를 입력으로 필요로 합니다:

   {"factories": [{"name": "shell-prod-adf", "resource_group": "rg-shell-prod", "location": "eastus"}]}

사용 가능한 도구(3단계)

모든 도구는 읽기 전용입니다. Azure Data Factory에서 어떤 것도 생성, 수정, 트리거 또는 삭제할 수 없습니다.

에이전트를 위한 예시 RCA 흐름: list_factories → list_pipeline_runs(status="Failed") → get_failed_activity_details(run_id=...)로 오류 분석을 직접 수행합니다.

사용 가능한 도구(4단계 추가)

실패한 파이프라인에 대한 전체 RCA 흐름: list_pipeline_runs(status="Failed") → get_failed_activity_details(run_id=...)로 오류를 확인하고, 별도로 get_trigger_status(trigger_name=...)로 "트리거가 아예 실행되지 않았는지"를 배제합니다.

테스트 실행

pip install -e ".[dev]" pytest-asyncio
pytest -v

프로젝트 구조

src/adf_mcp/ 참조 - server.py(MCP 전송), config.py(설정), logging_config.py(구조화된 로깅). 도메인 로직과 Azure 연결은 3단계부터 src/adf_mcp/domain/ 아래에 추가됩니다.

문제 해결

• 클라이언트에 "서버 연결 끊김"이 즉시 표시됨: 먼저 python -m adf_mcp.server가 자체적으로 정상 실행되는지 확인하세요. 시작 예외가 발생하면 클라이언트가 연결되기 전에 프로세스가 종료됩니다.

• 클라이언트가 응답을 구문 분석할 수 없거나 깨진 출력: MCP 프로토콜 자체 외에 다른 것이 stdout에 기록되었습니다(예: 잘못된 print()). 이 프로젝트의 모든 로깅은 정확히 이 이유로 stderr로 전송됩니다.

• check_auth가 "필수 서비스 주체 설정 누락" 반환: .env에서 AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET 중 하나가 비어 있습니다. 이 세 가지는 ADF_MCP_ 접두사를 사용하지 않습니다.

• check_auth가 "Azure 인증 실패" 반환: 일반적으로 만료/회전된 클라이언트 비밀번호, 비활성화된 앱 등록 또는 테넌트 ID 오타입니다. az ad sp show --id <AZURE_CLIENT_ID>로 다시 확인하세요.

• ClientAuthenticationError: AADSTS7000215: 잘못된 클라이언트 비밀번호입니다. 앱 등록에서 다시 생성하고 .env를 업데이트하세요.

• 도구가 {"error": "AZURE_SUBSCRIPTION_ID is not set..."} 반환: .env에 AZURE_SUBSCRIPTION_ID를 추가하세요. 모든 ADF 도구에 필요합니다(check_auth는 테넌트/클라이언트/비밀번호만 필요).

• 도구가 {"error": "Azure API error (403): ..."} 반환: 서비스 주체가 해당 팩토리/리소스 그룹에 대한 Reader 액세스 권한이 없습니다. 설정 시 az ad sp create-for-rbac --role Reader --scopes ... 할당을 다시 확인하세요.

• 도구가 {"error": "Azure API error (404): ..."} 반환: resource_group/factory_name/pipeline_name 철자를 확인하세요. 대소문자를 구분하며 list_factories/list_pipelines가 반환한 값과 정확히 일치해야 합니다.

• get_failed_activity_details가 빈 목록을 반환하지만 파이프라인이 실패한 것으로 알고 있음: 실패가 단일 활동이 아닌 파이프라인 수준(예: 잘못된 매개변수)일 수 있습니다. 대신 get_pipeline_run을 통해 부모 실행의 자체 message를 확인하세요.

• 파이프라인이 "그냥 실행되지 않았고" 실패한 실행이 전혀 없음: 해당 트리거에 대해 get_trigger_status를 확인하세요. runtime_state: "Stopped"는 트리거가 비활성화되어 실행되지 않았음을 의미하며, 실행이 생성되지 않았으므로 실패한 실행으로 표시되지 않습니다.