MCP Discovery Skill

Dynamic MCP package discovery at runtime. Instead of relying on a static registry, this skill verifies MCP availability by querying npm, GitHub, and vendor documentation.

Purpose

When a user selects a tool during /design-ops:setup, this skill discovers the best connection method:

1. Check for official/vendor MCPs
2. Evaluate community packages (with quality metrics)
3. Find API documentation for direct integration
4. Return a recommendation with confidence level

Why Dynamic Discovery?

• 100+ potential tools across operations/design/analytics
• Static registries become stale immediately
• New MCPs are published constantly
• Tool-agnostic design requires runtime discovery

Trigger

Invoked by tool-evaluator skill during setup flow:

skill: mcp-discovery
input:
  tool: "monday"
  pillar: "operations"

Discovery Flow

User selects tool (e.g., "Monday.com")
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 1: Check Known Tools (fast path)                      │
│  - Look up in known_tools.yaml for common tools             │
│  - If found with high confidence, return immediately        │
└─────────────────────────────────────────────────────────────┘
           │ not found
           ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 2: Search npm for Official MCP                        │
│  - npm view @modelcontextprotocol/server-{tool}             │
│  - npm view @{vendor}/mcp-server                            │
│  - Check for vendor-published packages                      │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 3: Search npm for Community MCPs                      │
│  - npm search {tool} mcp --json                             │
│  - Filter by: downloads > 1000, updated < 6 months          │
│  - Rank by quality metrics                                  │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 4: Check Anthropic MCP Servers Repo                   │
│  - GitHub API: repos/anthropics/mcp-servers/contents        │
│  - Look for tool-specific server                            │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 5: Discover API Documentation                         │
│  - Web search: "{tool} API documentation"                   │
│  - Check common patterns: api.{tool}.com, developers.{tool} │
│  - Scrape for authentication requirements                   │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 6: Return Discovery Result                            │
│  - Recommendation: mcp | api | both | unavailable           │
│  - Confidence level based on source quality                 │
│  - Warning if community package                             │
└─────────────────────────────────────────────────────────────┘

Output Schema

tool: monday
discovery_result:
  # MCP discovery
  mcp_found: true | false
  mcp_source: official | vendor | community | none
  mcp_package: "@monday/mcp-server"
  mcp_confidence: high | medium | low

  # Quality metrics (when available)
  npm_weekly_downloads: 5000
  npm_last_updated: "2025-03-15"
  github_stars: 120

  # API discovery
  api_available: true
  api_docs_url: "https://developer.monday.com/api-reference"
  api_auth_type: "api_key" | "oauth" | "token"

  # Final recommendation
  recommendation: mcp | api | both | unavailable
  status: connected | available | api_only | unavailable

  # Warnings
  warning: "Community package - not officially supported" | null
  warning_code: community_package | low_downloads | outdated | none

Confidence Levels

Known Tools (Fast Path)

For the 42 most common tools, we use a verified registry (known-tools.yaml) that has been validated against npm and official documentation. All entries have validated: true.

Registry Schema (v2.0)

# skills/mcp-discovery/known-tools.yaml

version: "2.0"
last_validated: "2026-04-19"
validation_method: "npm view + official docs"

# Each tool entry includes:
# - mcp_source: official | vendor | community | none
# - mcp_package: npm package name (null for HTTP MCPs)
# - mcp_type: stdio | http
# - mcp_url: URL for HTTP MCPs
# - mcp_confidence: high | medium | low | none
# - validated: true (verified to exist)
# - install_cmd: explicit install command (optional)
# - warning: caution message (optional)
# - env_required: required environment variables

Example Entries (Verified)

# Vendor stdio MCP (high confidence)
notion:
  mcp_source: vendor
  mcp_package: "@notionhq/notion-mcp-server"
  mcp_type: stdio
  mcp_confidence: high
  validated: true
  env_required:
    - NOTION_API_KEY

# Official stdio MCP (deprecated but functional)
github:
  mcp_source: official
  mcp_package: "@modelcontextprotocol/server-github"
  mcp_type: stdio
  mcp_confidence: high
  validated: true
  warning: "Package marked deprecated on npm"
  env_required:
    - GITHUB_PERSONAL_ACCESS_TOKEN

# Official HTTP MCP
figma:
  mcp_source: official
  mcp_package: null
  mcp_type: http
  mcp_url: "https://mcp.figma.com/mcp"
  mcp_confidence: high
  validated: true
  install_cmd: "claude mcp add --transport http figma https://mcp.figma.com/mcp"

# Official HTTP MCP
supabase:
  mcp_source: official
  mcp_package: null
  mcp_type: http
  mcp_url: "https://api.supabase.com/mcp"
  mcp_confidence: high
  validated: true
  install_cmd: "claude mcp add supabase https://api.supabase.com/mcp"

# Community MCP (medium confidence)
linear:
  mcp_source: community
  mcp_package: "mcp-server-linear"
  mcp_type: stdio
  mcp_confidence: medium
  validated: true
  warning: "Community package by dvcrn"

# No MCP available (API only)
google_analytics:
  mcp_source: none
  mcp_package: null
  mcp_confidence: none
  validated: true
  api_docs: "https://developers.google.com/analytics"
  recommendation: api
  note: "Use Google Analytics Data API directly."

Registry Summary (42 tools)

This is the source of truth for DESIGN-OPS tool recommendations. All packages have been verified to exist.

Discovery Implementation

Step 1: Check Known Tools Registry (Fast Path)

# First, check known-tools.yaml for validated entries
# If found with validated: true, return immediately
# This prevents unnecessary npm queries for known tools

Step 2: npm Package Search

# Check for official MCP packages (modelcontextprotocol namespace)
npm view @modelcontextprotocol/server-{tool} --json 2>/dev/null

# Check for vendor package patterns
npm view @{tool}hq/{tool}-mcp-server --json 2>/dev/nul