Apache Doris

Apache Doris MCP Server

English | 简体中文

Apache Doris MCP Server는 MCP 2026-07-28을 통해 MCP 호스트와 AI 에이전트에게 읽기 전용 Apache Doris 기능을 제공합니다. 버전 1.0은 크고 평평한 도구 표면을 8개의 안정적인 도메인과 55개의 점진적으로 공개되는 하위 기능으로 대체하면서, 런타임 가용성, 인증, 입력 스키마, 출력 스키마, 실패 동작을 명시적으로 유지합니다.

릴리스 상태

패키지 버전은 1.0.0입니다. master에서의 MCP 2026-07-28 프로토콜 호환성은 Streamable HTTP 및 stdio에서 GA(Generally Available) 상태입니다. 이 GA 선언은 프로토콜 호환성에 국한되며, Python 패키지 분류자는 여전히 Beta로 유지되고 문서화된 배포 제한은 계속 적용됩니다.

업그레이드 전에 1.0 릴리스 노트, 1.0 마이그레이션 가이드, 그리고 생성된 8-도메인/55-하위 레지스트리를 읽어보세요. 자세한 릴리스 기록은 Issue #189에 있습니다.

아키텍처 개요

MCP Host
  -> stdio or Streamable HTTP
  -> transport security and authentication
  -> MCP protocol validation and authorization
  -> stable domain discovery
  -> route-aware Doris capability detection
  -> exact child dispatch and read-only runtime
  -> request-specific Doris route and RBAC
  -> bounded, schema-validated result

기본 hierarchical 모드는 다음 도메인을 노출합니다:

도메인	하위 기능	담당
doris_catalog	5	카탈로그, 데이터베이스, 테이블, 테이블 컨텍스트, 크기
doris_query	7	쿼리, explain, 프로파일, 진단, 느린 쿼리, 명시적 ADBC
doris_cluster	11	노드, 태스크, 메트릭, 메모리, 캐시, 컴팩션, 워크로드
doris_pipeline	5	수집, 구체화된 뷰, 신선도, 의존성
doris_search	4	텍스트/벡터/하이브리드 검색, 분석기, 인덱스, 진단
doris_governance	8	품질, 스토리지, 계보, 감사, UDF, 인증 매핑
doris_lakehouse	3	외부 카탈로그, 레이크하우스 테이블, Variant
doris_semantic	12	선택적 Apache Ossie 그라운딩 및 MetricFlow 소비

{}으로 도메인을 호출하여 인증된 하위 기능과 정확한 스키마를 확인하세요. child_tool, arguments 및 반환된 manifest_version과 함께 동일한 도메인을 다시 호출하세요. 점진적 공개를 사용할 수 없는 호스트는 시작 전에 MCP_TOOL_EXPOSURE_MODE=flat을 설정할 수 있습니다. 이렇게 하면 동일한 55개 하위 기능이 충돌 없는 공식 이름으로 노출되며, 1.0 이전 별칭은 복원되지 않습니다.

아키텍처, 요청 수명 주기, 도구 도메인을 참조하세요.

빠른 시작

요구 사항:

• Python 3.12 이상;
• Apache Doris 2.0.0 이상;
• Doris FE MySQL 엔드포인트에 대한 네트워크 접근, 일반적으로 포트 9030.

고정 릴리스를 설치합니다:

pip install doris-mcp-server==1.0.0

doris-mcp-server은 서버를 시작합니다. doris-mcp-client은 별도 클라이언트이며, 두 명령은 서로 바꿔 쓸 수 없습니다.

Doris 경로를 구성합니다:

export DORIS_HOST=127.0.0.1
export DORIS_PORT=9030
export DORIS_USER=mcp_reader
export DORIS_PASSWORD='replace-me'
export DORIS_DATABASE=information_schema

루프백에서 Streamable HTTP를 시작합니다:

doris-mcp-server \
  --transport http \
  --host 127.0.0.1 \
  --port 3000

엔드포인트:

• MCP: POST http://127.0.0.1:3000/mcp
• 레거시 MCP(옵트인): POST http://127.0.0.1:3000/mcp/legacy
• 활성 상태 확인(liveness): GET http://127.0.0.1:3000/live
• Doris 기반 준비 상태 확인(readiness): GET http://127.0.0.1:3000/ready

MCP 2025-06-18을 사용하는 Dify 1.16.1을 포함하여 핸드셰이크 시대의 Streamable HTTP로 제한된 호스트는 ENABLE_LEGACY_HTTP_ADAPTER=true을 설정하고 /mcp/legacy에 연결해야 합니다. 어댑터는 프로토콜 경계만 변경합니다. 동일한 1.0 도구, 인증, 기능 게이트, 읽기 전용 실행을 유지합니다.

또는 로컬 호스트용 stdio를 실행합니다:

doris-mcp-server --transport stdio

전체 빠른 시작 및 호스트 통합 가이드를 참조하세요.

보안 경계

• 내장 1.0 카탈로그는 읽기 전용입니다. doris_admin은 예약되어 있으며 등록되지 않습니다.
• 상호 검증된 구성 경계에서 정적 토큰, JWT, 외부 OAuth/OIDC, Doris 기반 OAuth를 지원합니다.
• 도메인 발견 및 하위 기능 실행은 정확한 인증 식별자를 사용합니다.
• Doris RBAC는 표시되는 객체와 데이터에 대한 최종 권한입니다.
• SQL 형태, 식별자, 매개변수, 시간 초과, 행, 바이트, 결과 스키마는 데이터가 서버를 떠나기 전에 제한됩니다.
• 비밀 및 백엔드 오류는 공개 결과와 로그에서 삭제됩니다.
• 명시적인 위험한 개발 오버라이드가 활성화되지 않는 한, 비루프백 HTTP에는 인증이 필요합니다.

보안 및 권한 모델 및 Doris 세분화 액세스 가이드를 읽어보세요.

안정성 경계

서버는 결정적 매니페스트와 오류, 서명된 만료 커서, 경로 인식 기능 스냅샷, 제한된 오래된 폴백, 요청별 연결 라우팅, 다중 FE 장애 조치, 활성/준비 상태 분리, 출력 스키마 검증, 정화된 트레이스 전파를 사용합니다. 지원되지 않거나 잘못 구성된 기능은 callable=false으로 계속 발견 가능하며, 호출 시 안전하게 실패(fail closed)합니다.

현재 제한 사항으로는 프로세스 로컬 Doris 기반 OAuth, 기본적으로 비활성화되고 토큰 바인딩 경로에서 fail-closed인 명시적 전용 ADBC, 선택적 읽기 전용 Ossie 그라운딩, SQL이 제한된 MCP 쿼리 런타임을 통해 실행되어야 하는 선택적 MetricFlow 컴파일러 사이드카, 최선 노력(best-effort) 네이티브 계보 전달이 있습니다. 안정성 및 제한 사항을 참조하세요.

문서

루트 README는 의도적으로 진입점 역할을 합니다. 이중 언어 문서 시스템은 다음에서 색인됩니다:

• 영어 문서
• 简体中文文档

주요 가이드:

• 아키텍처
• 요청 및 데이터 흐름
• 도구 도메인
• 기능 가용성
• Doris 버전 기능 매트릭스
• MetricFlow 통합
• MCP 2026-07-28 계약
• 보안 모델
• 배포
• 안정성 및 제한 사항
• 문제 해결
• 구성 참조
• 호스트 통합
• 사용자 정의 도구 제공자
• 기여

개발

git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server
uv sync --group dev
uv run pytest

생성된 산출물은 동기화된 상태를 유지해야 합니다:

uv run python generate_tool_catalog.py --check
uv lock --check

기여 및 검증을 참조하세요.

라이선스

Apache License 2.0. LICENSE.txt 및 NOTICE를 참조하세요.