Apache Doris

chính thức

MCP Server dành cho Apache Doris, một kho dữ liệu thời gian thực dựa trên MPP.

GitHub

314

Bạn có thể làm gì với Apache Doris MCP?

Chạy truy vấn SQL — yêu cầu AI thực thi một câu lệnh SQL trên cơ sở dữ liệu Doris của bạn bằng cách sử dụng exec_query, tùy chọn chỉ định catalog, cơ sở dữ liệu hoặc giới hạn số dòng.
Khám phá siêu dữ liệu cơ sở dữ liệu — liệt kê catalog, cơ sở dữ liệu và bảng bằng get_catalog_list, get_db_list và get_db_table_list, sau đó kiểm tra lược đồ, chỉ mục và chú thích thông qua get_table_schema, get_table_indexes, get_table_comment và get_table_column_comments.
Phân tích hiệu suất truy vấn — truy xuất kế hoạch thực thi và hồ sơ bằng get_sql_explain và get_sql_profile để chẩn đoán các truy vấn chậm hoặc phức tạp.
Giám sát tình trạng cụm — lấy thống kê bộ nhớ thời gian thực và lịch sử, định nghĩa chỉ số giám sát và chỉ số nút thực tế bằng cách sử dụng get_realtime_memory_stats, get_historical_memory_stats, get_monitoring_metrics_info và get_monitoring_metrics_data.
Kiểm tra nhật ký kiểm toán và mẫu truy cập — xem lại nhật ký kiểm toán gần đây bằng get_recent_audit_logs và phân tích hành vi truy cập của người dùng thông qua analyze_data_access_patterns.
Chạy truy vấn hiệu suất cao qua Arrow Flight SQL — thực thi các truy vấn có kết quả lớn bằng exec_adbc_query và kiểm tra trạng thái kết nối ADBC bằng get_adbc_connection_info.

Tài liệu

Máy chủ Doris MCP

Doris MCP (Model Context Protocol) Server là một dịch vụ backend được xây dựng bằng Python và FastAPI. Nó triển khai MCP, cho phép các client tương tác với nó thông qua các "Công cụ" (Tools) đã được định nghĩa. Nó được thiết kế chủ yếu để kết nối với cơ sở dữ liệu Apache Doris, có khả năng tận dụng các Mô hình Ngôn ngữ Lớn (LLMs) cho các tác vụ như chuyển đổi truy vấn ngôn ngữ tự nhiên sang SQL (NL2SQL), thực thi truy vấn và thực hiện quản lý và phân tích metadata.

🚀 Có gì mới trong v0.6.0

🔐 Hệ thống Xác thực Doanh nghiệp: Cấu hình cơ sở dữ liệu liên kết token mang tính cách mạng với hỗ trợ xác thực Token, JWT và OAuth toàn diện, cho phép truy cập đa người thuê an toàn với các công tắc kiểm soát chi tiết và mặc định bảo mật cấp doanh nghiệp
⚡ Xác thực Cơ sở dữ liệu Ngay lập tức: Xác thực cấu hình cơ sở dữ liệu thời gian thực tại thời điểm kết nối, loại bỏ việc chặn tại thời điểm truy vấn và cung cấp phản hồi ngay lập tức cho các cấu hình không hợp lệ - đạt được 100% loại bỏ lỗi kết nối ở giai đoạn muộn
🔄 Quản lý Cấu hình Hot Reload: Cập nhật cấu hình không gián đoạn với hot reload thông minh của tokens.json, tự động xác thực lại token và xử lý lỗi toàn diện với cơ chế rollback
🏗️ Kiến trúc Kết nối Nâng cao: Bộ nhớ đệm phiên và tối ưu hóa pool kết nối với việc giảm 60% chi phí kết nối, tái tạo pool thông minh và quản lý tài nguyên tự động
🌐 Khả năng Mở rộng Đa Worker: Mở rộng ngang thực sự với kiến trúc đa worker không trạng thái, phân phối tải hiệu quả và khả năng xử lý đồng thời cấp doanh nghiệp
🔒 Khung Bảo mật Nâng cao: Kiểm soát truy cập toàn diện và xác thực bảo mật SQL với xác thực ngay lập tức, quyền dựa trên vai trò và các mẫu phát hiện injection nâng cao
🛠️ Hệ thống Cấu hình Hợp nhất: Quản lý cấu hình được tinh giản với ưu tiên dòng lệnh hợp lý, cải thiện khả năng tương thích Docker và hỗ trợ triển khai đa nền tảng
📊 Bảng điều khiển Quản lý Token: Quản lý vòng đời token hoàn chỉnh với tạo, thu hồi, thống kê và các dấu vết kiểm toán toàn diện cho quản trị token doanh nghiệp
🌐 Giao diện Quản lý Dựa trên Web: Quản trị token chỉ trên localhost an toàn với bảng điều khiển trực quan, cấu hình liên kết cơ sở dữ liệu, hoạt động thời gian thực và kiểm soát truy cập cấp doanh nghiệp

🚀 Cột mốc Quan trọng: v0.6.0 thiết lập nền tảng như một hệ thống xác thực và quản lý cơ sở dữ liệu doanh nghiệp sẵn sàng cho sản xuất với hoạt động không gián đoạn (hot reload + xác thực ngay lập tức + mở rộng đa worker), kiểm soát bảo mật nâng cao và cấu hình cơ sở dữ liệu liên kết token toàn diện - đại diện cho một bước tiến cơ bản trong khả năng nền tảng dữ liệu doanh nghiệp.

Những gì cũng được bao gồm từ v0.5.1

🔥 Sửa lỗi Kết nối at_eof Quan trọng: Loại bỏ hoàn toàn lỗi pool kết nối với giám sát tình trạng thông minh và phục hồi tự phục hồi
🔧 Hệ thống Ghi nhật ký Doanh nghiệp: Phân tách tệp dựa trên cấp độ với tự động dọn dẹp và dấu thời gian chính xác đến mili giây
📊 Bộ Phân tích Dữ liệu Nâng cao: 7 công cụ quản trị dữ liệu cấp doanh nghiệp bao gồm phân tích chất lượng, theo dõi dòng dữ liệu và giám sát hiệu suất
🏃‍♂️ Tích hợp ADBC Hiệu suất Cao: Hỗ trợ Apache Arrow Flight SQL với cải thiện hiệu suất gấp 3-10 lần cho các tập dữ liệu lớn
⚙️ Quản lý Cấu hình Nâng cao: Hệ thống cấu hình ADBC hoàn chỉnh với xác thực tham số thông minh

Tính năng Cốt lõi

Triển khai Giao thức MCP: Cung cấp các giao diện MCP tiêu chuẩn, hỗ trợ gọi công cụ, quản lý tài nguyên và tương tác prompt.
Giao tiếp HTTP Có thể Truyền phát: Điểm cuối HTTP hợp nhất hỗ trợ cả giao tiếp yêu cầu/phản hồi và truyền phát để có hiệu suất và độ tin cậy tối ưu.
Giao tiếp Stdio: Chế độ đầu vào/đầu ra tiêu chuẩn để tích hợp trực tiếp với các client MCP như Cursor.
Kiến trúc Cấp Doanh nghiệp: Thiết kế mô-đun với chức năng toàn diện:
- Trình quản lý Công cụ: Đăng ký và định tuyến công cụ tập trung với các giao diện hợp nhất (doris_mcp_server/tools/tools_manager.py)
- Mô-đun Công cụ Giám sát Nâng cao: Theo dõi bộ nhớ nâng cao, thu thập số liệu và khám phá nút BE linh hoạt với thiết kế mô-đun, có thể mở rộng
- Công cụ Thông tin Truy vấn: Giải thích SQL và lập hồ sơ nâng cao với cắt bớt nội dung có thể cấu hình, xuất tệp cho tệp đính kèm LLM và phân tích truy vấn nâng cao
- Trình quản lý Tài nguyên: Quản lý tài nguyên và hiển thị metadata (doris_mcp_server/tools/resources_manager.py)
- Trình quản lý Prompt: Mẫu prompt thông minh cho phân tích dữ liệu (doris_mcp_server/tools/prompts_manager.py)
Tính năng Cơ sở dữ liệu Nâng cao:
- Thực thi Truy vấn: Thực thi SQL hiệu suất cao với bộ nhớ đệm và tối ưu hóa nâng cao, độ ổn định kết nối được tăng cường và cơ chế thử lại tự động (doris_mcp_server/utils/query_executor.py)
- Quản lý Bảo mật: Xác thực bảo mật SQL toàn diện với từ khóa bị chặn có thể cấu hình, bảo vệ chống SQL injection, che dữ liệu và quản lý cấu hình bảo mật hợp nhất (doris_mcp_server/utils/security.py)
- Trích xuất Metadata: Metadata cơ sở dữ liệu toàn diện với hỗ trợ liên kết catalog (doris_mcp_server/utils/schema_extractor.py)
- Phân tích Hiệu suất: Phân tích cột nâng cao, giám sát hiệu suất và các công cụ phân tích dữ liệu (doris_mcp_server/utils/analysis_tools.py)
Hỗ trợ Liên kết Catalog: Hỗ trợ đầy đủ cho môi trường đa catalog (bảng Doris nội bộ và các nguồn dữ liệu bên ngoài như Hive, MySQL, v.v.)
Bảo mật Doanh nghiệp: Khung bảo mật toàn diện với xác thực, ủy quyền, bảo vệ chống SQL injection và khả năng che dữ liệu với hỗ trợ cấu hình biến môi trường
Quản lý Token Dựa trên Web: Giao diện chỉ trên localhost an toàn cho quản lý vòng đời token hoàn chỉnh với liên kết cơ sở dữ liệu, thống kê thời gian thực và kiểm soát truy cập cấp doanh nghiệp (doris_mcp_server/auth/token_handlers.py)
Khung Cấu hình Hợp nhất: Quản lý cấu hình tập trung thông qua config.py với xác thực toàn diện, đặt tên tham số tiêu chuẩn hóa và xử lý cơ sở dữ liệu mặc định thông minh với dự phòng tự động về information_schema

Yêu cầu Hệ thống

Python: 3.12+
Cơ sở dữ liệu: Chi tiết kết nối Apache Doris (Host, Port, User, Password, Database)

🚀 Bắt đầu Nhanh

Cài đặt từ PyPI

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

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

💡 Tương thích Lệnh: Sau khi cài đặt, cả hai lệnh doris-mcp-server đều có sẵn để tương thích ngược. Bạn có thể sử dụng một trong hai lệnh thay thế cho nhau.

Khởi động Chế độ HTTP Có thể Truyền phát (Dịch vụ Web)

Chế độ giao tiếp chính mang lại hiệu suất và độ tin cậy tối ưu:

# 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

Khởi động Chế độ Stdio (cho Cursor và các client MCP khác)

Chế độ đầu vào/đầu ra tiêu chuẩn để tích hợp trực tiếp với các client MCP:

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

🌐 Giao diện Quản lý Token (Mới trong v0.6.0)

Truy cập Bảng điều khiển Quản lý Token Dựa trên Web để quản trị token cấp doanh nghiệp:

Yêu cầu Truy cập An toàn

Chỉ Truy cập Localhost: Giao diện bị giới hạn ở 127.0.0.1 và ::1 để bảo mật tối đa
Xác thực Quản trị viên: Yêu cầu TOKEN_MANAGEMENT_ADMIN_TOKEN để truy cập

Điều kiện Tiên quyết về Cấu hình:

# 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

Truy cập Giao diện

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

Hoạt động Có sẵn

📊 Thống kê Token: Tổng quan thời gian thực về token đang hoạt động, đã hết hạn và tổng số
➕ Tạo Token:
- Thông tin cơ bản (ID, mô tả, hết hạn)
- Liên kết cơ sở dữ liệu (host, port, user, password, database)
- Giá trị token tùy chỉnh hoặc token an toàn được tạo tự động
📋 Quản lý Token:
- Liệt kê tất cả token với trạng thái liên kết cơ sở dữ liệu
- Thu hồi token chỉ với một cú nhấp chuột
- Tự động dọn dẹp token đã hết hạn
🔒 Bảo mật Doanh nghiệp:
- Tất cả hoạt động yêu cầu xác thực quản trị viên
- Xác thực IP thời gian thực
- Ghi nhật ký kiểm toán đầy đủ
- Tự động lưu trữ vào tokens.json

🔐 Lưu ý Bảo mật: Giao diện được thiết kế chỉ để quản trị localhost. Nó không thể được truy cập từ xa, đảm bảo bảo mật tối đa cho các hoạt động quản lý token.

Xác minh Cài đặt

# Check installation
doris-mcp-server --help

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

Biến Môi trường (Tùy chọn)

Thay vì các đối số dòng lệnh, bạn có thể sử dụng biến môi trường:

# 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

Đối số Dòng lệnh

Lệnh doris-mcp-server hỗ trợ các đối số sau:

Đối số	Mô tả	Mặc định	Bắt buộc
`--transport`	Chế độ truyền tải: `http` hoặc `stdio`	`http`	Không
`--host`	Host máy chủ HTTP (chỉ chế độ HTTP)	`0.0.0.0`	Không
`--port`	Cổng máy chủ HTTP (chỉ chế độ HTTP)	`3000`	Không
`--db-host`	Host cơ sở dữ liệu Doris	`localhost`	Không
`--db-port`	Cổng cơ sở dữ liệu Doris	`9030`	Không
`--db-user`	Tên người dùng cơ sở dữ liệu Doris	`root`	Không
`--db-password`	Mật khẩu cơ sở dữ liệu Doris	-	Có (trừ khi có trong env)

Thiết lập Phát triển

Dành cho các nhà phát triển muốn build từ mã nguồn:

1. Sao chép Kho lưu trữ

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

2. Cài đặt Phụ thuộc

pip install -r requirements.txt

3. Cấu hình Biến Môi trường

Sao chép tệp .env.example sang .env và sửa đổi cài đặt theo môi trường của bạn:

cp .env.example .env

Biến Môi trường Chính:

Kết nối Cơ sở dữ liệu:
- DORIS_HOST: Tên máy chủ cơ sở dữ liệu (mặc định: localhost)
- DORIS_PORT: Cổng cơ sở dữ liệu (mặc định: 9030)
- DORIS_USER: Tên người dùng cơ sở dữ liệu (mặc định: root)
- DORIS_PASSWORD: Mật khẩu cơ sở dữ liệu
- DORIS_DATABASE: Tên cơ sở dữ liệu mặc định (mặc định: information_schema)
- DORIS_MIN_CONNECTIONS: Kích thước tối thiểu của pool kết nối (mặc định: 5)
- DORIS_MAX_CONNECTIONS: Kích thước tối đa của pool kết nối (mặc định: 20)
- DORIS_BE_HOSTS: Các nút BE để giám sát (phân tách bằng dấu phẩy, tùy chọn - tự động phát hiện qua SHOW BACKENDS nếu để trống)
- DORIS_BE_WEBSERVER_PORT: Cổng máy chủ web BE cho các công cụ giám sát (mặc định: 8040)
- FE_ARROW_FLIGHT_SQL_PORT: Cổng Arrow Flight SQL của Frontend cho ADBC (Mới trong v0.5.0)
- BE_ARROW_FLIGHT_SQL_PORT: Cổng Arrow Flight SQL của Backend cho ADBC (Mới trong v0.5.0)
Cấu hình Xác thực (Nâng cao trong v0.6.0):
- ENABLE_TOKEN_AUTH: Bật xác thực dựa trên token (mặc định: false)
- ENABLE_JWT_AUTH: Bật xác thực JWT (mặc định: false)
- ENABLE_OAUTH_AUTH: Bật xác thực OAuth (mặc định: false)
- ENABLE_DORIS_OAUTH_AUTH: Bật xác thực OAuth do Doris hỗ trợ (mặc định: false)
- DORIS_OAUTH_BASE_URL: URL cơ sở công khai được sử dụng bởi các điểm cuối khám phá và token OAuth do Doris hỗ trợ
- TOKEN_FILE_PATH: Đường dẫn đến tệp tokens.json để quản lý token (mặc định: tokens.json)
- TOKEN_HOT_RELOAD: Bật tải lại nóng cấu hình token (mặc định: true)
- DEFAULT_ADMIN_TOKEN: Token quản trị mặc định (có thể tùy chỉnh qua biến môi trường)
- DEFAULT_ANALYST_TOKEN: Token nhà phân tích mặc định (có thể tùy chỉnh qua biến môi trường)
- DEFAULT_READONLY_TOKEN: Token chỉ đọc mặc định (có thể tùy chỉnh qua biến môi trường)
Cấu hình Bảo mật Kế thừa:
- AUTH_TYPE: Loại xác thực kế thừa (token/basic/oauth, không dùng nữa - sử dụng các công tắc riêng lẻ)
- TOKEN_SECRET: Khóa bí mật token kế thừa (thay vào đó hãy sử dụng xác thực dựa trên token)
- ENABLE_SECURITY_CHECK: Bật/tắt xác thực bảo mật SQL (mặc định: true)
- BLOCKED_KEYWORDS: Danh sách các từ khóa SQL bị chặn, phân tách bằng dấu phẩy
- ENABLE_MASKING: Bật che dấu dữ liệu (mặc định: true)
- MAX_RESULT_ROWS: Số hàng kết quả tối đa (mặc định: 10000)
Cấu hình ADBC (Mới trong v0.5.0):
- ADBC_DEFAULT_MAX_ROWS: Số hàng tối đa mặc định cho truy vấn ADBC (mặc định: 100000)
- ADBC_DEFAULT_TIMEOUT: Thời gian chờ truy vấn ADBC mặc định tính bằng giây (mặc định: 60)
- ADBC_DEFAULT_RETURN_FORMAT: Định dạng trả về mặc định - arrow/pandas/dict (mặc định: arrow)
- ADBC_CONNECTION_TIMEOUT: Thời gian chờ kết nối ADBC tính bằng giây (mặc định: 30)
- ADBC_ENABLED: Bật/tắt công cụ ADBC (mặc định: true)
Cấu hình Hiệu suất:
- ENABLE_QUERY_CACHE: Bật bộ nhớ đệm truy vấn (mặc định: true)
- CACHE_TTL: Thời gian sống của bộ nhớ đệm tính bằng giây (mặc định: 300)
- MAX_CONCURRENT_QUERIES: Số lượng truy vấn đồng thời tối đa (mặc định: 50)
- MAX_RESPONSE_CONTENT_SIZE: Kích thước nội dung phản hồi tối đa để tương thích LLM (mặc định: 4096, Mới trong v0.4.0)
Cấu hình Ghi nhật ký Nâng cao (Cải thiện trong v0.5.0):
- LOG_LEVEL: Mức ghi nhật ký (DEBUG/INFO/WARNING/ERROR, mặc định: INFO)
- LOG_FILE_PATH: Đường dẫn tệp nhật ký (tự động tổ chức theo mức)
- ENABLE_AUDIT: Bật ghi nhật ký kiểm toán (mặc định: true)
- ENABLE_LOG_CLEANUP: Bật tự động dọn dẹp nhật ký (mặc định: true, Nâng cao trong v0.5.0)
- LOG_MAX_AGE_DAYS: Tuổi tối đa của tệp nhật ký tính bằng ngày (mặc định: 30, Nâng cao trong v0.5.0)
- LOG_CLEANUP_INTERVAL_HOURS: Khoảng thời gian kiểm tra dọn dẹp nhật ký tính bằng giờ (mặc định: 24, Nâng cao trong v0.5.0)
- Tính năng Mới trong v0.5.0:
  - Phân tách Tệp theo Mức: Tự động phân tách thành debug.log, info.log, warning.log, error.log, critical.log
  - Định dạng Dấu thời gian: Định dạng nâng cao với độ chính xác mili giây và căn chỉnh phù hợp
  - Trình lập lịch Dọn dẹp Nền: Tự động dọn dẹp với chính sách lưu giữ có thể cấu hình
  - Dấu vết Kiểm toán: audit.log chuyên dụng với quản lý lưu giữ riêng biệt
  - Tối ưu Hiệu suất: Ghi nhật ký bất đồng bộ với chi phí tối thiểu, hỗ trợ xoay vòng

Công cụ MCP Khả dụng

Bảng sau liệt kê các công cụ chính hiện có sẵn để gọi thông qua một máy khách MCP:

Tên Công cụ	Mô tả	Tham số
`exec_query`	Thực thi truy vấn SQL và trả về kết quả.	`sql` (chuỗi, Bắt buộc), `db_name` (chuỗi, Tùy chọn), `catalog_name` (chuỗi, Tùy chọn), `max_rows` (số nguyên, Tùy chọn), `timeout` (số nguyên, Tùy chọn)
`get_table_schema`	Lấy thông tin cấu trúc bảng chi tiết.	`table_name` (chuỗi, Bắt buộc), `db_name` (chuỗi, Tùy chọn), `catalog_name` (chuỗi, Tùy chọn)
`get_db_table_list`	Lấy danh sách tất cả tên bảng trong cơ sở dữ liệu được chỉ định.	`db_name` (chuỗi, Tùy chọn), `catalog_name` (chuỗi, Tùy chọn)
`get_db_list`	Lấy danh sách tất cả tên cơ sở dữ liệu.	`catalog_name` (chuỗi, Tùy chọn)
`get_table_comment`	Lấy thông tin chú thích bảng.	`table_name` (chuỗi, Bắt buộc), `db_name` (chuỗi, Tùy chọn), `catalog_name` (chuỗi, Tùy chọn)
`get_table_column_comments`	Lấy thông tin chú thích cho tất cả các cột trong bảng.	`table_name` (chuỗi, Bắt buộc), `db_name` (chuỗi, Tùy chọn), `catalog_name` (chuỗi, Tùy chọn)
`get_table_indexes`	Lấy thông tin chỉ mục cho bảng được chỉ định.	`table_name` (chuỗi, Bắt buộc), `db_name` (chuỗi, Tùy chọn), `catalog_name` (chuỗi, Tùy chọn)
`get_recent_audit_logs`	Lấy bản ghi nhật ký kiểm toán trong khoảng thời gian gần đây.	`days` (số nguyên, Tùy chọn), `limit` (số nguyên, Tùy chọn)
`get_catalog_list`	Lấy danh sách tất cả tên catalog.	`random_string` (chuỗi, Bắt buộc)
`get_sql_explain`	Lấy kế hoạch thực thi SQL với khả năng cắt bớt nội dung có thể cấu hình và xuất tệp để phân tích LLM.	`sql` (chuỗi, Bắt buộc), `verbose` (boolean, Tùy chọn), `db_name` (chuỗi, Tùy chọn), `catalog_name` (chuỗi, Tùy chọn)
`get_sql_profile`	Lấy hồ sơ thực thi SQL với quản lý nội dung và xuất tệp cho các quy trình tối ưu hóa LLM.	`sql` (chuỗi, Bắt buộc), `db_name` (chuỗi, Tùy chọn), `catalog_name` (chuỗi, Tùy chọn), `timeout` (số nguyên, Tùy chọn)
`get_table_data_size`	Lấy thông tin kích thước dữ liệu bảng qua API HTTP của FE.	`db_name` (chuỗi, Tùy chọn), `table_name` (chuỗi, Tùy chọn), `single_replica` (boolean, Tùy chọn)
`get_monitoring_metrics_info`	Lấy định nghĩa và mô tả các chỉ số giám sát Doris.	`role` (chuỗi, Tùy chọn), `monitor_type` (chuỗi, Tùy chọn), `priority` (chuỗi, Tùy chọn)
`get_monitoring_metrics_data`	Lấy dữ liệu chỉ số giám sát Doris thực tế từ các nút với khả năng phát hiện BE linh hoạt.	`role` (chuỗi, Tùy chọn), `monitor_type` (chuỗi, Tùy chọn), `priority` (chuỗi, Tùy chọn)
`get_realtime_memory_stats`	Lấy thống kê bộ nhớ thời gian thực qua BE Memory Tracker với khả năng phát hiện BE tự động/thủ công.	`tracker_type` (chuỗi, Tùy chọn), `include_details` (boolean, Tùy chọn)
`get_historical_memory_stats`	Lấy thống kê bộ nhớ lịch sử qua giao diện BE Bvar với cấu hình BE linh hoạt.	`tracker_names` (mảng, Tùy chọn), `time_range` (chuỗi, Tùy chọn)
`analyze_data_quality`	Phân tích chất lượng dữ liệu toàn diện kết hợp phân tích tính đầy đủ và phân phối.	`table_name` (chuỗi, Bắt buộc), `analysis_scope` (chuỗi, Tùy chọn), `sample_size` (số nguyên, Tùy chọn), `business_rules` (mảng, Tùy chọn)
`trace_column_lineage`	Theo dõi dòng dữ liệu cột đầu cuối thông qua phân tích SQL và ánh xạ phụ thuộc.	`target_columns` (mảng, Bắt buộc), `analysis_depth` (số nguyên, Tùy chọn), `include_transformations` (boolean, Tùy chọn)
`monitor_data_freshness`	Giám sát độ trễ dữ liệu thời gian thực với ngưỡng độ mới có thể cấu hình.	`table_names` (mảng, Tùy chọn), `freshness_threshold_hours` (số nguyên, Tùy chọn), `include_update_patterns` (boolean, Tùy chọn)
`analyze_data_access_patterns`	Phân tích hành vi người dùng và phát hiện bất thường bảo mật với giám sát mẫu truy cập.	`days` (số nguyên, Tùy chọn), `include_system_users` (boolean, Tùy chọn), `min_query_threshold` (số nguyên, Tùy chọn)
`analyze_data_flow_dependencies`	Phân tích tác động luồng dữ liệu và ánh xạ phụ thuộc giữa các bảng và view.	`target_table` (chuỗi, Tùy chọn), `analysis_depth` (số nguyên, Tùy chọn), `include_views` (boolean, Tùy chọn)
`analyze_slow_queries_topn`	Xác định điểm nghẽn hiệu suất với phân tích truy vấn chậm top-N và các mẫu.	`days` (số nguyên, Tùy chọn), `top_n` (số nguyên, Tùy chọn), `min_execution_time_ms` (số nguyên, Tùy chọn), `include_patterns` (boolean, Tùy chọn)
`analyze_resource_growth_curves`	Lập kế hoạch dung lượng với phân tích tăng trưởng tài nguyên và dự báo xu hướng.	`days` (số nguyên, Tùy chọn), `resource_types` (mảng, Tùy chọn), `include_predictions` (boolean, Tùy chọn)
`exec_adbc_query`	Thực thi SQL hiệu suất cao sử dụng giao thức ADBC (Arrow Flight SQL).	`sql` (chuỗi, Bắt buộc), `max_rows` (số nguyên, Tùy chọn), `timeout` (số nguyên, Tùy chọn), `return_format` (chuỗi, Tùy chọn)
`get_adbc_connection_info`	Chẩn đoán kết nối ADBC và giám sát trạng thái cho Arrow Flight SQL.	Không yêu cầu tham số

Lưu ý: Tất cả các công cụ metadata đều hỗ trợ liên kết catalog cho môi trường đa catalog. Các công cụ giám sát nâng cao cung cấp khả năng theo dõi bộ nhớ và thu thập chỉ số toàn diện. Mới trong v0.5.0: 7 công cụ phân tích nâng cao cho quản trị dữ liệu doanh nghiệp và 2 công cụ ADBC để truyền dữ liệu hiệu suất cao với cải thiện hiệu suất gấp 3-10 lần cho các tập dữ liệu lớn.

Lưu ý về OAuth do Doris hỗ trợ: Bảng trên mô tả các khả năng toàn cục của máy chủ. OAuth do Doris hỗ trợ sử dụng các cổng cấu hình cho bề mặt hoạt động của nó. Các tài nguyên MCP khả dụng với bộ nhớ đệm metadata tài nguyên bị tắt. Các công cụ metadata đã xem xét có thể được gọi khi DORIS_OAUTH_DB_TOOLS_ENABLED=true; exec_query và get_sql_explain có thể được gọi khi các cổng truy vấn/giải thích OAuth Doris của chúng được bật. Các hoạt động kênh MySQL này chạy thông qua pool người dùng Doris đã đăng nhập, vì vậy RBAC của Doris là phần phụ trợ ủy quyền dữ liệu cuối cùng. Các prompt, ADBC, hồ sơ/giám sát HTTP FE, kiểm toán/quản trị và phân tích hiệu suất vẫn bị đóng cho đến khi chúng có định tuyến theo người dùng hoặc thiết kế tài khoản dịch vụ/quản trị viên rõ ràng.

4. Chạy Dịch vụ

Thực thi lệnh sau để khởi động máy chủ:

./start_server.sh

Lệnh này khởi động ứng dụng FastAPI với dịch vụ MCP HTTP có thể truyền trực tuyến.

5. Triển khai trên docker

Nếu bạn chỉ muốn chạy Máy chủ Doris MCP trong docker:

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

Điểm cuối Dịch vụ:

HTTP có thể truyền trực tuyến: http://<host>:<port>/mcp (Điểm cuối MCP chính - hỗ trợ GET, POST, DELETE, OPTIONS)
Kiểm tra Sức khỏe: http://<host>:<port>/health

Lưu ý: Máy chủ sử dụng HTTP có thể truyền trực tuyến cho giao tiếp dựa trên web, cung cấp khả năng yêu cầu/phản hồi và truyền trực tuyến thống nhất.

Cách sử dụng

Tương tác với Máy chủ Doris MCP yêu cầu một Máy khách MCP. Máy khách kết nối đến điểm cuối HTTP có thể truyền trực tuyến của máy chủ và gửi yêu cầu theo đặc tả MCP để gọi các công cụ của máy chủ.

Luồng Tương tác Chính:

Khởi tạo Client: Gửi lời gọi phương thức initialize đến /mcp (Streamable HTTP).
(Tùy chọn) Khám phá Công cụ: Client có thể gọi tools/list để lấy danh sách các công cụ được hỗ trợ, mô tả và lược đồ tham số của chúng.
Gọi Công cụ: Client gửi yêu cầu tools/call, chỉ định name và arguments.
- Ví dụ: Lấy Lược đồ Bảng
  - name: get_table_schema
  - arguments: Bao gồm table_name, db_name, catalog_name.
Xử lý Phản hồi:
- Không phân luồng: Client nhận phản hồi chứa content hoặc isError.
- Phân luồng: Client nhận một loạt thông báo tiến trình, tiếp theo là phản hồi cuối cùng.

Hỗ trợ Liên kết Catalog

Doris MCP Server hỗ trợ liên kết catalog, cho phép tương tác với nhiều catalog dữ liệu (bảng Doris nội bộ và các nguồn dữ liệu bên ngoài như Hive, MySQL, v.v.) trong một giao diện thống nhất.

Các Tính năng Chính:

Truy cập Metadata Đa Catalog: Tất cả các công cụ metadata (get_db_list, get_db_table_list, get_table_schema, v.v.) hỗ trợ tham số catalog_name tùy chọn để truy vấn các catalog cụ thể.
Truy vấn SQL Liên Catalog: Thực thi các truy vấn SQL trải dài nhiều catalog bằng cách đặt tên bảng ba phần.
Khám phá Catalog: Sử dụng get_catalog_list để khám phá các catalog có sẵn và loại của chúng.

Yêu cầu Đặt tên Ba Phần:

Tất cả các truy vấn SQL PHẢI sử dụng cách đặt tên ba phần cho tham chiếu bảng:

Bảng Nội bộ: internal.database_name.table_name
Bảng Bên ngoài: catalog_name.database_name.table_name

Ví dụ:

Lấy Catalog Có sẵn:

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

Lấy Cơ sở dữ liệu trong Catalog Cụ thể:

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

Truy vấn Catalog Nội bộ:

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

Truy vấn Catalog Bên ngoài:

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

Truy vấn Liên Catalog:

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

Cấu hình Bảo mật

Doris MCP Server bao gồm một khung bảo mật toàn diện cấp doanh nghiệp với xác thực nâng cao, ủy quyền, xác thực bảo mật SQL và khả năng che dữ liệu được tăng cường trong v0.6.0.

Các Tính năng Bảo mật (Tăng cường trong v0.6.0)

🔐 Hệ thống Đa Xác thực: Xác thực Token, JWT và OAuth hoàn chỉnh với các công tắc điều khiển độc lập
🔗 Cấu hình Cơ sở dữ liệu Liên kết Token: Cách tiếp cận mang tính cách mạng cho phép token mang theo các tham số kết nối cơ sở dữ liệu riêng
🔄 Bảo mật Tải lại Nóng: Cập nhật cấu hình bảo mật không gián đoạn với xác thực lại token thông minh
⚡ Xác thực Tức thì: Xác thực cơ sở dữ liệu và xác thực người dùng theo thời gian thực tại thời điểm kết nối
🛡️ Ủy quyền Dựa trên Vai trò: RBAC nâng cao với phân loại bảo mật bốn cấp
🚫 Bảo mật SQL Nâng cao: Bảo vệ chống SQL injection tiên tiến với phát hiện mẫu được cải thiện
🎭 Che Dữ liệu Thông minh: Tự động che dữ liệu nhạy cảm với quyền dựa trên người dùng
📊 Phân tích Bảo mật: Nhật ký kiểm tra toàn diện và giám sát bảo mật

Cấu hình Xác thực (v0.6.0)

Cấu hình hệ thống xác thực mới với kiểm soát chi tiết:

# 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

Xác thực OAuth do Doris Hỗ trợ

OAuth do Doris hỗ trợ là một chế độ OAuth riêng biệt, trong đó chính Doris là phần phụ trợ ủy quyền. MCP client khám phá metadata OAuth của máy chủ này, người dùng đăng nhập bằng tên người dùng và mật khẩu Doris, máy chủ xác thực những thông tin đó bằng cách tạo một nhóm kết nối Doris cho mỗi người dùng, và các token truy cập doa_ đã phát hành sẽ định tuyến các lời gọi công cụ thông qua nhóm Doris của người dùng đó. Phạm vi MCP kiểm soát những thao tác MCP nào có thể được gọi; RBAC của Doris kiểm soát những catalog, cơ sở dữ liệu, bảng và metadata nào mà người dùng có thể thấy.

Chế độ này không giống với OAuth/OIDC bên ngoài. ENABLE_DORIS_OAUTH_AUTH=true xung đột với ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true và AUTH_TYPE=oauth cũ; khởi động sẽ thất bại nhanh nếu cả hai chế độ được cấu hình. Một tác nhân MCP tiêu chuẩn nhập một URL MCP và sẽ khám phá chính xác một hành vi OAuth cho URL đó, vì vậy luồng đăng nhập OAuth bên ngoài /auth/* hiện có không được sử dụng trong chế độ OAuth do Doris hỗ trợ.

Cấu hình Cục bộ Tối thiểu

Ví dụ sau dành cho phát triển cục bộ trên một worker duy nhất:

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

Tài khoản dịch vụ Doris đã cấu hình vẫn được yêu cầu bởi xác thực khởi động và bởi các đường dẫn tương thích không phải Doris-OAuth. Các yêu cầu OAuth do Doris hỗ trợ sẽ bị đóng khi thất bại nếu thiếu nhóm cho mỗi người dùng và không được phép quay trở lại tài khoản dịch vụ/toàn cục.

Truy cập Công cụ OAuth của Doris

DORIS_OAUTH_DB_TOOLS_ENABLED=true mở nhóm metadata đã được xem xét. Các công cụ đã được xem xét là:

get_db_list
get_db_table_list
get_table_schema
get_table_comment
get_table_column_comments
get_table_indexes
get_catalog_list

Đối với các luồng OAuth MCP thông thường, client không cần truyền danh sách --scopes dài. Nếu yêu cầu OAuth bỏ qua phạm vi, máy chủ sẽ cấp phong bì khả năng OAuth của Doris đã cấu hình. Đối với các hoạt động kênh MySQL, RBAC của Doris quyết định liệu người dùng Doris đã đăng nhập có thực sự có thể đọc metadata, chạy SQL hoặc giải thích SQL hay không.

DORIS_OAUTH_QUERY_TOOLS_ENABLED=true mở exec_query. DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true mở get_sql_explain. Nếu ENABLE_SECURITY_CHECK=true, lớp bảo mật SQL MCP cũ vẫn có thể từ chối một số SQL trước khi Doris nhìn thấy. Đặt ENABLE_SECURITY_CHECK=false khi chính sách dự định là để RBAC của Doris quyết định SQL/DDL/DML.

OAuth do Doris hỗ trợ vẫn không mở các lời nhắc, ADBC, hồ sơ/giám sát FE HTTP, kiểm toán/quản trị hoặc phân tích hiệu suất trong giai đoạn này trừ khi các đường dẫn đó được định tuyến riêng qua thông tin xác thực của từng người dùng hoặc được cấp quyền quản trị/tài khoản dịch vụ rõ ràng.

Giới hạn Hoạt động Hiện tại

OAuth do Doris hỗ trợ hiện là quy trình đơn và worker đơn:

WORKERS=1 là bắt buộc. WORKERS=0 mở rộng thành số lượng CPU và thất bại khi OAuth do Doris hỗ trợ được bật.
Client OAuth, giao dịch ủy quyền, mã ủy quyền, token truy cập, token làm mới và client DCR chỉ nằm trong bộ nhớ và cục bộ theo quy trình.
Nhóm kết nối Doris cho mỗi người dùng là cục bộ theo quy trình.
Khởi động lại quy trình yêu cầu người dùng đăng nhập lại.
Token và nhóm không được chia sẻ giữa các worker, quy trình hoặc nút.
Mở rộng quy mô theo chiều ngang không trạng thái và triển khai đa nút chưa được hỗ trợ cho OAuth do Doris hỗ trợ.

Nếu token truy cập hợp lệ nhưng nhóm người dùng Doris của nó không còn, yêu cầu sẽ thất bại với yêu cầu đăng nhập / DORIS_OAUTH_POOL_MISSING. Máy chủ không lưu trữ mật khẩu Doris thô để tự động tái tạo nhóm.

Tăng cường cho Sản xuất

Đối với triển khai sản xuất:

Sử dụng HTTPS DORIS_OAUTH_BASE_URL cho bất kỳ địa chỉ không phải loopback nào.
Giữ DORIS_OAUTH_ALLOW_INSECURE_HTTP=false; http:// không phải loopback bị từ chối trừ khi được ghi đè rõ ràng cho phát triển.
Chỉ bật DORIS_OAUTH_TRUST_PROXY_HEADERS đằng sau một reverse proxy được kiểm soát và đặt DORIS_OAUTH_TRUSTED_PROXY_CIDRS.
Giữ giới hạn tốc độ đăng nhập, ủy quyền, token, làm mới, thu hồi và DCR được bật.
Sử dụng RBAC của Doris làm ranh giới ủy quyền dữ liệu cuối cùng và chỉ cấp cho người dùng Doris dữ liệu họ nên kiểm tra.
Không ghi nhật ký mật khẩu Doris, tiêu đề ủy quyền, token truy cập, token làm mới, mã ủy quyền, trình xác minh PKCE hoặc bí mật client.
Coi tiền tố doa_ là dành riêng cho token truy cập OAuth do Doris hỗ trợ; token tĩnh và giá trị bearer JWT không được sử dụng nó.
Giữ Đăng ký Client Động ở auto cho phát triển loopback hoặc cấu hình rõ ràng DCR sản xuất với ENABLE_DORIS_OAUTH_PRODUCTION_DCR=true.

Cấu hình Cơ sở dữ liệu Liên kết Token (Mới trong v0.6.0)

Tạo tệp tokens.json để quản lý token nâng cao với liên kết cơ sở dữ liệu:

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

Cập nhật Cấu hình Tải lại Nóng (Mới trong v0.6.0)

Hệ thống tự động phát hiện và áp dụng các thay đổi cấu hình:

Phát hiện Tự động: Giám sát sửa đổi tệp mỗi 10 giây
Xác thực Tức thì: Xác thực cấu hình cơ sở dữ liệu ngay lập tức cho token mới
Không Gián đoạn: Cập nhật cấu hình mà không làm gián đoạn dịch vụ
Bảo vệ Hoàn tác: Tự động hoàn tác khi có lỗi cấu hình
Nhật ký Kiểm tra: Ghi nhật ký đầy đủ các thay đổi cấu hình

Ví dụ Xác thực Token

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

Ví dụ Xác thực Cơ bản

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

Ủy quyền & Cấp độ Bảo mật

Hệ thống hỗ trợ bốn cấp độ bảo mật với kiểm soát truy cập phân cấp:

Cấp độ Bảo mật	Phạm vi Truy cập	Trường hợp Sử dụng Điển hình
Công khai	Truy cập không hạn chế	Báo cáo công khai, thống kê chung
Nội bộ	Nhân viên công ty	Bảng điều khiển nội bộ, chỉ số kinh doanh
Bảo mật	Nhân sự được ủy quyền	Dữ liệu khách hàng, báo cáo tài chính
Tuyệt mật	Quản lý cấp cao	Dữ liệu chiến lược, phân tích nhạy cảm

Cấu hình Vai trò

Cấu hình vai trò và quyền của người dùng:

# 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": ["*"]
    }
}

Xác thực Bảo mật SQL

Hệ thống tự động xác thực các truy vấn SQL để phát hiện rủi ro bảo mật:

Các Hoạt động bị Chặn

Cấu hình các hoạt động SQL bị chặn bằng biến môi trường (Mới trong 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

Từ khóa Bị chặn Mặc định (Thống nhất trong v0.4.2):

Hoạt động DDL: DROP, CREATE, ALTER, TRUNCATE
Hoạt động DML: DELETE, INSERT, UPDATE
Hoạt động DCL: GRANT, REVOKE
Hoạt động Hệ thống: EXEC, EXECUTE, SHUTDOWN, KILL

Bảo vệ SQL Injection

Hệ thống tự động phát hiện và chặn:

SQL injection dựa trên Union: Các cuộc tấn công UNION SELECT
SQL injection dựa trên Boolean: Các mẫu OR 1=1
SQL injection dựa trên Thời gian: Các hàm SLEEP(), WAITFOR
SQL injection dựa trên Chú thích: Các mẫu --, /**/
Truy vấn xếp chồng: Nhiều câu lệnh được phân tách bằng ;

Ví dụ Xác thực Bảo mật

# 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'"

Cấu hình Che Dữ liệu

Cấu hình tự động che dữ liệu cho thông tin nhạy cảm:

Quy tắc Che Tích hợp sẵn

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

Thuật toán Che

Thuật toán	Mô tả	Ví dụ
`phone_mask`	Che số điện thoại	`138****5678`
`email_mask`	Che địa chỉ email	`j***n@example.com`
`id_mask`	Che số chứng minh nhân dân	`110101****1234`
`name_mask`	Che tên cá nhân	`张*明`
`partial_mask`	Che một phần với tỷ lệ	`abc***xyz`

Quy tắc Che Tùy chỉnh

Thêm quy tắc che tùy chỉnh trong cấu hình của bạn:

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

Ví dụ Cấu hình Bảo mật

Biến Môi trường

# .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

Cấu hình Bảng Nhạy cảm

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

Thực tiễn Tốt nhất về Bảo mật

🔑 Xác thực Mạnh: Sử dụng token JWT với thời hạn phù hợp
🎯 Nguyên tắc Đặc quyền Tối thiểu: Chỉ cấp các quyền tối thiểu cần thiết
🔍 Kiểm tra Định kỳ: Bật ghi nhật ký kiểm tra để giám sát bảo mật
🛡️ Xác thực Đầu vào: Tất cả các truy vấn SQL được tự động xác thực
🎭 Phân loại Dữ liệu: Phân loại dữ liệu đúng cách với các cấp độ bảo mật
🔄 Cập nhật Thường xuyên: Luôn cập nhật các quy tắc và cấu hình bảo mật
Tăng cường OAuth do Doris Hỗ trợ: Sử dụng HTTPS, giữ OAuth bên ngoài bị tắt trong chế độ này, giữ WORKERS=1, dựa vào RBAC của Doris để truy cập dữ liệu kênh MySQL và chỉ hiển thị các hoạt động được cấu hình và xác minh để sử dụng thông tin xác thực của người dùng Doris đã đăng nhập.

Giám sát Bảo mật

Hệ thống cung cấp giám sát bảo mật toàn diện:

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

⚠️ Quan trọng: Luôn kiểm tra cấu hình bảo mật trong môi trường phát triển trước khi triển khai lên sản xuất. Thường xuyên xem xét và cập nhật các chính sách bảo mật dựa trên yêu cầu của tổ chức bạn.

Kết nối với Cursor

Bạn có thể kết nối Cursor với máy chủ MCP này bằng chế độ Stdio (khuyến nghị) hoặc chế độ Streamable HTTP.

Chế độ Stdio

Chế độ Stdio cho phép Cursor quản lý trực tiếp quy trình máy chủ. Cấu hình được thực hiện trong tệp cài đặt MCP Server của Cursor (thường là ~/.cursor/mcp.json hoặc tương tự).

Phương pháp 1: Sử dụng Cài đặt PyPI (Khuyến nghị)

Cài đặt gói từ PyPI và cấu hình Cursor để sử dụng:

pip install doris-mcp-server

Cấu hình Cursor: Thêm một mục như sau vào cấu hình Cursor MCP của bạn:

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

Phương pháp 2: Sử dụng uv (Phát triển)

Nếu bạn đã cài đặt uv và muốn chạy từ mã nguồn:

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

Lưu ý: Thay thế /path/to/doris-mcp-server bằng đường dẫn tuyệt đối thực tế đến thư mục dự án của bạn.

Cấu hình Cursor: Thêm một mục như sau vào cấu hình Cursor MCP của bạn:

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

Chế độ HTTP có thể truyền trực tuyến

Chế độ HTTP có thể truyền trực tuyến yêu cầu bạn chạy máy chủ MCP độc lập trước, sau đó cấu hình Cursor để kết nối đến nó.

Cấu hình .env: Đảm bảo thông tin xác thực cơ sở dữ liệu và bất kỳ cài đặt cần thiết nào khác được cấu hình chính xác trong tệp .env trong thư mục dự án.
Khởi động Máy chủ: Chạy máy chủ từ terminal của bạn trong thư mục gốc của dự án:
```
./start_server.sh
```
Tập lệnh này đọc tệp .env và khởi động máy chủ FastAPI với hỗ trợ HTTP có thể truyền trực tuyến. Lưu ý máy chủ và cổng mà máy chủ đang lắng nghe (mặc định là 0.0.0.0:3000).
Cấu hình Cursor: Thêm một mục như sau vào cấu hình Cursor MCP của bạn, trỏ đến điểm cuối HTTP có thể truyền trực tuyến của máy chủ đang chạy:
```
{
  "mcpServers": {
    "doris-http": {
       "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```
Lưu ý: Điều chỉnh máy chủ/cổng nếu máy chủ của bạn chạy trên một địa chỉ khác. Điểm cuối /mcp là giao diện HTTP có thể truyền trực tuyến thống nhất.

Sau khi cấu hình một trong hai chế độ trong Cursor, bạn sẽ có thể chọn máy chủ (ví dụ: doris-stdio hoặc doris-http) và sử dụng các công cụ của nó.

Kết nối với Kiro

Hoặc thêm phần sau vào tệp cấu hình Kiro MCP của bạn (~/.kiro/settings/mcp.json cho toàn cục, hoặc .kiro/settings/mcp.json cho phạm vi dự án). Xem tài liệu Kiro MCP để biết thêm chi tiết.

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

Cấu trúc Thư mục

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

Phát triển Công cụ Mới

Phần này phác thảo quy trình thêm công cụ MCP mới vào Máy chủ Doris MCP, dựa trên kiến trúc mô-đun thống nhất với quản lý công cụ tập trung.

1. Tận dụng các Mô-đun Tiện ích Hiện có

Máy chủ cung cấp các mô-đun tiện ích toàn diện cho các thao tác cơ sở dữ liệu phổ biến:

doris_mcp_server/utils/db.py: Quản lý kết nối cơ sở dữ liệu với pooling kết nối và giám sát tình trạng.
doris_mcp_server/utils/query_executor.py: Thực thi SQL hiệu suất cao với bộ nhớ đệm nâng cao, tối ưu hóa và giám sát hiệu suất.
doris_mcp_server/utils/schema_extractor.py: Trích xuất siêu dữ liệu với hỗ trợ liên kết catalog đầy đủ.
doris_mcp_server/utils/security.py: Quản lý bảo mật toàn diện, xác thực SQL và che dấu dữ liệu.
doris_mcp_server/utils/analysis_tools.py: Công cụ phân tích dữ liệu và thống kê nâng cao.
doris_mcp_server/utils/config.py: Quản lý cấu hình với xác thực.
doris_mcp_server/utils/data_governance_tools.py: Theo dõi dòng dữ liệu và giám sát độ mới của dữ liệu (Mới trong v0.5.0).
doris_mcp_server/utils/data_quality_tools.py: Khung phân tích chất lượng dữ liệu toàn diện (Mới trong v0.5.0).
doris_mcp_server/utils/adbc_query_tools.py: Thao tác Arrow Flight SQL hiệu suất cao (Mới trong v0.5.0).

2. Triển khai Logic Công cụ

Thêm công cụ mới của bạn vào lớp DorisToolsManager trong doris_mcp_server/tools/tools_manager.py. Trình quản lý công cụ cung cấp cách tiếp cận tập trung để đăng ký và thực thi công cụ với các giao diện thống nhất.

Ví dụ: Thêm một công cụ phân tích mới:

# 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. Đăng ký Công cụ

Thêm công cụ của bạn vào phương thức _register_tools trong cùng một lớp:

# 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. Tính năng Nâng cao

Đối với các công cụ phức tạp hơn, bạn có thể tận dụng khung toàn diện:

Bộ nhớ đệm Nâng cao: Sử dụng bộ nhớ đệm tích hợp của trình thực thi truy vấn để tăng hiệu suất
Bảo mật Doanh nghiệp: Áp dụng xác thực SQL toàn diện và che dấu dữ liệu thông qua trình quản lý bảo mật
Lời nhắc Thông minh: Sử dụng trình quản lý lời nhắc để tạo truy vấn nâng cao
Quản lý Tài nguyên: Hiển thị siêu dữ liệu thông qua trình quản lý tài nguyên
Giám sát Hiệu suất: Tích hợp với các công cụ phân tích để có khả năng giám sát

5. Kiểm thử

Kiểm thử công cụ mới của bạn bằng cách sử dụng máy khách MCP đi kèm:

# 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)

Máy khách MCP

Dự án bao gồm một máy khách MCP thống nhất (doris_mcp_client/) cho mục đích kiểm thử và tích hợp. Máy khách hỗ trợ nhiều chế độ kết nối và cung cấp giao diện thuận tiện để tương tác với máy chủ MCP.

Để biết tài liệu chi tiết về máy khách, xem doris_mcp_client/README.md.

Đóng góp

Hoan nghênh đóng góp thông qua Issues hoặc Pull Requests.

Giấy phép

Dự án này được cấp phép theo Giấy phép Apache 2.0. Xem tệp LICENSE để biết chi tiết.

Câu hỏi Thường gặp

Hỏi: Tại sao Qwen3-32b và các mô hình tham số nhỏ khác luôn thất bại khi gọi công cụ?

Đáp: Đây là một vấn đề phổ biến. Lý do chính là các mô hình này cần hướng dẫn rõ ràng hơn để sử dụng đúng các công cụ MCP. Khuyến nghị thêm lời nhắc hướng dẫn sau cho mô hình:

Phiên bản tiếng Trung：

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

Phiên bản tiếng Anh：

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

Nếu bạn có yêu cầu thêm đối với kết quả trả về, bạn có thể mô tả các yêu cầu cụ thể trong thẻ <output>.

Hỏi: Làm thế nào để cấu hình các kết nối cơ sở dữ liệu khác nhau?

Đáp: Bạn có thể cấu hình kết nối cơ sở dữ liệu theo một số cách:

Biến Môi trường (Khuyến nghị):

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

Tham số Dòng lệnh:

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

Tệp Cấu hình: Sửa đổi các mục cấu hình tương ứng trong tệp .env.

Hỏi: Làm thế nào để cấu hình các nút BE cho các công cụ giám sát?

Đáp: Chọn cấu hình phù hợp dựa trên kịch bản triển khai của bạn:

Mạng Ngoài (Cấu hình Thủ công):

# 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

Mạng Nội bộ (Tự động Khám phá):

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

Hỏi: Làm thế nào để sử dụng các tệp SQL Explain/Profile với LLM để tối ưu hóa?

Đáp: Các công cụ cung cấp cả nội dung rút gọn và tệp đầy đủ để phân tích LLM:

Nhận Kết quả Phân tích:

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

Quy trình Phân tích LLM:
- Xem xét nội dung rút gọn để có thông tin nhanh
- Tải tệp đầy đủ lên LLM của bạn dưới dạng tệp đính kèm
- Yêu cầu đề xuất tối ưu hóa hoặc phân tích hiệu suất
- Triển khai các cải tiến được khuyến nghị

Cấu hình Kích thước Nội dung:

MAX_RESPONSE_CONTENT_SIZE=4096  # Adjust as needed

Hỏi: Làm thế nào để kích hoạt các tính năng bảo mật và che dấu dữ liệu?

Đáp: Đặt các cấu hình sau trong tệp .env của bạn:

# 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

Hỏi: Sự khác biệt giữa chế độ Stdio và chế độ HTTP là gì?

Đáp:

Chế độ Stdio: Phù hợp để tích hợp trực tiếp với các máy khách MCP (như Cursor), nơi máy khách quản lý tiến trình máy chủ
Chế độ HTTP: Dịch vụ web độc lập hỗ trợ nhiều kết nối máy khách, phù hợp cho môi trường sản xuất

Khuyến nghị:

Phát triển và sử dụng cá nhân: Chế độ Stdio
Môi trường sản xuất và đa người dùng: Chế độ HTTP

Hỏi: Làm thế nào để giải quyết các vấn đề timeout kết nối?

Đáp: Thử các giải pháp sau:

Tăng cài đặt timeout:

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

Kiểm tra kết nối mạng:

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

Tối ưu hóa cấu hình pool kết nối:
```
DORIS_MAX_CONNECTIONS=20
```

Hỏi: Làm thế nào để giải quyết lỗi kết nối `at_eof`? (Đã khắc phục hoàn toàn trong v0.5.0)

Đáp: Phiên bản 0.5.0 đã giải quyết hoàn toàn các lỗi kết nối at_eof nghiêm trọng thông qua việc thiết kế lại toàn diện pool kết nối:

Vấn đề:

Lỗi at_eof xảy ra do tạo trước pool kết nối và quản lý trạng thái kết nối không đúng cách
Trạng thái reader MySQL aiomysql trở nên không nhất quán trong vòng đời kết nối
Pool kết nối không ổn định dưới tải đồng thời

Giải pháp (v0.5.0):

Đại tu Chiến lược Pool Kết nối:
- Không có Kết nối Tối thiểu: Thay đổi min_connections từ mặc định thành 0 để ngăn chặn các vấn đề tạo trước
- Tạo Kết nối Theo yêu cầu: Kết nối chỉ được tạo khi cần, loại bỏ các vấn đề kết nối cũ
- Chiến lược Kết nối Mới: Luôn lấy kết nối mới từ pool, không lưu trữ đệm cấp phiên
Giám sát Tình trạng Nâng cao:
- Kiểm tra Tình trạng Dựa trên Timeout: Timeout 3 giây cho các truy vấn xác thực kết nối
- Trình giám sát Tình trạng Nền: Giám sát tình trạng pool liên tục mỗi 30 giây
- Phát hiện Cũ Chủ động: Tự động phát hiện và dọn dẹp các kết nối có vấn đề
Hệ thống Phục hồi Thông minh:
- Tự động Phục hồi Pool: Pool tự phục hồi với xử lý lỗi toàn diện
- Thử lại với Backoff Lũy thừa: Cơ chế thử lại thông minh với tối đa 3 lần thử
- Phát hiện Lỗi Cụ thể cho Kết nối: Xác định chính xác các lỗi liên quan đến kết nối
Tối ưu hóa Hiệu suất:
- Khởi động Pool: Làm nóng pool kết nối thông minh để có hiệu suất tối ưu
- Dọn dẹp Nền: Dọn dẹp định kỳ các kết nối cũ mà không ảnh hưởng đến các thao tác đang hoạt động
- Chẩn đoán Kết nối: Giám sát và báo cáo tình trạng kết nối theo thời gian thực

Giám sát Tình trạng Kết nối:

# 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

Cấu hình cho Hiệu suất Kết nối Tối ưu:

# 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

Kết quả: Loại bỏ 99.9% lỗi at_eof với độ ổn định và hiệu suất kết nối được cải thiện đáng kể.

Hỏi: Làm thế nào để giải quyết các vấn đề tương thích phiên bản thư viện MCP? (Đã khắc phục trong v0.4.2)

Đáp: Phiên bản 0.4.2 đã giới thiệu một lớp tương thích MCP thông minh hỗ trợ cả phiên bản MCP 1.8.x và 1.9.x:

Vấn đề:

MCP 1.9.3 đã giới thiệu các thay đổi phá vỡ đối với lớp RequestContext (thay đổi từ 2 thành 3 tham số generic)
Điều này gây ra lỗi TypeError: Too few arguments for RequestContext

Giải pháp (v0.4.2):

Phát hiện Phiên bản Thông minh: Tự động phát hiện phiên bản MCP đã cài đặt
Lớp Tương thích: Xử lý khéo léo các khác biệt API giữa các phiên bản
Hỗ trợ Phiên bản Linh hoạt: mcp>=1.8.0,<2.0.0 trong các phụ thuộc

Các Phiên bản MCP được Hỗ trợ:

# 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

Thông tin Phiên bản:

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

Nếu bạn gặp lỗi khởi động liên quan đến 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

Hỏi: Làm thế nào để kích hoạt các tính năng hiệu suất cao ADBC? (Mới trong v0.5.0)

Đáp: ADBC (Arrow Flight SQL) cung cấp cải thiện hiệu suất gấp 3-10 lần cho các tập dữ liệu lớn:

Phụ thuộc ADBC (tự động bao gồm trong v0.5.0+):

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

Cấu hình Cổng Arrow Flight SQL:

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

Tùy chỉnh ADBC Tùy chọn:

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

Kiểm tra Kết nối ADBC:

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

Hỏi: Làm thế nào để sử dụng các công cụ phân tích dữ liệu mới? (Mới trong v0.5.0)

Đáp: 7 công cụ phân tích mới cung cấp khả năng quản trị dữ liệu toàn diện:

Phân tích Chất lượng Dữ liệu:

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

Theo dõi Dòng dữ liệu Cột:

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

Giám sát Độ mới của Dữ liệu:

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

Phân tích Hiệu suất:

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

Hỏi: Làm thế nào để sử dụng hệ thống ghi nhật ký nâng cao? (Cải thiện trong v0.5.0)

Đáp: Phiên bản 0.5.0 giới thiệu một hệ thống ghi nhật ký toàn diện với quản lý tự động và tổ chức dựa trên cấp độ:

Cấu trúc Tệp Nhật ký (Mới trong 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)

Các Tính năng Ghi nhật ký Nâng cao:

Phân tách Tệp Dựa trên Cấp độ: Tự động tổ chức theo cấp độ nhật ký để khắc phục sự cố dễ dàng hơn
Định dạng Dấu thời gian: Độ chính xác mili giây với căn chỉnh phù hợp cho ghi nhật ký chuyên nghiệp
Tự động Xoay Nhật ký: Ngăn chặn các vấn đề về dung lượng đĩa với giới hạn kích thước tệp có thể cấu hình
Dọn dẹp Nền: Lập lịch dọn dẹp thông minh với các chính sách lưu giữ có thể cấu hình
Dấu vết Kiểm toán: Ghi nhật ký kiểm toán riêng biệt để tuân thủ và giám sát bảo mật

Xem Nhật ký:

# 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

Cấu hình:

# 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)

Khắc phục Sự cố với Nhật ký Nâng cao:

# 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

Quản lý Dọn dẹp Nhật ký:

Tự động: Trình lập lịch nền xóa các tệp cũ hơn LOG_MAX_AGE_DAYS
Thủ công: Nhật ký được tự động xoay khi đạt 10MB
Sao lưu: Giữ 5 tệp sao lưu cho mỗi cấp độ nhật ký
Hiệu suất: Tác động tối thiểu đến hiệu suất máy chủ

Hỏi: Làm thế nào để sử dụng Cấu hình Cơ sở dữ liệu Ràng buộc Token mới? (Mới trong v0.6.0)

A: Cấu hình cơ sở dữ liệu ràng buộc token mang tính cách mạng cho phép mỗi token mang theo tham số kết nối cơ sở dữ liệu riêng để truy cập đa người thuê an toàn:

Bật Xác thực Token:

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

Tạo tệp cấu hình 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"
      }
    }
  ]
}

Ưu tiên cấu hình (Mới trong v0.6.0):
- Cấu hình DB ràng buộc token (ưu tiên cao nhất)
- Biến môi trường (.env)
- Lỗi nếu không có sẵn
Lợi ích của Hot Reload:
- Thêm người thuê mới mà không cần khởi động lại dịch vụ
- Cập nhật thông tin xác thực cơ sở dữ liệu theo thời gian thực
- Xác thực tự động và hoàn tác khi có lỗi
- Dấu vết kiểm toán đầy đủ các thay đổi

Sử dụng đa người thuê:

# 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

H: OAuth do Doris hậu thuẫn khác với OAuth/OIDC bên ngoài như thế nào?

Đ: OAuth/OIDC bên ngoài ủy quyền danh tính cho nhà cung cấp bên ngoài như Google, Azure AD, GitHub, GitLab hoặc Keycloak. OAuth do Doris hậu thuẫn được cấp bởi máy chủ MCP này sau khi người dùng đăng nhập bằng thông tin xác thực Doris. Máy chủ xác thực tên người dùng/mật khẩu Doris, tạo nhóm kết nối Doris cho mỗi người dùng, cấp doa_ token truy cập và làm mới, đồng thời để Doris RBAC quyết định dữ liệu và siêu dữ liệu mà người dùng đó có thể truy cập.

Các chế độ này loại trừ lẫn nhau trên một URL MCP. Không bật ENABLE_DORIS_OAUTH_AUTH=true cùng với ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true hoặc AUTH_TYPE=oauth; khởi động sẽ thất bại nhanh nếu cả hai chế độ OAuth được cấu hình.

OAuth do Doris hậu thuẫn hiện đang hiển thị tài nguyên MCP với bộ nhớ đệm siêu dữ liệu tài nguyên bị vô hiệu hóa. Nó hiển thị các công cụ siêu dữ liệu đã được xem xét khi DORIS_OAUTH_DB_TOOLS_ENABLED=true, exec_query khi DORIS_OAUTH_QUERY_TOOLS_ENABLED=true, và giải thích SQL khi DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true. Các máy khách thông thường không cần truyền danh sách phạm vi dài; phạm vi OAuth bị bỏ qua sẽ cấp phong bì khả năng OAuth Doris đã cấu hình. Doris RBAC vẫn là phần phụ trợ ủy quyền dữ liệu cuối cùng cho các hoạt động kênh MySQL này.

H: OAuth do Doris hậu thuẫn có thể chạy với nhiều worker hoặc nhiều nút không?

Đ: Không trong triển khai hiện tại. OAuth do Doris hậu thuẫn sử dụng kho lưu trữ OAuth chỉ trong bộ nhớ và các nhóm Doris cục bộ theo tiến trình cho mỗi người dùng. Token truy cập, token làm mới, mã ủy quyền, máy khách DCR và nhóm không được chia sẻ giữa các worker, tiến trình hoặc nút.

Sử dụng WORKERS=1 với OAuth do Doris hậu thuẫn. WORKERS=0 mở rộng thành số lượng CPU và thất bại vì nó sẽ tạo ra nhiều worker hiệu quả. Mở rộng ngang không trạng thái, lưu trữ token chia sẻ, thông tin xác thực Doris được mã hóa chia sẻ, khôi phục phiên dính và tái tạo nhóm là các thiết kế trong tương lai, không phải khả năng hiện tại.

H: Hot Reload hoạt động như thế nào và có an toàn không? (Mới trong v0.6.0)

Đ: Hệ thống hot reload được thiết kế cho môi trường sản xuất doanh nghiệp với các biện pháp an toàn toàn diện:

Cách thức hoạt động:

Giám sát tệp: Kiểm tra tokens.json mỗi 10 giây để phát hiện sửa đổi
Xác thực ngay lập tức: Token mới được xác thực bao gồm kết nối cơ sở dữ liệu
Cập nhật nguyên tử: Cập nhật cấu hình tất cả hoặc không có gì
Bảo vệ hoàn tác: Tự động hoàn tác nếu bất kỳ xác thực token nào thất bại

Tính năng an toàn:

Sao lưu và khôi phục: Cấu hình hiện tại được sao lưu trước khi thay đổi
Kiểm tra kết nối: Kết nối cơ sở dữ liệu được kiểm tra trước khi áp dụng thay đổi
Cô lập lỗi: Token không hợp lệ không ảnh hưởng đến token hợp lệ hiện có
Ghi nhật ký kiểm toán: Dấu vết đầy đủ của tất cả thay đổi cấu hình

Thực hành tốt nhất:

# 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

H: Làm thế nào để quản lý vòng đời và bảo mật Token? (Mới trong v0.6.0)

Đ: Quản lý token sử dụng cách tiếp cận dựa trên tệp an toàn với các điểm cuối quản trị tùy chọn có kiểm soát bảo mật toàn diện.

Phương pháp quản lý token chính (Khuyến nghị):

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

Điểm cuối quản trị (An toàn, chỉ truy cập cục bộ):

🛡️ BẢO MẬT: Các điểm cuối này được bảo vệ bởi kiểm soát bảo mật toàn diện và bị vô hiệu hóa theo mặc định.

# 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

Quy trình quản lý token khuyến nghị:

Phát triển/Kiểm thử:

// 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
    }
  ]
}

Triển khai sản xuất:

# 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

Tính năng bảo mật:

Quản lý dựa trên tệp: Quản lý chính thông qua tệp cấu hình được bảo mật
Hot Reload: Cập nhật cấu hình tự động mà không gián đoạn dịch vụ
Băm token: Token được lưu trữ dưới dạng băm SHA-256 nội bộ
Dấu vết kiểm toán: Ghi nhật ký đầy đủ tất cả hoạt động và thay đổi token
Quản lý hết hạn: Tự động dọn dẹp token hết hạn
Chỉ quản trị cục bộ: Điểm cuối quản lý bị hạn chế truy cập localhost
Xác thực cấu hình: Xác thực ngay lập tức cấu hình token và cơ sở dữ liệu

Thực hành bảo mật tốt nhất:

Luôn quản lý token thông qua tệp cấu hình an toàn
Không bao giờ để lộ điểm cuối quản lý token ra mạng bên ngoài
Sử dụng token mạnh, được tạo ngẫu nhiên cho sản xuất
Triển khai quyền tệp phù hợp cho tokens.json (600 hoặc 640)
Kiểm toán thường xuyên token đang hoạt động và mẫu sử dụng của chúng
Giám sát nhật ký hot reload để phát hiện thay đổi cấu hình trái phép

Đối với các vấn đề khác, vui lòng kiểm tra GitHub Issues hoặc gửi một issue mới.