Praison AI

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

bash
praisonai mcp tools search [query] [options]

Options

OptionDescriptionExample
<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-onlyShow only read-only tools--read-only
--jsonOutput in JSON format--json
--limit <n>Max results per page--limit 10
--cursor <cursor>Pagination cursor--cursor NTA

Basic Usage

Search by Query

bash
# 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

bash
# 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

bash
# 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

bash
# 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

bash
praisonai mcp tools search "memory" --json

Output:

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

JSON with Pagination

bash
praisonai mcp tools search --json --limit 5

Output:

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

Pagination

First Page

bash
praisonai mcp tools search --limit 10

Next Page

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

Iterate All Pages

bash
#!/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

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

Export Search Results

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

Count Results

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

Search with jq Processing

bash
# 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

bash
#!/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

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

Invalid Cursor

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

Exit Codes

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

Comparison with list-tools

Featurelist-toolstools 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