mcp-yahoo-fantasy: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

A single MCP (Model Context Protocol) server, in yahoo/, that wraps the Yahoo Fantasy Sports API for read and write access across NFL/NHL/NBA/MLB. It is a uv-managed Python 3.12 package. (The repo previously held an NHL server too; that has been removed and the project is now Yahoo-only.)

Commands

Run from the repo root unless noted.

• Install deps: ./scripts/setup.sh (wraps cd yahoo && uv sync).
• One-time Yahoo login: cd yahoo && uv run yahoo-login --client-id <id> --client-secret <secret> (out-of-band OAuth: open the printed URL, approve, paste back the verifier code). Writes credentials to .env in the working directory. Flags fall back to env vars / .env / prompt.
• Run the server: cd yahoo && uv run yahoo (stdio transport).
• Debug with the MCP Inspector: ./scripts/debug.sh.
• Add a dependency: cd yahoo && uv add <pkg> (keeps pyproject.toml + uv.lock in sync).
• Sanity-check tool registration without credentials: cd yahoo && uv run python -c "import asyncio; from yahoo.server import mcp; print(len(asyncio.run(mcp.list_tools())))"

Environment note: uv lock/uv sync need network; in a sandboxed shell run them with the sandbox disabled. Redirecting command output to /tmp also fails under the sandbox.

There is no automated test suite. Live behavior can only be exercised with real Yahoo credentials (a .env written by yahoo-login); without them the server starts and lists tools but tool calls raise a credentials error.

Architecture

Built on FastMCP (mcp.server.fastmcp). Three modules under src/yahoo/, each a deep layer hiding one concern:

• server.py — the FastMCP("yahoo") instance and ~29 @mcp.tool() functions. Tools are intentionally thin: resolve args, call one client method, return the result. They return yahoo_fantasy_api's plain dicts/lists, which FastMCP serializes to JSON for the model. Each tool's docstring IS its description shown to the model, so keep them accurate.
• client.py — YahooClient, the single seam over yahoo_fantasy_api. It owns the OAuth session (lazy), caches Game/League objects, and resolves defaults: an omitted league_key falls back to $YAHOO_LEAGUE_KEY; an omitted team_key falls back to the authenticated user's own team (League.team_key()). A module-level client singleton is shared by all tools.
• auth.py — the OAuth2 bridge plus .env helpers. yahoo_fantasy_api reads credentials via yahoo_oauth's oauth2.json. auth.session() calls load_env_file() (loads .env into the environment without clobbering real vars), then bridges $YAHOO_CONSUMER_KEY/ SECRET (+ token vars) into a oauth2.json and returns a token-refreshed OAuth2. Credential source priority: existing oauth2.json -> .env/env vars. The bridged file is written to ~/.config/yahoo-fantasy-mcp/oauth2.json (override path with $YAHOO_OAUTH_FILE or dir with $YAHOO_MCP_CONFIG_DIR); .env defaults to ./.env (override $YAHOO_ENV_FILE).
• login.py — the yahoo-login CLI (a [project.scripts] entry point). Runs yahoo_oauth's out-of-band OAuth flow (OAuth2(..., browser_callback=False, store_file=False)), then write_env()s the resulting client id/secret + access/refresh tokens to .env and deletes any stale oauth2.json so the server re-bridges from the fresh .env.