hana-cli/docs/developer-notes/issue-analysis.md

HANA Developer Command Line Interface

# Issue Analysis: Zero Results from List Tables Command

## Problem Statement

The `hana_tables` (and similar list commands) returns zero results when called through the MCP server.

## Root Cause

The issue is **not** with the `**CURRENT_SCHEMA**` transformation logic, which works correctly. The actual problem is:

### Missing database connection configuration

The hana-cli tools require a `default-env.json` file (or equivalent environment configuration) containing SAP HANA connection credentials. Without this configuration:

1. The connection is created but with `undefined` options
2. Database queries execute but fail silently
3. No results are returned, appearing as "zero results"

## Technical Details

### What Works ✓

- The `**CURRENT_SCHEMA**` placeholder replacement logic (in `utils/database/databaseInspect.js`)
- The default parameter handling in the MCP server
- The SQL query construction
- The command execution flow

### What Was Missing ✗

- Clear error messaging when database connection is not configured
- Validation that connection credentials are present before executing queries
- Documentation about the connection setup requirement

## Solution Implemented

### 1. Enhanced Error Handling

Added validation in `utils/base.js` to check for valid connection configuration:

```javascript
// Validate that we have a proper connection configuration
if (!this.options || !this.options.hana || !this.options.hana.host) {
    throw new Error('No valid database connection configuration found. Please create a default-env.json file or set up environment variables.')
}
```

### 2. Schema Validation

Added check in `utils/database/databaseInspect.js` to ensure schema is not empty:

```javascript
// Validate schema is not empty
if (!schema1 || schema1.trim() === '') {
    throw new Error('Unable to determine current schema. Please check your database connection configuration.')
}
```

### 3. Debug Logging

Enhanced the MCP server with debug logging to help diagnose issues:

```typescript
if (args.debug) {
    console.error('[DEBUG] hana_tables args:', JSON.stringify(args, null, 2));
    console.error('[DEBUG] Calling tables.default with:', JSON.stringify(tableArgs, null, 2));
    console.error('[DEBUG] Result type:', typeof result);
}
```

### 4. Documentation

Created comprehensive troubleshooting guide: `mcp-server/TROUBLESHOOTING.md`

## How to Fix for Users

Users experiencing zero results should:

1. **Set up database connection** using one of these methods:

   ```bash
   # Method 1: Via service key (recommended)
   hana-cli serviceKey -i <instance-name> -k <key-name>
   
   # Method 2: Interactive setup
   hana-cli connect
   ```

2. **Verify connection**:

   ```bash
   hana-cli status
   ```

3. **Check configuration file** exists:
   - `default-env.json` should be in the project root
   - Should contain valid HANA credentials

## Testing

All improvements have been tested:

- ✓ Error handling with missing configuration
- ✓ Proper error messages guide users to solution
- ✓ Schema transformation logic remains functional
- ✓ Debug mode provides diagnostic information

## Files Modified

1. `utils/base.js` - Added connection validation
2. `utils/database/databaseInspect.js` - Added schema validation
3. `mcp-server/src/index.ts` - Added debug logging
4. `mcp-server/README.md` - Added prerequisite documentation
5. `mcp-server/TROUBLESHOOTING.md` - New troubleshooting guide