feat(logging): add MCP protocol logging for database connection errors

PCfVW · PCfVW · commit 5a91c57b5216 · 2025-10-19T17:35:40.000+02:00
Implement recommended solution from DATABASE_CONNECTION_ERROR_REPORTING.md
to improve error visibility for end users in Claude Desktop and other MCP clients.

Changes:
- Add MCP protocol logging in call_tool() lazy connection failure path
- Send error-level log notifications with diagnostic info and troubleshooting suggestions
- Preserve existing Python logging (stderr) for server administrators
- Add arango_database_status tool for proactive connection status checking
- Use safe error handling to prevent notification failures from breaking tool execution

Implementation Details:
- entry.py: Added await ctx.session.send_log_message() in lazy connection exception handler
- tools.py: Added ARANGO_DATABASE_STATUS constant
- models.py: Added ArangoDatabaseStatusArgs model (empty, no parameters required)
- handlers.py: Added handle_arango_database_status() with @register_tool() decorator

Benefits:
- End users see error notifications in Claude Desktop UI (not just stderr)
- Server admins still have detailed Python logs for debugging
- Proactive status checking via dedicated tool
- Backward compatible (clients without logging support still get error responses)

Test Status: 172/193 passing (89%) - no regressions introduced
diff --git a/mcp_arangodb_async/entry.py b/mcp_arangodb_async/entry.py
@@ -352,8 +352,30 @@ async def call_tool(name: str, arguments: Dict[str, Any]) -> List[types.Content]
                 ctx.lifespan_context["client"] = client
             db = db_conn
             logger.info("Lazy DB connect succeeded during tool call: db=%s", cfg.database)
-        except Exception:
+        except Exception as e:
             logger.warning("Lazy DB connect failed; returning Database unavailable", exc_info=True)
+
+            # Send MCP log notification to client (if session available)
+            if ctx and hasattr(ctx, 'session') and ctx.session:
+                try:
+                    await ctx.session.send_log_message(
+                        level="error",
+                        data={
+                            "error": "Database unavailable",
+                            "message": "ArangoDB connection could not be established",
+                            "tool": name,
+                            "suggestion": "Please ensure ArangoDB is running and accessible",
+                            "config": {
+                                "url": os.getenv("ARANGO_URL", "http://localhost:8529"),
+                                "database": os.getenv("ARANGO_DB", "_system"),
+                            },
+                            "exception": str(e)
+                        },
+                        logger="mcp_arangodb_async.database"
+                    )
+                except Exception as log_err:
+                    logger.debug(f"Failed to send MCP log notification: {log_err}")
+
             return _json_content({
                 "error": "Database unavailable",
                 "tool": name,
diff --git a/mcp_arangodb_async/handlers.py b/mcp_arangodb_async/handlers.py
@@ -128,6 +128,7 @@
     ARANGO_BACKUP_NAMED_GRAPHS,
     ARANGO_VALIDATE_GRAPH_INTEGRITY,
     ARANGO_GRAPH_STATISTICS,
+    ARANGO_DATABASE_STATUS,
 )
 
 # Configure logger for handlers
@@ -224,6 +225,7 @@ def safe_cursor(cursor):
     BackupNamedGraphsArgs,
     ValidateGraphIntegrityArgs,
     GraphStatisticsArgs,
+    ArangoDatabaseStatusArgs,
 )
 
 
@@ -1602,6 +1604,67 @@ def handle_graph_statistics(db: StandardDatabase, args: Dict[str, Any]) -> Dict[
     )
 
 
+@register_tool(
+    name=ARANGO_DATABASE_STATUS,
+    description="Check database connection status and return diagnostic information.",
+    model=ArangoDatabaseStatusArgs,
+)
+@handle_errors
+def handle_arango_database_status(db: StandardDatabase, args: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Check database connection status and return diagnostic information.
+
+    This tool provides visibility into the database connection state, which is
+    especially useful when the database is unavailable at startup or during
+    operation. It complements MCP protocol logging by providing a proactive
+    way for users to check connection status.
+
+    Operator model:
+      Preconditions:
+        - None (works even when database is unavailable)
+      Effects:
+        - Returns connection status (connected: true/false)
+        - If connected: returns server version and database name
+        - If not connected: returns diagnostic information
+        - No database mutations
+    """
+    # Check if database connection is available
+    if db is None:
+        import os
+        return {
+            "connected": False,
+            "message": "Database connection is not available",
+            "config": {
+                "url": os.getenv("ARANGO_URL", "http://localhost:8529"),
+                "database": os.getenv("ARANGO_DB", "_system"),
+            },
+            "suggestion": "Please ensure ArangoDB is running and accessible. Check ARANGO_URL and ARANGO_DB environment variables."
+        }
+
+    # Database is connected - get server info
+    try:
+        version_info = db.version()
+        server_version = version_info if isinstance(version_info, str) else version_info.get("version", "unknown")
+
+        return {
+            "connected": True,
+            "database": db.name,
+            "server_version": server_version,
+            "message": "Database connection is active"
+        }
+    except Exception as e:
+        # Connection exists but query failed
+        import os
+        return {
+            "connected": False,
+            "message": f"Database connection exists but query failed: {str(e)}",
+            "config": {
+                "url": os.getenv("ARANGO_URL", "http://localhost:8529"),
+                "database": os.getenv("ARANGO_DB", "_system"),
+            },
+            "suggestion": "Database connection may be stale or server may be unresponsive."
+        }
+
+
 # Register aliases for backward compatibility
 from .tool_registry import ToolRegistration, TOOL_REGISTRY
 
diff --git a/mcp_arangodb_async/models.py b/mcp_arangodb_async/models.py
@@ -409,3 +409,8 @@ class GraphStatisticsArgs(BaseModel):
         alias="perCollectionStats",
         description="Provide detailed per-collection statistics breakdown"
     )
+
+
+class ArangoDatabaseStatusArgs(BaseModel):
+    """Arguments for arango_database_status tool (no parameters required)."""
+    pass
diff --git a/mcp_arangodb_async/tools.py b/mcp_arangodb_async/tools.py
@@ -101,3 +101,6 @@
 ARANGO_BACKUP_NAMED_GRAPHS = "arango_backup_named_graphs"
 ARANGO_VALIDATE_GRAPH_INTEGRITY = "arango_validate_graph_integrity"
 ARANGO_GRAPH_STATISTICS = "arango_graph_statistics"
+
+# Database Status Tool
+ARANGO_DATABASE_STATUS = "arango_database_status"

Original file line number	Diff line number	Diff line change
`@@ -409,3 +409,8 @@ class GraphStatisticsArgs(BaseModel):`
`409`	`409`	`alias="perCollectionStats",`
`410`	`410`	`description="Provide detailed per-collection statistics breakdown"`
`411`	`411`	`)`
	`412`	`+`
	`413`	`+`
	`414`	`+class ArangoDatabaseStatusArgs(BaseModel):`
	`415`	`+ """Arguments for arango_database_status tool (no parameters required)."""`
	`416`	`+ pass`