Entity Error Visibility and Logging (#27)

* Add logger interface and implementations for structured debugging and error reporting

- Introduce `Logger` interface for debug, info, warn, and error-level logs.
- Add `NopLogger` for discarding log output.
- Implement `StdLogger` using the standard library to support structured logging with optional debug mode.

* Enhance `Toolkit` with structured logging for debugging and error reporting

- Initialize logger with `Logger` interface and added structured logging in debug mode.
- Log tool invocation, middleware hooks, handler results, and client connection selection.
- Improve error visibility with detailed log messages for middleware and client failures.

* Improve error messaging in `GetEntity` for better debugging and nil entity handling

* Add debug logging fields to `Config` struct for enhanced debugging and logging support

* Add `Debug` and `Logger` fields to `Config` for improved debug logging and configurability

* Add structured logging to `Client` for improved debugging and error reporting

- Introduced `Logger` to `Client` for better log management.
- Added detailed logs for query execution, retries, errors, and response processing.
- Implemented utility functions for operation name extraction and string truncation.

* Refactor `Client` to modularize error handling and response parsing

- Extract request error handling to `handleRequestError`.
- Add `checkStatusCode` for HTTP status code validation.
- Modularize GraphQL error processing with `handleGraphQLErrors`.
- Introduce `parseGraphQLResponse` for clearer response parsing logic.

* Add `Debug` and `Logger` fields to `Config` and update documentation for enhanced debugging support

* Refactor `APIClient` response parsing and add enhanced error handling utilities

* Document `DATAHUB_DEBUG` configuration option in server settings

* Document `DATAHUB_DEBUG` configuration option in README

* Add comprehensive unit tests for `helpers`, `logger`, and GraphQL response handling utilities

- Created tests for utility functions like `extractOperationName`, `truncateString`, and `joinStrings`.
- Added robust test cases for error handling in GraphQL response parsing and logger behavior.
- Verified structured logging and debug behavior for `StdLogger` and `NopLogger`.

* Handle GraphQL `null` data correctly in response parsing

Author: cjimti

README.md

@@ -219,6 +219,7 @@ See the [tools reference](https://mcp-datahub.txn2.com/server/tools/) for detail
 | `DATAHUB_MAX_LIMIT` | Maximum limit | `100` |
 | `DATAHUB_CONNECTION_NAME` | Display name for primary connection | `datahub` |
 | `DATAHUB_ADDITIONAL_SERVERS` | JSON map of additional servers | (optional) |
+| `DATAHUB_DEBUG` | Enable debug logging (`1` or `true`) | `false` |
 
 See [configuration reference](https://mcp-datahub.txn2.com/server/configuration/) for all options.
 

docs/reference/configuration.md

@@ -20,6 +20,7 @@ Complete configuration reference for mcp-datahub.
 | `DATAHUB_DEFAULT_LIMIT` | Default search result limit | `10` |
 | `DATAHUB_MAX_LIMIT` | Maximum allowed search limit | `100` |
 | `DATAHUB_MAX_LINEAGE_DEPTH` | Maximum lineage traversal depth | `5` |
+| `DATAHUB_DEBUG` | Enable debug logging (`1` or `true`) | `false` |
 
 ## Client Configuration
 
@@ -34,6 +35,8 @@ type Config struct {
     DefaultLimit    int           // Default search limit
     MaxLimit        int           // Maximum search limit
     MaxLineageDepth int           // Max lineage depth
+    Debug           bool          // Enable debug logging
+    Logger          Logger        // Custom logger (nil = auto-select)
 }
 ```
 
@@ -49,6 +52,8 @@ func DefaultConfig() Config {
         DefaultLimit:    10,
         MaxLimit:        100,
         MaxLineageDepth: 5,
+        Debug:           false,
+        Logger:          nil, // Uses NopLogger; StdLogger when Debug=true
     }
 }
 ```
@@ -68,9 +73,11 @@ if err != nil {
 
 ```go
 type Config struct {
-    DefaultLimit    int // Default search limit
-    MaxLimit        int // Maximum search limit
-    MaxLineageDepth int // Max lineage depth
+    DefaultLimit    int           // Default search limit
+    MaxLimit        int           // Maximum search limit
+    MaxLineageDepth int           // Max lineage depth
+    Debug           bool          // Enable debug logging
+    Logger          client.Logger // Custom logger (nil = auto-select)
 }
 ```
 
@@ -84,6 +91,62 @@ toolkit := tools.NewToolkit(datahubClient, tools.Config{
 })
 ```
 
+## Debug Logging
+
+Enable debug logging to troubleshoot issues with DataHub connectivity, GraphQL queries, and tool execution.
+
+### Via Environment Variable
+
+```bash
+export DATAHUB_DEBUG=1
+./mcp-datahub
+```
+
+### Programmatic Configuration
+
+```go
+// Auto-create StdLogger when Debug=true
+cfg := client.Config{
+    URL:   "https://datahub.example.com",
+    Token: "token",
+    Debug: true,
+}
+
+// Or provide a custom logger
+cfg := client.Config{
+    URL:    "https://datahub.example.com",
+    Token:  "token",
+    Logger: myCustomLogger,
+}
+```
+
+### Logger Interface
+
+The `Logger` interface is compatible with `slog.Logger` patterns:
+
+```go
+type Logger interface {
+    Debug(msg string, args ...any)
+    Info(msg string, args ...any)
+    Warn(msg string, args ...any)
+    Error(msg string, args ...any)
+}
+```
+
+Built-in implementations:
+- `NopLogger` - Discards all output (default when debug disabled)
+- `StdLogger` - Writes to stderr with structured key-value format
+
+### Log Output
+
+When debug logging is enabled, you'll see:
+
+```
+[datahub] DEBUG: executing GraphQL query [operation=GetEntity endpoint=https://... request_size=256]
+[datahub] DEBUG: received response [status=200 response_size=1024]
+[datahub] DEBUG: request completed [operation=GetEntity duration_ms=150 attempts=1]
+```
+
 ## Validation
 
 Configuration is validated on client creation:

docs/server/configuration.md

@@ -20,6 +20,7 @@ All configuration is done through environment variables.
 | `DATAHUB_MAX_LINEAGE_DEPTH` | Maximum lineage traversal depth | `5` |
 | `DATAHUB_CONNECTION_NAME` | Display name for primary connection | `datahub` |
 | `DATAHUB_ADDITIONAL_SERVERS` | JSON map of additional servers | (empty) |
+| `DATAHUB_DEBUG` | Enable debug logging (`1` or `true`) | `false` |
 
 ## Example Configuration
 
@@ -32,6 +33,9 @@ export DATAHUB_TOKEN=your_personal_access_token
 export DATAHUB_TIMEOUT=60
 export DATAHUB_DEFAULT_LIMIT=20
 export DATAHUB_MAX_LIMIT=50
+
+# Debug logging (for troubleshooting)
+export DATAHUB_DEBUG=1
 ```
 
 ## Multi-Server Configuration

docs/support/troubleshooting.md

@@ -113,6 +113,41 @@ export DATAHUB_TOKEN=your_token
 # Or use .env file with direnv
 ```
 
+## Debug Logging
+
+Enable debug logging to see detailed information about requests, responses, and errors.
+
+### Enable Debug Mode
+
+```bash
+export DATAHUB_DEBUG=1
+./mcp-datahub
+```
+
+### What Debug Logging Shows
+
+- GraphQL operation names and request sizes
+- HTTP response status codes and sizes
+- Request duration and retry attempts
+- Detailed error messages with context
+- Connection selection in multi-server mode
+
+### Example Debug Output
+
+```
+[datahub] DEBUG: executing GraphQL query [operation=GetEntity endpoint=https://datahub.example.com/api/graphql request_size=256]
+[datahub] DEBUG: received response [status=200 response_size=1024]
+[datahub] DEBUG: request completed [operation=GetEntity duration_ms=150 attempts=1]
+```
+
+### Common Debug Scenarios
+
+**Silent failures**: If a query returns empty results unexpectedly, debug logging will show if GraphQL returned null data without errors.
+
+**Retry behavior**: See when and how often requests are retried, including backoff timing.
+
+**Auth issues**: Debug logs show when requests fail with 401/403 status codes before the error is returned.
+
 ## Getting Help
 
 If you're still having issues: