MCP Tool Search CLI

CLI commands for searching and filtering MCP tools

MCP Tool Search CLI

Command-line interface for searching and filtering MCP server tools.

Command Overview

praisonai mcp tools search [query] [options]

Options

Option	Description	Example
<query>	Text to search in name/description	"memory"
--category <cat>	Filter by category	--category file
--tag <tag>	Filter by tag (repeatable)	--tag search --tag web
--read-only	Show only read-only tools	--read-only
--json	Output in JSON format	--json
--limit <n>	Max results per page	--limit 10
--cursor <cursor>	Pagination cursor	--cursor NTA

Basic Usage

Search by Query

# Search for tools containing "memory"
praisonai mcp tools search "memory"

Output:

Search Results (2 of 2):

  • memory.show [read-only]
    Show memory contents

  • memory.clear [destructive]
    Clear memory contents

Search by Category

# Find all file-related tools
praisonai mcp tools search --category file

Output:

Search Results (3 of 3):

  • file.read [read-only]
    Read file contents

  • file.write [destructive]
    Write to file

  • file.delete [destructive]
    Delete a file

Search Read-Only Tools

# Find safe tools that don't modify state
praisonai mcp tools search --read-only

Output:

Search Results (5 of 5):

  • memory.show [read-only]
    Show memory contents

  • file.read [read-only]
    Read file contents

  • web.search [read-only]
    Search the web
  ...

Combined Filters

# Find read-only tools in memory category
praisonai mcp tools search --category memory --read-only

# Search with query and category filter
praisonai mcp tools search "show" --category memory

JSON Output

Basic JSON

praisonai mcp tools search "memory" --json

Output:

{
  "tools": [
    {
      "name": "memory.show",
      "description": "Show memory contents",
      "inputSchema": {"type": "object"},
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false
      }
    }
  ],
  "total": 1
}

JSON with Pagination

praisonai mcp tools search --json --limit 5

Output:

{
  "tools": [...],
  "total": 25,
  "nextCursor": "NQ"
}

Pagination

First Page

praisonai mcp tools search --limit 10

Next Page

praisonai mcp tools search --limit 10 --cursor NTA

Iterate All Pages

#!/bin/bash
# Search and iterate through all pages

query="$1"
cursor=""

while true; do
    if [ -z "$cursor" ]; then
        result=$(praisonai mcp tools search "$query" --json --limit 10)
    else
        result=$(praisonai mcp tools search "$query" --json --limit 10 --cursor "$cursor")
    fi
    
    # Process results
    echo "$result" | jq '.tools[].name'
    
    # Get next cursor
    cursor=$(echo "$result" | jq -r '.nextCursor // empty')
    
    if [ -z "$cursor" ]; then
        break
    fi
done

Examples

Find Destructive Tools

# List tools that may modify data (not read-only)
praisonai mcp tools search --json | \
  jq '.tools[] | select(.annotations.readOnlyHint != true) | .name'

Export Search Results

# Export memory tools to file
praisonai mcp tools search "memory" --json > memory_tools.json

Count Results

# Count read-only tools
praisonai mcp tools search --read-only --json | jq '.total'

Search with jq Processing

# Get names only
praisonai mcp tools search "file" --json | jq -r '.tools[].name'

# Get tools with descriptions
praisonai mcp tools search --json | \
  jq '.tools[] | "\(.name): \(.description)"'

# Filter by annotation in post-processing
praisonai mcp tools search --json | \
  jq '.tools[] | select(.annotations.idempotentHint == true)'

Build Tool Inventory

#!/bin/bash
# Create tool inventory by category

echo "# Tool Inventory"
echo ""

for category in memory file web config; do
    count=$(praisonai mcp tools search --category "$category" --json 2>/dev/null | jq '.total // 0')
    echo "## $category: $count tools"
    
    if [ "$count" -gt 0 ]; then
        praisonai mcp tools search --category "$category" --json | \
          jq -r '.tools[] | "- \(.name)"'
    fi
    echo ""
done

Error Handling

No Results

praisonai mcp tools search "nonexistent"
# No tools found matching your criteria
# Exit code: 0

Invalid Cursor

praisonai mcp tools search --cursor "invalid!!!"
# Error: Search error: Invalid cursor
# Exit code: 1

Exit Codes

Code	Meaning
0	Success (even with no results)
1	Error (invalid cursor, etc.)

Comparison with list-tools

Feature	list-tools	tools search
List all tools	✓	✓
Query filter	✗	✓
Category filter	✗	✓
Tag filter	✗	✓
Read-only filter	✗	✓
Pagination	✓	✓
JSON output	✓	✓
Total count	✗	✓

Use list-tools for simple listing, tools search for filtering.

See Also

• MCP Tool Search Module - Code-based search usage
• MCP Pagination CLI - Pagination details
• MCP Tool Annotations CLI - View tool annotations
• MCP CLI Overview - All MCP CLI commands