CLI Tools for NCP

Overview

NCP can integrate any CLI tool for discovery, making command-line utilities searchable alongside MCP servers. This solves a critical problem: AI has shell access but can't discover what tools are available.

How It Works

The Problem

• AI can execute CLI commands but doesn't know what tools exist
• find("convert video") won't suggest ffmpeg unless it's indexed
• Every user's machine has different CLI tools installed

The Solution: Discovery + Suggestions

NCP provides a two-tier system:

1. Tool Catalog - Knowledge of popular CLI tools (no installation required)
2. Tool Indexing - Makes installed tools discoverable

User Workflow

1. Discovery Phase (No Installation Required)

User needs to convert a video:

// AI searches for capability
find("convert video")
// Returns existing MCP tools (if any)

// AI suggests CLI tools that could help
run("cli:suggest", { query: "convert video" })

Output:

💡 CLI Tool Suggestions for "convert video":

**ffmpeg** - Complete solution to record, convert and stream audio and video
   Install: `brew install ffmpeg`
   Learn more: https://ffmpeg.org
   Add to NCP: run("ncp:add", { mcp_name: "cli:ffmpeg" })

2. Verification Phase

Check if tool is already installed:

run("cli:check", { tool_name: "ffmpeg" })

If Installed:

✅ ffmpeg is installed
   Version: ffmpeg version 8.0
Add to NCP: run("ncp:add", { mcp_name: "cli:ffmpeg" })

If Not Installed:

❌ ffmpeg is not installed

Install with:
   brew install ffmpeg

Learn more: https://ffmpeg.org

3. Installation (User Action)

User runs installation command:

brew install ffmpeg

4. Indexing Phase

Add tool to NCP for discovery:

run("ncp:add", { mcp_name: "cli:ffmpeg" })

Output:

✅ Added CLI tool: ffmpeg
   Indexed 16 operations for discovery

You can now use find() to discover ffmpeg operations:
   find("ffmpeg")
   find("convert video")

5. Usage Phase

Now the tool appears in searches:

find("convert video")

Returns:

• ffmpeg:convert - Convert video/audio to different format (0.82)
• ffmpeg:compress - Compress/reduce video file size (0.47)
• ffmpeg:resize - Resize/scale video dimensions (0.45)
...

AI can now execute with context:

ffmpeg -i input.mp4 -c:v libx264 output.mp4

Tool Catalog

Browse available CLI tools:

// List all categories
run("cli:catalog")

// Browse specific category
run("cli:catalog", { category: "media" })

Categories:

• media - ffmpeg, imagemagick, yt-dlp
• data - jq (JSON processing)
• documents - pandoc (document conversion)
• development - git (version control)
• network - curl (HTTP requests)
• search - ripgrep (fast text search)

Adding New Tools

Quick Add (Auto-Parse)

// Add any CLI tool by name
run("ncp:add", { mcp_name: "cli:jq" })

NCP will:

1. Verify the tool exists
2. Parse --help output
3. Extract operations and parameters
4. Create searchable index
5. Generate embeddings for semantic search

Pre-Defined Tools

Some tools (like ffmpeg) have pre-defined operation sets for better UX:

• ffmpeg: 16 operations (convert, extract_audio, compress, resize, cut, merge, etc.)
• Others use generic auto-parsing

Benefits

For Users

• ✅ No pre-installation required - suggestions work without tools installed
• ✅ Platform-specific install commands - correct for macOS/Linux/Windows
• ✅ Check before install - verify what's already available
• ✅ Browse capabilities - explore what tools can do
• ✅ Semantic search - find tools by describing what you need

For AI

• ✅ Discovers CLI capabilities - knows ffmpeg can convert videos
• ✅ Gets command templates - knows how to structure commands
• ✅ Validates availability - won't suggest unavailable tools
• ✅ Unified search - CLI tools + MCP servers in one query

Architecture

┌─────────────────────────────────────────┐
│         User Search Query               │
│       "convert video to gif"            │
└────────────┬────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────┐
│     NCP Discovery Engine                │
│   (Semantic Search + Embeddings)        │
└──┬──────────────────────────────────┬───┘
   │                                  │
   │                                  │
   ▼                                  ▼
┌──────────────────┐      ┌──────────────────┐
│  MCP Servers     │      │   CLI Tools      │
│  (connected)     │      │   (indexed)      │
└──────────────────┘      └──────────────────┘
   │                                  │
   │                                  │
   ▼                                  ▼
┌──────────────────┐      ┌──────────────────┐
│  MCP Tools       │      │ ffmpeg:create_gif│
│  video:encode    │      │ (confidence: 0.8)│
│  (confidence: 0.6)│      └──────────────────┘
└──────────────────┘

Implementation Details

Cache Structure

Metadata Cache (~/.ncp/cache/all-tools.json):

{
  "mcps": {
    "ffmpeg": {
      "configHash": "...",
      "tools": [
        {
          "name": "convert",
          "description": "Convert video/audio to different format",
          "inputSchema": {
            "type": "object",
            "properties": {
              "command_template": {
                "default": "ffmpeg -i {input} {output}"
              }
            }
          }
        }
      ]
    }
  }
}

Embeddings Cache (~/.ncp/embeddings.json):

{
  "vectors": {
    "ffmpeg:convert": [0.023, -0.145, 0.892, ...]
  },
  "metadata": {
    "ffmpeg:convert": {
      "mcpName": "ffmpeg",
      "enhancedDescription": "convert: Convert video/audio..."
    }
  }
}

CLI Tool Marker

CLI tools are marked in the profile to skip MCP connection:

{
  "mcpServers": {
    "ffmpeg": {
      "command": "ffmpeg",
      "args": [],
      "env": {
        "NCP_CLI_TOOL": "true"  // Marker: load from cache only
      }
    }
  }
}

Best Practices

For Tool Authors

1. Provide good --help output - Clear descriptions, examples
2. Consistent flag structure - Standard patterns like -i input -o output
3. Include examples - Helps users understand usage

For Users

1. Start with suggestions - run("cli:suggest", { query: "..." })
2. Check before installing - run("cli:check", { tool_name: "..." })
3. Browse catalog - Discover tools you didn't know existed
4. Add after install - Only index tools you actually have

For Developers

1. Extend the catalog - Add new tools to cli-catalog.ts
2. Add custom parsers - For complex tools (like ffmpeg)
3. Improve capabilities - Better keyword matching

Limitations

• Execution is manual - AI still uses shell, not a protocol wrapper
• No streaming output - Command runs to completion
• No interactive prompts - CLI tools must accept all args upfront
• Platform differences - Help output varies by OS

Future Enhancements

• [ ] Auto-detect installed CLI tools on startup
• [ ] Parse man pages for better documentation
• [ ] Support for tool aliases (e.g., convert → imagemagick)
• [ ] Integration with package managers (brew, apt, etc.)
• [ ] Tool usage analytics
• [ ] Community-contributed tool definitions

Examples

Example 1: Video Conversion

// User: "I need to convert this MP4 to WebM"

// Step 1: AI searches
find("convert video")
// No indexed tools found

// Step 2: AI asks for suggestions
run("cli:suggest", { query: "convert video" })
// Suggests: ffmpeg

// Step 3: User installs
// $ brew install ffmpeg

// Step 4: User adds to NCP
run("ncp:add", { mcp_name: "cli:ffmpeg" })

// Step 5: AI can now discover and use
find("convert video")
// Returns: ffmpeg:convert

// Step 6: AI executes
// $ ffmpeg -i input.mp4 -c:v libvpx output.webm

Example 2: JSON Processing

// User: "Extract email from this JSON"

// AI suggests
run("cli:suggest", { query: "process json" })
// Suggests: jq

// User has it installed
run("ncp:add", { mcp_name: "cli:jq" })

// AI can now use
// $ cat data.json | jq '.email'

Conclusion

NCP's CLI tool integration solves the discovery problem while respecting user choice. Tools aren't pre-installed or pre-indexed, but users can easily discover, verify, and add the tools they need. This creates a flexible, user-controlled ecosystem where CLI tools and MCP servers work seamlessly together.