hana-cli/docs/03-features/mcp/server-updates.md

HANA Developer Command Line Interface

# MCP Server Implementation Updates

**Date:** February 16, 2026  
**Version:** 1.202602.0

## Summary

The MCP (Model Context Protocol) Server has been updated to fully reflect all recent additions, enhancements, and changes to the hana-cli project. The server now dynamically exposes **150+ commands** with complete parameter documentation, including all new commands added in recent releases.

## Key Updates

### 1. Enhanced Command Parser (`src/command-parser.ts`)

**Previous Limitation:**

- Function-based builders were ignored, resulting in empty parameter schemas
- Only direct object builders were properly introspected

**Improvements:**

- Added `getBuilderObject()` function that intelligently handles both:
  - Direct object-based builders (majority of commands)
  - Function-based builders by safely attempting to invoke them
  - Proper error handling for function calls
- Better extraction of command metadata including aliases and descriptions
- More robust parameter type mapping

### 2. Improved Error Handling & Validation (`src/executor.ts`)

**Enhancements:**

- Better documentation of connection validation behavior
- Support for multiple connection methods:
  - `.env` files
  - `default-env.json` configuration
  - Connection parameters via CLI flags
  - Service keys and BTP connections
  - Database connection profiles
- Graceful error propagation allowing CLI to provide specific error messages
- Support for commands that don't require database connections

### 3. Better Command Loading (`src/index.ts`)

**Improvements:**

- Enhanced logging showing command module count and successful registrations
- Better differentiation between loaded modules and registered commands
- Improved error messages for debugging command loading issues
- Validation that commands were actually registered
- More informative console output for MCP server diagnostics

### 4. Output Formatting (`src/output-formatter.ts`)

**Features Maintained:**

- Command-specific formatters for common operations
- ASCII table parsing and conversion to markdown
- Schema name shortening for UUIDs
- Table grouping and aggregation
- Support for multiple output types (CSV, Excel formats)

## Recently Exposed Commands

The MCP server now properly exposes and documents all new commands added in recent releases:

### Import/Export Enhancements

- **`import`** - Now with new parameters:
  - `matchMode` - Match columns by order, name, or auto (new in v4.202602.0)
  - `dryRun` - Preview import without committing
  - `maxFileSizeMB` - Memory protection
  - `timeoutSeconds` - Operation timeout control
  - `nullValues` - Custom NULL value handling
  - `skipWithErrors` - Continue on errors
  - `maxErrorsAllowed` - Error threshold control
  
- **`export`** - With full parameter documentation
- **`tableCopy`** - Table data copying operations

### Data Analysis Commands

- **`dataValidator`** - Validate data quality
- **`dataDiff`** - Compare dataset differences
- **`dataProfile`** - Profile data distributions
- **`dataSync`** - Synchronize data between sources
- **`dataLineage`** - Trace data lineage

### Inspection & Analysis

- **`inspectTable`** - Detailed table analysis
- **`inspectProcedure`** - Procedure metadata
- **`inspectFunction`** - Function details
- **`inspectTrigger`** - Trigger information
- **`queryPlan`** - Query execution plans
- **`fragmentationCheck`** - Storage optimization analysis

### Database Management

- **`healthCheck`** - System health status (new)
- **`memoryLeaks`** - Memory leak detection (new)
- **`memoryAnalysis`** - Memory consumption analysis (new)
- **`duplicateDetection`** - Find duplicate records
- **`referentialCheck`** - Referential integrity validation
- **`timeSeriesTools`** - Time series data operations

### Cloud & BTP Integration

- **`hanaCloudInstances`** - SAP HANA Cloud instance management
- **`hanaCloudStart`** - Start HANA Cloud instances
- **`hanaCloudStop`** - Stop HANA Cloud instances
- **`btpInfo`** - BTP account information
- **`btpSubs`** - BTP subscriptions

### Maintenance & Optimization

- **`reclaim`** - Reclaim disk space
- **`cacheStats`** - Cache statistics
- **`calcViewAnalyzer`** - Analytical view analysis
- **`fragmentationCheck`** - Address fragmentation
- **`tableHotspots`** - Identify hot tables
- **`expensiveStatements`** - Find expensive queries

### Batch Operations

- **`massGrant`** - Batch permission grants
- **`massDelete`** - Bulk record deletion
- **`massUpdate`** - Bulk data updates
- **`massRename`** - Batch object renaming
- **`massConvert`** - Bulk data type conversion
- **`massExport`** - Batch export operations

## Technical Improvements

### Command Registration Flow

1. **Initialization** → `bin/index.js` loads all command modules
2. **Module Processing** → Each command's metadata is extracted
3. **Parameter Introspection** → Builder objects are converted to JSON Schema
4. **Registration** → All commands registered with aliases as separate tools
5. **Tool Exposure** → Tools available to MCP clients (Claude, etc.)

### Parameter Extraction

- String, number, boolean, and array types properly mapped
- Default values preserved in schema
- Enum/choice values included for validation
- Required parameters marked in schema
- Descriptions extracted from yargs configuration
- Aliases documented alongside main command names

### Performance & Stability

- Lazy loading of command modules reduces startup time
- Safe builder invocation prevents crashes from edge cases
- Proper error handling ensures MCP server stays responsive
- Timeout protection prevents hanging on long operations
- Connection validation deferred to CLI for better error messages

## Version Compatibility

- **MCP SDK:** ^1.26.0
- **Node.js:** ≥20.19.0 (matching parent project)
- **TypeScript:** ^5.7.3
- **CLI Version:** 4.202602.0 and later

## Usage Examples

Once configured in your MCP settings, the server exposes tools like:

```bash
hana_import          # Main import command
hana_imp             # Alias
hana_uploadData      # Alias
hana_tables          # List tables
hana_t               # Alias
hana_dataValidator   # Validate data
hana_healthCheck     # System health
# ... and 150+ more commands
```

## Configuration

See [README.md](./README.md) for MCP client configuration instructions.

For troubleshooting, refer to [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).

## Build Instructions

To rebuild the MCP server after making changes:

```bash
cd mcp-server
npm run build
```

The compiled JavaScript will be output to `build/` directory.

## What's Reflected

✅ **All 150+ commands** - Complete command set  
✅ **New parameters** - Import matchMode, dryRun, maxFileSizeMB, etc.  
✅ **Command aliases** - All aliases properly exposed  
✅ **Parameter documentation** - Full descriptions and types  
✅ **Output formatting** - Markdown tables for better readability  
✅ **Error handling** - Graceful degradation and helpful messages  
✅ **Connection methods** - Support for multiple connection types  
✅ **Latest features** - New v4.202602.0 capabilities included  

## Next Steps

1. **Configure MCP Client** - Add MCP server to your Claude Dev / Cline settings
2. **Test Commands** - Try commands like `hana_healthCheck`, `hana_dataValidator`
3. **Use in AI** - Leverage AI assistance with full command capabilities
4. **Monitor Logs** - Check console output for diagnostic information

## Support

For issues or feature requests related to the MCP server:

1. Check [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
2. Review [README.md](./README.md)
3. Consult main project documentation

## See Also

- [Server Usage](./server-usage.md)
- [Architecture](./architecture.md)
- [MCP Integration Overview](../mcp-integration.md)

---

**Updated:** 2026-02-16  
**MCP Server Version:** 1.202602.0  
**Main CLI Version:** 4.202602.0