25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。
TypeScript aicliclickhousedatabasedatabase-clientdatabase-managementdockerguimcpmongodbmysqlpostgresqlredisrustsql-serversqlitetaurivue
feat(mcp): support read-only Kafka message browsing
C.J.S5c95f2c00af4
diff --git a/apps/desktop/src/i18n/locales/az.ts b/apps/desktop/src/i18n/locales/az.tsindex cd57bac214..a679ac491e 100644--- a/apps/desktop/src/i18n/locales/az.ts+++ b/apps/desktop/src/i18n/locales/az.ts@@ -7576,6 +7576,7 @@ export default withEnglishFallback({mcpToolOpenSession: "Sorğu sessiyasını aç",mcpToolCloseSession: "Sorğu sessiyasını bağla",mcpToolExecuteRedisCommand: "Redis əmrini icra et",+ mcpToolPeekMessages: "Kafka mesajlarını oxu",mcpToolSendMessage: "Mesaj növbəsinə mesaj göndər",mcpToolAddConnection: "Əlaqə əlavə et",mcpToolDuplicateConnection: "Əlaqənin surətini yarat",diff --git a/apps/desktop/src/i18n/locales/en.ts b/apps/desktop/src/i18n/locales/en.tsindex 5ab25f75c7..93378ee00c 100644--- a/apps/desktop/src/i18n/locales/en.ts+++ b/apps/desktop/src/i18n/locales/en.ts@@ -7573,6 +7573,7 @@ export default {mcpToolOpenSession: "Open query session",mcpToolCloseSession: "Close query session",mcpToolExecuteRedisCommand: "Execute Redis command",+ mcpToolPeekMessages: "Read Kafka messages",mcpToolSendMessage: "Send message queue message",mcpToolAddConnection: "Add connection",mcpToolDuplicateConnection: "Duplicate connection",diff --git a/apps/desktop/src/i18n/locales/es.ts b/apps/desktop/src/i18n/locales/es.tsindex 5f42f8fc5d..5853130973 100644--- a/apps/desktop/src/i18n/locales/es.ts+++ b/apps/desktop/src/i18n/locales/es.ts@@ -7088,6 +7088,7 @@ export default withEnglishFallback({mcpToolOpenSession: "Abrir sesión de consulta",mcpToolCloseSession: "Cerrar sesión de consulta",mcpToolExecuteRedisCommand: "Ejecutar comando Redis",+ mcpToolPeekMessages: "Leer mensajes de Kafka",mcpToolSendMessage: "Enviar mensaje de cola de mensajes",mcpToolAddConnection: "Añadir conexión",mcpToolDuplicateConnection: "Duplicar conexión",diff --git a/apps/desktop/src/i18n/locales/it.ts b/apps/desktop/src/i18n/locales/it.tsindex 9014837c88..f7e900e2be 100644--- a/apps/desktop/src/i18n/locales/it.ts+++ b/apps/desktop/src/i18n/locales/it.ts@@ -7088,6 +7088,7 @@ export default withEnglishFallback({mcpToolOpenSession: "Apri sessione di query",mcpToolCloseSession: "Chiudi sessione di query",mcpToolExecuteRedisCommand: "Esegui comando Redis",+ mcpToolPeekMessages: "Leggi messaggi Kafka",mcpToolSendMessage: "Invia messaggio in coda",mcpToolAddConnection: "Aggiungi connessione",mcpToolDuplicateConnection: "Duplica connessione",diff --git a/apps/desktop/src/i18n/locales/ja.ts b/apps/desktop/src/i18n/locales/ja.tsindex d7f4b60b7b..7af37e4495 100644--- a/apps/desktop/src/i18n/locales/ja.ts+++ b/apps/desktop/src/i18n/locales/ja.ts@@ -7095,6 +7095,7 @@ export default withEnglishFallback({mcpToolOpenSession: "クエリセッションを開く",mcpToolCloseSession: "クエリセッションを閉じる",mcpToolExecuteRedisCommand: "Redis コマンドを実行",+ mcpToolPeekMessages: "Kafka メッセージを読み取る",mcpToolSendMessage: "メッセージキューのメッセージを送信",mcpToolAddConnection: "接続を追加",mcpToolDuplicateConnection: "接続を複製",diff --git a/apps/desktop/src/i18n/locales/ko.ts b/apps/desktop/src/i18n/locales/ko.tsindex c2ed1919d8..802985ae66 100644--- a/apps/desktop/src/i18n/locales/ko.ts+++ b/apps/desktop/src/i18n/locales/ko.ts@@ -6849,6 +6849,7 @@ export default withEnglishFallback({mcpToolOpenSession: "쿼리 세션 열기",mcpToolCloseSession: "쿼리 세션 닫기",mcpToolExecuteRedisCommand: "Redis 명령 실행",+ mcpToolPeekMessages: "Kafka 메시지 읽기",mcpToolSendMessage: "메시지 큐 메시지 전송",mcpToolAddConnection: "연결 추가",mcpToolDuplicateConnection: "연결 복제",diff --git a/apps/desktop/src/i18n/locales/pt-BR.ts b/apps/desktop/src/i18n/locales/pt-BR.tsindex 58e10e0729..bba554a6ad 100644--- a/apps/desktop/src/i18n/locales/pt-BR.ts+++ b/apps/desktop/src/i18n/locales/pt-BR.ts@@ -7090,6 +7090,7 @@ export default withEnglishFallback({mcpToolOpenSession: "Abrir sessão de consulta",mcpToolCloseSession: "Fechar sessão de consulta",mcpToolExecuteRedisCommand: "Executar comando Redis",+ mcpToolPeekMessages: "Ler mensagens Kafka",mcpToolSendMessage: "Enviar mensagem da fila",mcpToolAddConnection: "Adicionar conexão",mcpToolDuplicateConnection: "Duplicar conexão",diff --git a/apps/desktop/src/i18n/locales/tr.ts b/apps/desktop/src/i18n/locales/tr.tsindex 35c807732f..c96dd3fa4a 100644--- a/apps/desktop/src/i18n/locales/tr.ts+++ b/apps/desktop/src/i18n/locales/tr.ts@@ -7456,6 +7456,7 @@ export default withEnglishFallback({mcpToolOpenSession: "Sorgu oturumu aç",mcpToolCloseSession: "Sorgu oturumunu kapat",mcpToolExecuteRedisCommand: "Redis komutunu çalıştır",+ mcpToolPeekMessages: "Kafka mesajlarını oku",mcpToolSendMessage: "Mesaj kuyruğu mesajı gönder",mcpToolAddConnection: "Bağlantı ekle",mcpToolDuplicateConnection: "Bağlantıyı çoğalt",diff --git a/apps/desktop/src/i18n/locales/zh-CN.ts b/apps/desktop/src/i18n/locales/zh-CN.tsindex 0ea9bd98d7..94a969e06b 100644--- a/apps/desktop/src/i18n/locales/zh-CN.ts+++ b/apps/desktop/src/i18n/locales/zh-CN.ts@@ -7558,6 +7558,7 @@ export default withEnglishFallback({mcpToolOpenSession: "打开查询会话",mcpToolCloseSession: "关闭查询会话",mcpToolExecuteRedisCommand: "执行 Redis 命令",+ mcpToolPeekMessages: "读取 Kafka 消息",mcpToolSendMessage: "发送消息队列消息",mcpToolAddConnection: "新增连接",mcpToolDuplicateConnection: "复制连接",diff --git a/apps/desktop/src/i18n/locales/zh-TW.ts b/apps/desktop/src/i18n/locales/zh-TW.tsindex 790a132ef9..2d98eeac8e 100644--- a/apps/desktop/src/i18n/locales/zh-TW.ts+++ b/apps/desktop/src/i18n/locales/zh-TW.ts@@ -6449,6 +6449,7 @@ export default withEnglishFallback({mcpToolOpenSession: "開啟查詢工作階段",mcpToolCloseSession: "關閉查詢工作階段",mcpToolExecuteRedisCommand: "執行 Redis 命令",+ mcpToolPeekMessages: "讀取 Kafka 訊息",mcpToolSendMessage: "傳送訊息佇列訊息",mcpToolAddConnection: "新增連線",mcpToolDuplicateConnection: "複製連線",diff --git a/apps/desktop/src/lib/__tests__/mcp/mcpPolicySelection.spec.ts b/apps/desktop/src/lib/__tests__/mcp/mcpPolicySelection.spec.tsindex ad0769dd18..92ef184626 100644--- a/apps/desktop/src/lib/__tests__/mcp/mcpPolicySelection.spec.ts+++ b/apps/desktop/src/lib/__tests__/mcp/mcpPolicySelection.spec.ts@@ -97,6 +97,13 @@ describe("MCP tool permission selection", () => {expect(next).not.toContain("dbx_send_message");});+ it("keeps Kafka reading independent from message sending", () => {+ const next = toggleMcpAllowedToolName(null, "dbx_send_message", false);+ expect(next).toContain("dbx_peek_messages");+ expect(toggleMcpAllowedToolName(next, "dbx_peek_messages", false)).not.toContain("dbx_peek_messages");+ expect(toggleMcpAllowedToolName([], "dbx_peek_messages", true)).toEqual(["dbx_peek_messages"]);+ });+it("lets batch execution be enabled and disabled independently", () => {expect(toggleMcpAllowedToolName(["dbx_execute_query"], "dbx_execute_batch", true)).toEqual(["dbx_execute_query", "dbx_execute_batch"]);expect(toggleMcpAllowedToolName(["dbx_execute_query", "dbx_execute_batch"], "dbx_execute_batch", false)).toEqual(["dbx_execute_query"]);diff --git a/apps/desktop/src/lib/mcp/mcpPolicySelection.ts b/apps/desktop/src/lib/mcp/mcpPolicySelection.tsindex c99590e74f..b2cb830f20 100644--- a/apps/desktop/src/lib/mcp/mcpPolicySelection.ts+++ b/apps/desktop/src/lib/mcp/mcpPolicySelection.ts@@ -34,6 +34,7 @@ export const MCP_TOOL_OPTIONS = [{ name: "dbx_open_session", labelKey: "settings.mcpToolOpenSession" },{ name: "dbx_close_session", labelKey: "settings.mcpToolCloseSession" },{ name: "dbx_execute_redis_command", labelKey: "settings.mcpToolExecuteRedisCommand" },+ { name: "dbx_peek_messages", labelKey: "settings.mcpToolPeekMessages" },{ name: "dbx_send_message", labelKey: "settings.mcpToolSendMessage" },{ name: "dbx_add_connection", labelKey: "settings.mcpToolAddConnection" },{ name: "dbx_duplicate_connection", labelKey: "settings.mcpToolDuplicateConnection" },diff --git a/crates/dbx-mcp/src/backend.rs b/crates/dbx-mcp/src/backend.rsindex 6c040f0196..ef1eba7499 100644--- a/crates/dbx-mcp/src/backend.rs+++ b/crates/dbx-mcp/src/backend.rs@@ -215,6 +215,17 @@ pub trait DbxBackend: Send + Sync {let _ = (connection, request);Err("Message queue sending is not supported by this backend.".to_string())}+ #[cfg(feature = "mq-admin")]+ async fn peek_messages(+ &self,+ connection: &ConnectionConfig,+ topic: dbx_core::mq::TopicRef,+ count: u32,+ options: dbx_core::mq::PeekMessagesOptions,+ ) -> Result<dbx_core::mq::PeekMessagesResult, String> {+ let _ = (connection, topic, count, options);+ Err("Message queue reading is not supported by this backend.".to_string())+ }async fn execute_query(&self,connection: &ConnectionConfig,@@ -766,6 +777,25 @@ impl DbxBackend for LocalBackend {dbx_core::mq::service::mq_send_message_core(&self.state, &connection.id, request).await}+ #[cfg(feature = "mq-admin")]+ async fn peek_messages(+ &self,+ connection: &ConnectionConfig,+ topic: dbx_core::mq::TopicRef,+ count: u32,+ options: dbx_core::mq::PeekMessagesOptions,+ ) -> Result<dbx_core::mq::PeekMessagesResult, String> {+ dbx_core::mq::service::mq_peek_messages_core(+ &self.state,+ &connection.id,+ topic,+ "__dbx_kafka_viewer__".into(),+ count,+ Some(options),+ )+ .await+ }+async fn execute_query(&self,connection: &ConnectionConfig,@@ -1174,6 +1204,21 @@ impl DbxBackend for WebBackend {.map_err(|error| format!("Invalid message send response: {error}"))}+ #[cfg(feature = "mq-admin")]+ async fn peek_messages(+ &self,+ connection: &ConnectionConfig,+ topic: dbx_core::mq::TopicRef,+ count: u32,+ options: dbx_core::mq::PeekMessagesOptions,+ ) -> Result<dbx_core::mq::PeekMessagesResult, String> {+ self.request(+ reqwest::Method::POST,+ "/api/mq/subscriptions/peek-messages",+ Some(json!({ "connectionId": connection.id, "topic": topic, "sub": "__dbx_kafka_viewer__", "count": count, "options": options })),+ ).await?.json().await.map_err(|error| format!("Invalid message peek response: {error}"))+ }+async fn execute_query(&self,connection: &ConnectionConfig,@@ -2538,6 +2583,81 @@ mod tests {assert_eq!(second_request["timeoutSecs"], 300);}+ #[cfg(feature = "mq-admin")]+ #[tokio::test]+ async fn web_peek_messages_forwards_kafka_options_and_preserves_partial_results() {+ use dbx_core::mq::{PeekMessagesOptions, PeekStartPosition, TopicRef};+ use std::io::BufRead;+ let listener = TcpListener::bind("127.0.0.1:0").unwrap();+ let address = listener.local_addr().unwrap();+ let server = std::thread::spawn(move || {+ let (mut stream, _) = listener.accept().unwrap();+ stream.set_read_timeout(Some(Duration::from_secs(5))).unwrap();+ let mut reader = std::io::BufReader::new(&mut stream);+ let mut line = String::new();+ reader.read_line(&mut line).unwrap();+ assert_eq!(line.trim(), "POST /api/mq/subscriptions/peek-messages HTTP/1.1");+ let mut content_length = 0;+ loop {+ line.clear();+ assert!(reader.read_line(&mut line).unwrap() > 0);+ if line == "\r\n" {+ break;+ }+ if let Some((name, value)) = line.split_once(':') {+ if name.eq_ignore_ascii_case("content-length") {+ content_length = value.trim().parse::<usize>().unwrap();+ }+ }+ }+ let mut body = vec![0; content_length];+ reader.read_exact(&mut body).unwrap();+ let body: Value = serde_json::from_slice(&body).unwrap();+ assert_eq!(body["connectionId"], "kafka-peek");+ assert_eq!(body["topic"]["topic"], "events");+ assert_eq!(body["sub"], "__dbx_kafka_viewer__");+ assert_eq!(body["count"], 7);+ assert_eq!(body["options"], json!({"startPosition":"offset", "partition":2, "offset":17}));+ let response = r#"{"messages":[{"position":1,"messageId":"2:17","payloadBase64":"/w==","headers":{"type":"binary"}}],"incomplete":true}"#;+ write!(stream, "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}", response.len(), response).unwrap();+ });+ let backend =+ WebBackend::new_with_config(format!("http://{address}"), String::new(), None, None, None, false, None)+ .unwrap();+ backend.auth.lock().await.checked = true;+ let connection = new_connection_config(+ "kafka-peek".into(),+ "Kafka".into(),+ DatabaseType::MessageQueue,+ "localhost".into(),+ 9092,+ String::new(),+ String::new(),+ None,+ false,+ None,+ )+ .unwrap();+ let result = backend+ .peek_messages(+ &connection,+ TopicRef { topic: "events".into(), ..Default::default() },+ 7,+ PeekMessagesOptions {+ start_position: Some(PeekStartPosition::Offset),+ partition: Some(2),+ offset: Some(17),+ },+ )+ .await+ .unwrap();+ assert!(result.incomplete);+ assert_eq!(result.messages[0].payload_base64, "/w==");+ assert_eq!(result.messages[0].message_id.as_deref(), Some("2:17"));+ assert_eq!(result.messages[0].headers.get("type").map(String::as_str), Some("binary"));+ server.join().unwrap();+ }+#[tokio::test]async fn web_execute_batch_hits_execute_multi_and_decodes_statement_results() {let listener = TcpListener::bind("127.0.0.1:0").unwrap();diff --git a/crates/dbx-mcp/src/server.rs b/crates/dbx-mcp/src/server.rsindex cb3d5a1e91..f684aeeeac 100644--- a/crates/dbx-mcp/src/server.rs+++ b/crates/dbx-mcp/src/server.rs@@ -197,6 +197,32 @@ pub struct ExecuteRedisCommandRequest {pub command: String,}+#[derive(Debug, Default, serde::Serialize, Deserialize, schemars::JsonSchema)]+#[serde(rename_all = "lowercase")]+pub enum PeekStartPosition {+ #[default]+ Latest,+ Earliest,+ Offset,+}++#[derive(Debug, Deserialize, schemars::JsonSchema)]+pub struct PeekMessagesRequest {+ #[serde(flatten)]+ pub selector: ConnectionSelector,+ #[schemars(description = "Kafka topic name")]+ pub topic: String,+ #[schemars(description = "Number of messages, 1 to 100 (default 20)", extend("type" = "integer"))]+ pub count: Option<u32>,+ #[serde(default)]+ #[schemars(description = "Read latest messages (default), earliest messages, or from an offset")]+ pub start_position: PeekStartPosition,+ #[schemars(description = "Non-negative partition; omit to read across partitions", extend("type" = "integer"))]+ pub partition: Option<i32>,+ #[schemars(description = "Non-negative offset, required only for start_position=offset", extend("type" = "integer"))]+ pub offset: Option<i64>,+}+#[derive(Debug, Deserialize, schemars::JsonSchema)]pub struct SendMessageRequest {#[serde(flatten)]@@ -382,7 +408,10 @@ impl DbxMcpServer {tool_router.disable_route("dbx_execute_and_show");}#[cfg(not(feature = "mq-admin"))]- tool_router.disable_route("dbx_send_message");+ {+ tool_router.disable_route("dbx_send_message");+ tool_router.disable_route("dbx_peek_messages");+ }Self { backend, scope, sessions: McpSessionStore::new(), tool_router }}@@ -1059,6 +1088,68 @@ impl DbxMcpServer {}}+ #[tool(+ name = "dbx_peek_messages",+ description = "Read up to 100 Kafka messages without committing consumer offsets. Defaults to the latest 20 messages. Returns JSON with base64 payloads, UTF-8 previews, metadata, incomplete (partial broker read), and outputTruncated (256 KiB message output budget). Only Kafka is supported."+ )]+ async fn peek_messages(&self, Parameters(request): Parameters<PeekMessagesRequest>) -> CallToolResult {+ if let Err(error) = self.ensure_tool_allowed("dbx_peek_messages").await {+ return error;+ }+ #[cfg(not(feature = "mq-admin"))]+ {+ let _ = request;+ tool_error("MQ_UNSUPPORTED", "Message queue support is not compiled into this DBX MCP build.")+ }+ #[cfg(feature = "mq-admin")]+ {+ use dbx_core::mq::{+ config::MqAdminConfig, MqSystemKind, PeekMessagesOptions, PeekStartPosition as Start, TopicRef,+ };+ let resolved = match self.resolve_connection(&request.selector).await {+ Ok(resolved) => resolved,+ Err(error) => return error,+ };+ match MqAdminConfig::from_connection(&resolved.connection) {+ Ok(config) if config.system_kind == MqSystemKind::Kafka => {}+ _ => {+ return tool_error("MQ_UNSUPPORTED", "Message reading through MCP supports Kafka connections only.")+ }+ }+ let count = request.count.unwrap_or(20);+ let start_position = match request.start_position {+ PeekStartPosition::Latest => Start::Latest,+ PeekStartPosition::Earliest => Start::Earliest,+ PeekStartPosition::Offset => Start::Offset,+ };+ if request.topic.trim().is_empty() {+ return tool_error("MESSAGE_TOPIC_REQUIRED", "Message topic must not be empty.");+ }+ if !(1..=100).contains(&count)+ || request.partition.is_some_and(|value| value < 0)+ || request.offset.is_some_and(|value| value < 0)+ || (start_position == Start::Offset) != request.offset.is_some()+ {+ return tool_error("INVALID_PEEK_OPTIONS", "count must be 1..100; partition and offset must be non-negative; offset is required only for start_position=offset.");+ }+ let topic = TopicRef {+ tenant: "_kafka".into(),+ namespace: "default".into(),+ topic: request.topic.trim().into(),+ ..Default::default()+ };+ let options = PeekMessagesOptions {+ start_position: Some(start_position),+ partition: request.partition,+ offset: request.offset,+ };+ match self.backend.peek_messages(&resolved.connection, topic, count, options).await {+ Ok(result) => text(format_peek_messages_result(result, count as usize)),+ Err(error) => backend_tool_error("MESSAGE_PEEK_ERROR", error),+ }+ }+ }+#[tool(name = "dbx_send_message",description = "Send a base64-encoded message to a Kafka, RocketMQ, or RabbitMQ topic/queue"@@ -2127,6 +2218,23 @@ fn non_empty_env(name: &str) -> Option<String> {std::env::var(name).ok().map(|value| value.trim().to_string()).filter(|value| !value.is_empty())}+#[cfg(feature = "mq-admin")]+fn format_peek_messages_result(result: dbx_core::mq::PeekMessagesResult, count: usize) -> String {+ let mut messages = Vec::new();+ let mut bytes = 0;+ let mut truncated = result.messages.len() > count;+ for message in result.messages.into_iter().take(count) {+ let value = serde_json::to_value(message).expect("message is JSON serializable");+ bytes += value.to_string().len();+ if bytes > 256 * 1024 {+ truncated = true;+ break;+ }+ messages.push(value);+ }+ json!({ "messages": messages, "incomplete": result.incomplete, "outputTruncated": truncated }).to_string()+}+#[cfg(feature = "mq-admin")]fn format_send_message_result(system_kind: &dbx_core::mq::MqSystemKind,@@ -2391,6 +2499,28 @@ mod tests {}}+ #[cfg(feature = "mq-admin")]+ async fn peek_messages(+ &self,+ connection: &ConnectionConfig,+ topic: dbx_core::mq::TopicRef,+ count: u32,+ options: dbx_core::mq::PeekMessagesOptions,+ ) -> Result<dbx_core::mq::PeekMessagesResult, String> {+ self.recorded_arguments.lock().unwrap().push((+ "peek_messages".into(),+ json!({"connectionId": connection.id, "topic": topic, "count": count, "options": options}),+ ));+ Ok(dbx_core::mq::PeekMessagesResult {+ messages: vec![dbx_core::mq::PeekedMessage {+ payload_base64: "aGk=".into(),+ payload_text: Some("hi".into()),+ ..Default::default()+ }],+ incomplete: true,+ })+ }+async fn close_client_session(&self,_connection_id: &str,@@ -2480,6 +2610,155 @@ mod tests {}}+ #[cfg(feature = "mq-admin")]+ fn kafka_connection() -> ConnectionConfig {+ let mut conn = connection("kafka", "Kafka", "mq", "");+ conn.read_only = true;+ conn.is_production = true;+ conn.external_config = Some(+ json!({"systemKind":"kafka", "adminUrl":"", "auth":{"kind":"none"}, "extra":{"bootstrapServers":"localhost:9092"}}),+ );+ conn+ }++ #[cfg(feature = "mq-admin")]+ #[tokio::test]+ async fn peek_messages_reads_with_read_only_policy_and_forwards_positions() {+ let backend = Arc::new(FakeBackend { connections: vec![kafka_connection()], ..Default::default() });+ let server = DbxMcpServer::with_runtime_options(backend.clone(), McpScope::default(), false);+ for (extra, expected) in [+ (json!({}), json!({"startPosition":"latest"})),+ (json!({"start_position":"earliest", "partition":0}), json!({"startPosition":"earliest", "partition":0})),+ (+ json!({"start_position":"offset", "partition":2, "offset":17}),+ json!({"startPosition":"offset", "partition":2, "offset":17}),+ ),+ (json!({"start_position":"offset", "offset":0}), json!({"startPosition":"offset", "offset":0})),+ ] {+ let mut request = json!({"connection_id":"kafka", "topic":" events "});+ request.as_object_mut().unwrap().extend(extra.as_object().unwrap().clone());+ let result = server.peek_messages(Parameters(serde_json::from_value(request).unwrap())).await;+ assert_ne!(result.is_error, Some(true), "{}", result_text(&result));+ let response: serde_json::Value = serde_json::from_str(result_text(&result)).unwrap();+ assert_eq!(response["messages"][0]["payloadBase64"], "aGk=");+ assert_eq!(response["incomplete"], true);+ assert_eq!(response["outputTruncated"], false);+ let calls = backend.recorded_arguments.lock().unwrap();+ let args = &calls.last().unwrap().1;+ assert_eq!(args["options"], expected);+ assert_eq!(args["count"], 20);+ assert_eq!(args["topic"]["topic"], "events");+ }+ }++ #[cfg(feature = "mq-admin")]+ #[tokio::test]+ async fn peek_messages_rejects_invalid_options_before_backend_call() {+ let backend = Arc::new(FakeBackend { connections: vec![kafka_connection()], ..Default::default() });+ let server = DbxMcpServer::with_runtime_options(backend.clone(), McpScope::default(), false);+ for extra in [+ json!({"count":0}),+ json!({"count":101}),+ json!({"partition":-1}),+ json!({"start_position":"offset"}),+ json!({"offset":1}),+ json!({"start_position":"earliest", "offset":0}),+ json!({"start_position":"offset", "offset":-1}),+ json!({"topic":" "}),+ ] {+ let mut request = json!({"connection_id":"kafka", "topic":"events"});+ request.as_object_mut().unwrap().extend(extra.as_object().unwrap().clone());+ let result = server.peek_messages(Parameters(serde_json::from_value(request).unwrap())).await;+ assert_eq!(result.is_error, Some(true), "{}", result_text(&result));+ }+ assert!(backend.recorded_arguments.lock().unwrap().is_empty());+ }++ #[cfg(feature = "mq-admin")]+ #[tokio::test]+ async fn peek_messages_enforces_tool_connection_scope_and_kafka_only() {+ for (policy, conn, expected) in [+ (+ McpGlobalPolicy { allowed_tool_names: Some(vec![]), ..Default::default() },+ kafka_connection(),+ "TOOL_OUT_OF_SCOPE",+ ),+ (+ McpGlobalPolicy { allowed_connection_ids: Some(vec![]), ..Default::default() },+ kafka_connection(),+ "CONNECTION_OUT_OF_SCOPE",+ ),+ (McpGlobalPolicy::default(), connection("kafka", "redis", "redis", "0"), "MQ_UNSUPPORTED"),+ ] {+ let backend = Arc::new(FakeBackend { policy, connections: vec![conn], ..Default::default() });+ let server = DbxMcpServer::with_runtime_options(backend.clone(), McpScope::default(), false);+ let result = server+ .peek_messages(Parameters(+ serde_json::from_value(json!({"connection_id":"kafka", "topic":"events"})).unwrap(),+ ))+ .await;+ assert_eq!(result.is_error, Some(true));+ assert!(result_text(&result).contains(expected), "{}", result_text(&result));+ assert!(backend.recorded_arguments.lock().unwrap().is_empty());+ }+ }++ #[cfg(feature = "mq-admin")]+ #[tokio::test]+ async fn peek_messages_respects_session_scope_and_rejects_other_queues() {+ let mut rabbit = kafka_connection();+ rabbit.external_config.as_mut().unwrap()["systemKind"] = json!("rabbitmq");+ for (conn, scope, expected) in [+ (+ kafka_connection(),+ McpScope { connection_ids: vec!["other".into()], ..Default::default() },+ "CONNECTION_OUT_OF_SCOPE",+ ),+ (rabbit, McpScope::default(), "MQ_UNSUPPORTED"),+ ] {+ let backend = Arc::new(FakeBackend { connections: vec![conn], ..Default::default() });+ let server = DbxMcpServer::with_runtime_options(backend.clone(), scope, false);+ let result = server+ .peek_messages(Parameters(+ serde_json::from_value(json!({"connection_id":"kafka", "topic":"events"})).unwrap(),+ ))+ .await;+ assert_eq!(result.is_error, Some(true));+ assert!(result_text(&result).contains(expected), "{}", result_text(&result));+ assert!(backend.recorded_arguments.lock().unwrap().is_empty());+ }+ }++ #[cfg(feature = "mq-admin")]+ #[test]+ fn peek_messages_output_preserves_metadata_and_bounds_whole_messages() {+ use dbx_core::mq::{PeekMessagesResult, PeekedMessage};+ let message = PeekedMessage {+ payload_base64: "/w==".into(),+ message_id: Some("2:17".into()),+ headers: [("kind".into(), "event".into())].into(),+ ..Default::default()+ };+ let output = format_peek_messages_result(PeekMessagesResult::complete(vec![message.clone(), message]), 1);+ let result: serde_json::Value = serde_json::from_str(&output).unwrap();+ assert_eq!(result["messages"].as_array().unwrap().len(), 1);+ assert_eq!(result["messages"][0]["messageId"], "2:17");+ assert_eq!(result["messages"][0]["headers"]["kind"], "event");+ assert_eq!(result["outputTruncated"], true);+ assert_eq!(result["incomplete"], false);+ let output = format_peek_messages_result(+ PeekMessagesResult::complete(vec![PeekedMessage {+ payload_base64: "a".repeat(300_000),+ ..Default::default()+ }]),+ 20,+ );+ let result: serde_json::Value = serde_json::from_str(&output).unwrap();+ assert!(result["messages"].as_array().unwrap().is_empty());+ assert_eq!(result["outputTruncated"], true);+ assert!(output.len() < 256 * 1024);+ }+#[test]fn connection_table_escapes_markdown_cells() {let output = format_connections(&[ConnectionSummary {@@ -2502,9 +2781,13 @@ mod tests {let tools = server.tool_router.list_all();let names = tools.iter().map(|tool| tool.name.as_ref()).collect::<Vec<_>>();#[cfg(feature = "mq-admin")]- assert_eq!(tools.len(), 18);+ assert_eq!(tools.len(), 19);#[cfg(not(feature = "mq-admin"))]assert_eq!(tools.len(), 17);+ #[cfg(feature = "mq-admin")]+ assert!(names.contains(&"dbx_peek_messages"));+ #[cfg(not(feature = "mq-admin"))]+ assert!(!names.contains(&"dbx_peek_messages"));assert!(names.contains(&"dbx_list_connections"));assert!(names.contains(&"dbx_list_databases"));assert!(names.contains(&"dbx_list_tables"));@@ -2638,6 +2921,8 @@ mod tests {checks.push(("dbx_send_message", &["key", "payload_text", "partition", "exchange", "routing_key", "namespace"]));+ #[cfg(feature = "mq-admin")]+ checks.push(("dbx_peek_messages", &["count", "partition", "offset"]));for (tool_name, fields) in checks {let tool = tools.iter().find(|tool| tool.name == *tool_name).expect("tool should be registered");let properties = tool@@ -2748,7 +3033,7 @@ mod tests {);let names = server.tool_router.list_all().into_iter().map(|tool| tool.name).collect::<Vec<_>>();#[cfg(feature = "mq-admin")]- assert_eq!(names.len(), 13);+ assert_eq!(names.len(), 14);#[cfg(not(feature = "mq-admin"))]assert_eq!(names.len(), 12);assert!(!names.iter().any(|name| name == "dbx_add_connection"));diff --git a/crates/dbx-mcp/tests/protocol.rs b/crates/dbx-mcp/tests/protocol.rsindex 3ca7b550e0..23320a8dbb 100644--- a/crates/dbx-mcp/tests/protocol.rs+++ b/crates/dbx-mcp/tests/protocol.rs@@ -121,6 +121,25 @@ struct CapturingBackend {#[async_trait]impl DbxBackend for CapturingBackend {+ #[cfg(feature = "mq-admin")]+ async fn peek_messages(+ &self,+ connection: &ConnectionConfig,+ topic: dbx_core::mq::TopicRef,+ count: u32,+ options: dbx_core::mq::PeekMessagesOptions,+ ) -> Result<dbx_core::mq::PeekMessagesResult, String> {+ self.calls+ .lock()+ .unwrap()+ .push(json!({"connection":connection.id, "topic":topic.topic, "count":count, "options":options}));+ Ok(dbx_core::mq::PeekMessagesResult::complete(vec![dbx_core::mq::PeekedMessage {+ payload_base64: "aGk=".into(),+ payload_text: Some("hi".into()),+ ..Default::default()+ }]))+ }+async fn load_mcp_global_policy(&self) -> Result<McpGlobalPolicy, String> {Ok(self.policy.clone())}@@ -285,9 +304,13 @@ async fn initializes_lists_tools_and_calls_a_tool() {let tools = client.peer().list_tools(None).await.expect("list tools");let names = tools.tools.iter().map(|tool| tool.name.as_ref()).collect::<Vec<_>>();#[cfg(feature = "mq-admin")]- assert_eq!(names.len(), 18);+ assert_eq!(names.len(), 19);#[cfg(not(feature = "mq-admin"))]assert_eq!(names.len(), 17);+ #[cfg(feature = "mq-admin")]+ assert!(names.contains(&"dbx_peek_messages"));+ #[cfg(not(feature = "mq-admin"))]+ assert!(!names.contains(&"dbx_peek_messages"));assert!(names.contains(&"dbx_list_connections"));assert!(names.contains(&"dbx_list_databases"));assert!(names.contains(&"dbx_duplicate_connection"));@@ -309,6 +332,51 @@ async fn initializes_lists_tools_and_calls_a_tool() {server_task.abort();}+#[cfg(feature = "mq-admin")]+#[tokio::test]+async fn kafka_peek_round_trips_over_mcp_in_local_and_web_modes() {+ let mut connection = test_connection("kafka", "Kafka");+ connection.db_type = dbx_core::models::connection::DatabaseType::MessageQueue;+ connection.read_only = true;+ connection.is_production = true;+ connection.external_config = Some(json!({"systemKind":"kafka", "adminUrl":"", "auth":{"kind":"none"}}));+ for web_mode in [false, true] {+ let backend = Arc::new(CapturingBackend {+ policy: McpGlobalPolicy::default(),+ connections: vec![connection.clone()],+ calls: Mutex::new(vec![]),+ });+ let (server_transport, client_transport) = tokio::io::duplex(16 * 1024);+ let server = DbxMcpServer::with_runtime_options(backend.clone(), McpScope::default(), web_mode);+ let server_task = tokio::spawn(async move { server.serve(server_transport).await });+ let client = ().serve(client_transport).await.unwrap();+ let result = client.peer().call_tool(CallToolRequestParams::new("dbx_peek_messages").with_arguments(json!({"connection_name":"Kafka", "topic":"events", "count":100, "start_position":"offset", "partition":0, "offset":120}).as_object().unwrap().clone())).await.unwrap();+ assert_ne!(result.is_error, Some(true), "{result:?}");+ let body: Value = serde_json::from_str(&result.content[0].as_text().unwrap().text).unwrap();+ assert_eq!(body["messages"][0]["payloadText"], "hi");+ assert_eq!(body["incomplete"], false);+ assert_eq!(+ backend.calls.lock().unwrap()[0],+ json!({"connection":"kafka", "topic":"events", "count":100, "options":{"startPosition":"offset", "partition":0, "offset":120}})+ );+ let invalid = client+ .peer()+ .call_tool(+ CallToolRequestParams::new("dbx_peek_messages").with_arguments(+ json!({"connection_id":"kafka", "topic":"events", "start_position":"invalid"})+ .as_object()+ .unwrap()+ .clone(),+ ),+ )+ .await;+ assert!(invalid.is_err() || invalid.unwrap().is_error == Some(true));+ assert_eq!(backend.calls.lock().unwrap().len(), 1);+ client.cancel().await.unwrap();+ server_task.abort();+ }+}+#[tokio::test]async fn remove_connection_respects_global_connection_scope() {let backend = PolicyBackend {diff --git a/docs/content/docs/mcp.cn.mdx b/docs/content/docs/mcp.cn.mdxindex ea70d84991..900c259693 100644--- a/docs/content/docs/mcp.cn.mdx+++ b/docs/content/docs/mcp.cn.mdx@@ -87,7 +87,7 @@ DeepSeek Harness 通过 Cordis 插件条目加载 MCP Server,不读取 `mcpSer## 工具列表-DBX MCP 当前提供 18 个工具:+DBX MCP 当前提供以下工具(具体可用工具取决于构建功能及权限设置):| 工具 | 说明 || --- | --- |@@ -106,12 +106,35 @@ DBX MCP 当前提供 18 个工具:| `dbx_open_session` | 为 SQL 连接打开固定后端连接的有状态查询会话 || `dbx_close_session` | 关闭会话并释放固定连接资源 || `dbx_execute_redis_command` | 执行 Redis 命令 |+| `dbx_peek_messages` | 读取 Kafka 消息,不提交消费位点 || `dbx_send_message` | 向支持的消息队列 Topic 或队列发送消息 || `dbx_open_table` | 在运行中的 DBX 桌面端打开表 || `dbx_execute_and_show` | 执行查询并在 DBX 中展示结果 |启用连接作用域后,修改连接和桌面 UI 工具会被隐藏。+## 读取 Kafka 消息++包含 `mq-admin` 的构建在本地和 Web 模式下均提供 `dbx_peek_messages`。通过 `connection_id` 或 `connection_name` 选择已保存的 Kafka 连接,并指定 `topic`。工具遵守 MCP 连接范围及工具白名单,允许读取只读连接和生产连接,不提交消费位点。++```json+{+ "connection_name": "Kafka",+ "topic": "events",+ "count": 20,+ "start_position": "offset",+ "partition": 0,+ "offset": 120+}+```++- `count`:1–100,默认 20。+- `start_position`:`latest`(默认)、`earliest` 或 `offset`。仅 `offset` 模式必须且允许传入非负 `offset`。+- `partition`:可选的非负分区号。不传时跨分区读取;offset 模式下从各分区的该位点开始读取。+- JSON 结果包含 `messages`,保留 base64 消息体、可无损解码时的 UTF-8 预览、消息 ID 和元数据。`incomplete` 表示读取达到超时或扫描上限;`outputTruncated` 表示为满足 256 KiB 消息输出预算而省略了整条消息。如果首条消息过大,可能返回空列表并标记 `outputTruncated: true`,不会静默截断消息体。++该工具读取有限条消息快照,不提供持续订阅或全 Topic 文本搜索。其他消息队列类型会被拒绝。+## 批量 SQL 执行`dbx_execute_batch` 在单次调用内执行包含多条语句的 SQL 脚本。默认(自动提交)模式下按语句返回结果,因此调用方可以清楚看到哪条失败、每条影响多少行、各自返回什么;使用 `use_transaction` 且脚本包含多条语句时,只返回一个合并的事务结果。diff --git a/docs/content/docs/mcp.mdx b/docs/content/docs/mcp.mdxindex ad8ec8213d..5411b1b89a 100644--- a/docs/content/docs/mcp.mdx+++ b/docs/content/docs/mcp.mdx@@ -87,7 +87,7 @@ Run `dsh web --dump-config` to verify the composed configuration, then restart D## Tools-DBX MCP currently provides 18 tools:+DBX MCP provides the following tools (availability depends on build features and access settings):| Tool | Description || --- | --- |@@ -106,12 +106,35 @@ DBX MCP currently provides 18 tools:| `dbx_open_session` | Open a stateful SQL query session pinned to one backend connection || `dbx_close_session` | Close a session and release its pinned connection resources || `dbx_execute_redis_command` | Execute a Redis command |+| `dbx_peek_messages` | Read Kafka messages without committing consumer offsets || `dbx_send_message` | Send a message to a supported message queue topic or queue || `dbx_open_table` | Open a table in the running DBX desktop app || `dbx_execute_and_show` | Execute a query and display the result in DBX |Connection-scoped sessions hide connection-mutating and desktop UI tools.+## Read Kafka Messages++`dbx_peek_messages` is available in builds with `mq-admin`, in both local and Web modes. Select a saved Kafka connection by `connection_id` or `connection_name` and provide `topic`. It respects MCP connection scopes and tool allowlists and works with read-only and production connections without committing consumer offsets.++```json+{+ "connection_name": "Kafka",+ "topic": "events",+ "count": 20,+ "start_position": "offset",+ "partition": 0,+ "offset": 120+}+```++- `count`: 1–100, defaults to 20.+- `start_position`: `latest` (default), `earliest`, or `offset`. Supply a non-negative `offset` only with `offset` mode.+- `partition`: optional non-negative partition number. If omitted, reads across topic partitions; in offset mode, the offset applies to every partition.+- The JSON response contains `messages` with base64 payloads, lossless UTF-8 previews when available, message IDs and metadata. `incomplete` means the broker read reached a deadline or scan limit. `outputTruncated` means whole messages were omitted to fit the 256 KiB message output budget. A single oversized message may therefore yield no messages with `outputTruncated: true`; payloads are never silently clipped.++This is a bounded snapshot, not a continuous consumer or a topic-wide text search. Other message queue types are rejected.+## Batch SQL Execution`dbx_execute_batch` runs a SQL script containing multiple statements in a single call. In auto-commit mode (the default) it returns one result per statement, so callers see exactly which statement failed, how many rows each affected, and what each returned. With `use_transaction` and a script containing multiple statements it returns a single merged transaction outcome instead.diff --git a/docs/content/docs/mcp.tr.mdx b/docs/content/docs/mcp.tr.mdxindex d643302e48..c73aa908d9 100644--- a/docs/content/docs/mcp.tr.mdx+++ b/docs/content/docs/mcp.tr.mdx@@ -87,7 +87,7 @@ Oluşan yapılandırmayı doğrulamak için `dsh web --dump-config` çalıştır## Araçlar-DBX MCP şu anda 17 araç sunar:+DBX MCP aşağıdaki araçları sunar:| Araç | Açıklama || --- | --- |@@ -105,6 +105,7 @@ DBX MCP şu anda 17 araç sunar:| `dbx_open_session` | Tek bir arka uç bağlantısına sabitlenmiş durumlu bir SQL sorgu oturumu açar || `dbx_close_session` | Bir oturumu kapatır ve sabitlenmiş bağlantı kaynaklarını serbest bırakır || `dbx_execute_redis_command` | Bir Redis komutu çalıştırır |+| `dbx_peek_messages` | Tüketici ofsetlerini kaydetmeden Kafka mesajlarını okur || `dbx_send_message` | Desteklenen bir mesaj kuyruğu konusuna ya da kuyruğuna mesaj gönderir || `dbx_open_table` | Çalışan DBX masaüstü uygulamasında bir tablo açar || `dbx_execute_and_show` | Bir sorgu çalıştırır ve sonucu DBX'te gösterir |diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.mdindex 9148471f6b..b28d3f3949 100644--- a/packages/mcp-server/README.md+++ b/packages/mcp-server/README.md@@ -157,12 +157,15 @@ Ask the MCP client to:| `dbx_open_session` | Open a stateful SQL query session pinned to one backend connection || `dbx_close_session` | Close a session and release its pinned connection resources || `dbx_execute_redis_command` | Execute a Redis command |+| `dbx_peek_messages` | Read Kafka messages without committing consumer offsets || `dbx_send_message` | Send a message to a supported message queue topic || `dbx_open_table` | Open a table in the running DBX desktop application || `dbx_execute_and_show` | Execute a query and display the result in the DBX desktop application |When connection scoping is enabled, mutating connection tools and desktop UI tools are hidden.+`dbx_peek_messages` reads a Kafka topic in local or Web mode when `mq-admin` is enabled. Pass `connection_id` or `connection_name`, `topic`, optional `count` (1–100, default 20), `start_position` (`latest` by default, `earliest`, or `offset`), and optional non-negative `partition`. A non-negative `offset` is required only in offset mode; without a partition it applies to all partitions. The JSON response preserves base64 payloads and metadata, reports broker partial reads via `incomplete`, and reports whole-message omissions under a 256 KiB output budget via `outputTruncated`. It respects connection/tool scopes and permits read-only and production reads without committing consumer offsets. It does not support other MQ types or continuous subscriptions.+`dbx_list_databases` returns only database names allowed by the selected connection's MCP database scope. `dbx_send_message` is available when message-queue support is included in the server build.## Execution Modes@@ -531,10 +534,13 @@ MCP 配置:| `dbx_open_session` | 为 SQL 连接打开固定后端连接的有状态查询会话 || `dbx_close_session` | 关闭会话并释放固定连接资源 || `dbx_execute_redis_command` | 执行 Redis 命令 |+| `dbx_peek_messages` | 读取 Kafka 消息,不提交消费位点 || `dbx_send_message` | 向支持的消息队列 Topic 发送消息 || `dbx_open_table` | 在 DBX 桌面端打开表 || `dbx_execute_and_show` | 执行查询并在 DBX 桌面端展示结果 |+启用 `mq-admin` 后,`dbx_peek_messages` 可在本地和 Web 模式下读取 Kafka Topic。参数为 `connection_id` 或 `connection_name`、`topic`、可选 `count`(1–100,默认 20)、`start_position`(默认 `latest`,也支持 `earliest`、`offset`)及可选的非负 `partition`。仅 offset 模式必须且允许指定非负 `offset`,未指定分区时该位点应用于所有分区。JSON 结果保留 base64 消息体和元数据,通过 `incomplete` 标记底层不完整读取,通过 `outputTruncated` 标记因 256 KiB 输出预算而省略整条消息。工具遵守连接和工具范围,允许只读与生产连接读取,不提交消费位点,不支持其他 MQ 类型或持续订阅。+`dbx_list_databases` 只返回该连接 MCP 数据库范围内允许访问的名称。`dbx_send_message` 仅在 Server 构建时包含消息队列支持时可用。### 本地数据目录