adf-mcp-server

Azure Data Factory 모니터링 및 근본 원인 분석을 위한 읽기 전용 MCP(Model Context Protocol) 서버로, VS Code / Claude Code에서 사용할 수 있도록 만들어졌습니다.

상태: Step 1 (스켈레톤 + 헬스 체크). 아직 Azure 연결은 없습니다 - 이 부분은 Step 2 (인증)와 Step 3 (ADF 도구)에서 추가됩니다.

요구 사항

• Python 3.11+

Related MCP server: azure-adf-mcp

로컬 설정

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

.env에는 현재 서버 설정 블록(ADF_MCP_*)만 있으면 됩니다. AZURE_* 줄은 Step 2를 위한 자리표시자이므로 지금은 주석 처리해 두세요.

서버 실행

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

연결이 완료되면 health_check 도구를 호출합니다. Azure에 전혀 접촉하지 않고 {"status": "ok", ...}를 반환해야 합니다.

테스트 실행

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

프로젝트 구조

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

문제 해결

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

• 클라이언트가 응답을 파싱하지 못하거나 출력이 깨짐: MCP 프로토콜 자체가 아닌 다른 무언가가 stdout에 출력된 것입니다. (예: 잘못 쓰인 print()). 이 프로젝트의 모든 로깅이 바로 이 이유로 stderr로 출력됩니다.