# Handler Sets Management
## Overview
V2 server supports flexible handler set configuration through the `--exposition` parameter.
## Handler Sets
### Available Sets
1. **readonly** - Read-only operations (safe, recommended for production)
- Programs, classes, functions (read)
- Tables and structures (schema only)
- Search operations
- Package and interface queries
- Type information
2. **high** - High-level write operations
- Object creation
- Object modification through ADT
- Package creation
- Transport operations
3. **low** - Low-level direct operations (dangerous)
- Direct ABAP execution
- System modifications
- Database operations
4. **compact** - Compact facade operations
- `HandlerValidate`
- `HandlerActivate`
- `HandlerLock`
- `HandlerUnlock`
- `HandlerCheckRun`
- `HandlerUnitTestRun`, `HandlerUnitTestStatus`, `HandlerUnitTestResult`
- `HandlerCdsUnitTestStatus`, `HandlerCdsUnitTestResult`
- `HandlerProfileRun`, `HandlerProfileList`, `HandlerProfileView`
- `HandlerDumpList`, `HandlerDumpView`
- `HandlerServiceBindingListTypes`, `HandlerServiceBindingValidate`
- `HandlerTransportCreate`
- `HandlerCreate`
- `HandlerGet`
- `HandlerUpdate`
- `HandlerDelete`
- Contract:
- CRUD via `HandlerCreate|Get|Update|Delete` + required `object_type`
- Lifecycle via `HandlerValidate|Activate|Lock|Unlock|CheckRun`
- Runtime/tests/service-binding/transport via dedicated compact handlers
- Source of truth for compact route coverage:
- `src/handlers/compact/high/compactMatrix.ts`
- auto-reflected into `docs/user-guide/AVAILABLE_TOOLS_COMPACT.md`
- Current action coverage:
- `UNIT_TEST`: `run`, `status`, `result`
- `CDS_UNIT_TEST`: `status`, `result`
- `SERVICE_BINDING`: `list_types`, `validate`
- `TRANSPORT`: `create_transport`
- `CLASS` / `PROGRAM`: `runProfiling`
- `RUNTIME_PROFILE`: `viewProfiles`, `viewProfile`
- `RUNTIME_DUMP`: `viewDumps`, `viewDump`
5. **search** - Always included automatically
- Object search
- Code search
6. **system** - Always included automatically
- Where-used analysis (GetWhereUsed)
- Type information (GetTypeInfo)
- Object info (GetObjectInfo)
- ABAP AST and semantic analysis
- System symbols
- Session management
- SQL queries
- Inactive objects
- Transactions
## Usage
**Note:** `search` and `system` handler groups are ALWAYS included regardless of `--exposition` setting.
### Command Line
```bash
# Default: readonly + high (+ search + system always included)
node bin/mcp-abap-adt-v2.js --transport=stdio --env-path=.env
# Only read-only operations (safest)
node bin/mcp-abap-adt-v2.js --transport=stdio --env-path=.env --exposition=readonly
# Read-only + high-level writes (recommended)
node bin/mcp-abap-adt-v2.js --transport=stdio --env-path=.env --exposition=readonly,high
# Compact facade only
node bin/mcp-abap-adt-v2.js --transport=stdio --env-path=.env --exposition=compact
# All operations (dangerous, for development only)
node bin/mcp-abap-adt-v2.js --transport=stdio --env-path=.env --exposition=readonly,high,low,compact
```
### Config File
If using `--config` parameter, specify in YAML:
```yaml
transport: stdio
envFile: .env
exposition:
- readonly
- high
- compact
```
### Environment Variable
Set `MCP_EXPOSITION`:
```bash
export MCP_EXPOSITION=readonly,high
node bin/mcp-abap-adt-v2.js --transport=stdio --env-path=.env
```
## Generating Handler Documentation
### Generate Full List
```bash
npm run docs:tools
```
This generates:
- `docs/user-guide/AVAILABLE_TOOLS.md`
- `docs/user-guide/AVAILABLE_TOOLS_READONLY.md`
- `docs/user-guide/AVAILABLE_TOOLS_HIGH.md`
- `docs/user-guide/AVAILABLE_TOOLS_LOW.md`
- `docs/user-guide/AVAILABLE_TOOLS_COMPACT.md`
With:
- All available handlers
- Parameters and types
- Usage examples
- Category grouping
## Manual Inspection
List handlers by set:
```bash
# ReadOnly handlers
ls -la src/handlers/*/readonly/
# High-level handlers
ls -la src/handlers/*/high/
# Low-level handlers
ls -la src/handlers/*/low/
```
## Handler Set Details
### ReadOnly Handlers Location
```
src/handlers/
├── class/readonly/
├── function/readonly/
├── package/readonly/
├── program/readonly/
├── system/readonly/
├── table/readonly/
└── transport/readonly/
```
### High-Level Handlers Location
```
src/handlers/
├── class/high/
├── function/high/
├── package/high/
├── program/high/
└── transport/high/
```
### Low-Level Handlers Location
```
src/handlers/
├── class/low/
├── function/low/
└── program/low/
```
## Security Recommendations
1. **Production**: Use only `readonly`
2. **Development**: Use `readonly,high`
3. **Testing/Admin**: Use `readonly,high,low` with caution
4. **Never expose low-level handlers to untrusted users**
## Implementation
Handler sets are registered in [src/server/v2/launcher.ts](../src/server/v2/launcher.ts):
```typescript
const handlerGroups: any[] = [];
if (config.exposition.includes('readonly')) {
handlerGroups.push(new ReadOnlyHandlersGroup(baseContext));
}
if (config.exposition.includes('high')) {
handlerGroups.push(new HighLevelHandlersGroup(baseContext));
}
if (config.exposition.includes('compact')) {
handlerGroups.push(new CompactHandlersGroup(baseContext));
}
if (config.exposition.includes('low')) {
handlerGroups.push(new LowLevelHandlersGroup(baseContext));
}
// SearchHandlersGroup is always included
handlerGroups.push(new SearchHandlersGroup(baseContext));
```
## Adding New Handlers
To add handlers to a specific set:
1. Create handler file in appropriate directory:
- `src/handlers/<domain>/readonly/` for read operations
- `src/handlers/<domain>/high/` for safe writes
- `src/handlers/<domain>/low/` for dangerous operations
2. Export `TOOL_DEFINITION`:
```typescript
export const TOOL_DEFINITION = {
name: 'my_handler',
description: 'Handler description',
inputSchema: { /* zod schema */ }
} as const;
```
3. Export handler function:
```typescript
export async function handleMyOperation(args: any, context: HandlerContext) {
// implementation
}
```
4. Register in appropriate group:
- `src/server/v2/handlers/ReadOnlyHandlersGroup.ts`
- `src/server/v2/handlers/HighLevelHandlersGroup.ts`
- `src/server/v2/handlers/LowLevelHandlersGroup.ts`
5. Regenerate docs:
```bash
npm run docs:tools
```
