diff --git a/crates/dbx-core/src/agent_tools.rs b/crates/dbx-core/src/agent_tools.rs index 79fb11e7e5..767f10863a 100644 --- a/crates/dbx-core/src/agent_tools.rs +++ b/crates/dbx-core/src/agent_tools.rs @@ -27,6 +27,53 @@ const BROWSE_COLLECTION_LIMIT: usize = 20; /// Absolute maximum rows any query tool may request. const MAX_ALLOWED_ROWS: usize = 100; +/// Default string-cell character budget for AI and local MCP query results. +const DEFAULT_QUERY_CELL_CHAR_LIMIT: usize = 200; + +/// Explicit string-cell windows stay bounded so one tool call cannot flood the model context. +const MAX_QUERY_CELL_CHAR_LIMIT: usize = 4_000; + +/// Bounds explicit sliding-window scans without changing the underlying database request. +const MAX_QUERY_CELL_CHAR_OFFSET: usize = 1_000_000; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct QueryCellWindow { + offset: usize, + limit: usize, +} + +impl Default for QueryCellWindow { + fn default() -> Self { + Self { offset: 0, limit: DEFAULT_QUERY_CELL_CHAR_LIMIT } + } +} + +impl QueryCellWindow { + pub fn from_options(offset: Option, limit: Option) -> Self { + Self { + offset: bounded_query_cell_option(offset, 0, MAX_QUERY_CELL_CHAR_OFFSET), + limit: bounded_query_cell_option(limit, DEFAULT_QUERY_CELL_CHAR_LIMIT, MAX_QUERY_CELL_CHAR_LIMIT).max(1), + } + } + + pub fn from_arguments(arguments: &serde_json::Value) -> Self { + Self::from_options( + arguments.get("cell_char_offset").and_then(serde_json::Value::as_u64), + arguments.get("cell_char_limit").and_then(serde_json::Value::as_u64), + ) + } + + pub fn explicit_from_arguments(arguments: &serde_json::Value) -> Option { + let offset = arguments.get("cell_char_offset").and_then(serde_json::Value::as_u64); + let limit = arguments.get("cell_char_limit").and_then(serde_json::Value::as_u64); + (offset.is_some() || limit.is_some()).then(|| Self::from_options(offset, limit)) + } +} + +fn bounded_query_cell_option(value: Option, default: usize, maximum: usize) -> usize { + value.map(|value| value.min(maximum as u64) as usize).unwrap_or(default) +} + #[derive(Debug, Clone, Default, PartialEq, Eq)] pub struct AgentSqlPermissions { pub allow_writes: bool, @@ -297,6 +344,18 @@ fn execute_query_tool(sql_permissions: AgentSqlPermissions) -> ToolDefinition { "type": "number", "description": "Max rows to return (default 50, max 100)" }, + "cell_char_offset": { + "type": "integer", + "minimum": 0, + "maximum": 1000000, + "description": "Start character offset for every string cell (default 0). Use the next offset reported by a truncated result to slide through long values. Narrow the query to the target row and column before expanding." + }, + "cell_char_limit": { + "type": "integer", + "minimum": 1, + "maximum": 4000, + "description": "Maximum characters returned per string cell (default 200, max 4000). Increase only for an explicit long-value expansion." + }, "client_session_id": { "type": "string", "description": "Opaque DBX session handle that pins this query to the same backend connection as earlier queries in the session (preserves USE/SET/session state). Managed by DBX; agents should not invent values." @@ -644,9 +703,10 @@ async fn execute_execute_query( .and_then(|v| v.as_u64()) .map(|l| (l as usize).min(MAX_ALLOWED_ROWS)) .unwrap_or(EXECUTE_QUERY_LIMIT); + let cell_window = QueryCellWindow::from_arguments(&tool_call.arguments); if *db_type == DatabaseType::MongoDb { - return execute_mongo_query(state, connection_id, database, sql, limit.max(1)).await; + return execute_mongo_query(state, connection_id, database, sql, limit.max(1), cell_window).await; } // Classify SQL risk using the concrete database dialect. @@ -703,7 +763,7 @@ async fn execute_execute_query( ) .await?; - format_query_result_as_text(&result, limit) + format_query_result_as_text(&result, limit, cell_window) } async fn execute_mongo_query( @@ -712,6 +772,7 @@ async fn execute_mongo_query( database: &str, source: &str, limit: usize, + cell_window: QueryCellWindow, ) -> Result { let command = crate::mongo_shell::parse(source).map_err(|error| { format!( @@ -726,11 +787,15 @@ async fn execute_mongo_query( } let result = crate::mongo_ops::execute_mongo_command_core(state, connection_id, database, &command, limit).await?; - format_query_result_as_text(&result, limit) + format_query_result_as_text(&result, limit, cell_window) } /// Format a QueryResult as a Markdown table for LLM consumption. -fn format_query_result_as_text(result: &QueryResult, limit: usize) -> Result { +pub fn format_query_result_as_text( + result: &QueryResult, + limit: usize, + cell_window: QueryCellWindow, +) -> Result { // A result without columns is a command result, not an empty result set. // This is how drivers represent DML that does not use RETURNING. if result.columns.is_empty() { @@ -753,16 +818,7 @@ fn format_query_result_as_text(result: &QueryResult, limit: usize) -> Result "NULL".to_string(), - serde_json::Value::String(s) => { - // Truncate long strings to keep result compact - if s.len() > 200 { - let truncated: String = - s.char_indices().take_while(|(i, _)| *i < 200).map(|(_, c)| c).collect(); - format!("{}...", truncated) - } else { - s.clone() - } - } + serde_json::Value::String(value) => format_query_string_cell(value, cell_window), other => other.to_string(), }) .collect(); @@ -780,6 +836,24 @@ fn format_query_result_as_text(result: &QueryResult, limit: usize) -> Result String { + let mut characters = value.chars().skip(window.offset); + let mut returned = 0usize; + let content = characters.by_ref().take(window.limit).inspect(|_| returned += 1).collect::(); + let has_more = characters.next().is_some(); + if window.offset == 0 && !has_more { + return content; + } + + let end = window.offset.saturating_add(returned); + let prefix = if window.offset > 0 { "..." } else { "" }; + if has_more { + format!("{prefix}{content}... [chars {}..{end}; next cell_char_offset={end}]", window.offset) + } else { + format!("{prefix}{content} [chars {}..{end}; end of value]", window.offset) + } +} + /// Append server messages in the same style as the MCP `format_query_result` /// renderer: a `Server messages:` section with `- SEVERITY: message` lines. fn append_server_messages(mut output: String, messages: &[QueryMessage]) -> String { @@ -942,7 +1016,7 @@ async fn execute_explain_query( // Serialize the raw QueryResult for the frontend ExplainPlanViewer let explain_data = serde_json::to_value(&result).ok(); - let text = match format_query_result_as_text(&result, 100) { + let text = match format_query_result_as_text(&result, 100, QueryCellWindow::default()) { Ok(t) => t, Err(e) => return (Err(e), None), }; @@ -1042,7 +1116,7 @@ async fn execute_browse_collection( crate::query::execute_sql_statement_with_options(state, connection_id, database, &query, None, None, options) .await?; - format_query_result_as_text(&result, limit) + format_query_result_as_text(&result, limit, QueryCellWindow::default()) } /// Build a browse query for the given vector database type. @@ -1387,7 +1461,10 @@ for line in sys.stdin: fn query_result_formatter_reports_dml_affected_rows() { let result = query_result(vec![], vec![], 2); - assert_eq!(format_query_result_as_text(&result, 50).unwrap(), "Query executed. 2 row(s) affected."); + assert_eq!( + format_query_result_as_text(&result, 50, QueryCellWindow::default()).unwrap(), + "Query executed. 2 row(s) affected." + ); } #[test] @@ -1395,8 +1472,14 @@ for line in sys.stdin: let dml = query_result(vec![], vec![], 0); let returning = query_result(vec!["id", "name"], vec![], 0); - assert_eq!(format_query_result_as_text(&dml, 50).unwrap(), "Query executed. 0 row(s) affected."); - assert_eq!(format_query_result_as_text(&returning, 50).unwrap(), "| id | name |\n|---|---|\n(0 rows, 1ms)"); + assert_eq!( + format_query_result_as_text(&dml, 50, QueryCellWindow::default()).unwrap(), + "Query executed. 0 row(s) affected." + ); + assert_eq!( + format_query_result_as_text(&returning, 50, QueryCellWindow::default()).unwrap(), + "| id | name |\n|---|---|\n(0 rows, 1ms)" + ); } #[test] @@ -1405,11 +1488,59 @@ for line in sys.stdin: query_result(vec!["id", "name"], vec![vec![serde_json::json!(5), serde_json::json!("returning")]], 0); assert_eq!( - format_query_result_as_text(&result, 50).unwrap(), + format_query_result_as_text(&result, 50, QueryCellWindow::default()).unwrap(), "| id | name |\n|---|---|\n| 5 | returning |\n(1 rows, 1ms)" ); } + #[test] + fn query_result_formatter_marks_the_default_character_window() { + let value = format!("{}DBX_ISSUE_5620_SENTINEL", "A".repeat(200)); + let result = query_result(vec!["message"], vec![vec![serde_json::json!(value)]], 0); + + let output = format_query_result_as_text(&result, 50, QueryCellWindow::from_options(None, None)).unwrap(); + + assert!(output.contains(&format!("{}... [chars 0..200; next cell_char_offset=200]", "A".repeat(200)))); + assert!(!output.contains("DBX_ISSUE_5620_SENTINEL")); + } + + #[test] + fn query_result_formatter_supports_expanded_and_sliding_character_windows() { + let value = format!("{}DBX_ISSUE_5620_SENTINEL{}", "A".repeat(200), "Z".repeat(20)); + let result = query_result(vec!["message"], vec![vec![serde_json::json!(value)]], 0); + + let expanded = + format_query_result_as_text(&result, 50, QueryCellWindow::from_options(None, Some(400))).unwrap(); + assert!(expanded.contains("DBX_ISSUE_5620_SENTINEL")); + assert!(!expanded.contains("next cell_char_offset")); + + let sliding = + format_query_result_as_text(&result, 50, QueryCellWindow::from_options(Some(200), Some(23))).unwrap(); + assert!(sliding.contains("...DBX_ISSUE_5620_SENTINEL... [chars 200..223; next cell_char_offset=223]")); + } + + #[test] + fn query_result_formatter_counts_unicode_characters_in_windows() { + let result = query_result(vec!["message"], vec![vec![serde_json::json!("甲乙丙丁戊己庚辛")]], 0); + + let output = format_query_result_as_text(&result, 50, QueryCellWindow::from_options(Some(2), Some(3))).unwrap(); + + assert!(output.contains("...丙丁戊... [chars 2..5; next cell_char_offset=5]")); + } + + #[test] + fn query_cell_window_clamps_explicit_bounds() { + assert_eq!(QueryCellWindow::from_options(None, None), QueryCellWindow::default()); + assert_eq!( + QueryCellWindow::from_options(Some(u64::MAX), Some(0)), + QueryCellWindow { offset: 1_000_000, limit: 1 } + ); + assert_eq!( + QueryCellWindow::from_options(Some(1_000_001), Some(u64::MAX)), + QueryCellWindow { offset: 1_000_000, limit: 4_000 } + ); + } + #[test] fn query_result_formatter_appends_server_messages() { let mut dml = query_result(vec![], vec![], 2); @@ -1430,7 +1561,7 @@ for line in sys.stdin: }, ]; assert_eq!( - format_query_result_as_text(&dml, 50).unwrap(), + format_query_result_as_text(&dml, 50, QueryCellWindow::default()).unwrap(), "Query executed. 2 row(s) affected.\n\nServer messages:\n- NOTICE: hello world (code: 00000, hint: use a table)\n- WARNING: careful" ); @@ -1443,7 +1574,7 @@ for line in sys.stdin: hint: None, }]; assert_eq!( - format_query_result_as_text(&result, 50).unwrap(), + format_query_result_as_text(&result, 50, QueryCellWindow::default()).unwrap(), "| id |\n|---|\n| 1 |\n(1 rows, 1ms)\n\nServer messages:\n- INFO: print output" ); } diff --git a/crates/dbx-mcp/src/backend.rs b/crates/dbx-mcp/src/backend.rs index 388be09b21..a3b7dea95b 100644 --- a/crates/dbx-mcp/src/backend.rs +++ b/crates/dbx-mcp/src/backend.rs @@ -7,7 +7,7 @@ use std::{ use async_trait::async_trait; use dbx_core::{ agent_events::{ToolCall, ToolResult}, - agent_tools::{self, AgentSqlPermissions}, + agent_tools::{self, format_query_result_as_text, AgentSqlPermissions, QueryCellWindow}, connection::AppState, db::{redis_driver::RedisCommandResult, ColumnInfo, IndexInfo, TableInfo}, models::connection::{ConnectionConfig, DatabaseType}, @@ -587,6 +587,7 @@ impl DbxBackend for WebBackend { arguments: Value, permissions: AgentSqlPermissions, ) -> ToolResult { + let explicit_cell_window = QueryCellWindow::explicit_from_arguments(&arguments); let result = async { if tool_name != "execute_query" { return Err(format!("Unsupported DBX Web agent tool: {tool_name}")); @@ -630,7 +631,10 @@ impl DbxBackend for WebBackend { let response = self.request(reqwest::Method::POST, "/api/query/execute", Some(body)).await?; let query_result: dbx_core::db::QueryResult = response.json().await.map_err(|error| format!("Invalid query response: {error}"))?; - Ok(format_query_result(&query_result, max_rows)) + match explicit_cell_window { + Some(window) => format_query_result_as_text(&query_result, max_rows, window), + None => Ok(format_query_result(&query_result, max_rows)), + } } .await; ToolResult { diff --git a/crates/dbx-mcp/src/server.rs b/crates/dbx-mcp/src/server.rs index 200d0f75d5..d2fb6219f1 100644 --- a/crates/dbx-mcp/src/server.rs +++ b/crates/dbx-mcp/src/server.rs @@ -13,6 +13,7 @@ use crate::backend::{format_query_result, new_connection_config, parse_database_ use crate::mongo::{self, MongoCommand, MongoSafetyError}; use crate::session::{McpSession, McpSessionStore}; use dbx_core::{ + agent_tools::{format_query_result_as_text, QueryCellWindow}, db::redis_driver::{classify_command, parse_command_argv, RedisCommandResult, RedisCommandSafety}, models::connection::DatabaseType, production_safety::{ @@ -70,6 +71,14 @@ pub struct ExecuteQueryRequest { description = "Session ID from dbx_open_session. When set, the query runs on the session's pinned connection, preserving USE/SET and other session state across calls." )] pub session_id: Option, + #[schemars( + description = "Start character offset for every string cell (default 0, max 1000000). Use the next offset reported by a truncated result to slide through a long value; narrow the query to the target row and column first." + )] + pub cell_char_offset: Option, + #[schemars( + description = "Maximum characters returned per string cell (default 200, max 4000). Increase only for an explicit long-value expansion." + )] + pub cell_char_limit: Option, } #[derive(Debug, Deserialize, schemars::JsonSchema)] @@ -309,6 +318,8 @@ impl DbxMcpServer { description = "Execute a SQL query on a database connection (max 100 rows returned)" )] async fn execute_query(&self, Parameters(request): Parameters) -> CallToolResult { + let explicit_cell_window = (request.cell_char_offset.is_some() || request.cell_char_limit.is_some()) + .then(|| QueryCellWindow::from_options(request.cell_char_offset, request.cell_char_limit)); let resolved = match self.resolve_connection(&request.selector).await { Ok(resolved) => resolved, Err(error) => return error, @@ -367,7 +378,13 @@ impl DbxMcpServer { Err(error) => return error, }; return match self.backend.execute_mongo_command(connection, &database, &command).await { - Ok(result) => text(format_query_result(&result, 100)), + Ok(result) => match explicit_cell_window { + Some(window) => match format_query_result_as_text(&result, 100, window) { + Ok(output) => text(output), + Err(error) => backend_tool_error("QUERY_FORMAT_ERROR", error), + }, + None => text(format_query_result(&result, 100)), + }, Err(error) => backend_tool_error("QUERY_ERROR", error), }; } @@ -387,6 +404,12 @@ impl DbxMcpServer { if let Some(session) = &session { arguments["client_session_id"] = json!(session.client_session_id); } + if let Some(offset) = request.cell_char_offset { + arguments["cell_char_offset"] = json!(offset); + } + if let Some(limit) = request.cell_char_limit { + arguments["cell_char_limit"] = json!(limit); + } let result = self.backend.execute_agent_tool(connection, &database, "execute_query", arguments, permissions).await; agent_result(result) @@ -1610,6 +1633,8 @@ mod tests { database: None, sql: "USE analytics".to_string(), session_id: Some(session_id.clone()), + cell_char_offset: None, + cell_char_limit: None, })) .await; assert_eq!(result_text(&result), "ok"); @@ -1627,6 +1652,8 @@ mod tests { database: Some("other".to_string()), sql: "SELECT 1".to_string(), session_id: Some(session_id.clone()), + cell_char_offset: None, + cell_char_limit: None, })) .await; assert!(result_text(&mismatch).contains("SESSION_DATABASE_MISMATCH")); @@ -1643,6 +1670,8 @@ mod tests { database: None, sql: "SELECT 1".to_string(), session_id: Some(session_id.clone()), + cell_char_offset: None, + cell_char_limit: None, })) .await; assert!(result_text(&missing).contains("SESSION_NOT_FOUND")); @@ -1651,6 +1680,30 @@ mod tests { assert!(result_text(&second_close).contains("SESSION_NOT_FOUND")); } + #[tokio::test] + async fn execute_query_forwards_character_window_options() { + let elasticsearch = connection("es", "es", "elasticsearch", ""); + let backend = Arc::new(FakeBackend { connections: vec![elasticsearch], ..Default::default() }); + let server = DbxMcpServer::with_runtime_options(backend.clone(), McpScope::default(), false); + + let result = server + .execute_query(Parameters(ExecuteQueryRequest { + selector: selector("es"), + database: None, + sql: "GET /logs/_search".to_string(), + session_id: None, + cell_char_offset: Some(200), + cell_char_limit: Some(800), + })) + .await; + + assert_eq!(result_text(&result), "ok"); + let recorded = backend.recorded_arguments.lock().unwrap(); + let (_, arguments) = recorded.iter().find(|(name, _)| name == "execute_query").unwrap(); + assert_eq!(arguments["cell_char_offset"], 200); + assert_eq!(arguments["cell_char_limit"], 800); + } + #[tokio::test] async fn expired_sessions_close_backend_pools_without_accumulating() { let starrocks = connection("sr", "sr", "starrocks", "default_catalog"); @@ -1668,6 +1721,8 @@ mod tests { database: None, sql: "SELECT 1".to_string(), session_id: Some(session_id.clone()), + cell_char_offset: None, + cell_char_limit: None, })) .await; assert_eq!(result_text(&result), "ok"); @@ -1703,6 +1758,8 @@ mod tests { database: None, sql: "SELECT 1".to_string(), session_id: Some(session_id.clone()), + cell_char_offset: None, + cell_char_limit: None, })) .await; assert_eq!(result_text(&query), "ok"); @@ -1717,6 +1774,8 @@ mod tests { database: None, sql: "SELECT 1".to_string(), session_id: Some(session_id.clone()), + cell_char_offset: None, + cell_char_limit: None, })) .await; assert_eq!(result_text(&retry_query), "ok"); @@ -1746,6 +1805,8 @@ mod tests { database: None, sql: "SELECT 1".to_string(), session_id: Some("mcp-session-nope".to_string()), + cell_char_offset: None, + cell_char_limit: None, })) .await; assert!(result_text(&missing).contains("SESSION_NOT_FOUND"));