added mcp_disconnect function and improve error handling

Author: Gioee

API.md

@@ -63,11 +63,6 @@ SELECT mcp_connect(
 );
 ```
 
-**Response:**
-```json
-{"status": "connected", "transport": "streamable_http"}
-```
-
 See [USAGE.md](USAGE.md) for more examples of using custom headers.
 
 ---
@@ -423,10 +418,31 @@ SELECT mcp_connect('http://localhost:8931/sse', NULL, 1);
 
 ## Error Handling
 
-All functions return JSON with error information on failure:
+The sqlite-mcp extension has two types of error handling:
+
+1. **JSON Functions** (ending with `_json`): Return JSON with error information
+2. **Non-JSON Functions**: Return error strings directly (extracted from JSON)
+3. **Virtual Tables**: Return no rows on error, use scalar functions to check status
+
+### mcp_connect()
+
+Returns `NULL` on success, or an error string on failure:
+
+```sql
+-- Check if connection succeeded
+SELECT mcp_connect('http://localhost:8000/mcp') IS NULL;
+-- Returns 1 (true) on success, 0 (false) on failure
+
+-- Get error message if connection failed
+SELECT mcp_connect('http://invalid:8000/mcp');
+-- Returns: "Failed to connect to MCP server: ..."
+```
+
+### JSON Functions: mcp_list_tools_json() and mcp_call_tool_json()
+
+Always return JSON - either with results or error information:
 
 ```json
-{"error": "Connection failed: timeout"}
 {"error": "Not connected. Call mcp_connect() first"}
 {"error": "Tool not found: invalid_tool"}
 {"error": "Invalid JSON arguments"}
@@ -442,4 +458,74 @@ SELECT
     ELSE 'Success'
   END
 FROM (SELECT mcp_call_tool_json('test', '{}') as result);
+```
+
+### Virtual Tables: mcp_list_tools, mcp_call_tool, mcp_list_tools_respond, mcp_call_tool_respond
+
+Virtual tables return no rows on error. To check for errors, use the corresponding JSON functions:
+
+```sql
+-- Check if server is connected before querying virtual table
+SELECT 
+  CASE 
+    WHEN json_extract(mcp_list_tools_json(), '$.error') IS NOT NULL
+    THEN 'Error: Cannot query virtual table - ' || json_extract(mcp_list_tools_json(), '$.error')
+    ELSE 'OK to query virtual table'
+  END;
+
+-- Query virtual table only if no error
+SELECT name, description FROM mcp_list_tools WHERE name LIKE 'browser_%';
+```
+
+### Common Error Messages
+
+All functions may return these error types:
+
+- **Connection errors**: `"Not connected. Call mcp_connect() first"`
+- **Server errors**: `"Failed to connect to MCP server: ..."`
+- **Tool errors**: `"Tool not found: tool_name"`
+- **Argument errors**: `"Invalid JSON arguments"`
+- **Transport errors**: `"Transport error: ..."`
+- **Timeout errors**: `"Request timeout"`
+
+### Error Handling Best Practices
+
+1. **Always check mcp_connect() result**:
+```sql
+-- Good practice: Check connection first
+SELECT 
+  CASE 
+    WHEN mcp_connect('http://localhost:8931/mcp') IS NULL 
+    THEN 'Connected successfully'
+    ELSE mcp_connect('http://localhost:8931/mcp')
+  END;
+```
+
+2. **Use JSON functions for error checking before virtual tables**:
+```sql
+-- Check for errors before using virtual table
+WITH error_check AS (
+  SELECT json_extract(mcp_list_tools_json(), '$.error') as error
+)
+SELECT 
+  CASE 
+    WHEN error_check.error IS NOT NULL 
+    THEN 'Error: ' || error_check.error
+    ELSE 'Tools: ' || (SELECT GROUP_CONCAT(name) FROM mcp_list_tools)
+  END
+FROM error_check;
+```
+
+3. **Handle tool call errors**:
+```sql
+-- Safe tool calling with error handling
+SELECT 
+  CASE 
+    WHEN json_extract(result, '$.error') IS NOT NULL
+    THEN 'Tool Error: ' || json_extract(result, '$.error')
+    ELSE json_extract(result, '$.content[0].text') 
+  END as output
+FROM (
+  SELECT mcp_call_tool_json('browser_navigate', '{"url": "https://example.com"}') as result
+);
 ```

src/lib.rs

@@ -13,10 +13,26 @@ use std::sync::{Mutex, OnceLock};
 use rmcp::transport::{SseClientTransport, StreamableHttpClientTransport};
 use rmcp::{ServiceExt, RoleClient};
 use rmcp::model::{ClientInfo, ClientCapabilities, Implementation};
+use serde_json;
 
 // Global client instance - one client per process
 static GLOBAL_CLIENT: OnceLock<Mutex<Option<McpClient>>> = OnceLock::new();
 
+/// Extract error message from JSON error response
+/// Returns the error message string if found, or the original JSON if not found
+fn extract_error_message(json_str: &str) -> String {
+    match serde_json::from_str::<serde_json::Value>(json_str) {
+        Ok(json) => {
+            if let Some(error) = json.get("error").and_then(|e| e.as_str()) {
+                error.to_string()
+            } else {
+                json_str.to_string()
+            }
+        }
+        Err(_) => json_str.to_string(),
+    }
+}
+
 /// Initialize the MCP library
 /// Returns 0 on success, non-zero on error
 #[no_mangle]
@@ -538,30 +554,55 @@ pub extern "C" fn mcp_connect(
                     // Return NULL on successful connection
                     ptr::null_mut()
                 } else {
-                    // Return error if status is not "connected"
-                    match CString::new(result) {
+                    // Return error string (extracted from JSON)
+                    let error_msg = extract_error_message(&result);
+                    match CString::new(error_msg) {
                         Ok(c_str) => c_str.into_raw(),
                         Err(_) => ptr::null_mut(),
                     }
                 }
             } else {
-                // No status field found, return as error
-                match CString::new(result) {
+                // No status field found, extract error message
+                let error_msg = extract_error_message(&result);
+                match CString::new(error_msg) {
                     Ok(c_str) => c_str.into_raw(),
                     Err(_) => ptr::null_mut(),
                 }
             }
         }
         Err(_) => {
-            // Invalid JSON, return as error
-            match CString::new(result) {
+            // Invalid JSON, return as error string
+            let error_msg = extract_error_message(&result);
+            match CString::new(error_msg) {
                 Ok(c_str) => c_str.into_raw(),
                 Err(_) => ptr::null_mut(),
             }
         }
     }
 }
 
+/// Disconnect from MCP server and reset global client state
+/// Returns NULL on success
+#[no_mangle]
+pub extern "C" fn mcp_disconnect() -> *mut c_char {
+    let global_client = GLOBAL_CLIENT.get_or_init(|| Mutex::new(None));
+    *global_client.lock().unwrap() = None;
+    
+    // Also clear any active stream channels
+    {
+        let runtime = tokio::runtime::Runtime::new().unwrap();
+        runtime.block_on(async {
+            let mut channels = STREAM_CHANNELS.lock().await;
+            channels.clear();
+        });
+    }
+    
+    // Reset stream counter
+    *STREAM_COUNTER.lock().unwrap() = 0;
+    
+    ptr::null_mut()
+}
+
 /// List tools available on the connected MCP server (returns raw JSON)
 /// Returns: JSON string with tools list (must be freed with mcp_free_string)
 #[no_mangle]

src/mcp_ffi.h

@@ -55,6 +55,12 @@ void mcp_client_free(McpClient* client);
  */
 char* mcp_connect(McpClient* client, const char* server_url, const char* headers_json, int32_t legacy_sse);
 
+/**
+ * Disconnect from MCP server and reset global client state
+ * Returns: NULL on success
+ */
+char* mcp_disconnect(void);
+
 #ifdef __cplusplus
 }
 #endif

src/sqlite-mcp.c

@@ -93,6 +93,27 @@ static void mcp_connect_func(
   mcp_free_string(result);
 }
 
+static void mcp_disconnect_func(
+  sqlite3_context *context,
+  int argc,
+  sqlite3_value **argv
+){
+  if (argc != 0) {
+    sqlite3_result_error(context, "mcp_disconnect takes no arguments", -1);
+    return;
+  }
+
+  char *result = mcp_disconnect();
+  
+  // Should always return NULL (success)
+  if (!result) {
+    sqlite3_result_null(context);
+  } else {
+    sqlite3_result_text(context, result, -1, SQLITE_TRANSIENT);
+    mcp_free_string(result);
+  }
+}
+
 /*
 ** STREAMING Virtual Table for mcp_list_tools
 ** Returns parsed tool information as rows using streaming API
@@ -1260,6 +1281,11 @@ int sqlite3_mcp_init(
                                0, mcp_connect_func, 0, 0);
   if (rc != SQLITE_OK) return rc;
 
+  rc = sqlite3_create_function(db, "mcp_disconnect", 0,
+                               SQLITE_UTF8,
+                               0, mcp_disconnect_func, 0, 0);
+  if (rc != SQLITE_OK) return rc;
+
   // Scalar functions that return JSON strings
   rc = sqlite3_create_function(db, "mcp_list_tools_json", 0,
                                SQLITE_UTF8,