fix(api): improve error handling for virtual tables

Author: Gioee

API.md

@@ -418,11 +418,11 @@ SELECT mcp_connect('http://localhost:8931/sse', NULL, 1);
 
 ## Error Handling
 
-The sqlite-mcp extension has two types of error handling:
+The sqlite-mcp extension has consistent error handling across all interfaces:
 
 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
+3. **Virtual Tables**: Return SQL errors with extracted error messages (like non-JSON functions)
 
 ### mcp_connect()
 
@@ -462,21 +462,26 @@ 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:
+Virtual tables return SQL errors with extracted error messages (similar to `mcp_connect()`):
 
 ```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 - errors are automatically returned as SQL errors
+SELECT name, description FROM mcp_list_tools;
+-- If not connected, returns SQL error: "Not connected. Call mcp_connect() first"
+
+-- Query call tool virtual table
+SELECT text FROM mcp_call_tool('nonexistent_tool', '{}');
+-- Returns SQL error: "Tool not found: nonexistent_tool"
 
--- Query virtual table only if no error
-SELECT name, description FROM mcp_list_tools WHERE name LIKE 'browser_%';
+-- Errors can be caught in application code using sqlite3_errmsg()
+-- Or handled in SQL with error handlers
 ```
 
+**Error Behavior:**
+- When an MCP error occurs (not connected, tool not found, invalid JSON, etc.), the virtual table returns `SQLITE_ERROR`
+- The error message is extracted from the JSON error response and set as the SQL error message
+- This provides immediate, clear feedback without needing to check JSON functions separately
+
 ### Common Error Messages
 
 All functions may return these error types:
@@ -493,37 +498,34 @@ All functions may return these error types:
 1. **Always check mcp_connect() result**:
 ```sql
 -- Good practice: Check connection first
-SELECT 
-  CASE 
-    WHEN mcp_connect('http://localhost:8931/mcp') IS NULL 
+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**:
+2. **Virtual tables automatically return errors**:
 ```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;
+-- Virtual tables automatically return SQL errors - no need to pre-check
+SELECT name, description FROM mcp_list_tools;
+-- If not connected, query fails with error: "Not connected. Call mcp_connect() first"
+
+-- Errors can be caught in application code:
+-- C: sqlite3_errmsg(db)
+-- Python: except sqlite3.Error as e
+-- Node.js: try/catch with better-sqlite3
 ```
 
-3. **Handle tool call errors**:
+3. **Handle JSON function errors manually**:
 ```sql
--- Safe tool calling with error handling
-SELECT 
-  CASE 
+-- JSON functions still return JSON with error field
+SELECT
+  CASE
     WHEN json_extract(result, '$.error') IS NOT NULL
     THEN 'Tool Error: ' || json_extract(result, '$.error')
-    ELSE json_extract(result, '$.content[0].text') 
+    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

@@ -51,6 +51,39 @@ pub extern "C" fn mcp_free_string(s: *mut c_char) {
     }
 }
 
+/// Extract error message from JSON error response
+/// Returns the error message string if found, or NULL if no error
+#[no_mangle]
+pub extern "C" fn mcp_extract_error_message(json_str: *const c_char) -> *mut c_char {
+    if json_str.is_null() {
+        return std::ptr::null_mut();
+    }
+
+    let json_string = unsafe {
+        match CStr::from_ptr(json_str).to_str() {
+            Ok(s) => s,
+            Err(_) => return std::ptr::null_mut(),
+        }
+    };
+
+    // Check if this is an error JSON
+    match serde_json::from_str::<serde_json::Value>(json_string) {
+        Ok(json) => {
+            if let Some(error) = json.get("error").and_then(|e| e.as_str()) {
+                // Found an error message, return it
+                match CString::new(error) {
+                    Ok(c_str) => c_str.into_raw(),
+                    Err(_) => std::ptr::null_mut(),
+                }
+            } else {
+                // No error field found
+                std::ptr::null_mut()
+            }
+        }
+        Err(_) => std::ptr::null_mut(),
+    }
+}
+
 /// Parse tools JSON and extract structured data for virtual table
 /// Returns number of tools found, or 0 on error
 #[no_mangle]

src/sqlite-mcp.c

@@ -137,6 +137,7 @@ extern void mcp_stream_free_result(StreamResult* result);
 extern char* mcp_list_tools_json(void*);
 extern char* mcp_call_tool_json(void*, const char*, const char*);
 extern void mcp_free_string(char*);
+extern char* mcp_extract_error_message(const char*);
 
 // JSON parsing functions (using serde_json in Rust)
 extern size_t mcp_parse_tools_json(const char* json_str);
@@ -275,10 +276,21 @@ static int mcp_stream_next_impl(sqlite3_vtab_cursor *cur) {
       break;
 
     case STREAM_TYPE_ERROR:
-      // Stream error - stop iteration
+      // Stream error - stop iteration and set error message
       DF("mcp_stream_next_impl: STREAM_TYPE_ERROR - %s", result->data ? result->data : "unknown error");
+      if (result->data) {
+        char *error_msg = mcp_extract_error_message(result->data);
+        if (error_msg) {
+          ((mcp_stream_vtab*)pCur->base.pVtab)->base.zErrMsg = sqlite3_mprintf("%s", error_msg);
+          mcp_free_string(error_msg);
+        } else {
+          // If not JSON error format, use the data directly
+          ((mcp_stream_vtab*)pCur->base.pVtab)->base.zErrMsg = sqlite3_mprintf("%s", result->data);
+        }
+      }
       pCur->eof = 1;
-      break;
+      mcp_stream_free_result(result);
+      return SQLITE_ERROR;
 
     case STREAM_TYPE_DONE:
       // Stream complete
@@ -543,6 +555,24 @@ static int mcp_call_tool_stream_next(sqlite3_vtab_cursor *cur){
     return SQLITE_OK;
   }
 
+  if (result->result_type == STREAM_TYPE_ERROR) {
+    // Stream error - stop iteration and set error message
+    DF("mcp_call_tool_stream_next: STREAM_TYPE_ERROR - %s", result->data ? result->data : "unknown error");
+    if (result->data) {
+      char *error_msg = mcp_extract_error_message(result->data);
+      if (error_msg) {
+        ((mcp_call_tool_stream_vtab*)pCur->base.pVtab)->base.zErrMsg = sqlite3_mprintf("%s", error_msg);
+        mcp_free_string(error_msg);
+      } else {
+        // If not JSON error format, use the data directly
+        ((mcp_call_tool_stream_vtab*)pCur->base.pVtab)->base.zErrMsg = sqlite3_mprintf("%s", result->data);
+      }
+    }
+    pCur->eof = 1;
+    mcp_stream_free_result(result);
+    return SQLITE_ERROR;
+  }
+
   if (result->result_type == STREAM_TYPE_DONE) {
     pCur->eof = 1;
     mcp_stream_free_result(result);
@@ -763,12 +793,15 @@ static int mcp_tools_filter(
     }
 
     DF("mcp_tools_filter: Got JSON result (%d bytes)", (int)strlen(result));
-    // Check for errors - only check if it starts with error
-    if (strncmp(result, "{\"error\"", 8) == 0) {
+    // Check for errors and extract error message
+    char *error_msg = mcp_extract_error_message(result);
+    if (error_msg) {
       D("mcp_tools_filter: JSON contains error");
+      pVtab->base.zErrMsg = sqlite3_mprintf("%s", error_msg);
+      mcp_free_string(error_msg);
       mcp_free_string(result);
       pCur->eof = 1;
-      return SQLITE_OK;
+      return SQLITE_ERROR;
     }
 
     // Create temporary table
@@ -1073,6 +1106,17 @@ static int mcp_results_filter(
   // Parse JSON in the Rust layer
   DF("  Tool result (%d bytes): %.200s%s", (int)strlen(pCur->json_result),
      pCur->json_result, strlen(pCur->json_result) > 200 ? "..." : "");
+
+  // Check for errors first
+  char *error_msg = mcp_extract_error_message(pCur->json_result);
+  if (error_msg) {
+    D("  JSON contains error");
+    pVtab->base.zErrMsg = sqlite3_mprintf("%s", error_msg);
+    mcp_free_string(error_msg);
+    pCur->eof = 1;
+    return SQLITE_ERROR;
+  }
+
   pCur->content_count = mcp_parse_call_result_json(pCur->json_result);
   DF("  Parsed content count: %d", (int)pCur->content_count);