# Runtime CLI Discovery - Zero Maintenance
## Overview
Instead of maintaining a static catalog of CLI tools, NCP now **automatically discovers** what's installed on your system at runtime. This approach:
- ✅ **Zero maintenance** - No hardcoded tool definitions
- ✅ **Always current** - Parses actual `--help` output
- ✅ **User-specific** - Only shows what YOU have installed
- ✅ **Version-agnostic** - Works with any tool version
## Architecture
### 1. CLI Scanner (`src/services/cli-scanner.ts`)
**Discovers tools at runtime:**
```typescript
const scanner = new CLIScanner();
const tools = await scanner.scanSystem();
// Returns: All useful CLI tools installed on this system
```
**How it works:**
1. Use `compgen -c` to list all available commands
2. Filter to likely useful tools (exclude shell built-ins)
3. Test each tool with `--help` flags
4. Parse help output to extract:
- Description
- Capabilities (keywords)
- Category (media, data, network, etc.)
**Smart filtering:**
- Excludes: `cd`, `echo`, `test` (shell built-ins)
- Includes: Tools with useful keywords (convert, process, search, etc.)
- Categorizes: Based on description and capabilities
### 2. CLI Suggestions MCP (`src/internal-mcps/cli-suggestions.ts`)
**New tools available:**
#### `cli:scan`
Scan system for all available CLI tools
```javascript
run("cli:scan")
```
**Output:**
```
🔍 System Scan Complete
Found **42** CLI tools
media (12 tools)
ffmpeg, ffprobe, imagemagick, yt-dlp ...
data (5 tools)
jq, yq, csvkit ...
development (8 tools)
git, node, npm, docker ...
```
#### `cli:search`
Search for tools by capability
```javascript
run("cli:search", { query: "convert video" })
```
**Output:**
```
🔍 CLI Tools for "convert video":
**ffmpeg** - Complete solution to record, convert and stream audio and video
Category: media
Path: /opt/homebrew/bin/ffmpeg
Capabilities: convert, video, audio, encode, mp4, webm
Add to NCP: run("ncp:add", { mcp_name: "cli:ffmpeg" })
**handbrake** - Video transcoder
Category: media
Path: /usr/local/bin/HandBrakeCLI
...
```
#### `cli:check`
Check if a specific tool is installed
```javascript
run("cli:check", { tool_name: "ffmpeg" })
```
**Output:**
```
✅ ffmpeg is installed
Description: Complete solution to record, convert and stream audio and video
Category: media
Path: /opt/homebrew/bin/ffmpeg
Capabilities: convert, video, audio, encode, decode, mp4, webm, avi
Add to NCP: run("ncp:add", { mcp_name: "cli:ffmpeg" })
```
#### `cli:browse`
Browse tools by category
```javascript
run("cli:browse", { category: "media" })
```
**Output:**
```
📚 media tools (12 found):
**ffmpeg** - Complete solution to record, convert and stream audio and video
/opt/homebrew/bin/ffmpeg
Add: run("ncp:add", { mcp_name: "cli:ffmpeg" })
**imagemagick** - Create, edit, compose digital images
/usr/local/bin/convert
Add: run("ncp:add", { mcp_name: "cli:imagemagick" })
...
```
## User Workflow (Zero Knowledge Required)
### Scenario 1: Auto-scan on startup (with shell access)
```javascript
// 1. User initializes NCP with Shell MCP installed
// Auto-scan detects shell access and scans in background
// → Discovers ffmpeg, jq, git, etc. are installed
// 2. User asks AI to convert video
find("convert video")
// → Returns: ffmpeg:convert, handbrake:transcode (if installed)
// All discovered automatically - zero manual steps!
```
### Scenario 2: Fallback scan on empty results
```javascript
// 1. User asks AI to convert video
find("convert video")
// → No results initially
// 2. NCP detects empty results + shell access
// → Triggers CLI scan automatically
// → Retries search after scan
// 3. Returns discovered tools
// → ffmpeg:convert (0.82 confidence)
// → handbrake:transcode (0.76 confidence)
// Auto-recovery - zero manual intervention!
```
### Scenario 3: Manual discovery (advanced users)
```javascript
// 1. User explicitly scans
run("cli:scan")
// → Discovers ffmpeg, handbrake, etc. are installed
// 2. Search for specific capabilities
run("cli:search", { query: "convert video" })
// → Returns ffmpeg, handbrake with descriptions
// 3. Add specific tool
run("ncp:add", { mcp_name: "cli:ffmpeg" })
// → ffmpeg now indexed for discovery
```
## Conditional Auto-Scanning
Auto-scanning is **smart and non-intrusive**:
### When it triggers:
- ✅ **On startup**: If Shell or desktop-commander MCP is present
- ✅ **On empty search**: If find() returns no results and shell access available
- ✅ **Force mode**: Set `NCP_FORCE_CLI_SCAN=true` to always scan
### When it DOESN'T trigger:
- ❌ No shell access (no way to discover tools)
- ❌ User disabled it (`NCP_DISABLE_CLI_SCAN=true`)
- ❌ Already scanned (1 hour cache)
### Environment Variables:
```bash
# Disable auto-scanning (manual only)
export NCP_DISABLE_CLI_SCAN=true
# Force scanning even without shell access
export NCP_FORCE_CLI_SCAN=true
```
## Benefits vs. Static Catalog
### Static Catalog (Old Approach)
❌ Requires manual maintenance
❌ Gets outdated when tools change
❌ Shows tools user doesn't have
❌ Hardcoded knowledge of specific versions
❌ Missing new/uncommon tools
### Runtime Discovery (New Approach)
✅ Zero maintenance required
✅ Always reflects current tool version
✅ Only shows installed tools
✅ Works with any tool version
✅ Discovers ALL installed tools
## Implementation Details
### Scanning Algorithm
```typescript
1. Get all commands: compgen -c
2. Filter candidates:
- Exclude shell built-ins (cd, echo, etc.)
- Include tools with useful keywords
- Limit to ~100 for performance
3. For each candidate:
- Check if executable: which <tool>
- Try help flags: --help, -h, help
- Parse help output:
* Extract description (first meaningful line)
* Extract capabilities (verbs, file types)
* Categorize (media, data, network, etc.)
4. Cache results (1 hour TTL)
5. Return discovered tools
```
### Performance
- **Initial scan**: ~2-5 seconds for 100 tools
- **Cached results**: <10ms
- **Cache TTL**: 1 hour
- **Force refresh**: Available via `force_refresh` parameter
### Smart Categorization
Tools are auto-categorized based on keywords:
```typescript
'media': video, audio, image, ffmpeg, mp4, mp3
'data': json, xml, csv, parse, jq
'documents': pdf, markdown, pandoc, docx
'development': git, npm, docker, build
'network': http, api, curl, download
'search': grep, find, search
'archive': zip, tar, compress
'security': encrypt, hash, crypto
'utilities': (fallback)
```
## Example: ffmpeg Discovery
```javascript
// Scan discovers ffmpeg
{
name: "ffmpeg",
path: "/opt/homebrew/bin/ffmpeg",
description: "Complete solution to record, convert and stream audio and video",
category: "media",
capabilities: [
"ffmpeg",
"convert",
"process",
"encode",
"decode",
"video",
"audio",
"mp4",
"webm",
"avi",
"mp3",
"aac"
]
}
// User searches: "convert video"
// Match score: HIGH (contains "convert" and "video")
// Returned as top result
// After adding via ncp:add:
// - CLI parser extracts operations from ffmpeg --help
// - 16 operations indexed (convert, extract_audio, etc.)
// - Available via find("convert video")
```
## Comparison
### Before (Static Catalog)
**Problem:** ffmpeg 6.0 changes syntax, catalog is outdated
```javascript
run("cli:suggest", { query: "convert video" })
// Returns: ffmpeg with hardcoded v5.0 knowledge
// User installs ffmpeg 7.0
// Suggestions are wrong!
```
### After (Runtime Discovery)
**Solution:** Parse actual current version
```javascript
run("cli:scan")
// Runs: ffmpeg --help (whatever version is installed)
// Parses: Current syntax, current options
// Always correct!
```
## Migration Path
Old static catalog can coexist during transition:
1. **Phase 1**: Add runtime scanner (this PR)
2. **Phase 2**: Use scanner for discovery, catalog for installation hints
3. **Phase 3**: Remove static catalog completely
## Testing
```javascript
// Test scanning
const scanner = new CLIScanner();
const tools = await scanner.scanSystem();
console.log(`Found ${tools.length} tools`);
// Test search
const results = await scanner.searchTools("convert video");
console.log(results.map(t => t.name));
// Test categorization
const mediaTools = await scanner.getToolsByCategory("media");
console.log(mediaTools);
```
## Implemented Features
- [x] **Conditional auto-scanning** - Triggers based on shell access
- [x] **Fallback on empty results** - Auto-scans and retries when no tools found
- [x] **Environment variable controls** - NCP_DISABLE_CLI_SCAN, NCP_FORCE_CLI_SCAN
- [x] **Smart caching** - 1 hour TTL, prevents redundant scans
- [x] **Non-blocking background scans** - No impact on initialization speed
## Future Enhancements
- [ ] Parallel scanning for speed (currently sequential)
- [ ] Parse man pages for richer descriptions
- [ ] Tool usage analytics (most used tools)
- [ ] Auto-suggest based on file types in context
- [ ] Integration with package managers (brew, apt) for installation hints
- [ ] Tool version compatibility warnings
- [ ] Smart re-scan triggers (new tools installed, PATH changes)
## Conclusion
Runtime CLI discovery with conditional auto-scanning eliminates maintenance burden while providing accurate, user-specific tool suggestions. The system:
1. **Automatically discovers** what's installed when shell access is available
2. **Falls back gracefully** when searches return empty results
3. **Respects user control** via environment variables
4. **Parses current help output** ensuring recommendations are always correct and up-to-date
Zero maintenance, maximum utility.
