MLB Stats MCP Server - Enhanced with Meta-Tools

🔧 Version 2.1 - Now with Entity Resolution Meta-Tools!

A Cloudflare Worker that serves as an enhanced MCP (Model Context Protocol) server for accessing MLB Stats API data. Features meta-tools for intelligent entity resolution, comprehensive team/player mappings, and optimized data access patterns.

🎯 Enhanced Features

🔧 Meta-Tools for Entity Resolution

• resolve_team: Convert team names to canonical MLB team IDs
• resolve_player: Convert player names to canonical MLB player IDs
• Comprehensive Mappings: All 30 MLB teams with aliases and abbreviations
• Fuzzy Matching: "Yankees", "NYY", "New York Yankees" all resolve correctly
• Smart Suggestions: "Did you mean?" fallbacks for typos and partial matches

⚾ MLB Data Access

• Direct MLB API proxy with zero additional latency
• All MLB endpoints supported (teams, players, stats, schedules, etc.)
• CORS enabled for web applications
• No API keys required (MLB Stats API is public)
• Error handling and validation with detailed responses

🏗️ Architecture Benefits

• Domain logic ownership: All MLB-specific logic contained within this worker
• Service binding ready: Optimized for Cloudflare worker-to-worker communication
• Token efficient: Meta-tools reduce round-trips and enable smart caching
• Future-proof: Extensible pattern for other sports (NFL, NBA, NHL)

🛠️ Available Commands

🔧 Meta-Tools (Entity Resolution)

resolve_team - Team Name Resolution

Convert any team reference to canonical MLB team information.

Request:

{
  "command": "resolve_team",
  "params": {
    "name": "Yankees"
  }
}

Response:

{
  "result": {
    "id": 147,
    "name": "New York Yankees", 
    "abbreviation": "NYY",
    "query": "Yankees",
    "resolved": true
  }
}

Supported Inputs:

• Team names: "Yankees", "Red Sox", "Dodgers"
• Full names: "New York Yankees", "Boston Red Sox"
• Abbreviations: "NYY", "BOS", "LAD"
• Cities: "New York", "Boston", "Los Angeles"

resolve_player - Player Name Resolution

Convert any player reference to canonical MLB player information.

Request:

{
  "command": "resolve_player",
  "params": {
    "name": "Judge"
  }
}

Response:

{
  "result": {
    "id": 592450,
    "name": "Aaron Judge",
    "team": "New York Yankees",
    "query": "Judge", 
    "resolved": true
  }
}

Supported Players:

• Aaron Judge, Shohei Ohtani, Mookie Betts, Freddie Freeman
• Ronald Acuna Jr., Mike Trout, and other star players
• Both full names and last names supported

⚾ MLB Data Commands

• getTeamInfo - Get team information and details
• getRoster - Get team roster and player positions
• getPlayerStats - Get player statistics (hitting, pitching)
• getSchedule - Get game schedule and dates
• getLiveGame - Get live game data and updates
• getStandings - Get league and division standings
• getGameBoxscore - Get detailed game boxscore
• getPlayerInfo - Get player biographical information
• getSeasons - Get season information and years
• getVenues - Get stadium and venue information

🎯 Enhanced Workflow

Traditional Approach:

// Step 1: User needs to know exact team ID
{"command": "getRoster", "params": {"pathParams": {"teamId": "147"}}}

Enhanced Meta-Tool Approach:

// Step 1: Resolve team name to ID
{"command": "resolve_team", "params": {"name": "Yankees"}}
// Returns: {"result": {"id": 147, "name": "New York Yankees"}}

// Step 2: Use resolved ID automatically (handled by sports-proxy)
{"command": "getRoster", "params": {"pathParams": {"teamId": "147"}}}

Request Format

Send POST requests to the worker endpoint with the following JSON structure:

{
  "command": "getPlayerStats",
  "params": {
    "pathParams": {
      "playerId": "660271"
    },
    "queryParams": {
      "stats": "season",
      "group": "hitting",
      "season": "2024"
    }
  }
}

Response Format

Successful responses return:

{
  "result": {
    // MLB API response data
  }
}

Error responses return:

{
  "error": "Error message"
}

Development

1. Install Wrangler CLI:

   npm install -g wrangler
   

2. Login to Cloudflare:

   wrangler login
   

3. Deploy the worker:

   wrangler deploy
   

📋 Complete Usage Examples

🔧 Meta-Tool Examples

Resolve Team Names

# Basic team resolution
curl -X POST https://mlbstats-mcp.your-domain.workers.dev \
  -H "Content-Type: application/json" \
  -d '{
    "command": "resolve_team",
    "params": {"name": "Yankees"}
  }'

# Response: {"result": {"id": 147, "name": "New York Yankees", "abbreviation": "NYY"}}

# Handle abbreviations and cities
curl -X POST https://mlbstats-mcp.your-domain.workers.dev \
  -H "Content-Type: application/json" \
  -d '{
    "command": "resolve_team", 
    "params": {"name": "LAD"}
  }'

# Response: {"result": {"id": 119, "name": "Los Angeles Dodgers", "abbreviation": "LAD"}}

Resolve Player Names

# Resolve player by last name
curl -X POST https://mlbstats-mcp.your-domain.workers.dev \
  -H "Content-Type: application/json" \
  -d '{
    "command": "resolve_player",
    "params": {"name": "Ohtani"}
  }'

# Response: {"result": {"id": 660271, "name": "Shohei Ohtani", "team": "Los Angeles Dodgers"}}

⚾ Data Retrieval Examples

Get Team Information

{
  "command": "getTeamInfo",
  "params": {
    "queryParams": {
      "season": "2025",
      "sportId": "1"
    }
  }
}

Get Player Stats (with resolved player ID)

{
  "command": "getPlayerStats", 
  "params": {
    "pathParams": {
      "playerId": "592450"  // Aaron Judge (from resolve_player)
    },
    "queryParams": {
      "stats": "season",
      "group": "hitting",
      "season": "2025"
    }
  }
}

Get Team Roster (with resolved team ID)

{
  "command": "getRoster",
  "params": {
    "pathParams": {
      "teamId": "147"  // Yankees (from resolve_team)
    },
    "queryParams": {
      "season": "2025"
    }
  }
}

Get Schedule

{
  "command": "getSchedule",
  "params": {
    "queryParams": {
      "sportId": "1",
      "date": "2025-07-04",
      "teamId": "147"  // Optional: filter by resolved team
    }
  }
}

🔍 Error Handling Examples

Team Not Found

// Request: {"command": "resolve_team", "params": {"name": "Cowbays"}}
// Response: 
{
  "error": "Team \"Cowbays\" not found. Did you mean: cowboys, astros, royals?"
}

Player Not Found

// Request: {"command": "resolve_player", "params": {"name": "Jduge"}}
// Response:
{
  "error": "Player \"Jduge\" not found. Did you mean: judge?"
}

🚀 Integration with Sports-Proxy

When used with the enhanced sports-proxy, the workflow becomes seamless:

# User input: "Get the Yankees roster"
# 1. Sports-proxy detects MLB sport
# 2. Extracts tools: resolve_team("yankees"), get_team_roster({})
# 3. MLB MCP resolves: resolve_team → {id: 147}
# 4. Sports-proxy enriches: get_team_roster({teamId: "147"})
# 5. MLB MCP returns: Complete roster data

This eliminates the need for manual entity resolution and creates a natural language interface to MLB data!