Feature/mcp tool reduction

.github/instructions/mcp-server-development.instructions.md

@@ -131,9 +131,86 @@ mcp-server/src/
 ├── readme-knowledge-base.ts      # README parsing and search
 ├── connection-context.ts         # Project connection management
 ├── resources.ts                  # MCP resource handlers
-└── prompts.ts                    # MCP prompt handlers
+├── prompts.ts                    # MCP prompt handlers
+└── tools/
+    ├── tier-config.ts            # Tier-1 command list, router name, caps
+    ├── cli-tools.ts              # Tool definitions (tier-1, per-category, all)
+    ├── router-tool.ts            # hana_execute router implementation
+    ├── discovery-tools.ts        # Category/tag/recommend tools
+    └── content-tools.ts          # Examples, presets, docs tools
 ```
 
+## Tiered Tool Architecture
+
+The MCP server uses progressive discovery to keep the initial tool surface small (~22 tools) while providing access to all 186 commands.
+
+### Configuration: `tools/tier-config.ts`
+
+```typescript
+// Tier-1 commands are always exposed as first-class tools
+export const TIER_1_COMMANDS: string[] = [
+  'querySimple', 'tables', 'inspectTable', 'views', 'status',
+];
+
+export const ROUTER_TOOL_NAME = 'hana_execute';
+export const MAX_DYNAMIC_TOOLS = 50;
+```
+
+### Tool Layers
+
+| Layer | Source | Registration |
+| ----- | ------ | ------------ |
+| Tier-1 | `tools/cli-tools.ts → getCliToolDefinitions()` | Always registered |
+| Router | `tools/router-tool.ts` | Always registered; dispatches 183+ commands |
+| Discovery/Content | `tools/discovery-tools.ts`, `tools/content-tools.ts` | Always registered |
+| Dynamic | `tools/cli-tools.ts → getCliToolDefinitionsForCategory()` | Promoted on demand via `activateCategory()` |
+
+### Router Tool: `tools/router-tool.ts`
+
+The `hana_execute` router accepts `{ command, args }` and resolves commands via:
+1. Direct name match (e.g., `"dataProfile"`)
+2. Sanitized name match (camelCase to snake_case)
+3. Alias lookup
+
+```typescript
+export async function handleRouterTool(params: { command: string; args?: Record<string, any> }): Promise<ExecutionResult> {
+  const resolved = resolveCommand(params.command);
+  return executeCommand(resolved, params.args || {});
+}
+```
+
+### Dynamic Tool Promotion
+
+When `hana_discover_by_category` is called, the server promotes those tools to first-class MCP tools:
+
+```typescript
+private activateCategory(category: string): void {
+  const tools = getCliToolDefinitionsForCategory(category);
+  // Filter out any tier-1 tools to avoid duplicates
+  const newTools = tools.filter(t => !isTier1Command(t.originalName));
+
+  this.dynamicTools.set(category, newTools);
+  this.enforceCap(); // FIFO eviction if over MAX_DYNAMIC_TOOLS
+  this.server.sendToolListChanged(); // Notify client to refresh
+}
+```
+
+**Important implementation details:**
+- Tier-1 tools are filtered out before adding category tools (deduplication)
+- A FIFO cap of `MAX_DYNAMIC_TOOLS` (50) evicts the oldest category first
+- `sendToolListChanged()` triggers an MCP `notifications/tools/list_changed` notification
+
+### Full Mode (`--full` flag)
+
+Pass `--full` to bypass tiering and register all 186 tools at startup:
+
+```typescript
+const fullMode = process.argv.includes('--full');
+const cliTools = fullMode ? getAllCliToolDefinitions() : getCliToolDefinitions();
+```
+
+Use `--full` in environments where tool count is not a concern (e.g., dedicated HANA AI agents).
+
 ## Tool Registration Pattern
 
 ### Sanitize Tool Names

README.md

@@ -455,29 +455,29 @@ hana-cli serve        # Start the web server standalone
 
 The web UI runs on `http://localhost:3010` by default and provides access to all CLI functionality through an easy-to-use graphical interface. For complete documentation of all web applications, UI5 components, configuration, and development guides, see the [app/README.md](app/README.md) file.
 
-### Experimental MCP (Model Context Protocol) Integration
+### MCP (Model Context Protocol) Integration
 
-The hana-cli tool now includes experimental support for the Model Context Protocol (MCP), enabling AI assistants like Claude to interact with SAP HANA databases through natural language. This integration exposes all 100+ hana-cli commands as tools that AI assistants can invoke directly.
+The hana-cli tool includes a Model Context Protocol (MCP) server, enabling AI assistants like Claude to interact with SAP HANA databases through natural language. The server uses a progressive discovery model — starting with ~22 focused tools and expanding on demand to all 186 commands.
 
 ```mermaid
 graph LR
     AI["🤖 AI Assistant<br/>Claude, etc."]
-    
-    AI -->|Natural Language<br/>Query| MCP["MCP Server<br/>hana-cli Integration"]
-    
-    MCP -->|Tool Invocation| Tools["100+ hana-cli<br/>Commands as Tools"]
-    
+
+    AI -->|Natural Language<br/>Query| MCP["MCP Server<br/>~22 Default Tools"]
+
+    MCP -->|Router or<br/>Direct Call| Tools["186 hana-cli<br/>Commands"]
+
     Tools --> DB["SAP HANA<br/>Database"]
     Tools --> Cloud["BTP/Cloud<br/>Services"]
     Tools --> HDI["HDI<br/>Containers"]
-    
+
     DB -->|Data & Results| Tools
     Cloud -->|Service Info| Tools
     HDI -->|Container Status| Tools
-    
+
     Tools -->|Formatted<br/>Response| MCP
     MCP -->|Natural Language<br/>Result| AI
-    
+
     style AI fill:#9D55F0,color:#fff
     style MCP fill:#0070C0,color:#fff
     style Tools fill:#FF6B6B,color:#fff
@@ -486,17 +486,16 @@ graph LR
 
 **Key Features:**
 
-- Natural language database queries and operations
-- Full access to all hana-cli commands through AI assistants
-- Seamless integration with AI development environments (Cline/Claude Dev, etc.)
-- Command execution with proper parameter handling and error responses
+- Progressive tool discovery — tier-1 tools always available, others via router or dynamic promotion
+- Router tool (`hana_execute`) dispatches any of 183+ commands by name
+- AI-guided command recommendations and smart search
+- Seamless integration with Claude Desktop, VS Code, Cursor, and other MCP clients
+- `--full` mode available for environments where tool count is not a concern
 
 For detailed setup instructions, configuration options, and usage examples, please refer to:
 
-- [mcp-server/README.md](mcp-server/README.md) - Complete installation and configuration guide
-- [mcp-server/TROUBLESHOOTING.md](mcp-server/TROUBLESHOOTING.md) - Common issues and solutions
-
-**Note:** This is an experimental feature and may be subject to changes as the MCP specification evolves.
+- [docs/03-features/mcp-integration.md](docs/03-features/mcp-integration.md) - Complete MCP overview and setup guide
+- [mcp-server/README.md](mcp-server/README.md) - Server installation and configuration
 
 ## Standard Parameters and Conventions
 

docs/03-features/mcp-integration.md

@@ -8,7 +8,8 @@ The Model Context Protocol enables AI assistants to interact with external tools
 
 **Key Capabilities:**
 
-- **150+ Tools** - All CLI commands accessible via MCP interface
+- **Progressive Tool Discovery** - Starts with ~22 focused tools; promotes additional tools on demand (up to 186 total)
+- **Router Tool** - `hana_execute` dispatches any of 183+ commands by name without pre-registration
 - **Discovery** - AI-guided command recommendations and smart search
 - **Workflows** - Pre-built multi-step task templates
 - **Examples** - Real-world usage scenarios and parameter presets
@@ -110,20 +111,86 @@ You can also point directly to a local build:
 Replace the path with your actual project location. Connection credentials are read from `default-env.json` in the project root. Use `hana-cli connect` or `hana-cli serviceKey` to configure database connections.
 :::
 
+## Tool Architecture
+
+### Tiered Tool Exposure
+
+The MCP server uses a progressive discovery model to keep the initial tool surface small and focused:
+
+| Layer | Tools | Description |
+| ----- | ----- | ----------- |
+| **Tier 1** (always-on) | `hana_query_simple`, `hana_tables`, `hana_inspect_table`, `hana_views`, `hana_status` | Core database tools available immediately |
+| **Router** | `hana_execute` | Dispatches any of 183+ commands by name |
+| **Discovery** | `hana_discover_categories`, `hana_discover_by_category`, `hana_discover_by_tag`, `hana_recommend`, etc. | Help AI agents find the right tools |
+| **Content** | `hana_examples`, `hana_parameter_presets`, `hana_get_doc`, etc. | Usage examples and documentation |
+| **Dynamic** | Up to 50 additional tools | Promoted when a category is explored via `hana_discover_by_category` |
+
+**Default:** ~22 tools registered at startup.
+**Full mode:** All 186 tools registered (use `--full` flag).
+
+### The Router Tool (`hana_execute`)
+
+For commands not in the tier-1 set, the router tool provides direct access without requiring dynamic promotion:
+
+```json
+{
+  "tool": "hana_execute",
+  "arguments": {
+    "command": "dataProfile",
+    "args": { "schema": "MY_SCHEMA", "table": "ORDERS" }
+  }
+}
+```
+
+The router resolves commands by exact name, camelCase-to-snake_case conversion, or alias matching.
+
+### Dynamic Tool Promotion
+
+When an AI agent calls `hana_discover_by_category` (e.g., to browse "data-tools"), the server:
+
+1. Promotes all tools in that category to first-class MCP tools
+2. Sends a `tools/list_changed` notification so the client refreshes its tool list
+3. Enforces a cap of 50 dynamically-promoted tools (oldest category evicted first)
+
+This means frequently-used categories become directly callable without the router.
+
+### Full Mode
+
+For environments where tool count is not a concern, pass `--full` to expose all 186 tools at startup:
+
+```json
+{
+  "mcpServers": {
+    "hana-cli": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "-p", "hana-cli", "hana-cli-mcp", "--full"]
+    }
+  }
+}
+```
+
 ## Core Features
 
 ### 1. Command Tools
 
-All CLI commands are exposed with the `hana_` prefix:
+Tier-1 commands are always available with the `hana_` prefix:
 
 ```text
 hana_status              Check database connection
 hana_tables              List tables in a schema
-hana_import              Import data from CSV/Excel
-hana_dataProfile         Analyze data quality
-hana_duplicateDetection  Find duplicate rows
-hana_compareSchema       Compare database schemas
-hana_inspectTable        View table structure and metadata
+hana_inspect_table       View table structure and metadata
+hana_views               List views in a schema
+hana_query_simple        Execute SQL queries
+```
+
+All other commands (183+) are accessible via `hana_execute`:
+
+```text
+hana_execute { command: "import", args: { ... } }
+hana_execute { command: "dataProfile", args: { ... } }
+hana_execute { command: "duplicateDetection", args: { ... } }
+hana_execute { command: "compareSchema", args: { ... } }
 ```
 
 Command aliases still work when called (e.g., `hana_s` for status, `hana_imp` for import), but they are not registered as separate tools to keep the tool list concise.

docs/03-features/mcp/advanced-features.md

@@ -2,6 +2,42 @@
 
 Advanced capabilities and workflows for the MCP server.
 
+## Progressive Tool Discovery
+
+The MCP server uses a tiered architecture to keep the initial tool surface small while providing access to all 183+ commands:
+
+### Using the Router Tool
+
+For any command not in the tier-1 set, use `hana_execute`:
+
+```json
+{
+  "tool": "hana_execute",
+  "arguments": {
+    "command": "dataProfile",
+    "args": {
+      "schema": "MY_SCHEMA",
+      "table": "ORDERS"
+    }
+  }
+}
+```
+
+### Dynamic Tool Promotion
+
+Calling `hana_discover_by_category` promotes all tools in that category:
+
+```json
+{
+  "tool": "hana_discover_by_category",
+  "arguments": { "category": "data-tools" }
+}
+```
+
+After this call, tools like `hana_import`, `hana_export`, `hana_data_profile` become directly callable. The server sends a `tools/list_changed` notification and the AI client refreshes its tool list.
+
+A cap of 50 dynamically-promoted tools is enforced (oldest category evicted first via FIFO).
+
 ## Advanced Topics
 
 ### Presets & Configurations

docs/03-features/mcp/index.md

@@ -15,9 +15,11 @@ Complete documentation for the Model Context Protocol (MCP) server that enables
 
 ## Key Capabilities
 
-**Context-Aware Commands**: Pass project directory and connection file to MCP server
+**Progressive Tool Discovery**: Starts with ~22 focused tools; expands on demand via router or dynamic promotion
+
+**Router Tool (`hana_execute`)**: Execute any of 183+ commands by name without pre-registration
 
-**150+ Tools Exposed**: All HANA CLI commands available to AI assistants
+**Context-Aware Commands**: Pass project directory and connection file to MCP server
 
 **Structured Output**: Markdown tables and formatted responses
 

docs/03-features/mcp/server-usage.md

@@ -40,9 +40,12 @@ npm run build
 ### Running the Server
 
 ```bash
-# Start MCP server (listens on stdio)
+# Start MCP server (listens on stdio) — default: ~22 tools
 node build/index.js
 
+# Full mode: all 186 tools exposed at startup
+node build/index.js --full
+
 # With debug logging
 DEBUG=hana-cli:* node build/index.js
 
@@ -65,15 +68,21 @@ The MCP server:
 
 ## Available Tools
 
-The MCP server exposes 150+ HANA CLI tools:
+By default, the MCP server exposes ~22 tools at startup using a progressive discovery model:
+
+**Tier-1 (always available):** `hana_query_simple`, `hana_tables`, `hana_inspect_table`, `hana_views`, `hana_status`
+
+**Router:** `hana_execute` — dispatches any of 183+ commands by name (e.g., `{ "command": "import", "args": { ... } }`)
+
+**Discovery:** `hana_discover_categories`, `hana_discover_by_category`, `hana_discover_by_tag`, `hana_recommend`, `hana_search`, `hana_quickstart`
 
-**Data Tools:** import, export, compareData, dataProfile, dataDiff, dataValidator, dataMask, dataSync, duplicateDetection, dataLineage
+**Content:** `hana_examples`, `hana_parameter_presets`, `hana_get_doc`, `hana_interpret_result`, `hana_conversation_templates`, `hana_get_template`
 
-**Schema Tools:** compareSchema, schemaClone, tableCopy, erdDiagram, generateDocs, generateTestData
+**Workflows:** `hana_workflows`, `hana_workflow_by_id`, `hana_search_workflows`
 
-**Query Tools:** querySimple, callProcedure, tables, views, functions, procedures, roles, etc
+When an AI agent explores a category via `hana_discover_by_category`, those tools are dynamically promoted to first-class tools (up to 50 additional tools, oldest category evicted first).
 
-**System Tools:** backup, replicationStatus, partitions, spatialData, and more
+Use `--full` mode to expose all 186 tools at startup for environments where tool count is not a concern.
 
 ## Usage with AI Assistants
 

docs/troubleshooting/mcp.md

@@ -58,6 +58,36 @@ Resolve common issues when using the Model Context Protocol (MCP) server integra
 
 ## Command Failures
 
+### Tool Not Found
+
+**Problem:** AI assistant reports a tool like `hana_dataProfile` is not available
+
+**Cause:** The MCP server uses progressive discovery — only ~22 tools are registered at startup. Other tools must be accessed via the router or promoted dynamically.
+
+**Solutions:**
+
+1. Use the router tool directly:
+
+   ```json
+   { "tool": "hana_execute", "arguments": { "command": "dataProfile", "args": { "schema": "MY_SCHEMA", "table": "ORDERS" } } }
+   ```
+
+2. Promote the category first by calling `hana_discover_by_category`:
+
+   ```json
+   { "tool": "hana_discover_by_category", "arguments": { "category": "data-tools" } }
+   ```
+
+   After this call, tools like `hana_data_profile` become directly callable.
+
+3. Use `--full` mode to expose all 186 tools at startup:
+
+   ```json
+   { "command": "npx", "args": ["-y", "-p", "hana-cli", "hana-cli-mcp", "--full"] }
+   ```
+
+4. Use `hana_recommend` with a natural language description to find the right tool name.
+
 ### Command Execution Errors
 
 **Problem:** Tool call returns error from HANA CLI
@@ -116,7 +146,7 @@ Resolve common issues when using the Model Context Protocol (MCP) server integra
 2. Verify MCP server is running: `npm run dev`
 3. Check your IDE's MCP configuration file (e.g., `claude_desktop_config.json`)
 4. Ensure the correct path to the MCP executable is configured
-5. Verify the MCP server is accessible on the expected port
+5. Note: by default only ~22 tools are registered. Use `hana_execute` router for other commands, or start with `--full` to expose all 186 tools
 
 ### AI Returns Incorrect Results