Apache Doris

Apache Doris MCP Server

English | 简体中文

Apache Doris MCP Server hiển thị các khả năng chỉ-đọc của Apache Doris cho MCP Hosts và các tác nhân AI qua MCP 2026-07-28. Phiên bản 1.0 thay thế bề mặt công cụ phẳng lớn bằng tám miền ổn định và năm mươi lăm khả năng con được tiết lộ dần, đồng thời giữ cho tính khả dụng runtime, ủy quyền, schema đầu vào, schema đầu ra và hành vi lỗi được tường minh.

Trạng thái phát hành

Phiên bản package là 1.0.0. Khả năng tương thích giao thức MCP 2026-07-28 trên master là Generally Available (GA) trên Streamable HTTP và stdio. Tuyên bố GA này chỉ giới hạn ở khả năng tương thích giao thức; bộ phân loại package Python vẫn ở mức Beta và các giới hạn triển khai đã ghi vẫn được áp dụng.

Trước khi nâng cấp, hãy đọc ghi chú phát hành 1.0, hướng dẫn di chuyển 1.0 và registry 8 miền/55 khả năng con được tạo ra. Bản ghi phát hành chi tiết là Issue #189.

Tổng quan kiến trúc

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

Chế độ hierarchical mặc định hiển thị các miền sau:

Miền	Khả năng con	Trách nhiệm
doris_catalog	5	catalogs, databases, tables, bối cảnh table, kích thước
doris_query	7	query, explain, profile, chẩn đoán, truy vấn chậm, ADBC tường minh
doris_cluster	11	nodes, tasks, metrics, bộ nhớ, cache, compaction, khối lượng công việc
doris_pipeline	5	ingestion, materialized views, độ tươi mới, dependencies
doris_search	4	tìm kiếm text/vector/hybrid, analyzers, indexes, chẩn đoán
doris_governance	8	chất lượng, lưu trữ, lineage, kiểm toán, UDFs, ánh xạ xác thực
doris_lakehouse	3	external catalogs, lakehouse tables, Variant
doris_semantic	12	Apache Ossie grounding tùy chọn và tiêu thụ MetricFlow

Gọi một miền với {} để khám phá các khả năng con được ủy quyền và schema chính xác của chúng. Gọi lại cùng miền đó với child_tool, arguments và manifest_version được trả về. Các Host không thể sử dụng tiết lộ dần có thể đặt MCP_TOOL_EXPOSURE_MODE=flat trước khi khởi động; điều này hiển thị cùng 55 khả năng con với tên chính thức không xung đột và không khôi phục các bí danh trước 1.0.

Xem Kiến trúc, Vòng đời yêu cầu và Các miền công cụ.

Bắt đầu nhanh

Yêu cầu:

• Python 3.12 trở lên;
• Apache Doris 2.0.0 trở lên;
• truy cập mạng tới endpoint MySQL Doris FE, thường là cổng 9030.

Cài đặt bản phát hành đã chốt:

pip install doris-mcp-server==1.0.0

doris-mcp-server khởi động Server. doris-mcp-client là một client riêng biệt; hai lệnh này không thể thay thế cho nhau.

Cấu hình tuyến Doris:

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

Khởi động Streamable HTTP trên loopback:

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

Endpoints:

• MCP: POST http://127.0.0.1:3000/mcp
• legacy MCP (tùy chọn): POST http://127.0.0.1:3000/mcp/legacy
• liveness: GET http://127.0.0.1:3000/live
• mức sẵn sàng dựa trên Doris: GET http://127.0.0.1:3000/ready

Các Host chỉ giới hạn ở Streamable HTTP thời kỳ handshake, bao gồm Dify 1.16.1 với MCP 2025-06-18, phải đặt ENABLE_LEGACY_HTTP_ADAPTER=true và kết nối tới /mcp/legacy. Bộ điều hợp chỉ thay đổi ranh giới giao thức; nó giữ nguyên các công cụ 1.0, ủy quyền, cổng khả năng và thực thi chỉ-đọc.

Hoặc chạy stdio cho Host cục bộ:

doris-mcp-server --transport stdio

Xem Quick start đầy đủ và hướng dẫn tích hợp Host.

Ranh giới bảo mật

• Catalog 1.0 tích hợp sẵn chỉ đọc; doris_admin được dành riêng và không được đăng ký.
• Token tĩnh, JWT, OAuth/OIDC bên ngoài và OAuth dựa trên Doris được hỗ trợ trong các ranh giới cấu hình được xác thực lẫn nhau.
• Việc khám phá miền và thực thi khả năng con sử dụng định danh ủy quyền chính xác.
• Doris RBAC vẫn là cơ quan thẩm quyền cuối cùng cho các đối tượng và dữ liệu hiển thị.
• Hình dạng SQL, định danh, tham số, timeout, số hàng, byte và schema kết quả đều được giới hạn trước khi dữ liệu rời khỏi Server.
• Bí mật và lỗi backend được che giấu khỏi kết quả công khai và nhật ký.
• HTTP không loopback yêu cầu xác thực trừ khi có override phát triển nguy hiểm tường minh được bật.

Đọc Mô hình bảo mật và quyền và Hướng dẫn truy cập chi tiết Doris.

Ranh giới độ tin cậy

Server sử dụng manifest và lỗi xác định, con trỏ hết hạn được ký, snapshot khả năng nhận biết tuyến, fallback cũ có giới hạn, định tuyến kết nối theo yêu cầu cụ thể, chuyển đổi dự phòng đa FE, tách liveness/readiness, xác thực Schema đầu ra và lan truyền trace đã làm sạch. Các khả năng không được hỗ trợ hoặc cấu hình sai vẫn có thể khám phá bằng callable=false và fail closed khi được gọi.

Các giới hạn hiện tại bao gồm OAuth dựa trên Doris cục bộ theo tiến trình, ADBC chỉ tường minh bị tắt theo mặc định và fail-closed trên các tuyến ràng buộc token, Ossie grounding chỉ-đọc tùy chọn, sidecar trình biên dịch MetricFlow tùy chọn có SQL phải thực thi qua runtime truy vấn MCP có giới hạn, và phân phối lineage gốc best-effort. Xem Độ tin cậy và giới hạn.

Tài liệu

README gốc được thiết kế có chủ đích như một điểm vào. Hệ thống tài liệu song ngữ được lập chỉ mục tại:

• English documentation
• 简体中文文档

Hướng dẫn chính:

• Kiến trúc
• Luồng yêu cầu và dữ liệu
• Các miền công cụ
• Khả năng sẵn có
• Ma trận khả năng theo phiên bản Doris
• Tích hợp MetricFlow
• Hợp đồng MCP 2026-07-28
• Mô hình bảo mật
• Triển khai
• Độ tin cậy và giới hạn
• Xử lý sự cố
• Tham chiếu cấu hình
• Tích hợp Host
• Nhà cung cấp công cụ tùy chỉnh
• Đóng góp

Phát triển

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

Các tạo phẩm được sinh ra phải duy trì đồng bộ:

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

Xem Đóng góp và xác minh.

Giấy phép

Apache License 2.0. Xem LICENSE.txt và NOTICE.