|
| 1 | +#!/bin/bash |
| 2 | +# MCP Server Discovery Script |
| 3 | +# Search the official MCP Registry and enrich results with GitHub stars |
| 4 | + |
| 5 | +set -euo pipefail |
| 6 | + |
| 7 | +# Configuration |
| 8 | +REGISTRY_URL="https://registry.modelcontextprotocol.io/v0/servers" |
| 9 | +DEFAULT_LIMIT=10 |
| 10 | +DEFAULT_FORMAT="table" |
| 11 | + |
| 12 | +# Colors (disabled if not a terminal) |
| 13 | +if [ -t 1 ]; then |
| 14 | + BOLD='\033[1m' |
| 15 | + DIM='\033[2m' |
| 16 | + RESET='\033[0m' |
| 17 | + YELLOW='\033[33m' |
| 18 | + RED='\033[31m' |
| 19 | + GREEN='\033[32m' |
| 20 | +else |
| 21 | + BOLD='' |
| 22 | + DIM='' |
| 23 | + RESET='' |
| 24 | + YELLOW='' |
| 25 | + RED='' |
| 26 | + GREEN='' |
| 27 | +fi |
| 28 | + |
| 29 | +# Show help message |
| 30 | +show_help() { |
| 31 | + cat << 'EOF' |
| 32 | +MCP Server Discovery |
| 33 | +
|
| 34 | +Search the official MCP Registry for servers and sort by GitHub popularity. |
| 35 | +
|
| 36 | +USAGE: |
| 37 | + search-mcp-servers.sh [OPTIONS] <keywords...> |
| 38 | +
|
| 39 | +OPTIONS: |
| 40 | + -n, --limit N Maximum results to return (default: 10) |
| 41 | + -f, --format FMT Output format: table, json, simple (default: table) |
| 42 | + -t, --transport T Filter by transport type: stdio, sse, http, ws |
| 43 | + -h, --help Show this help message |
| 44 | +
|
| 45 | +EXAMPLES: |
| 46 | + # Search for database servers |
| 47 | + ./search-mcp-servers.sh database postgres |
| 48 | +
|
| 49 | + # Get top 5 results as JSON |
| 50 | + ./search-mcp-servers.sh -n 5 --format json filesystem |
| 51 | +
|
| 52 | + # Search for stdio-only servers |
| 53 | + ./search-mcp-servers.sh --transport stdio github |
| 54 | +
|
| 55 | + # Simple output for scripting |
| 56 | + ./search-mcp-servers.sh --format simple "web search" |
| 57 | +
|
| 58 | +OUTPUT FORMATS: |
| 59 | + table - Formatted table with stars, name, description, URL (default) |
| 60 | + json - JSON array for programmatic use |
| 61 | + simple - One server per line: stars|name|url |
| 62 | +
|
| 63 | +NOTES: |
| 64 | + - Results are sorted by GitHub stars (descending) |
| 65 | + - Servers without GitHub repos appear at the bottom |
| 66 | + - Requires: curl, jq, gh (GitHub CLI) |
| 67 | +EOF |
| 68 | +} |
| 69 | + |
| 70 | +# Check for required dependencies |
| 71 | +check_dependencies() { |
| 72 | + local missing=() |
| 73 | + |
| 74 | + if ! command -v curl &> /dev/null; then |
| 75 | + missing+=("curl") |
| 76 | + fi |
| 77 | + |
| 78 | + if ! command -v jq &> /dev/null; then |
| 79 | + missing+=("jq") |
| 80 | + fi |
| 81 | + |
| 82 | + if ! command -v gh &> /dev/null; then |
| 83 | + missing+=("gh (GitHub CLI)") |
| 84 | + fi |
| 85 | + |
| 86 | + if [ ${#missing[@]} -gt 0 ]; then |
| 87 | + echo -e "${RED}❌ Missing required dependencies:${RESET}" >&2 |
| 88 | + for dep in "${missing[@]}"; do |
| 89 | + echo " - $dep" >&2 |
| 90 | + done |
| 91 | + exit 1 |
| 92 | + fi |
| 93 | +} |
| 94 | + |
| 95 | +# Get GitHub stars for a repository URL |
| 96 | +# Returns 0 if not a GitHub repo or on error |
| 97 | +get_github_stars() { |
| 98 | + local repo_url="$1" |
| 99 | + local stars=0 |
| 100 | + |
| 101 | + # Extract owner/repo from GitHub URL |
| 102 | + if [[ "$repo_url" =~ github\.com[/:]([^/]+)/([^/]+) ]]; then |
| 103 | + local owner="${BASH_REMATCH[1]}" |
| 104 | + local repo="${BASH_REMATCH[2]}" |
| 105 | + # Remove .git suffix if present |
| 106 | + repo="${repo%.git}" |
| 107 | + |
| 108 | + # Query GitHub API |
| 109 | + stars=$(gh api "repos/$owner/$repo" --jq '.stargazers_count' 2>/dev/null || echo "0") |
| 110 | + |
| 111 | + # Handle non-numeric responses |
| 112 | + if ! [[ "$stars" =~ ^[0-9]+$ ]]; then |
| 113 | + stars=0 |
| 114 | + fi |
| 115 | + fi |
| 116 | + |
| 117 | + echo "$stars" |
| 118 | +} |
| 119 | + |
| 120 | +# Query the MCP Registry |
| 121 | +query_registry() { |
| 122 | + local keywords="$1" |
| 123 | + local limit="$2" |
| 124 | + |
| 125 | + local encoded_keywords |
| 126 | + encoded_keywords=$(echo -n "$keywords" | jq -sRr @uri) |
| 127 | + |
| 128 | + local url="${REGISTRY_URL}?search=${encoded_keywords}&limit=${limit}" |
| 129 | + |
| 130 | + local response |
| 131 | + if ! response=$(curl -s --fail --max-time 30 "$url" 2>/dev/null); then |
| 132 | + echo -e "${RED}❌ Failed to query MCP Registry${RESET}" >&2 |
| 133 | + echo -e "${DIM} URL: $url${RESET}" >&2 |
| 134 | + echo -e "${DIM} Check your network connection${RESET}" >&2 |
| 135 | + exit 1 |
| 136 | + fi |
| 137 | + |
| 138 | + # Validate response is valid JSON with servers array |
| 139 | + if ! echo "$response" | jq -e '.servers' &>/dev/null; then |
| 140 | + echo -e "${RED}❌ Invalid response from MCP Registry${RESET}" >&2 |
| 141 | + exit 1 |
| 142 | + fi |
| 143 | + |
| 144 | + echo "$response" |
| 145 | +} |
| 146 | + |
| 147 | +# Format output as table |
| 148 | +format_table() { |
| 149 | + local data="$1" |
| 150 | + local count |
| 151 | + count=$(echo "$data" | jq 'length') |
| 152 | + |
| 153 | + if [ "$count" -eq 0 ]; then |
| 154 | + echo -e "${YELLOW}No servers found matching your search.${RESET}" |
| 155 | + echo "" |
| 156 | + echo "Suggestions:" |
| 157 | + echo " - Try broader search terms" |
| 158 | + echo " - Check spelling" |
| 159 | + echo " - Browse categories at https://smithery.ai/" |
| 160 | + return |
| 161 | + fi |
| 162 | + |
| 163 | + echo -e "${BOLD}┌─────────────────────────────────────────────────────────────────┐${RESET}" |
| 164 | + echo -e "${BOLD}│ MCP Server Discovery Results (sorted by GitHub stars) │${RESET}" |
| 165 | + echo -e "${BOLD}├─────────────────────────────────────────────────────────────────┤${RESET}" |
| 166 | + |
| 167 | + echo "$data" | jq -r '.[] | "\(.stars)|\(.name)|\(.description)|\(.repository)"' | while IFS='|' read -r stars name description repo; do |
| 168 | + # Truncate description if too long |
| 169 | + if [ ${#description} -gt 55 ]; then |
| 170 | + description="${description:0:52}..." |
| 171 | + fi |
| 172 | + |
| 173 | + # Format stars with padding |
| 174 | + if [ "$stars" -eq 0 ]; then |
| 175 | + stars_display=" - " |
| 176 | + else |
| 177 | + stars_display=$(printf "⭐ %'d" "$stars") |
| 178 | + # Pad to 6 chars |
| 179 | + while [ ${#stars_display} -lt 8 ]; do |
| 180 | + stars_display="$stars_display " |
| 181 | + done |
| 182 | + fi |
| 183 | + |
| 184 | + echo -e "│ ${GREEN}${stars_display}${RESET} ${BOLD}${name}${RESET}" |
| 185 | + echo -e "│ ${DIM}${description}${RESET}" |
| 186 | + echo -e "│ ${DIM}${repo}${RESET}" |
| 187 | + echo -e "├─────────────────────────────────────────────────────────────────┤" |
| 188 | + done | head -n -1 # Remove last separator |
| 189 | + |
| 190 | + echo -e "${BOLD}└─────────────────────────────────────────────────────────────────┘${RESET}" |
| 191 | + echo "" |
| 192 | + echo -e "Found ${BOLD}$count${RESET} server(s) matching your search" |
| 193 | +} |
| 194 | + |
| 195 | +# Format output as JSON |
| 196 | +format_json() { |
| 197 | + local data="$1" |
| 198 | + echo "$data" | jq '.' |
| 199 | +} |
| 200 | + |
| 201 | +# Format output as simple (one per line) |
| 202 | +format_simple() { |
| 203 | + local data="$1" |
| 204 | + echo "$data" | jq -r '.[] | "\(.stars)|\(.name)|\(.repository)"' |
| 205 | +} |
| 206 | + |
| 207 | +# Main function |
| 208 | +main() { |
| 209 | + local limit=$DEFAULT_LIMIT |
| 210 | + local format=$DEFAULT_FORMAT |
| 211 | + local transport="" |
| 212 | + local keywords="" |
| 213 | + |
| 214 | + # Parse arguments |
| 215 | + while [ $# -gt 0 ]; do |
| 216 | + case "$1" in |
| 217 | + -h|--help) |
| 218 | + show_help |
| 219 | + exit 0 |
| 220 | + ;; |
| 221 | + -n|--limit) |
| 222 | + if [ -z "${2:-}" ] || [[ "$2" == -* ]]; then |
| 223 | + echo -e "${RED}❌ --limit requires a number${RESET}" >&2 |
| 224 | + exit 1 |
| 225 | + fi |
| 226 | + limit="$2" |
| 227 | + if ! [[ "$limit" =~ ^[0-9]+$ ]] || [ "$limit" -eq 0 ]; then |
| 228 | + echo -e "${RED}❌ --limit must be a positive number${RESET}" >&2 |
| 229 | + exit 1 |
| 230 | + fi |
| 231 | + shift 2 |
| 232 | + ;; |
| 233 | + -f|--format) |
| 234 | + if [ -z "${2:-}" ] || [[ "$2" == -* ]]; then |
| 235 | + echo -e "${RED}❌ --format requires a value (table, json, simple)${RESET}" >&2 |
| 236 | + exit 1 |
| 237 | + fi |
| 238 | + format="$2" |
| 239 | + if [[ ! "$format" =~ ^(table|json|simple)$ ]]; then |
| 240 | + echo -e "${RED}❌ Invalid format: $format (use table, json, or simple)${RESET}" >&2 |
| 241 | + exit 1 |
| 242 | + fi |
| 243 | + shift 2 |
| 244 | + ;; |
| 245 | + -t|--transport) |
| 246 | + if [ -z "${2:-}" ] || [[ "$2" == -* ]]; then |
| 247 | + echo -e "${RED}❌ --transport requires a value (stdio, sse, http, ws)${RESET}" >&2 |
| 248 | + exit 1 |
| 249 | + fi |
| 250 | + transport="$2" |
| 251 | + if [[ ! "$transport" =~ ^(stdio|sse|http|ws)$ ]]; then |
| 252 | + echo -e "${RED}❌ Invalid transport: $transport (use stdio, sse, http, or ws)${RESET}" >&2 |
| 253 | + exit 1 |
| 254 | + fi |
| 255 | + shift 2 |
| 256 | + ;; |
| 257 | + -*) |
| 258 | + echo -e "${RED}❌ Unknown option: $1${RESET}" >&2 |
| 259 | + echo "Use --help for usage information" >&2 |
| 260 | + exit 1 |
| 261 | + ;; |
| 262 | + *) |
| 263 | + # Collect positional arguments as keywords |
| 264 | + if [ -n "$keywords" ]; then |
| 265 | + keywords="$keywords $1" |
| 266 | + else |
| 267 | + keywords="$1" |
| 268 | + fi |
| 269 | + shift |
| 270 | + ;; |
| 271 | + esac |
| 272 | + done |
| 273 | + |
| 274 | + # Validate keywords |
| 275 | + if [ -z "$keywords" ]; then |
| 276 | + echo -e "${RED}❌ No search keywords provided${RESET}" >&2 |
| 277 | + echo "" >&2 |
| 278 | + echo "Usage: search-mcp-servers.sh [OPTIONS] <keywords...>" >&2 |
| 279 | + echo "Use --help for more information" >&2 |
| 280 | + exit 1 |
| 281 | + fi |
| 282 | + |
| 283 | + # Check dependencies |
| 284 | + check_dependencies |
| 285 | + |
| 286 | + # Query registry |
| 287 | + if [ "$format" = "table" ]; then |
| 288 | + echo -e "${DIM}Searching MCP Registry for: $keywords${RESET}" |
| 289 | + echo "" |
| 290 | + fi |
| 291 | + |
| 292 | + local response |
| 293 | + response=$(query_registry "$keywords" "$limit") |
| 294 | + |
| 295 | + # Extract servers and enrich with stars |
| 296 | + local servers |
| 297 | + servers=$(echo "$response" | jq -c '.servers // []') |
| 298 | + |
| 299 | + local server_count |
| 300 | + server_count=$(echo "$servers" | jq 'length') |
| 301 | + |
| 302 | + if [ "$server_count" -eq 0 ]; then |
| 303 | + format_table "[]" |
| 304 | + exit 0 |
| 305 | + fi |
| 306 | + |
| 307 | + # Build enriched data with stars |
| 308 | + if [ "$format" = "table" ]; then |
| 309 | + echo -e "${DIM}Fetching GitHub stars for $server_count server(s)...${RESET}" |
| 310 | + fi |
| 311 | + |
| 312 | + local enriched="[]" |
| 313 | + local rate_limit_warned=false |
| 314 | + |
| 315 | + while IFS= read -r server; do |
| 316 | + local name description repo stars |
| 317 | + |
| 318 | + name=$(echo "$server" | jq -r '.name // "unknown"') |
| 319 | + description=$(echo "$server" | jq -r '.description // "No description"') |
| 320 | + repo=$(echo "$server" | jq -r '.repository // ""') |
| 321 | + |
| 322 | + # Get stars (with rate limit handling) |
| 323 | + if [ -n "$repo" ]; then |
| 324 | + stars=$(get_github_stars "$repo") |
| 325 | + |
| 326 | + # Check for potential rate limiting (all zeros after first few) |
| 327 | + if [ "$stars" -eq 0 ] && [ "$rate_limit_warned" = false ]; then |
| 328 | + # Simple heuristic: if we're getting zeros, might be rate limited |
| 329 | + : |
| 330 | + fi |
| 331 | + else |
| 332 | + stars=0 |
| 333 | + fi |
| 334 | + |
| 335 | + # Add to enriched array |
| 336 | + enriched=$(echo "$enriched" | jq --arg name "$name" \ |
| 337 | + --arg desc "$description" \ |
| 338 | + --arg repo "$repo" \ |
| 339 | + --argjson stars "$stars" \ |
| 340 | + '. + [{name: $name, description: $desc, repository: $repo, stars: $stars}]') |
| 341 | + |
| 342 | + done < <(echo "$servers" | jq -c '.[]') |
| 343 | + |
| 344 | + # Filter by transport if specified |
| 345 | + if [ -n "$transport" ]; then |
| 346 | + # Note: Transport info may not be in registry response |
| 347 | + # This is a placeholder for when that data becomes available |
| 348 | + if [ "$format" = "table" ]; then |
| 349 | + echo -e "${YELLOW}Note: Transport filtering may not match all servers (data not always available)${RESET}" |
| 350 | + fi |
| 351 | + fi |
| 352 | + |
| 353 | + # Sort by stars descending |
| 354 | + enriched=$(echo "$enriched" | jq 'sort_by(-.stars)') |
| 355 | + |
| 356 | + # Output in requested format |
| 357 | + case "$format" in |
| 358 | + table) |
| 359 | + echo "" |
| 360 | + format_table "$enriched" |
| 361 | + ;; |
| 362 | + json) |
| 363 | + format_json "$enriched" |
| 364 | + ;; |
| 365 | + simple) |
| 366 | + format_simple "$enriched" |
| 367 | + ;; |
| 368 | + esac |
| 369 | +} |
| 370 | + |
| 371 | +# Run main function |
| 372 | +main "$@" |
0 commit comments