Apache Doris

공식

Apache Doris를 위한 MCP 서버로, MPP 기반의 실시간 데이터 웨어하우스입니다.

GitHub

316

Apache Doris MCP(으)로 무엇을 할 수 있나요?

SQL 쿼리 실행 — AI가 exec_query를 사용하여 Doris 데이터베이스에 대해 SQL 문을 실행하도록 요청하며, 선택적으로 카탈로그, 데이터베이스 또는 행 제한을 지정할 수 있습니다.
데이터베이스 메타데이터 탐색 — get_catalog_list, get_db_list, get_db_table_list로 카탈로그, 데이터베이스 및 테이블을 나열하고, get_table_schema, get_table_indexes, get_table_comment, get_table_column_comments를 통해 스키마, 인덱스 및 주석을 검사합니다.
쿼리 성능 분석 — get_sql_explain과 get_sql_profile로 실행 계획 및 프로필을 검색하여 느리거나 복잡한 쿼리를 진단합니다.
클러스터 상태 모니터링 — get_realtime_memory_stats, get_historical_memory_stats, get_monitoring_metrics_info, get_monitoring_metrics_data를 사용하여 실시간 및 과거 메모리 통계, 모니터링 지표 정의, 실제 노드 지표를 가져옵니다.
감사 및 접근 패턴 검사 — get_recent_audit_logs로 최근 감사 로그를 검토하고, analyze_data_access_patterns를 통해 사용자 접근 행동을 분석합니다.
Arrow Flight SQL을 통한 고성능 쿼리 실행 — exec_adbc_query로 대규모 결과 쿼리를 실행하고, get_adbc_connection_info로 ADBC 연결 상태를 확인합니다.

문서

Doris MCP 서버

Doris MCP (Model Context Protocol) 서버는 Python과 FastAPI로 구축된 백엔드 서비스입니다. MCP를 구현하여 클라이언트가 정의된 "도구"를 통해 상호 작용할 수 있도록 합니다. 주로 Apache Doris 데이터베이스에 연결하도록 설계되었으며, 자연어 쿼리를 SQL로 변환(NL2SQL), 쿼리 실행, 메타데이터 관리 및 분석과 같은 작업에 대규모 언어 모델(LLM)을 활용할 수 있습니다.

🚀 v0.6.0의 새로운 기능

🔐 엔터프라이즈 인증 시스템: 혁신적인 토큰 바인딩 데이터베이스 구성과 포괄적인 토큰, JWT, OAuth 인증 지원을 통해 세분화된 제어 스위치와 엔터프라이즈급 보안 기본값으로 안전한 멀티 테넌트 액세스를 가능하게 합니다.
⚡ 즉각적인 데이터베이스 유효성 검사: 연결 시점에 실시간 데이터베이스 구성 유효성 검사를 수행하여 쿼리 시간 차단을 없애고 잘못된 구성에 대한 즉각적인 피드백을 제공합니다. 이를 통해 후기 단계 연결 실패를 100% 제거합니다.
🔄 핫 리로드 구성 관리: 무중단 구성 업데이트를 지능형 tokens.json 핫 리로딩, 자동 토큰 재검증, 롤백 메커니즘을 통한 포괄적인 오류 처리로 실현합니다.
🏗️ 고급 연결 아키텍처: 세션 캐싱 및 연결 풀 최적화로 연결 오버헤드 60% 감소, 지능형 풀 재생성, 자동 리소스 관리를 제공합니다.
🌐 멀티 워커 확장성: 진정한 수평 확장을 상태 비저장 멀티 워커 아키텍처, 효율적인 부하 분산, 엔터프라이즈급 동시 처리 기능으로 달성합니다.
🔒 강화된 보안 프레임워크: 포괄적인 액세스 제어 및 SQL 보안 유효성 검사를 즉각적인 유효성 검사, 역할 기반 권한, 향상된 주입 탐지 패턴으로 제공합니다.
🛠️ 통합 구성 시스템: 간소화된 구성 관리를 적절한 명령줄 우선 순위, Docker 호환성 개선, 크로스 플랫폼 배포 지원으로 실현합니다.
📊 토큰 관리 대시보드: 완전한 토큰 수명 주기 관리를 생성, 해지, 통계, 엔터프라이즈 토큰 거버넌스를 위한 포괄적인 감사 추적과 함께 제공합니다.
🌐 웹 기반 관리 인터페이스: 안전한 로컬호스트 전용 토큰 관리를 직관적인 대시보드, 데이터베이스 바인딩 구성, 실시간 운영, 엔터프라이즈급 액세스 제어로 제공합니다.

🚀 주요 이정표: v0.6.0은 플랫폼을 프로덕션 준비가 완료된 엔터프라이즈 인증 및 데이터베이스 관리 시스템으로 확립하며, 무중단 운영(핫 리로드 + 즉각적인 유효성 검사 + 멀티 워커 확장), 고급 보안 제어, 포괄적인 토큰 바인딩 데이터베이스 구성을 통해 엔터프라이즈 데이터 플랫폼 기능의 근본적인 발전을 나타냅니다.

v0.5.1에서도 포함된 사항

🔥 중요한 at_eof 연결 수정: 지능형 상태 모니터링 및 자가 치유 복구를 통한 연결 풀 오류 완전 제거
🔧 엔터프라이즈 로깅 시스템: 자동 정리 및 밀리초 정밀도 타임스탬프를 갖춘 레벨 기반 파일 분리
📊 고급 데이터 분석 제품군: 품질 분석, 계보 추적, 성능 모니터링을 포함한 7가지 엔터프라이즈급 데이터 거버넌스 도구
🏃‍♂️ 고성능 ADBC 통합: 대규모 데이터 세트에 대해 3~10배 성능 향상을 제공하는 Apache Arrow Flight SQL 지원
⚙️ 향상된 구성 관리: 지능형 매개변수 유효성 검사를 갖춘 완전한 ADBC 구성 시스템

핵심 기능

MCP 프로토콜 구현: 도구 호출, 리소스 관리, 프롬프트 상호 작용을 지원하는 표준 MCP 인터페이스를 제공합니다.
스트리밍 가능한 HTTP 통신: 최적의 성능과 안정성을 위해 요청/응답 및 스트리밍 통신을 모두 지원하는 통합 HTTP 엔드포인트입니다.
Stdio 통신: Cursor와 같은 MCP 클라이언트와 직접 통합하기 위한 표준 입출력 모드입니다.
엔터프라이즈급 아키텍처: 포괄적인 기능을 갖춘 모듈식 설계:
- 도구 관리자: 통합 인터페이스를 통한 중앙 집중식 도구 등록 및 라우팅(doris_mcp_server/tools/tools_manager.py)
- 향상된 모니터링 도구 모듈: 고급 메모리 추적, 메트릭 수집, 모듈식 확장 가능 설계를 통한 유연한 BE 노드 검색
- 쿼리 정보 도구: 구성 가능한 콘텐츠 잘라내기, LLM 첨부 파일용 파일 내보내기, 고급 쿼리 분석을 통한 향상된 SQL explain 및 프로파일링
- 리소스 관리자: 리소스 관리 및 메타데이터 노출(doris_mcp_server/tools/resources_manager.py)
- 프롬프트 관리자: 데이터 분석을 위한 지능형 프롬프트 템플릿(doris_mcp_server/tools/prompts_manager.py)
고급 데이터베이스 기능:
- 쿼리 실행: 고급 캐싱 및 최적화, 향상된 연결 안정성 및 자동 재시도 메커니즘을 통한 고성능 SQL 실행(doris_mcp_server/utils/query_executor.py)
- 보안 관리: 구성 가능한 차단 키워드, SQL 주입 보호, 데이터 마스킹, 통합 보안 구성 관리를 통한 포괄적인 SQL 보안 유효성 검사(doris_mcp_server/utils/security.py)
- 메타데이터 추출: 카탈로그 페더레이션 지원을 통한 포괄적인 데이터베이스 메타데이터(doris_mcp_server/utils/schema_extractor.py)
- 성능 분석: 고급 컬럼 분석, 성능 모니터링, 데이터 분석 도구(doris_mcp_server/utils/analysis_tools.py)
카탈로그 페더레이션 지원: 멀티 카탈로그 환경(내부 Doris 테이블 및 Hive, MySQL 등과 같은 외부 데이터 소스)에 대한 완전한 지원
엔터프라이즈 보안: 인증, 권한 부여, SQL 주입 보호, 환경 변수 구성 지원을 통한 데이터 마스킹 기능을 갖춘 포괄적인 보안 프레임워크
웹 기반 토큰 관리: 데이터베이스 바인딩, 실시간 통계, 엔터프라이즈급 액세스 제어를 통한 완전한 토큰 수명 주기 관리를 위한 안전한 로컬호스트 전용 인터페이스(doris_mcp_server/auth/token_handlers.py)
통합 구성 프레임워크: 포괄적인 유효성 검사, 표준화된 매개변수 명명, information_schema로의 자동 폴백을 통한 스마트 기본 데이터베이스 처리를 갖춘 config.py을 통한 중앙 집중식 구성 관리

시스템 요구 사항

Python: 3.12 이상
데이터베이스: Apache Doris 연결 세부 정보 (호스트, 포트, 사용자, 비밀번호, 데이터베이스)

🚀 빠른 시작

PyPI에서 설치

# Install the latest version
pip install doris-mcp-server

# Install specific version
pip install doris-mcp-server==0.6.0

💡 명령 호환성: 설치 후, 하위 호환성을 위해 doris-mcp-server 명령을 모두 사용할 수 있습니다. 두 명령을 서로 바꿔 사용할 수 있습니다.

스트리밍 가능한 HTTP 모드 시작 (웹 서비스)

최적의 성능과 안정성을 제공하는 기본 통신 모드:

# Full configuration with database connection
doris-mcp-server \
    --transport http \
    --host 0.0.0.0 \
    --port 3000 \
    --db-host 127.0.0.1 \
    --db-port 9030 \
    --db-user root \
    --db-password your_password

Stdio 모드 시작 (Cursor 및 기타 MCP 클라이언트용)

MCP 클라이언트와 직접 통합하기 위한 표준 입출력 모드:

# For direct integration with MCP clients like Cursor
doris-mcp-server --transport stdio

🌐 토큰 관리 인터페이스 (v0.6.0의 새로운 기능)

엔터프라이즈급 토큰 관리를 위한 웹 기반 토큰 관리 대시보드에 액세스하세요:

보안 액세스 요구 사항

로컬호스트 액세스 전용: 최대 보안을 위해 인터페이스가 127.0.0.1 및 ::1로 제한됩니다.
관리자 인증: 액세스하려면 TOKEN_MANAGEMENT_ADMIN_TOKEN이(가) 필요합니다.

구성 전제 조건:

# Required environment variables
ENABLE_HTTP_TOKEN_MANAGEMENT=true
ENABLE_TOKEN_AUTH=true
TOKEN_MANAGEMENT_ADMIN_TOKEN=your_secure_admin_token
TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

인터페이스 액세스

# Access the token management interface
http://localhost:3000/token/management?admin_token=your_secure_admin_token

사용 가능한 작업

📊 토큰 통계: 활성, 만료 및 총 토큰에 대한 실시간 개요
➕ 토큰 생성:
- 기본 정보 (ID, 설명, 만료)
- 데이터베이스 바인딩 (호스트, 포트, 사용자, 비밀번호, 데이터베이스)
- 사용자 지정 토큰 값 또는 자동 생성된 보안 토큰
📋 토큰 관리:
- 데이터베이스 바인딩 상태가 포함된 모든 토큰 나열
- 원클릭 토큰 해지
- 만료된 토큰 자동 정리
🔒 엔터프라이즈 보안:
- 모든 작업에 관리자 인증 필요
- 실시간 IP 유효성 검사
- 완전한 감사 로깅
- tokens.json에 자동 지속성

🔐 보안 참고: 인터페이스는 로컬호스트 관리 전용으로 설계되었습니다. 원격으로 액세스할 수 없으므로 토큰 관리 작업에 대한 최대 보안을 보장합니다.

설치 확인

# Check installation
doris-mcp-server --help

# Test HTTP mode (in another terminal)
curl http://localhost:3000/health

환경 변수 (선택 사항)

명령줄 인수 대신 환경 변수를 사용할 수 있습니다:

# Basic Database Configuration
export DORIS_HOST="127.0.0.1"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

# Token Management Interface (Security-Critical)
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export ENABLE_TOKEN_AUTH=true
export TOKEN_MANAGEMENT_ADMIN_TOKEN="your_secure_admin_token"
export TOKEN_MANAGEMENT_ALLOWED_IPS="127.0.0.1,::1"

# Then start with simplified command
doris-mcp-server --transport http --host 0.0.0.0 --port 3000

명령줄 인수

doris-mcp-server 명령은 다음 인수를 지원합니다:

인수	설명	기본값	필수
`--transport`	전송 모드: `http` 또는 `stdio`	`http`	아니요
`--host`	HTTP 서버 호스트 (HTTP 모드 전용)	`0.0.0.0`	아니요
`--port`	HTTP 서버 포트 (HTTP 모드 전용)	`3000`	아니요
`--db-host`	Doris 데이터베이스 호스트	`localhost`	아니요
`--db-port`	Doris 데이터베이스 포트	`9030`	아니요
`--db-user`	Doris 데이터베이스 사용자 이름	`root`	아니요
`--db-password`	Doris 데이터베이스 비밀번호	-	예 (환경 변수에 없는 경우)

개발 설정

소스에서 빌드하려는 개발자를 위한 정보:

1. 리포지토리 복제

# Replace with the actual repository URL if different
git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server

2. 종속성 설치

pip install -r requirements.txt

3. 환경 변수 구성

.env.example 파일을 .env에 복사하고 환경에 맞게 설정을 수정합니다:

cp .env.example .env

주요 환경 변수:

데이터베이스 연결:
- DORIS_HOST: 데이터베이스 호스트명 (기본값: localhost)
- DORIS_PORT: 데이터베이스 포트 (기본값: 9030)
- DORIS_USER: 데이터베이스 사용자명 (기본값: root)
- DORIS_PASSWORD: 데이터베이스 비밀번호
- DORIS_DATABASE: 기본 데이터베이스 이름 (기본값: information_schema)
- DORIS_MIN_CONNECTIONS: 최소 연결 풀 크기 (기본값: 5)
- DORIS_MAX_CONNECTIONS: 최대 연결 풀 크기 (기본값: 20)
- DORIS_BE_HOSTS: 모니터링할 BE 노드 (쉼표로 구분, 선택 사항 - 비어 있으면 SHOW BACKENDS를 통한 자동 검색)
- DORIS_BE_WEBSERVER_PORT: 모니터링 도구용 BE 웹서버 포트 (기본값: 8040)
- FE_ARROW_FLIGHT_SQL_PORT: ADBC용 프론트엔드 Arrow Flight SQL 포트 (v0.5.0에 새로 추가됨)
- BE_ARROW_FLIGHT_SQL_PORT: ADBC용 백엔드 Arrow Flight SQL 포트 (v0.5.0에 새로 추가됨)
인증 구성 (v0.6.0에서 향상됨):
- ENABLE_TOKEN_AUTH: 토큰 기반 인증 활성화 (기본값: false)
- ENABLE_JWT_AUTH: JWT 인증 활성화 (기본값: false)
- ENABLE_OAUTH_AUTH: OAuth 인증 활성화 (기본값: false)
- ENABLE_DORIS_OAUTH_AUTH: Doris 기반 OAuth 인증 활성화 (기본값: false)
- DORIS_OAUTH_BASE_URL: Doris 기반 OAuth 검색 및 토큰 엔드포인트에서 사용하는 공개 기본 URL
- TOKEN_FILE_PATH: 토큰 관리를 위한 tokens.json 파일 경로 (기본값: tokens.json)
- TOKEN_HOT_RELOAD: 토큰 구성의 핫 리로딩 활성화 (기본값: true)
- DEFAULT_ADMIN_TOKEN: 기본 관리자 토큰 (환경 변수를 통해 사용자 정의 가능)
- DEFAULT_ANALYST_TOKEN: 기본 분석가 토큰 (환경 변수를 통해 사용자 정의 가능)
- DEFAULT_READONLY_TOKEN: 기본 읽기 전용 토큰 (환경 변수를 통해 사용자 정의 가능)
레거시 보안 구성:
- AUTH_TYPE: 레거시 인증 유형 (token/basic/oauth, 사용 중단됨 - 개별 스위치 사용)
- TOKEN_SECRET: 레거시 토큰 비밀 키 (대신 토큰 기반 인증 사용)
- ENABLE_SECURITY_CHECK: SQL 보안 검증 활성화/비활성화 (기본값: true)
- BLOCKED_KEYWORDS: 차단된 SQL 키워드의 쉼표로 구분된 목록
- ENABLE_MASKING: 데이터 마스킹 활성화 (기본값: true)
- MAX_RESULT_ROWS: 최대 결과 행 수 (기본값: 10000)
ADBC 구성 (v0.5.0에 새로 추가됨):
- ADBC_DEFAULT_MAX_ROWS: ADBC 쿼리의 기본 최대 행 수 (기본값: 100000)
- ADBC_DEFAULT_TIMEOUT: ADBC 쿼리 기본 제한 시간(초) (기본값: 60)
- ADBC_DEFAULT_RETURN_FORMAT: 기본 반환 형식 - arrow/pandas/dict (기본값: arrow)
- ADBC_CONNECTION_TIMEOUT: ADBC 연결 제한 시간(초) (기본값: 30)
- ADBC_ENABLED: ADBC 도구 활성화/비활성화 (기본값: true)
성능 구성:
- ENABLE_QUERY_CACHE: 쿼리 캐싱 활성화 (기본값: true)
- CACHE_TTL: 캐시 TTL(초) (기본값: 300)
- MAX_CONCURRENT_QUERIES: 최대 동시 쿼리 수 (기본값: 50)
- MAX_RESPONSE_CONTENT_SIZE: LLM 호환성을 위한 최대 응답 콘텐츠 크기 (기본값: 4096, v0.4.0에 새로 추가됨)
향상된 로깅 구성 (v0.5.0에서 개선됨):
- LOG_LEVEL: 로그 레벨 (DEBUG/INFO/WARNING/ERROR, 기본값: INFO)
- LOG_FILE_PATH: 로그 파일 경로 (레벨별로 자동 구성됨)
- ENABLE_AUDIT: 감사 로깅 활성화 (기본값: true)
- ENABLE_LOG_CLEANUP: 자동 로그 정리 활성화 (기본값: true, v0.5.0에서 향상됨)
- LOG_MAX_AGE_DAYS: 로그 파일 최대 보관 기간(일) (기본값: 30, v0.5.0에서 향상됨)
- LOG_CLEANUP_INTERVAL_HOURS: 로그 정리 확인 간격(시간) (기본값: 24, v0.5.0에서 향상됨)
- v0.5.0의 새로운 기능:
  - 레벨 기반 파일 분리: debug.log, info.log, warning.log, error.log, critical.log로 자동 분리
  - 타임스탬프 형식: 밀리초 정밀도와 적절한 정렬로 향상된 형식
  - 백그라운드 정리 스케줄러: 구성 가능한 보존 정책으로 자동 정리
  - 감사 추적: 별도의 보존 관리가 포함된 전용 audit.log
  - 성능 최적화: 순환 지원이 포함된 최소 오버헤드 비동기 로깅

사용 가능한 MCP 도구

다음 표는 MCP 클라이언트를 통해 호출할 수 있는 주요 도구 목록입니다.

도구 이름	설명	매개변수
`exec_query`	SQL 쿼리를 실행하고 결과를 반환합니다.	`sql` (문자열, 필수), `db_name` (문자열, 선택), `catalog_name` (문자열, 선택), `max_rows` (정수, 선택), `timeout` (정수, 선택)
`get_table_schema`	자세한 테이블 구조 정보를 가져옵니다.	`table_name` (문자열, 필수), `db_name` (문자열, 선택), `catalog_name` (문자열, 선택)
`get_db_table_list`	지정된 데이터베이스의 모든 테이블 이름 목록을 가져옵니다.	`db_name` (문자열, 선택), `catalog_name` (문자열, 선택)
`get_db_list`	모든 데이터베이스 이름 목록을 가져옵니다.	`catalog_name` (문자열, 선택)
`get_table_comment`	테이블 주석 정보를 가져옵니다.	`table_name` (문자열, 필수), `db_name` (문자열, 선택), `catalog_name` (문자열, 선택)
`get_table_column_comments`	테이블의 모든 열에 대한 주석 정보를 가져옵니다.	`table_name` (문자열, 필수), `db_name` (문자열, 선택), `catalog_name` (문자열, 선택)
`get_table_indexes`	지정된 테이블의 인덱스 정보를 가져옵니다.	`table_name` (문자열, 필수), `db_name` (문자열, 선택), `catalog_name` (문자열, 선택)
`get_recent_audit_logs`	최근 기간의 감사 로그 레코드를 가져옵니다.	`days` (정수, 선택), `limit` (정수, 선택)
`get_catalog_list`	모든 카탈로그 이름 목록을 가져옵니다.	`random_string` (문자열, 필수)
`get_sql_explain`	구성 가능한 콘텐츠 잘림 및 LLM 분석을 위한 파일 내보내기 기능이 있는 SQL 실행 계획을 가져옵니다.	`sql` (문자열, 필수), `verbose` (부울, 선택), `db_name` (문자열, 선택), `catalog_name` (문자열, 선택)
`get_sql_profile`	LLM 최적화 워크플로우를 위한 콘텐츠 관리 및 파일 내보내기 기능이 있는 SQL 실행 프로필을 가져옵니다.	`sql` (문자열, 필수), `db_name` (문자열, 선택), `catalog_name` (문자열, 선택), `timeout` (정수, 선택)
`get_table_data_size`	FE HTTP API를 통해 테이블 데이터 크기 정보를 가져옵니다.	`db_name` (문자열, 선택), `table_name` (문자열, 선택), `single_replica` (부울, 선택)
`get_monitoring_metrics_info`	Doris 모니터링 메트릭 정의 및 설명을 가져옵니다.	`role` (문자열, 선택), `monitor_type` (문자열, 선택), `priority` (문자열, 선택)
`get_monitoring_metrics_data`	유연한 BE 검색 기능으로 노드에서 실제 Doris 모니터링 메트릭 데이터를 가져옵니다.	`role` (문자열, 선택), `monitor_type` (문자열, 선택), `priority` (문자열, 선택)
`get_realtime_memory_stats`	자동/수동 BE 검색 기능이 있는 BE 메모리 트래커를 통해 실시간 메모리 통계를 가져옵니다.	`tracker_type` (문자열, 선택), `include_details` (부울, 선택)
`get_historical_memory_stats`	유연한 BE 구성이 가능한 BE Bvar 인터페이스를 통해 과거 메모리 통계를 가져옵니다.	`tracker_names` (배열, 선택), `time_range` (문자열, 선택)
`analyze_data_quality`	완전성 및 분포 분석을 결합한 포괄적인 데이터 품질 분석입니다.	`table_name` (문자열, 필수), `analysis_scope` (문자열, 선택), `sample_size` (정수, 선택), `business_rules` (배열, 선택)
`trace_column_lineage`	SQL 분석 및 종속성 매핑을 통한 엔드투엔드 열 계보 추적입니다.	`target_columns` (배열, 필수), `analysis_depth` (정수, 선택), `include_transformations` (부울, 선택)
`monitor_data_freshness`	구성 가능한 최신성 임계값을 사용한 실시간 데이터 부실 모니터링입니다.	`table_names` (배열, 선택), `freshness_threshold_hours` (정수, 선택), `include_update_patterns` (부울, 선택)
`analyze_data_access_patterns`	액세스 패턴 모니터링을 통한 사용자 행동 분석 및 보안 이상 탐지입니다.	`days` (정수, 선택), `include_system_users` (부울, 선택), `min_query_threshold` (정수, 선택)
`analyze_data_flow_dependencies`	테이블 및 뷰 간의 데이터 흐름 영향 분석 및 종속성 매핑입니다.	`target_table` (문자열, 선택), `analysis_depth` (정수, 선택), `include_views` (부울, 선택)
`analyze_slow_queries_topn`	상위 N개 느린 쿼리 분석 및 패턴을 통한 성능 병목 현상 식별입니다.	`days` (정수, 선택), `top_n` (정수, 선택), `min_execution_time_ms` (정수, 선택), `include_patterns` (부울, 선택)
`analyze_resource_growth_curves`	리소스 증가 분석 및 추세 예측을 통한 용량 계획입니다.	`days` (정수, 선택), `resource_types` (배열, 선택), `include_predictions` (부울, 선택)
`exec_adbc_query`	ADBC(Arrow Flight SQL) 프로토콜을 사용한 고성능 SQL 실행입니다.	`sql` (문자열, 필수), `max_rows` (정수, 선택), `timeout` (정수, 선택), `return_format` (문자열, 선택)
`get_adbc_connection_info`	Arrow Flight SQL을 위한 ADBC 연결 진단 및 상태 모니터링입니다.	매개변수 필요 없음

참고: 모든 메타데이터 도구는 멀티 카탈로그 환경을 위한 카탈로그 페더레이션을 지원합니다. 향상된 모니터링 도구는 포괄적인 메모리 추적 및 메트릭 수집 기능을 제공합니다. v0.5.0의 새로운 기능: 엔터프라이즈 데이터 거버넌스를 위한 7가지 고급 분석 도구와 대규모 데이터 세트에 대해 3~10배의 성능 향상을 제공하는 고성능 데이터 전송용 ADBC 도구 2개.

Doris 기반 OAuth 참고: 위 표는 전역 서버 기능을 설명합니다. Doris 기반 OAuth는 작업 표면에 구성 게이트를 사용합니다. MCP 리소스는 리소스 메타데이터 캐싱이 비활성화된 상태로 사용할 수 있습니다. 검토된 메타데이터 도구는 DORIS_OAUTH_DB_TOOLS_ENABLED=true일 때 호출 가능하며, exec_query 및 get_sql_explain은 해당 Doris OAuth 쿼리/설명 게이트가 활성화된 경우 호출 가능합니다. 이러한 MySQL 채널 작업은 로그인된 Doris 사용자 풀을 통해 실행되므로 Doris RBAC가 최종 데이터 권한 부여 백엔드입니다. 프롬프트, ADBC, FE HTTP 프로필/모니터링, 감사/거버넌스 및 성능 분석은 사용자별 라우팅 또는 명시적인 서비스 계정/관리자 설계가 있을 때까지 닫혀 있습니다.

4. 서비스 실행

다음 명령을 실행하여 서버를 시작합니다.

./start_server.sh

이 명령은 스트리밍 가능한 HTTP MCP 서비스로 FastAPI 애플리케이션을 시작합니다.

5. Docker에 배포하기

Docker에서 Doris MCP 서버만 실행하려는 경우:

cd doris-mcp-server
docker build -t doris-mcp-server .
docker run -d -p <port>:<port> -v /*your-host*/doris-mcp-server/.env:/app/.env --name <your-mcp-server-name> -it doris-mcp-server:latest

서비스 엔드포인트:

스트리밍 가능한 HTTP: http://<host>:<port>/mcp (기본 MCP 엔드포인트 - GET, POST, DELETE, OPTIONS 지원)
상태 확인: http://<host>:<port>/health

참고: 서버는 웹 기반 통신을 위해 스트리밍 가능한 HTTP를 사용하여 통합된 요청/응답 및 스트리밍 기능을 제공합니다.

사용법

Doris MCP 서버와 상호 작용하려면 MCP 클라이언트가 필요합니다. 클라이언트는 서버의 스트리밍 가능한 HTTP 엔드포인트에 연결하고 MCP 사양에 따라 요청을 보내 서버의 도구를 호출합니다.

주요 상호 작용 흐름:

클라이언트 초기화: initialize 메서드 호출을 /mcp (스트리밍 HTTP)로 전송합니다.
(선택 사항) 도구 검색: 클라이언트가 tools/list을 호출하여 지원되는 도구 목록, 설명 및 매개변수 스키마를 가져올 수 있습니다.
도구 호출: 클라이언트가 tools/call 요청을 전송하여 name 및 arguments을 지정합니다.
- 예시: 테이블 스키마 가져오기
  - name: get_table_schema
  - arguments: table_name, db_name, catalog_name을 포함합니다.
응답 처리:
- 비스트리밍: 클라이언트가 content 또는 isError이 포함된 응답을 수신합니다.
- 스트리밍: 클라이언트가 일련의 진행 알림을 받은 후 최종 응답을 수신합니다.

카탈로그 페더레이션 지원

Doris MCP 서버는 카탈로그 페더레이션을 지원하여 통합 인터페이스 내에서 여러 데이터 카탈로그(내부 Doris 테이블 및 Hive, MySQL 등과 같은 외부 데이터 소스)와 상호 작용할 수 있습니다.

주요 기능:

멀티 카탈로그 메타데이터 액세스: 모든 메타데이터 도구(get_db_list, get_db_table_list, get_table_schema 등)는 특정 카탈로그를 쿼리하기 위한 선택적 catalog_name 매개변수를 지원합니다.
교차 카탈로그 SQL 쿼리: 세 부분으로 구성된 테이블 명명법을 사용하여 여러 카탈로그에 걸친 SQL 쿼리를 실행합니다.
카탈로그 검색: get_catalog_list를 사용하여 사용 가능한 카탈로그와 해당 유형을 검색합니다.

세 부분 명명법 요구 사항:

모든 SQL 쿼리는 테이블 참조에 세 부분 명명법을 사용해야 합니다:

내부 테이블: internal.database_name.table_name
외부 테이블: catalog_name.database_name.table_name

예시:

사용 가능한 카탈로그 가져오기:

{
  "tool_name": "get_catalog_list",
  "arguments": {"random_string": "unique_id"}
}

특정 카탈로그의 데이터베이스 가져오기:

{
  "tool_name": "get_db_list", 
  "arguments": {"random_string": "unique_id", "catalog_name": "mysql"}
}

내부 카탈로그 쿼리:

{
  "tool_name": "exec_query",
  "arguments": {
    "random_string": "unique_id",
    "sql": "SELECT COUNT(*) FROM internal.ssb.customer"
  }
}

외부 카탈로그 쿼리:

{
  "tool_name": "exec_query", 
  "arguments": {
    "random_string": "unique_id",
    "sql": "SELECT COUNT(*) FROM mysql.ssb.customer"
  }
}

교차 카탈로그 쿼리:

{
  "tool_name": "exec_query",
  "arguments": {
    "random_string": "unique_id", 
    "sql": "SELECT i.c_name, m.external_data FROM internal.ssb.customer i JOIN mysql.test.user_info m ON i.c_custkey = m.customer_id"
  }
}

보안 구성

Doris MCP 서버에는 v0.6.0에서 향상된 고급 인증, 권한 부여, SQL 보안 검증 및 데이터 마스킹 기능을 갖춘 포괄적인 엔터프라이즈급 보안 프레임워크가 포함되어 있습니다.

보안 기능 (v0.6.0에서 향상됨)

🔐 다중 인증 시스템: 독립적인 제어 스위치가 있는 완전한 토큰, JWT 및 OAuth 인증
🔗 토큰 바인딩 데이터베이스 구성: 토큰이 자체 데이터베이스 연결 매개변수를 전달할 수 있도록 하는 혁신적인 접근 방식
🔄 핫 리로드 보안: 지능형 토큰 재검증을 통한 무중단 보안 구성 업데이트
⚡ 즉시 검증: 연결 시 실시간 데이터베이스 및 인증 검증
🛡️ 역할 기반 권한 부여: 4단계 보안 분류를 통한 고급 RBAC
🚫 향상된 SQL 보안: 향상된 패턴 감지를 통한 고급 SQL 인젝션 보호
🎭 지능형 데이터 마스킹: 사용자 기반 권한을 통한 자동 민감 데이터 마스킹
📊 보안 분석: 포괄적인 감사 추적 및 보안 모니터링

인증 구성 (v0.6.0)

세분화된 제어로 새로운 인증 시스템을 구성합니다:

# Individual Authentication Control (New in v0.6.0)
ENABLE_TOKEN_AUTH=true          # Enable token-based authentication
ENABLE_JWT_AUTH=false           # Enable JWT authentication  
ENABLE_OAUTH_AUTH=false         # Enable OAuth authentication

# Token Management (New in v0.6.0)
TOKEN_FILE_PATH=tokens.json     # Token configuration file
TOKEN_HOT_RELOAD=true          # Enable hot reloading

# Default Tokens (Customizable via environment)
DEFAULT_ADMIN_TOKEN=doris_admin_token_123456
DEFAULT_ANALYST_TOKEN=doris_analyst_token_123456
DEFAULT_READONLY_TOKEN=doris_readonly_token_123456

# Legacy Configuration (Deprecated)
# AUTH_TYPE=token               # Use individual switches instead
# TOKEN_SECRET=your_secret_key  # Use token-based auth instead

Doris 기반 OAuth 인증

Doris 기반 OAuth는 Doris 자체가 권한 부여 백엔드인 별도의 OAuth 모드입니다. MCP 클라이언트가 이 서버의 OAuth 메타데이터를 검색하고, 사용자가 Doris 사용자 이름과 비밀번호로 로그인하면, 서버는 사용자별 Doris 연결 풀을 생성하여 해당 자격 증명을 검증하고, 발급된 doa_ 액세스 토큰은 해당 Doris 사용자의 풀을 통해 도구 호출을 라우팅합니다. MCP 범위는 호출할 수 있는 MCP 작업을 제어하고, Doris RBAC는 사용자가 볼 수 있는 카탈로그, 데이터베이스, 테이블 및 메타데이터를 제어합니다.

이 모드는 외부 OAuth/OIDC와 동일하지 않습니다. ENABLE_DORIS_OAUTH_AUTH=true은 ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true 및 레거시 AUTH_TYPE=oauth와 충돌합니다. 두 모드가 모두 구성되면 시작이 빠르게 실패합니다. 표준 MCP 에이전트는 하나의 MCP URL에 진입하며 해당 URL에 대해 정확히 하나의 OAuth 동작을 검색해야 하므로, Doris 기반 OAuth 모드에서는 기존 /auth/* 외부 OAuth 로그인 흐름이 사용되지 않습니다.

최소 로컬 구성

다음 예시는 단일 작업자에서의 로컬 개발을 위한 것입니다:

TRANSPORT=http
WORKERS=1

DORIS_HOST=localhost
DORIS_PORT=9030
DORIS_USER=root
DORIS_PASSWORD=<service-account-password>
DORIS_DATABASE=information_schema

ENABLE_DORIS_OAUTH_AUTH=true
DORIS_OAUTH_BASE_URL=http://localhost:3000
ENABLE_OAUTH_AUTH=false

DORIS_OAUTH_DB_TOOLS_ENABLED=true
DORIS_OAUTH_DB_TOOL_ALLOWLIST=get_db_list,get_db_table_list,get_table_schema,get_table_comment,get_table_column_comments,get_table_indexes,get_catalog_list
DORIS_OAUTH_QUERY_TOOLS_ENABLED=true
DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true

# Optional: let Doris RBAC, not the legacy MCP SQL guard, decide DDL/DML.
ENABLE_SECURITY_CHECK=false

구성된 서비스 Doris 계정은 시작 검증 및 비 Doris OAuth 호환성 경로에 여전히 필요합니다. Doris 기반 OAuth 요청은 사용자별 풀이 누락된 경우 실패-클로즈되며 서비스/글로벌 계정으로 폴백해서는 안 됩니다.

Doris OAuth 도구 액세스

DORIS_OAUTH_DB_TOOLS_ENABLED=true은 검토된 메타데이터 버킷을 엽니다. 검토된 도구는 다음과 같습니다:

get_db_list
get_db_table_list
get_table_schema
get_table_comment
get_table_column_comments
get_table_indexes
get_catalog_list

일반 MCP OAuth 흐름의 경우 클라이언트는 긴 --scopes 목록을 전달할 필요가 없습니다. OAuth 요청이 범위를 생략하면 서버는 구성된 Doris OAuth 기능 범위를 부여합니다. MySQL 채널 작업의 경우 Doris RBAC는 로그인한 Doris 사용자가 실제로 메타데이터를 읽거나, SQL을 실행하거나, SQL을 설명할 수 있는지 여부를 결정합니다.

DORIS_OAUTH_QUERY_TOOLS_ENABLED=true은 exec_query을 엽니다. DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true는 get_sql_explain을 엽니다. ENABLE_SECURITY_CHECK=true인 경우, 레거시 MCP SQL 보안 계층은 Doris가 이를 보기 전에 일부 SQL을 여전히 거부할 수 있습니다. 의도된 정책이 Doris RBAC가 SQL/DDL/DML을 결정하도록 하는 것이라면 ENABLE_SECURITY_CHECK=false를 설정하십시오.

Doris 기반 OAuth는 이 단계에서 프롬프트, ADBC, FE HTTP 프로필/모니터링, 감사/거버넌스 또는 성능 분석을 열지 않습니다. 단, 해당 경로가 사용자별 자격 증명을 통해 별도로 라우팅되거나 명시적인 서비스 계정/관리자 지정이 제공된 경우는 예외입니다.

현재 운영 제한 사항

Doris 기반 OAuth는 현재 단일 프로세스 및 단일 작업자입니다:

WORKERS=1이 필요합니다. WORKERS=0은 CPU 수로 확장되며 Doris 기반 OAuth가 활성화된 경우 실패합니다.
OAuth 클라이언트, 권한 부여 트랜잭션, 권한 부여 코드, 액세스 토큰, 갱신 토큰 및 DCR 클라이언트는 메모리 전용이며 프로세스 로컬입니다.
사용자별 Doris 연결 풀은 프로세스 로컬입니다.
프로세스를 다시 시작하면 사용자가 다시 로그인해야 합니다.
토큰과 풀은 작업자, 프로세스 또는 노드 간에 공유되지 않습니다.
상태 비저장 수평 확장 및 다중 노드 배포는 아직 Doris 기반 OAuth에 대해 지원되지 않습니다.

액세스 토큰이 유효하지만 해당 Doris 사용자 풀이 사라진 경우, 요청은 로그인 필요 / DORIS_OAUTH_POOL_MISSING 오류와 함께 실패합니다. 서버는 자동 풀 재구성을 위해 원시 Doris 비밀번호를 저장하지 않습니다.

프로덕션 강화

프로덕션 배포의 경우:

비루프백 주소에는 HTTPS DORIS_OAUTH_BASE_URL를 사용하십시오.
DORIS_OAUTH_ALLOW_INSECURE_HTTP=false을 유지하십시오. 비루프백 http://은 개발을 위해 명시적으로 재정의되지 않는 한 거부됩니다.
제어된 리버스 프록시 뒤에서만 DORIS_OAUTH_TRUST_PROXY_HEADERS을 활성화하고 DORIS_OAUTH_TRUSTED_PROXY_CIDRS을 설정하십시오.
로그인, 권한 부여, 토큰, 갱신, 취소 및 DCR 속도 제한을 활성화된 상태로 유지하십시오.
Doris RBAC를 최종 데이터 권한 부여 경계로 사용하고 Doris 사용자에게 검사해야 하는 데이터만 부여하십시오.
Doris 비밀번호, 권한 부여 헤더, 액세스 토큰, 갱신 토큰, 권한 부여 코드, PKCE 검증기 또는 클라이언트 비밀을 기록하지 마십시오.
doa_ 접두사를 Doris 기반 OAuth 액세스 토큰용으로 예약된 것으로 처리하십시오. 정적 토큰 및 JWT 베어러 값은 이를 사용해서는 안 됩니다.
루프백 개발을 위해 동적 클라이언트 등록을 auto로 유지하거나 ENABLE_DORIS_OAUTH_PRODUCTION_DCR=true을 사용하여 프로덕션 DCR을 명시적으로 구성하십시오.

토큰 바인딩 데이터베이스 구성 (v0.6.0의 새로운 기능)

데이터베이스 바인딩을 통한 고급 토큰 관리를 위해 tokens.json 파일을 생성합니다:

{
  "version": "1.0",
  "tokens": [
    {
      "token_id": "customer-a-token",
      "token": "customer_a_secure_token_12345",
      "description": "Customer A dedicated database access",
      "expires_hours": null,
      "is_active": true,
      "database_config": {
        "host": "customer-a-db.example.com",
        "port": 9030,
        "user": "customer_a_user",
        "password": "secure_password",
        "database": "customer_a_data",
        "charset": "UTF8",
        "fe_http_port": 8030
      }
    },
    {
      "token_id": "customer-b-token", 
      "token": "customer_b_secure_token_67890",
      "description": "Customer B dedicated database access",
      "expires_hours": 720,
      "is_active": true,
      "database_config": {
        "host": "customer-b-db.example.com",
        "port": 9030,
        "user": "customer_b_user", 
        "password": "secure_password",
        "database": "customer_b_data",
        "charset": "UTF8",
        "fe_http_port": 8030
      }
    }
  ]
}

핫 리로드 구성 업데이트 (v0.6.0의 새로운 기능)

시스템이 자동으로 구성 변경을 감지하고 적용합니다:

자동 감지: 10초마다 파일 수정 모니터링
즉시 검증: 새 토큰에 대한 즉각적인 데이터베이스 구성 검증
무중단: 서비스 중단 없는 구성 업데이트
롤백 보호: 구성 오류 시 자동 롤백
감사 추적: 구성 변경에 대한 완전한 로깅

토큰 인증 예시

# Client authentication with token
auth_info = {
    "type": "token",
    "token": "your_jwt_token",
    "session_id": "unique_session_id"
}

기본 인증 예시

# Client authentication with username/password
auth_info = {
    "type": "basic",
    "username": "analyst",
    "password": "secure_password",
    "session_id": "unique_session_id"
}

권한 부여 및 보안 수준

시스템은 계층적 액세스 제어를 통해 네 가지 보안 수준을 지원합니다:

보안 수준	액세스 범위	일반적인 사용 사례
공개	무제한 액세스	공개 보고서, 일반 통계
내부	회사 직원	내부 대시보드, 비즈니스 지표
기밀	권한이 부여된 담당자	고객 데이터, 재무 보고서
비밀	고위 경영진	전략 데이터, 민감한 분석

역할 구성

사용자 역할 및 권한을 구성합니다:

# Example role configuration
role_permissions = {
    "data_analyst": {
        "security_level": "internal",
        "permissions": ["read_data", "execute_query"],
        "allowed_tables": ["sales", "products", "orders"]
    },
    "data_admin": {
        "security_level": "confidential", 
        "permissions": ["read_data", "execute_query", "admin"],
        "allowed_tables": ["*"]
    },
    "executive": {
        "security_level": "secret",
        "permissions": ["read_data", "execute_query", "admin"],
        "allowed_tables": ["*"]
    }
}

SQL 보안 검증

시스템이 자동으로 SQL 쿼리의 보안 위험을 검증합니다:

차단된 작업

환경 변수를 사용하여 차단된 SQL 작업을 구성합니다 (v0.4.2의 새로운 기능):

# Enable/disable SQL security check (New in v0.4.2)
ENABLE_SECURITY_CHECK=true

# Customize blocked keywords via environment variable (New in v0.4.2)
BLOCKED_KEYWORDS="DROP,DELETE,TRUNCATE,ALTER,CREATE,INSERT,UPDATE,GRANT,REVOKE,EXEC,EXECUTE,SHUTDOWN,KILL"

# Maximum query complexity score
MAX_QUERY_COMPLEXITY=100

기본 차단 키워드 (v0.4.2에서 통합됨):

DDL 작업: DROP, CREATE, ALTER, TRUNCATE
DML 작업: DELETE, INSERT, UPDATE
DCL 작업: GRANT, REVOKE
시스템 작업: EXEC, EXECUTE, SHUTDOWN, KILL

SQL 인젝션 보호

시스템이 자동으로 다음을 감지하고 차단합니다:

Union 기반 인젝션: UNION SELECT 공격
Boolean 기반 인젝션: OR 1=1 패턴
시간 기반 인젝션: SLEEP(), WAITFOR 함수
주석 인젝션: --, /**/ 패턴
스택형 쿼리: ;로 구분된 여러 문

보안 검증 예시

# This query would be blocked
dangerous_sql = "SELECT * FROM users WHERE id = 1; DROP TABLE users;"

# This query would be allowed
safe_sql = "SELECT name, email FROM users WHERE department = 'sales'"

데이터 마스킹 구성

민감한 정보에 대한 자동 데이터 마스킹을 구성합니다:

내장 마스킹 규칙

# Default masking rules
masking_rules = [
    {
        "column_pattern": r".*phone.*|.*mobile.*",
        "algorithm": "phone_mask",
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 3,
            "keep_suffix": 4
        },
        "security_level": "internal"
    },
    {
        "column_pattern": r".*email.*", 
        "algorithm": "email_mask",
        "parameters": {"mask_char": "*"},
        "security_level": "internal"
    },
    {
        "column_pattern": r".*id_card.*|.*identity.*",
        "algorithm": "id_mask", 
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 6,
            "keep_suffix": 4
        },
        "security_level": "confidential"
    }
]

마스킹 알고리즘

알고리즘	설명	예시
`phone_mask`	전화번호 마스킹	`138****5678`
`email_mask`	이메일 주소 마스킹	`j***n@example.com`
`id_mask`	주민등록번호 마스킹	`110101****1234`
`name_mask`	개인 이름 마스킹	`张*明`
`partial_mask`	비율에 따른 부분 마스킹	`abc***xyz`

사용자 정의 마스킹 규칙

구성에 사용자 정의 마스킹 규칙을 추가합니다:

# Custom masking rule
custom_rule = {
    "column_pattern": r".*salary.*|.*income.*",
    "algorithm": "partial_mask",
    "parameters": {
        "mask_char": "*",
        "mask_ratio": 0.6
    },
    "security_level": "confidential"
}

보안 구성 예시

환경 변수

# .env file
AUTH_TYPE=token
TOKEN_SECRET=your_jwt_secret_key
ENABLE_MASKING=true
MAX_RESULT_ROWS=10000
BLOCKED_SQL_OPERATIONS=DROP,DELETE,TRUNCATE,ALTER
MAX_QUERY_COMPLEXITY=100
ENABLE_AUDIT=true

민감한 테이블 구성

# Configure sensitive tables with security levels
sensitive_tables = {
    "user_profiles": "confidential",
    "payment_records": "secret", 
    "employee_salaries": "secret",
    "customer_data": "confidential",
    "public_reports": "public"
}

보안 모범 사례

🔑 강력한 인증: 적절한 만료 시간이 있는 JWT 토큰 사용
🎯 최소 권한 원칙: 필요한 최소 권한만 부여
🔍 정기 감사: 보안 모니터링을 위한 감사 로깅 활성화
🛡️ 입력 검증: 모든 SQL 쿼리가 자동으로 검증됨
🎭 데이터 분류: 보안 수준에 따라 데이터를 적절하게 분류
🔄 정기 업데이트: 보안 규칙 및 구성을 최신 상태로 유지
Doris 기반 OAuth 강화: HTTPS 사용, 이 모드에서 외부 OAuth 비활성화 유지, WORKERS=1 유지, MySQL 채널 데이터 액세스에 Doris RBAC 의존, 로그인한 Doris 사용자의 자격 증명을 사용하도록 구성 및 검증된 작업만 노출.

보안 모니터링

시스템이 포괄적인 보안 모니터링을 제공합니다:

# Security audit log example
{
    "timestamp": "2024-01-15T10:30:00Z",
    "user_id": "analyst_user",
    "action": "query_execution", 
    "resource": "customer_data",
    "result": "blocked",
    "reason": "insufficient_permissions",
    "risk_level": "medium"
}

⚠️ 중요: 프로덕션에 배포하기 전에 항상 개발 환경에서 보안 구성을 테스트하십시오. 조직의 요구 사항에 따라 정기적으로 보안 정책을 검토하고 업데이트하십시오.

Cursor와 연결하기

Stdio 모드(권장) 또는 스트리밍 HTTP 모드를 사용하여 Cursor를 이 MCP 서버에 연결할 수 있습니다.

Stdio 모드

Stdio 모드를 사용하면 Cursor가 서버 프로세스를 직접 관리할 수 있습니다. 구성은 Cursor의 MCP 서버 설정 파일(일반적으로 ~/.cursor/mcp.json 또는 유사) 내에서 수행됩니다.

방법 1: PyPI 설치 사용 (권장)

PyPI에서 패키지를 설치하고 Cursor에서 사용하도록 구성합니다:

pip install doris-mcp-server

Cursor 구성: Cursor MCP 구성에 다음과 같은 항목을 추가합니다:

{
  "mcpServers": {
    "doris-stdio": {
      "command": "doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

방법 2: uv 사용 (개발)

uv이(가) 설치되어 있고 소스에서 실행하려는 경우:

uv run --project /path/to/doris-mcp-server doris-mcp-server

참고: /path/to/doris-mcp-server을(를) 프로젝트 디렉터리의 실제 절대 경로로 바꾸십시오.

Cursor 구성: Cursor MCP 구성에 다음과 같은 항목을 추가합니다:

{
  "mcpServers": {
    "doris-stdio": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/your/doris-mcp-server", "doris-mcp-server"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

스트리밍 가능 HTTP 모드

스트리밍 가능 HTTP 모드를 사용하려면 먼저 MCP 서버를 독립적으로 실행한 다음, Cursor가 이에 연결하도록 구성해야 합니다.

.env 구성: 프로젝트 디렉터리 내의 .env 파일에 데이터베이스 자격 증명 및 기타 필요한 설정이 올바르게 구성되었는지 확인합니다.
서버 시작: 프로젝트의 루트 디렉터리에서 터미널을 통해 서버를 실행합니다:
```
./start_server.sh
```
이 스크립트는 .env 파일을 읽고 스트리밍 가능 HTTP를 지원하는 FastAPI 서버를 시작합니다. 서버가 수신 대기 중인 호스트와 포트를 기록해 둡니다(기본값은 0.0.0.0:3000).
Cursor 구성: 실행 중인 서버의 스트리밍 가능 HTTP 엔드포인트를 가리키도록 Cursor MCP 구성에 다음과 같은 항목을 추가합니다:
```
{
  "mcpServers": {
    "doris-http": {
       "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```
참고: 서버가 다른 주소에서 실행되는 경우 호스트/포트를 조정하십시오. /mcp 엔드포인트는 통합된 스트리밍 가능 HTTP 인터페이스입니다.

Cursor에서 두 모드 중 하나를 구성한 후에는 서버(예: doris-stdio 또는 doris-http)를 선택하고 해당 도구를 사용할 수 있습니다.

Kiro와 연결하기

또는 Kiro MCP 구성 파일(~/.kiro/settings/mcp.json은(는) 전역, .kiro/settings/mcp.json은(는) 프로젝트 범위)에 다음을 추가합니다. 자세한 내용은 Kiro MCP 문서를 참조하십시오.

{
  "mcpServers": {
    "doris-stdio": {
      "command": "doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

디렉터리 구조

doris-mcp-server/
├── doris_mcp_server/           # Main server package
│   ├── main.py                 # Main entry point and FastAPI app
│   ├── multiworker_app.py      # Multi-worker application module (New in v0.6.0)
│   ├── auth/                   # Authentication modules (New in v0.6.0)
│   │   ├── token_manager.py    # Enterprise token management with hot reload
│   │   ├── jwt_manager.py      # JWT authentication provider
│   │   ├── oauth_provider.py   # OAuth authentication provider  
│   │   ├── oauth_handlers.py   # OAuth HTTP endpoint handlers
│   │   ├── token_handlers.py   # Token management HTTP endpoints
│   │   ├── auth_middleware.py  # Authentication middleware
│   │   └── __init__.py
│   ├── tools/                  # MCP tools implementation
│   │   ├── tools_manager.py    # Centralized tools management and registration
│   │   ├── resources_manager.py # Resource management and metadata exposure
│   │   ├── prompts_manager.py  # Intelligent prompt templates for data analysis
│   │   └── __init__.py
│   ├── utils/                  # Core utility modules
│   │   ├── config.py           # Configuration management with validation
│   │   ├── db.py               # Enhanced database connection management with token binding (Enhanced in v0.6.0)
│   │   ├── query_executor.py   # High-performance SQL execution with caching
│   │   ├── security.py         # Advanced security management and authentication (Enhanced in v0.6.0)
│   │   ├── schema_extractor.py # Metadata extraction with catalog federation
│   │   ├── analysis_tools.py   # Data analysis and performance monitoring
│   │   ├── data_governance_tools.py  # Data lineage and freshness monitoring (v0.5.0)
│   │   ├── data_quality_tools.py     # Comprehensive data quality analysis (v0.5.0)
│   │   ├── data_exploration_tools.py # Advanced statistical analysis (v0.5.0)
│   │   ├── security_analytics_tools.py # Access pattern analysis (v0.5.0)
│   │   ├── dependency_analysis_tools.py # Impact analysis and dependency mapping (v0.5.0)
│   │   ├── performance_analytics_tools.py # Query optimization and capacity planning (v0.5.0)
│   │   ├── adbc_query_tools.py       # High-performance Arrow Flight SQL operations (v0.5.0)
│   │   ├── logger.py           # Logging configuration
│   │   └── __init__.py
│   └── __init__.py
├── doris_mcp_client/           # MCP client implementation
│   ├── client.py               # Unified MCP client for testing and integration
│   ├── README.md               # Client documentation
│   └── __init__.py
├── logs/                       # Log files directory
├── tokens.json                 # Token configuration file (New in v0.6.0)
├── README.md                   # This documentation
├── RELEASE_NOTES_v0.6.0.md     # Release notes for v0.6.0
├── .env.example                # Environment variables template
├── requirements.txt            # Python dependencies
├── pyproject.toml              # Project configuration and entry points
├── uv.lock                     # UV package manager lock file
├── generate_requirements.py    # Requirements generation script
├── start_server.sh             # Server startup script
└── restart_server.sh           # Server restart script

새 도구 개발

이 섹션에서는 중앙 집중식 도구 관리를 갖춘 통합 모듈식 아키텍처를 기반으로 Doris MCP 서버에 새 MCP 도구를 추가하는 프로세스를 간략히 설명합니다.

1. 기존 유틸리티 모듈 활용

서버는 일반적인 데이터베이스 작업을 위한 포괄적인 유틸리티 모듈을 제공합니다:

doris_mcp_server/utils/db.py: 연결 풀링 및 상태 모니터링을 통한 데이터베이스 연결 관리.
doris_mcp_server/utils/query_executor.py: 고급 캐싱, 최적화 및 성능 모니터링을 통한 고성능 SQL 실행.
doris_mcp_server/utils/schema_extractor.py: 전체 카탈로그 페더레이션을 지원하는 메타데이터 추출.
doris_mcp_server/utils/security.py: 포괄적인 보안 관리, SQL 유효성 검사 및 데이터 마스킹.
doris_mcp_server/utils/analysis_tools.py: 고급 데이터 분석 및 통계 도구.
doris_mcp_server/utils/config.py: 유효성 검사를 통한 구성 관리.
doris_mcp_server/utils/data_governance_tools.py: 데이터 계보 추적 및 최신성 모니터링 (v0.5.0의 새로운 기능).
doris_mcp_server/utils/data_quality_tools.py: 포괄적인 데이터 품질 분석 프레임워크 (v0.5.0의 새로운 기능).
doris_mcp_server/utils/adbc_query_tools.py: 고성능 Arrow Flight SQL 작업 (v0.5.0의 새로운 기능).

2. 도구 로직 구현

doris_mcp_server/tools/tools_manager.py의 DorisToolsManager 클래스에 새 도구를 추가합니다. 도구 관리자는 통합된 인터페이스를 통해 도구 등록 및 실행에 대한 중앙 집중식 접근 방식을 제공합니다.

예시: 새 분석 도구 추가:

# In doris_mcp_server/tools/tools_manager.py

async def your_new_analysis_tool(self, arguments: Dict[str, Any]) -> List[Dict[str, Any]]:
    """
    Your new analysis tool implementation
    
    Args:
        arguments: Tool arguments from MCP client
        
    Returns:
        List of MCP response messages
    """
    try:
        # Use existing utilities
        result = await self.query_executor.execute_sql_for_mcp(
            sql="SELECT COUNT(*) FROM your_table",
            max_rows=arguments.get("max_rows", 100)
        )
        
        return [{
            "type": "text",
            "text": json.dumps(result, ensure_ascii=False, indent=2)
        }]
        
    except Exception as e:
        logger.error(f"Tool execution failed: {str(e)}", exc_info=True)
        return [{
            "type": "text", 
            "text": f"Error: {str(e)}"
        }]

3. 도구 등록

동일한 클래스의 _register_tools 메서드에 도구를 추가합니다:

# In the _register_tools method of DorisToolsManager

@self.mcp.tool(
    name="your_new_analysis_tool",
    description="Description of your new analysis tool",
    inputSchema={
        "type": "object",
        "properties": {
            "parameter1": {
                "type": "string",
                "description": "Description of parameter1"
            },
            "parameter2": {
                "type": "integer", 
                "description": "Description of parameter2",
                "default": 100
            }
        },
        "required": ["parameter1"]
    }
)
async def your_new_analysis_tool_wrapper(arguments: Dict[str, Any]) -> List[Dict[str, Any]]:
    return await self.your_new_analysis_tool(arguments)

4. 고급 기능

더 복잡한 도구의 경우 포괄적인 프레임워크를 활용할 수 있습니다:

고급 캐싱: 향상된 성능을 위해 쿼리 실행기의 내장 캐싱 사용
엔터프라이즈 보안: 보안 관리자를 통해 포괄적인 SQL 유효성 검사 및 데이터 마스킹 적용
지능형 프롬프트: 고급 쿼리 생성을 위해 프롬프트 관리자 사용
리소스 관리: 리소스 관리자를 통해 메타데이터 노출
성능 모니터링: 모니터링 기능을 위해 분석 도구와 통합

5. 테스트

포함된 MCP 클라이언트를 사용하여 새 도구를 테스트합니다:

# Using doris_mcp_client/client.py
from doris_mcp_client.client import DorisUnifiedMCPClient

async def test_new_tool():
    client = DorisUnifiedMCPClient()
    result = await client.call_tool("your_new_analysis_tool", {
        "parameter1": "test_value",
        "parameter2": 50
    })
    print(result)

MCP 클라이언트

이 프로젝트에는 테스트 및 통합 목적을 위한 통합 MCP 클라이언트(doris_mcp_client/)가 포함되어 있습니다. 이 클라이언트는 여러 연결 모드를 지원하며 MCP 서버와 상호 작용하기 위한 편리한 인터페이스를 제공합니다.

자세한 클라이언트 문서는 doris_mcp_client/README.md을(를) 참조하십시오.

기여

이슈 또는 풀 리퀘스트를 통한 기여를 환영합니다.

라이선스

이 프로젝트는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하십시오.

FAQ

Q: Qwen3-32b 및 기타 소형 매개변수 모델이 도구를 호출할 때 항상 실패하는 이유는 무엇입니까?

A: 이는 일반적인 문제입니다. 주된 이유는 이러한 모델이 MCP 도구를 올바르게 사용하려면 더 명시적인 지침이 필요하기 때문입니다. 모델에 다음 지침 프롬프트를 추가하는 것이 좋습니다:

중국어 버전：

<instruction>
尽可能使用MCP工具完成任务，仔细阅读每个工具的注解、方法名、参数说明等内容。请按照以下步骤操作：

1. 仔细分析用户的问题，从已有的Tools列表中匹配最合适的工具。
2. 确保工具名称、方法名和参数完全按照工具注释中的定义使用，不要自行创造工具名称或参数。
3. 传入参数时，严格遵循工具注释中规定的参数格式和要求。
4. 调用工具时，根据需要直接调用工具，但参数请求参考以下请求格式：{"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. 输出结果时，不要包含任何XML标签，仅返回纯文本内容。

<input>
用户问题：user_query
</input>

<output>
返回工具调用结果或最终答案，以及对结果的分析。
</output>
</instruction>

영어 버전：

<instruction>
Use MCP tools to complete tasks as much as possible. Carefully read the annotations, method names, and parameter descriptions of each tool. Please follow these steps:

1. Carefully analyze the user's question and match the most appropriate tool from the existing Tools list.
2. Ensure tool names, method names, and parameters are used exactly as defined in the tool annotations. Do not create tool names or parameters on your own.
3. When passing parameters, strictly follow the parameter format and requirements specified in the tool annotations.
4. When calling tools, call them directly as needed, but refer to the following request format for parameters: {"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. When outputting results, do not include any XML tags, return plain text content only.

<input>
User question: user_query
</input>

<output>
Return tool call results or final answer, along with analysis of the results.
</output>
</instruction>

반환된 결과에 대한 추가 요구 사항이 있는 경우 <output> 태그에 구체적인 요구 사항을 설명할 수 있습니다.

Q: 다른 데이터베이스 연결을 구성하는 방법은 무엇입니까?

A: 여러 가지 방법으로 데이터베이스 연결을 구성할 수 있습니다:

환경 변수 (권장):

export DORIS_HOST="your_doris_host"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

명령줄 인수:

doris-mcp-server --db-host your_host --db-port 9030 --db-user root --db-password your_password

구성 파일: .env 파일에서 해당 구성 항목을 수정합니다.

Q: 모니터링 도구를 위한 BE 노드를 구성하는 방법은 무엇입니까?

A: 배포 시나리오에 따라 적절한 구성을 선택합니다:

외부 네트워크 (수동 구성):

# Manually specify BE node addresses
DORIS_BE_HOSTS=10.1.1.100,10.1.1.101,10.1.1.102
DORIS_BE_WEBSERVER_PORT=8040

내부 네트워크 (자동 검색):

# Leave BE_HOSTS empty for auto-discovery
# DORIS_BE_HOSTS=  # Not set or empty
# System will use 'SHOW BACKENDS' command to get internal IPs

Q: 최적화를 위해 LLM과 함께 SQL Explain/Profile 파일을 사용하는 방법은 무엇입니까?

A: 이 도구는 LLM 분석을 위해 잘린 내용과 전체 파일을 모두 제공합니다:

분석 결과 가져오기:

{
  "content": "Truncated plan for immediate review",
  "file_path": "/tmp/explain_12345.txt",
  "is_content_truncated": true
}

LLM 분석 워크플로:
- 빠른 통찰력을 위해 잘린 내용 검토
- 전체 파일을 첨부 파일로 LLM에 업로드
- 최적화 제안 또는 성능 분석 요청
- 권장 개선 사항 구현

콘텐츠 크기 구성:

MAX_RESPONSE_CONTENT_SIZE=4096  # Adjust as needed

Q: 데이터 보안 및 마스킹 기능을 활성화하는 방법은 무엇입니까?

A: .env 파일에서 다음 구성을 설정합니다:

# Enable data masking
ENABLE_MASKING=true
# Set authentication type
AUTH_TYPE=token
# Configure token secret
TOKEN_SECRET=your_secret_key
# Set maximum result rows
MAX_RESULT_ROWS=10000

Q: Stdio 모드와 HTTP 모드의 차이점은 무엇입니까?

Stdio 모드: 클라이언트가 서버 프로세스를 관리하는 MCP 클라이언트(예: Cursor)와의 직접 통합에 적합합니다.
HTTP 모드: 여러 클라이언트 연결을 지원하는 독립적인 웹 서비스로, 프로덕션 환경에 적합합니다.

권장 사항:

개발 및 개인 사용: Stdio 모드
프로덕션 및 다중 사용자 환경: HTTP 모드

Q: 연결 시간 초과 문제를 해결하는 방법은 무엇입니까?

A: 다음 해결 방법을 시도해 보십시오:

시간 초과 설정 늘리기:

# Set in .env file
QUERY_TIMEOUT=60
CONNECTION_TIMEOUT=30

네트워크 연결 확인:

# Test database connection
curl http://localhost:3000/health

연결 풀 구성 최적화:
```
DORIS_MAX_CONNECTIONS=20
```

Q: `at_eof` 연결 오류를 해결하는 방법은 무엇입니까? (v0.5.0에서 완전히 수정됨)

A: 버전 0.5.0은 포괄적인 연결 풀 재설계를 통해 심각한 at_eof 연결 오류를 완전히 해결했습니다:

문제점:

연결 풀 사전 생성 및 부적절한 연결 상태 관리로 인해 at_eof 오류 발생
연결 수명 주기 동안 MySQL aiomysql 리더 상태가 일관되지 않게 됨
동시 부하 시 연결 풀 불안정

해결책 (v0.5.0):

연결 풀 전략 전면 개편:
- 최소 연결 수 0: 사전 생성 문제를 방지하기 위해 min_connections을(를) 기본값에서 0으로 변경
- 주문형 연결 생성: 필요할 때만 연결을 생성하여 오래된 연결 문제 제거
- 새 연결 전략: 항상 풀에서 새 연결을 획득하며 세션 수준 캐싱 없음
향상된 상태 모니터링:
- 시간 초과 기반 상태 확인: 연결 유효성 검사 쿼리에 3초 시간 초과 적용
- 백그라운드 상태 모니터: 30초마다 지속적인 풀 상태 모니터링
- 사전 예방적 오래된 연결 감지: 문제가 있는 연결의 자동 감지 및 정리
지능형 복구 시스템:
- 자동 풀 복구: 포괄적인 오류 처리를 통한 자가 치유 풀
- 지수 백오프 재시도: 최대 3회 시도하는 스마트 재시도 메커니즘
- 연결별 오류 감지: 연결 관련 오류의 정확한 식별
성능 최적화:
- 풀 워밍업: 최적의 성능을 위한 지능형 연결 풀 워밍
- 백그라운드 정리: 활성 작업에 영향을 주지 않고 오래된 연결의 주기적 정리
- 연결 진단: 실시간 연결 상태 모니터링 및 보고

연결 상태 모니터링:

# Monitor connection pool health in real-time
tail -f logs/doris_mcp_server_info.log | grep -E "(pool|connection|at_eof)"

# Check detailed connection diagnostics
tail -f logs/doris_mcp_server_debug.log | grep "connection health"

# View connection pool metrics
curl http://localhost:8000/health  # If running in HTTP mode

최적의 연결 성능을 위한 구성:

# Recommended connection pool settings in .env
DORIS_MAX_CONNECTIONS=20          # Adjust based on workload
CONNECTION_TIMEOUT=30             # Connection establishment timeout
QUERY_TIMEOUT=60                  # Query execution timeout

# Health monitoring settings
HEALTH_CHECK_INTERVAL=60          # Pool health check frequency

결과: 연결 안정성과 성능이 크게 향상되어 at_eof 오류의 99.9%가 제거되었습니다.

Q: MCP 라이브러리 버전 호환성 문제를 해결하는 방법은 무엇입니까? (v0.4.2에서 수정됨)

A: 버전 0.4.2는 MCP 1.8.x 및 1.9.x 버전을 모두 지원하는 지능형 MCP 호환성 계층을 도입했습니다:

문제점:

MCP 1.9.3에서 RequestContext 클래스에 대한 주요 변경 사항이 도입됨 (제네릭 매개변수가 2개에서 3개로 변경)
이로 인해 TypeError: Too few arguments for RequestContext 오류 발생

해결책 (v0.4.2):

지능형 버전 감지: 설치된 MCP 버전을 자동으로 감지
호환성 계층: 버전 간 API 차이를 원활하게 처리
유연한 버전 지원: 종속성에서 mcp>=1.8.0,<2.0.0

지원되는 MCP 버전:

# Both versions now work seamlessly
pip install mcp==1.8.0  # Stable version (recommended)
pip install mcp==1.9.3  # Latest version with new features

버전 정보:

# Check which MCP version is being used
doris-mcp-server --transport stdio
# The server will log: "Using MCP version: x.x.x"

MCP 관련 시작 오류가 발생하는 경우:

# Recommended: Use stable version
pip uninstall mcp
pip install mcp==1.8.0

# Or upgrade to latest compatible version
pip install --upgrade doris-mcp-server==0.5.0

Q: ADBC 고성능 기능을 활성화하는 방법은 무엇입니까? (v0.5.0의 새로운 기능)

A: ADBC(Arrow Flight SQL)는 대규모 데이터 세트에 대해 3~10배의 성능 향상을 제공합니다:

ADBC 종속성 (v0.5.0 이상에 자동으로 포함됨):

# ADBC dependencies are now included by default in doris-mcp-server>=0.5.0
# No separate installation required

Arrow Flight SQL 포트 구성:

# Add to your .env file
FE_ARROW_FLIGHT_SQL_PORT=8096
BE_ARROW_FLIGHT_SQL_PORT=8097

선택적 ADBC 사용자 지정:

# Customize ADBC behavior (optional)
ADBC_DEFAULT_MAX_ROWS=200000
ADBC_DEFAULT_TIMEOUT=120
ADBC_DEFAULT_RETURN_FORMAT=pandas  # arrow/pandas/dict

ADBC 연결 테스트:

# Use get_adbc_connection_info tool to verify setup
# Should show "status": "ready" and port connectivity

Q: 새로운 데이터 분석 도구를 사용하는 방법은 무엇입니까? (v0.5.0의 새로운 기능)

A: 7개의 새로운 분석 도구는 포괄적인 데이터 거버넌스 기능을 제공합니다:

데이터 품질 분석:

{
  "tool_name": "analyze_data_quality",
  "arguments": {
    "table_name": "customer_data",
    "analysis_scope": "comprehensive",
    "sample_size": 100000
  }
}

열 계보 추적:

{
  "tool_name": "trace_column_lineage", 
  "arguments": {
    "target_columns": ["users.email", "orders.customer_id"],
    "analysis_depth": 3
  }
}

데이터 최신성 모니터링:

{
  "tool_name": "monitor_data_freshness",
  "arguments": {
    "freshness_threshold_hours": 24,
    "include_update_patterns": true
  }
}

성능 분석:

{
  "tool_name": "analyze_slow_queries_topn",
  "arguments": {
    "days": 7,
    "top_n": 20,
    "include_patterns": true
  }
}

Q: 향상된 로깅 시스템을 사용하는 방법은 무엇입니까? (v0.5.0에서 개선됨)

A: 버전 0.5.0은 자동 관리 및 수준 기반 구성을 갖춘 포괄적인 로깅 시스템을 도입했습니다:

로그 파일 구조 (v0.5.0의 새로운 기능):

logs/
├── doris_mcp_server_debug.log      # DEBUG level messages
├── doris_mcp_server_info.log       # INFO level messages  
├── doris_mcp_server_warning.log    # WARNING level messages
├── doris_mcp_server_error.log      # ERROR level messages
├── doris_mcp_server_critical.log   # CRITICAL level messages
├── doris_mcp_server_all.log        # Combined log (all levels)
└── doris_mcp_server_audit.log      # Audit trail (separate)

향상된 로깅 기능:

수준 기반 파일 분리: 더 쉬운 문제 해결을 위해 로그 수준별 자동 구성
타임스탬프 형식: 전문적인 로깅을 위한 적절한 정렬과 밀리초 정밀도
자동 로그 순환: 구성 가능한 파일 크기 제한으로 디스크 공간 문제 방지
백그라운드 정리: 구성 가능한 보존 정책을 갖춘 지능형 정리 스케줄러
감사 추적: 규정 준수 및 보안 모니터링을 위한 별도의 감사 로깅

로그 보기:

# View real-time logs by level
tail -f logs/doris_mcp_server_info.log     # General operational info
tail -f logs/doris_mcp_server_error.log    # Error tracking
tail -f logs/doris_mcp_server_debug.log    # Detailed debugging

# View all activity in combined log
tail -f logs/doris_mcp_server_all.log

# Monitor specific operations
tail -f logs/doris_mcp_server_info.log | grep -E "(query|connection|tool)"

# View audit trail
tail -f logs/doris_mcp_server_audit.log

구성:

# Enhanced logging configuration in .env
LOG_LEVEL=INFO                         # Base log level
ENABLE_AUDIT=true                      # Enable audit logging
ENABLE_LOG_CLEANUP=true                # Enable automatic cleanup
LOG_MAX_AGE_DAYS=30                    # Keep logs for 30 days
LOG_CLEANUP_INTERVAL_HOURS=24          # Check for cleanup daily

# Advanced settings
LOG_FILE_PATH=logs                     # Log directory (auto-organized)

향상된 로그를 통한 문제 해결:

# Debug connection issues
grep -E "(connection|pool|at_eof)" logs/doris_mcp_server_error.log

# Monitor tool performance
grep "execution_time" logs/doris_mcp_server_info.log

# Check system health
tail -20 logs/doris_mcp_server_warning.log

# View recent critical issues
cat logs/doris_mcp_server_critical.log

로그 정리 관리:

자동: 백그라운드 스케줄러가 LOG_MAX_AGE_DAYS보다 오래된 파일을 제거합니다.
수동: 로그는 10MB에 도달하면 자동으로 순환됩니다.
백업: 각 로그 수준에 대해 5개의 백업 파일을 유지합니다.
성능: 서버 성능에 미치는 영향이 최소화됩니다.

Q: 새로운 토큰 바인딩 데이터베이스 구성을 사용하는 방법은 무엇입니까? (v0.6.0의 새로운 기능)

A: 혁신적인 토큰 바인딩 데이터베이스 구성은 각 토큰이 자체 데이터베이스 연결 매개변수를 지니도록 하여 안전한 멀티 테넌트 접근을 가능하게 합니다:

토큰 인증 활성화:

# In your .env file
ENABLE_TOKEN_AUTH=true
TOKEN_HOT_RELOAD=true
TOKEN_FILE_PATH=tokens.json

tokens.json 구성 생성:

{
  "version": "1.0",
  "tokens": [
    {
      "token_id": "tenant-alpha",
      "token": "tenant_alpha_secure_token_123",
      "description": "Tenant Alpha database access",
      "expires_hours": null,
      "is_active": true,
      "database_config": {
        "host": "tenant-alpha-db.company.com",
        "port": 9030,
        "user": "alpha_user",
        "password": "secure_password",
        "database": "alpha_analytics",
        "charset": "UTF8"
      }
    }
  ]
}

구성 우선순위 (v0.6.0에서 새로 추가):
- 토큰 바인딩 DB 구성 (최우선)
- 환경 변수 (.env)
- 둘 다 사용할 수 없으면 오류
핫 리로드 이점:
- 서비스 재시작 없이 새 테넌트 추가
- 데이터베이스 자격 증명 실시간 업데이트
- 오류 발생 시 자동 검증 및 롤백
- 변경 사항에 대한 완전한 감사 추적

멀티 테넌트 사용법:

# Different tokens access different databases automatically
curl -H "Authorization: Bearer tenant_alpha_secure_token_123" http://localhost:3000/mcp
curl -H "Authorization: Bearer tenant_beta_secure_token_456" http://localhost:3000/mcp

Q: Doris 기반 OAuth는 외부 OAuth/OIDC와 어떻게 다릅니까?

A: 외부 OAuth/OIDC는 Google, Azure AD, GitHub, GitLab 또는 Keycloak과 같은 외부 제공자에게 신원을 위임합니다. Doris 기반 OAuth는 사용자가 Doris 자격 증명으로 로그인한 후 이 MCP 서버가 발급합니다. 서버는 Doris 사용자 이름/비밀번호를 검증하고, 사용자별 Doris 연결 풀을 생성하며, doa_ 액세스 및 갱신 토큰을 발급하고, Doris RBAC가 해당 사용자가 접근할 수 있는 데이터와 메타데이터를 결정하도록 합니다.

이 모드들은 하나의 MCP URL에서 상호 배타적입니다. ENABLE_DORIS_OAUTH_AUTH=true을(를) ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true 또는 AUTH_TYPE=oauth과(와) 함께 활성화하지 마십시오. 두 OAuth 모드가 모두 구성되면 시작이 빠르게 실패합니다.

Doris 기반 OAuth는 현재 리소스 메타데이터 캐시가 비활성화된 상태로 MCP 리소스를 노출합니다. DORIS_OAUTH_DB_TOOLS_ENABLED=true일 때 검토된 메타데이터 도구를, DORIS_OAUTH_QUERY_TOOLS_ENABLED=true일 때 exec_query을(를), 그리고 DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true일 때 SQL explain을 노출합니다. 일반 클라이언트는 긴 범위 목록을 전달할 필요가 없습니다. 생략된 OAuth 범위는 구성된 Doris OAuth 기능 범위를 부여합니다. Doris RBAC는 이러한 MySQL 채널 작업에 대한 최종 데이터 권한 부여 백엔드로 남아 있습니다.

Q: Doris 기반 OAuth를 여러 워커 또는 여러 노드에서 실행할 수 있습니까?

A: 현재 구현에서는 불가능합니다. Doris 기반 OAuth는 메모리 전용 OAuth 저장소와 프로세스 로컬 사용자별 Doris 풀을 사용합니다. 액세스 토큰, 갱신 토큰, 인증 코드, DCR 클라이언트 및 풀은 워커, 프로세스 또는 노드 간에 공유되지 않습니다.

Doris 기반 OAuth와 함께 WORKERS=1을(를) 사용하십시오. WORKERS=0은(는) CPU 수로 확장되어 여러 유효 워커를 생성하므로 실패합니다. 무상태 수평 확장, 공유 토큰 저장소, 공유 암호화 Doris 자격 증명, 고정 세션 복구 및 풀 재구성은 현재 기능이 아닌 향후 설계입니다.

Q: 핫 리로드는 어떻게 작동하며 안전합니까? (v0.6.0에서 새로 추가)

A: 핫 리로드 시스템은 포괄적인 안전 조치를 갖추고 엔터프라이즈 프로덕션 환경을 위해 설계되었습니다:

작동 방식:

파일 모니터링: 10초마다 tokens.json의 수정 사항 확인
즉시 검증: 데이터베이스 연결을 포함하여 새 토큰 검증
원자적 업데이트: 전부 아니면 전무 방식의 구성 업데이트
롤백 보호: 토큰 검증 실패 시 자동 롤백

안전 기능:

백업 및 복원: 변경 전 현재 구성 백업
연결 테스트: 변경 사항 적용 전 데이터베이스 연결 테스트
오류 격리: 유효하지 않은 토큰이 기존 유효 토큰에 영향을 미치지 않음
감사 로깅: 모든 구성 변경에 대한 완전한 추적

모범 사례:

# Monitor hot reload activity
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

# Test configuration before applying
cp tokens.json tokens.json.backup
# Make changes to tokens.json
# System will automatically validate and apply or rollback

Q: 토큰 수명 주기와 보안을 어떻게 관리합니까? (v0.6.0에서 새로 추가)

A: 토큰 관리는 포괄적인 보안 제어 기능을 갖춘 선택적 관리 엔드포인트와 함께 안전한 파일 기반 접근 방식을 사용합니다.

기본 토큰 관리 방법 (권장):

# 1. Edit tokens.json file directly (safest method)
nano tokens.json

# 2. Hot reload will automatically detect changes
# No server restart required - changes applied within 10 seconds

# 3. Monitor hot reload in logs
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

관리 엔드포인트 (보안, 로컬 접근만 가능):

🛡️ 보안: 이 엔드포인트는 포괄적인 보안 제어로 보호되며 기본적으로 비활성화되어 있습니다.

# Security Requirements (ALL must be met):
# ✓ HTTP token management explicitly enabled in configuration
# ✓ Access only from localhost (127.0.0.1/::1) - IP restrictions enforced
# ✓ Valid admin authentication token required
# ✓ Admin authentication enabled in configuration

# Enable HTTP token management (disabled by default)
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export TOKEN_MANAGEMENT_ADMIN_TOKEN=your_secure_admin_token
export REQUIRE_ADMIN_AUTH=true
export TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

# Access with proper authentication
curl -H "Authorization: Bearer your_secure_admin_token" http://127.0.0.1:3000/token/stats

# Demo page (local access only, with authentication)
# Access: http://127.0.0.1:3000/token/demo

권장 토큰 관리 워크플로우:

개발/테스트:

// tokens.json
{
  "version": "1.0",
  "tokens": [
    {
      "token_id": "dev-token",
      "token": "dev_secure_token_123",
      "description": "Development environment access",
      "expires_hours": 24,
      "is_active": true
    }
  ]
}

프로덕션 배포:

# Use secure token generation
openssl rand -hex 32  # Generate secure token

# Store in secure configuration management
# Never commit tokens to version control
# Use environment variables for sensitive tokens

보안 기능:

파일 기반 관리: 보안 구성 파일을 통한 기본 관리
핫 리로드: 서비스 중단 없는 자동 구성 업데이트
토큰 해싱: 내부적으로 SHA-256 해시로 저장된 토큰
감사 추적: 모든 토큰 작업 및 변경에 대한 완전한 로깅
만료 관리: 만료된 토큰 자동 정리
로컬 관리자 전용: 관리 엔드포인트가 localhost 접근으로 제한됨
구성 검증: 토큰 및 데이터베이스 구성의 즉각적인 검증

보안 모범 사례:

항상 안전한 구성 파일을 통해 토큰 관리
토큰 관리 엔드포인트를 외부 네트워크에 노출하지 않음
프로덕션에는 강력하고 무작위로 생성된 토큰 사용
tokens.json에 적절한 파일 권한 구현 (600 또는 640)
활성 토큰 및 사용 패턴 정기 감사
무단 구성 변경에 대한 핫 리로드 로그 모니터링

기타 문제는 GitHub Issues를 확인하거나 새 이슈를 제출해 주십시오.