Doris MCP Server

Doris MCP 服务

Doris MCP（Model Context Protocol）服务是一项使用 Python 和 FastAPI 构建的后端服务。它实现了 MCP，使客户端能够通过定义的“工具”与其交互。该服务主要用于连接 Apache Doris 数据库，并可利用大模型（LLM）执行自然语言转 SQL（NL2SQL）、查询执行以及元数据管理和分析等任务。

🚀 v0.6.0 新增内容

• 🔐 企业级身份验证系统：革命性的令牌绑定数据库配置，全面支持 Token、JWT 和 OAuth 身份验证，可通过精细化控制开关和企业级安全默认设置实现安全的多租户访问
• ⚡ 即时数据库验证：在连接时实时验证数据库配置，消除查询时阻塞，并对无效配置即时反馈，实现 100% 消除后期连接失败
• 🔄 热重载配置管理：通过智能热重载 tokens.json、自动重新验证令牌以及完善的错误处理和回滚机制，实现零停机配置更新
• 🏗️ 高级连接架构：通过会话缓存和连接池优化，将连接开销降低 60%，并实现智能连接池重建和自动资源管理
• 🌐 多工作进程扩展能力：通过无状态多工作进程架构、高效负载分配和企业级并发处理能力，实现真正的水平扩展
• 🔒 增强的安全框架：提供全面的访问控制和 SQL 安全验证，包括即时验证、基于角色的权限以及增强的注入检测模式
• 🛠️ 统一配置系统：通过规范的命令行优先级、更完善的 Docker 兼容性以及跨平台部署支持，简化配置管理
• 📊 令牌管理仪表板：提供完整的令牌生命周期管理，包括创建、撤销、统计信息以及用于企业令牌治理的全面审计跟踪
• 🌐 Web 管理界面：通过直观的仪表板、数据库绑定配置、实时操作和企业级访问控制，安全地管理仅限 localhost 使用的令牌

🚀 重要里程碑：v0.6.0 将该平台打造为可用于生产环境的企业级身份验证和数据库管理系统，具备零停机运行能力（热重载 + 即时验证 + 多工作进程扩展）、高级安全控制以及全面的令牌绑定数据库配置，标志着企业数据平台能力的一项根本性进步。

还包括 v0.5.1 的新增内容

• 🔥 关键的 at_eof 连接修复：通过智能健康监控和自愈恢复，彻底消除连接池错误
• 🔧 企业级日志系统：按级别分离文件，自动清理，并使用毫秒级精度时间戳
• 📊 高级数据分析套件：包含 7 种企业级数据治理工具，涵盖质量分析、血缘跟踪和性能监控
• 🏃‍♂️ 高性能 ADBC 集成：支持 Apache Arrow Flight SQL，大型数据集的性能提升 3–10 倍
• ⚙️ 增强的配置管理：完整的 ADBC 配置系统，具备智能参数验证

核心功能

• MCP 协议实现：提供标准 MCP 接口，支持工具调用、资源管理和提示词交互。
• 可流式传输的 HTTP 通信：统一的 HTTP 端点，同时支持请求/响应和流式通信，确保最佳性能与可靠性。
• Stdio 通信：标准输入/输出模式，可直接集成 Cursor 等 MCP 客户端。
• 企业级架构：采用模块化设计，功能全面：
  • 工具管理器：集中注册和路由工具，并提供统一接口（doris_mcp_server/tools/tools_manager.py）
  • 增强型监控工具模块：提供高级内存跟踪、指标收集和灵活的 BE 节点发现功能，采用模块化、可扩展的设计
  • 查询信息工具：增强 SQL 解释和性能分析功能，支持可配置的内容截断、将文件导出为大模型附件，以及高级查询分析
  • 资源管理器：管理资源并公开元数据（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 注入防护和数据脱敏，并支持通过环境变量进行配置
• 基于 Web 的令牌管理：仅限本地主机访问的安全界面，可全面管理令牌生命周期，支持数据库绑定、实时统计和企业级访问控制（doris_mcp_server/auth/token_handlers.py）
• 统一配置框架：通过 config.py 集中管理配置，提供全面验证、标准化参数命名和智能默认数据库处理，并在必要时自动回退到 information_schema

系统要求

• 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 模式（Web 服务）

主要通信模式，提供最佳性能与可靠性：

# 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 新增）

访问基于 Web 的令牌管理仪表板，进行企业级令牌管理：

安全访问要求

• 仅限本地主机访问：界面仅允许通过 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 Web 服务器端口（默认值：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）
  • 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：缓存生存时间（秒，默认值：300）
  • MAX_CONCURRENT_QUERIES：最大并发查询数（默认值：50）
  • MAX_RESPONSE_CONTENT_SIZE：与大模型兼容的最大响应内容大小（默认值：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	获取 SQL 执行计划，支持配置内容截断并导出文件，供大模型分析。	sql（字符串，必填），verbose（布尔值，可选），db_name（字符串，可选），catalog_name（字符串，可选）
get_sql_profile	获取 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	从节点获取 Doris 实际监控指标数据，并支持灵活发现 BE。	role（字符串，可选），monitor_type（字符串，可选），priority（字符串，可选）
get_realtime_memory_stats	通过 BE Memory Tracker 获取实时内存统计信息，支持自动或手动发现 BE。	tracker_type（字符串，可选），include_details（布尔值，可选）
get_historical_memory_stats	通过 BE Bvar 接口获取历史内存统计信息，支持灵活配置 BE。	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	通过 Top-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 个用于企业数据治理的高级分析工具，以及 2 个 ADBC 工具，可实现高性能数据传输，并将大型数据集的性能提升 3–10 倍。

4. 运行服务

执行以下命令以启动服务：

./start_server.sh

此命令会启动包含 Streamable HTTP MCP 服务的 FastAPI 应用。

5. 使用 docker 部署

如果只想在 docker 中运行 Doris MCP Server：

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

服务端点：

• Streamable HTTP：http://<host>:<port>/mcp（主要 MCP 端点，支持 GET、POST、DELETE、OPTIONS）
• 健康检查：http://<host>:<port>/health

注意： 服务器使用 Streamable HTTP 进行基于 Web 的通信，提供统一的请求/响应和流式传输功能。

使用方法

与 Doris MCP Server 交互需要使用 MCP 客户端。客户端连接到服务器的 Streamable HTTP 端点，并根据 MCP 规范发送请求，以调用服务器的工具。

主要交互流程：

1. 客户端初始化：向 /mcp（Streamable HTTP）发送 initialize 方法调用。
2. （可选）发现工具：客户端可以调用 tools/list，获取受支持的工具列表、工具描述和参数架构。
3. 调用工具：客户端发送 tools/call 请求，指定 name 和 arguments。
   • 示例：获取表架构
     • name：get_table_schema
     • arguments：包含 table_name、db_name、catalog_name。
4. 处理响应：
   • 非流式：客户端收到包含 content 或 isError 的响应。
   • 流式：客户端收到一系列进度通知，随后收到最终响应。

目录联合支持

Doris MCP Server 支持目录联合，可在统一界面中与多个数据目录（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

示例：

1. 获取可用目录：

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

2. 获取指定目录中的数据库：

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

3. 查询内部目录：

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

4. 查询外部目录：

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

5. 跨目录查询：

   {
     "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 Server 包含一个全面的企业级安全框架，具备高级身份验证、授权、SQL 安全验证和数据脱敏功能，并在 v0.6.0 中得到了增强。

安全功能（在 v0.6.0 中增强）

• 🔐 多重身份验证系统：全面支持 Token、JWT 和 OAuth 身份验证，并提供独立的控制开关
• 🔗 Token 绑定数据库配置：一种创新方案，允许 Token 携带自己的数据库连接参数
• 🔄 安全配置热重载：无需停机即可更新安全配置，并智能地重新验证 Token
• ⚡ 即时验证：在连接时实时验证数据库和身份验证信息
• 🛡️ 基于角色的授权：采用四级安全分类的高级 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

Token 绑定数据库配置（v0.6.0 新增）

创建 tokens.json 文件，以通过数据库绑定进行高级 Token 管理：

{
  "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 秒监控一次文件修改
• 即时验证：立即验证新 Token 的数据库配置
• 零停机时间：更新配置时服务不中断
• 回滚保护：配置出错时自动回滚
• 审计跟踪：完整记录配置更改

Token 身份验证示例

# 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 SELECT 攻击
• 基于布尔值的注入：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***[email protected]
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"
}

安全最佳实践

1. 🔑 强身份验证：使用具有适当有效期的 JWT 令牌
2. 🎯 最小权限原则：仅授予所需的最低权限
3. 🔍 定期审计：启用审计日志以监控安全情况
4. 🛡️ 输入验证：所有 SQL 查询都会自动验证
5. 🎭 数据分类：根据安全级别妥善分类数据
6. 🔄 定期更新：及时更新安全规则和配置

安全监控

系统提供全面的安全监控：

# 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 模式（推荐）或 Streamable 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"
      }
    }
  }
}

Streamable HTTP 模式

Streamable HTTP 模式需要先独立运行 MCP 服务，然后配置 Cursor 连接到该服务。

1. **配置 .env：**确保项目目录中的 .env 文件已正确配置数据库凭据和其他必要设置。

2. **启动服务：**在项目根目录中通过终端运行服务：

   ./start_server.sh
   

   此脚本会读取 .env 文件，并启动支持 Streamable HTTP 的 FastAPI 服务。请记下服务监听的主机和端口（默认为 0.0.0.0:3000）。

3. **配置 Cursor：**在 Cursor 的 MCP 配置中添加如下条目，并指向正在运行的服务的 Streamable HTTP 端点：

   {
     "mcpServers": {
       "doris-http": {
          "url": "http://127.0.0.1:3000/mcp"
       }
     }
   }
   

   注意：如果服务运行在其他地址，请调整主机和端口。/mcp 端点是统一的 Streamable HTTP 接口。

在 Cursor 中配置任一模式后，你应该就可以选择服务（例如 doris-stdio 或 doris-http）并使用其工具。

目录结构

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 Server 添加新的 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。

贡献

欢迎通过 Issues 或 Pull Requests 贡献项目。

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。

常见问题

问：为什么 Qwen3-32b 和其他小参数模型在调用工具时总是失败？

**答：**这是一个常见问题。主要原因是，这些模型需要更明确的指导，才能正确使用 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> 标签中描述具体要求。

问：如何配置不同的数据库连接？

**答：**你可以通过以下几种方式配置数据库连接：

1. 环境变量（推荐）：

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

2. 命令行参数：

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

3. 配置文件： 修改 .env 文件中对应的配置项。

问：如何为监控工具配置 BE 节点？

**答：**根据部署场景选择合适的配置：

外部网络（手动配置）：

# 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：如何将 SQL Explain/Profile 文件与大模型结合进行优化？

答： 这些工具会同时提供截断内容和完整文件，供大模型分析：

1. 获取分析结果：

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

2. 大模型分析工作流：

   • 查看截断内容，快速获取见解
   • 将完整文件作为附件上传到大模型
   • 请求提供优化建议或性能分析
   • 实施建议的改进

3. 配置内容大小：

   MAX_RESPONSE_CONTENT_SIZE=4096  # Adjust as needed
   

Q：如何启用数据安全和脱敏功能？

答： 在 .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 模式：独立的 Web 服务，支持多个客户端连接，适合生产环境

建议：

• 开发和个人使用：Stdio 模式
• 生产和多用户环境：HTTP 模式

Q：如何解决连接超时问题？

答： 尝试以下解决方案：

1. 增加超时设置：

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

2. 检查网络连接：

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

3. 优化连接池配置：

   DORIS_MAX_CONNECTIONS=20
   

Q：如何解决 at_eof 连接错误？（已在 v0.5.0 中彻底修复）

答： 版本 0.5.0 通过全面重构连接池，彻底解决了关键的 at_eof 连接错误：

问题：

• at_eof 错误是由连接池预创建和连接状态管理不当导致的
• MySQL aiomysql 读取器状态在连接生命周期中变得不一致
• 并发负载下连接池不稳定

解决方案（v0.5.0）：

1. 全面调整连接池策略：

   • 最小连接数设为 0：将 min_connections 从默认值改为 0，避免预创建问题
   • 按需创建连接：仅在需要时创建连接，消除陈旧连接问题
   • 使用全新连接策略：始终从连接池获取全新连接，不进行会话级缓存

2. 增强健康监控：

   • 基于超时的健康检查：连接验证查询设置 3 秒超时
   • 后台健康监控：每 30 秒持续监控连接池健康状况
   • 主动检测陈旧连接：自动检测并清理有问题的连接

3. 智能恢复系统：

   • 自动恢复连接池：具备全面错误处理能力的自愈连接池
   • 指数退避重试：智能重试机制，最多尝试 3 次
   • 连接特定错误检测：精准识别与连接相关的错误

4. 性能优化：

   • 连接池预热：智能预热连接池，以实现最佳性能
   • 后台清理：定期清理陈旧连接，不影响正在进行的操作
   • 连接诊断：实时监控并报告连接健康状况

监控连接健康状况：

# 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%，连接稳定性和性能显著提升。

问：如何解决 MCP 库版本兼容性问题？（已在 v0.4.2 中修复）

答： v0.4.2 引入了智能 MCP 兼容层，同时支持 MCP 1.8.x 和 1.9.x 版本：

问题：

• 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

问：如何启用 ADBC 高性能功能？（v0.5.0 新增）

答： ADBC（Arrow Flight SQL）可为大型数据集带来 3–10 倍的性能提升：

1. ADBC 依赖项（已在 v0.5.0 及更高版本中自动包含）：

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

2. 配置 Arrow Flight SQL 端口：

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

3. 可选的 ADBC 自定义配置：

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

4. 测试 ADBC 连接：

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

问：如何使用新的数据分析工具？（v0.5.0 新增）

答： 这 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
  }
}

问：如何使用增强的日志系统？（v0.5.0 改进）

答： 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)

增强的日志功能：

1. 按级别分离文件：按日志级别自动分类，便于排查问题
2. 带时间戳的格式：精确到毫秒并保持格式对齐，实现专业的日志记录
3. 自动日志轮转：可配置文件大小限制，避免磁盘空间问题
4. 后台清理：智能清理调度器，支持配置保留策略
5. 审计跟踪：单独记录审计日志，用于合规和安全监控

查看日志：

# 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 个备份文件
• 性能：对服务性能的影响极小

问：如何使用新的 Token 绑定数据库配置？（v0.6.0 新增）

答： 这种创新的 Token 绑定数据库配置允许每个 Token 携带自己的数据库连接参数，实现安全的多租户访问：

1. 启用 Token 身份验证：

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

2. 创建 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"
         }
       }
     ]
   }
   

3. 配置优先级（v0.6.0 新增）：

   • Token 绑定的数据库配置（优先级最高）
   • 环境变量（.env）
   • 两者都不可用时出错

4. 热重载的优势：

   • 无需重启服务即可添加新租户
   • 实时更新数据库凭据
   • 出错时自动验证并回滚
   • 完整记录变更审计跟踪

5. 多租户用法：

   # 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：热重载如何工作？是否安全？（v0.6.0 新增）

答： 热重载系统专为企业生产环境设计，并配备了全面的安全措施：

工作原理：

• 文件监控：每 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 新增）

答： 令牌管理采用安全的文件管理方式，并提供可选的管理端点，这些端点配有全面的安全控制措施。

主要令牌管理方式（推荐）：

# 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

推荐的令牌管理工作流：

1. 开发/测试：

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

2. 生产部署：

   # 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 或提交新问题。