Skip to content

MCP_QUICKSTART.md

Latest commit

 

History

History
217 lines (166 loc) · 9.12 KB

MCP_QUICKSTART.md

File metadata and controls

217 lines (166 loc) · 9.12 KB
Raw

CourtVision MCP -- Quickstart (zero to connected)

Repository layout note (2026-09-17). The public repository is the evidence surface: the analytics site, the documentation, the evidence artifacts, the eval gate and the sport-blind kernel. The production engine, adapters, API, operational tooling and bulk corpora (src/, api/, domains/, most of scripts/ and tests/, data/) are kept in a private repository; reviewers can request read access. A path cited below that is not in this tree resolves there at tag pre-minimize-2026-09-17.

The MCP server itself ships with the private distribution (it reads the private data lake and resolver ledgers). This page documents its interface and contract.

Connect the CourtVision fail-closed sports-intelligence MCP server to Claude in under five minutes. You need a Claude subscription (Claude Code CLI or Claude Desktop) and Python 3.10+.

The server is a read-only oracle: every answer is a typed envelope with status (ok / no_data / not_supported / refused), a source_artifact, and an as_of timestamp. It never answers from model memory and never claims a dollar edge -- an honest NO_DATA is a correct answer, not a failure. See docs/AI_CONSUMER_CONTRACT.md.

Replace <REPO_ROOT> below with the absolute path to your clone (e.g. C:\Users\you\nba-ai-system or /home/you/nba-ai-system).

0. Fastest path -- remote connector (no clone, no install)

When the hosted endpoint is live, you can skip everything below: add it to claude.ai as a custom connector (Settings > Connectors > Add custom connector) using the URL published on the site's Ask page:

https://<current-tunnel-host>.trycloudflare.com/mcp

Same nine tools, same fail-closed envelopes, served over the MCP streamable-HTTP transport (scripts/platformkit/mcp_server/http_server.py). The URL rotates per hosting session -- if it does not respond, fall back to the local install below or ask for a fresh link.

1. Clone + Python env

git clone <this-repo-url> nba-ai-system
cd nba-ai-system
python --version            # must be 3.10 or newer

# minimal deps the server actually uses (the repo already pins these):
python -m pip install pandas numpy
# optional: pyarrow -- only for the parquet-backed tools, which are NO_DATA
# on a fresh clone anyway (see section 6). Skip it for the demo.

The server process itself imports only the Python standard library -- it starts with zero third-party deps. pandas/numpy are pulled lazily the first time you call a data tool. No compiler, no GPU, no network needed to launch it.

Sanity-check it runs (Ctrl-C to exit -- it waits on stdin):

python -m scripts.platformkit.mcp_server.server

If that prints nothing and blocks, it is working (it is a stdio JSON-RPC loop).

2. Claude Code (CLI)

One command from inside the repo root:

claude mcp add courtvision --env PYTHONPATH=. -- python -m scripts.platformkit.mcp_server.server

Or drop this .mcp.json at <REPO_ROOT>/.mcp.json (already checked in -- Claude Code auto-loads it when you launch claude from the repo root):

{
  "mcpServers": {
    "courtvision": {
      "command": "python",
      "args": ["-m", "scripts.platformkit.mcp_server.server"],
      "env": { "PYTHONPATH": "." }
    }
  }
}

PYTHONPATH=. lets python -m scripts... resolve the package; launch claude from <REPO_ROOT> so the relative path anchors correctly (see the cwd troubleshooting row). Verify with /mcp inside Claude Code -- courtvision should list 9 tools.

3. Claude Desktop

Edit claude_desktop_config.json (create it if absent):

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Desktop does not inherit a working directory, so pin cwd to the repo root:

{
  "mcpServers": {
    "courtvision": {
      "command": "python",
      "args": ["-m", "scripts.platformkit.mcp_server.server"],
      "cwd": "<REPO_ROOT>",
      "env": { "PYTHONPATH": "." }
    }
  }
}

On Windows, if python is not on PATH, set "command" to your full interpreter path (e.g. C:\\Users\\you\\miniconda3\\python.exe, doubled backslashes). Restart Claude Desktop; the tools appear under the plug/tools icon.

4. First 5 questions (with expected envelope shapes)

Ask these in plain English. The model routes each through a CourtVision tool and must quote the envelope verbatim. Shapes below are real outputs.

1. Atlas card (works on a bare clone -- reads a committed manifest):

"Show the CourtVision atlas card for LeBron James."

{ "status": "ok", "category": "atlas_card", "sport": "nba",
  "source_artifact": "scripts/platformkit/analytics_showcase/out/atlas_nba_manifest.json",
  "as_of": "..." }

2. Refusal (edge/ROI language is refused by contract) -- shows the guardrail:

"What's the ROI of your best bets?"

{ "status": "refused", "category": "edge_language",
  "source_artifact": ".claude/rules/no-edge-claims.md" }

The model must refuse and cite the rule -- it will NOT invent a profit number.

3. Deliberate NO_DATA (fail-closed honesty) -- an unbuilt store on a clone:

"What's the latest injury report for the Lakers?"

{ "status": "no_data", "category": "edge_facts_injury_report", "sport": "nba",
  "source_artifact": "data/cache/edge_engine/injury_facts_nba.jsonl",
  "note": "fact store not built in this clone" }

This is the point of the system: no fresh artifact -> it says NO_DATA and names the missing file, instead of hallucinating an injury list.

4. Win probability (calibrated number, not a market claim):

"Calibrated win probability, Lakers home vs Celtics."

{ "status": "ok"|"no_data", "category": "prediction_winprob", "sport": "nba",
  "p_home_win": 0.xx, "source_artifact": "...", "as_of": "..." }

Returns no_data on a bare clone (Elo corpora live under gitignored data/).

5. Analytics receipts (verified-claims ledger):

"Show the CourtVision claim-survival receipts."

{ "status": "ok"|"no_data", "category": "analytics_receipts",
  "source_artifact": "data/cache/analytics_verify/claim_survival.json", "as_of": "..." }

Every answer names a source_artifact and as_of. If one doesn't, it's non-compliant -- re-ask.

5. Troubleshooting

Symptom Cause Fix
python: command not found / server won't start Python not on PATH Install Python 3.10+; on Desktop set "command" to the full interpreter path (Windows: doubled backslashes).
Every tool returns a uniform no_data Launched with the wrong cwd, so relative data roots miss Launch claude from <REPO_ROOT> (CLI), or set "cwd": "<REPO_ROOT>" (Desktop). PYTHONPATH=. alone does not set cwd.
ModuleNotFoundError: scripts... PYTHONPATH not set, or not run as a module Keep "env": {"PYTHONPATH": "."} and the -m scripts.platformkit.mcp_server.server form; run from repo root.
ModuleNotFoundError: pandas / numpy on a data question Deps not installed python -m pip install pandas numpy (the server launches without them; data tools need them).
courtvision absent from /mcp or the tools icon Config not picked up CLI: confirm .mcp.json is at repo root and you launched from there. Desktop: fully restart the app after editing the config.
A tool takes minutes / hits the network You invoked run_burst That's the one write/network tool. For a read-only status use system_health, or pass skip_slow=true to run_burst.

6. What ships in the clone vs. what stays NO_DATA (honest)

The public repo commits code + a few JSON manifests, not the private data lake. So a fresh clone is a working server with mostly empty shelves -- and it tells you so, per tool, instead of faking it.

Works on a bare clone (committed artifacts):

  • atlas_card questions via ask -- reads committed analytics_showcase/out/*_manifest.json.
  • mechanism_effect questions -- reads committed domains/*/knowledge ledgers.
  • Any refused path (edge/ROI/retracted-number language) -- reads committed .claude/rules/.
  • system_health -- returns status: ok with each block honestly no_data.

Returns NO_DATA on a bare clone (data lives under gitignored data/ + vault/):

  • scouting_report, comparables -- need data/cache/profiles/*.parquet.
  • injury_report -- needs data/cache/edge_engine/injury_facts_*.jsonl.
  • analytics_receipts -- needs data/cache/analytics_verify/*.json.
  • win_probability, most ask stat/ranking/prediction categories -- need data/domains/*.parquet and Elo corpora.
  • matchup_preview -- overall status: ok, but its sub-blocks report blocks_absent for the missing data pieces.

This is by design: the demo proves the fail-closed contract (honest NO_DATA beats a confident guess). To light up the data tools you must build or sync the local data/ lake -- which is intentionally not part of the public clone.

See also: docs/AI_CONSUMER_CONTRACT.md (envelope rules) - .claude/rules/no-edge-claims.md (private repository) (why nothing here claims a dollar edge).