pog-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,867 @@
+/**
+ * server — the Proof of Goal MCP surface.
+ *
+ * Design rule: every tool should be callable by an agent that has read nothing
+ * but the tool descriptions. The API is already agent-friendly over plain HTTP
+ * (see AGENTS.md); what MCP adds is that the agent no longer has to parse a
+ * runbook, hold a Solana keypair, or guess payload shapes. So descriptions here
+ * carry the CONSTRAINTS, not just the parameter names — a squad rejected for
+ * "212 points" is a wasted round-trip the schema could have prevented.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { ApiError, LEADERBOARD_MAX_LIMIT, PogClient } from './client.js';
+import { existsSync } from 'node:fs';
+import { addressFromMnemonic, isValidMnemonic, loadOrCreateWallet, readWallet, walletFilePath, } from './wallet.js';
+/** Positions the squad validator recognises. */
+const POSITIONS = ['GK', 'DF', 'DMF', 'OMF', 'FW'];
+/** Cup bracket stages, in the order they are played. */
+const CUP_STAGES = ['qualifier', 'group', 'r32', 'r16', 'qf', 'sf', '3rd', 'final'];
+/**
+ * Longest team name POST/PUT /api/teams accept. Declared here so the schema
+ * rejects an over-long name before the request, rather than the agent
+ * discovering it from a raw Fastify 400.
+ */
+const TEAM_NAME_MAX = 30;
+/**
+ * One squad player, in the FLAT shape POST /api/teams takes.
+ *
+ * Not the engine shape: the engine nests the SAME four names under `attrs`.
+ * (dori/shoo/defe are the Postgres column names only — team-store is the sole
+ * place that translation happens.) Both shapes exist here and mixing them is a
+ * documented trap, so this schema only ever describes the flat one.
+ */
+const PlayerSchema = z.object({
+    /**
+     * Identity, not position. PUT /api/teams/:id resolves each entry to the
+     * player currently in that slot unless a playerId says otherwise, so moving
+     * players between slots WITHOUT this silently rewrites whoever was already
+     * there — and for minted players it discards the submitted stats too. Zod
+     * strips unknown keys, so omitting it from the schema was the same as
+     * deleting it from every request.
+     */
+    playerId: z
+        .string()
+        .uuid()
+        .optional()
+        .describe('Existing player to place in this slot, from get_squad. Required when ' +
+        'rearranging an existing squad; omit for new players.'),
+    slotIndex: z
+        .number()
+        .int()
+        .min(0)
+        .max(10)
+        .describe('Squad slot 0-10. Each slot must appear exactly once across the 11 players.'),
+    name: z.string().min(1).max(10).describe('Display name, max 10 chars, unique within the squad'),
+    position: z.enum(POSITIONS).describe('Exactly one GK; at least one each of DF, DMF, OMF, FW'),
+    pass: z.number().int().min(1).max(10),
+    dribble: z.number().int().min(1).max(10),
+    shoot: z.number().int().min(1).max(10),
+    defense: z.number().int().min(1).max(10),
+    // Required by the route schema, not optional — an agent that omits them gets a
+    // raw Fastify validation error instead of a rule explanation.
+    // Defaulted, not required. Twenty-two booleans that are false on nine or ten
+    // of the eleven players is a lot of payload for an agent to emit correctly,
+    // and getting one wrong costs a whole rejected call — which is what happened
+    // the first time this surface was driven end to end.
+    isFkKicker: z
+        .boolean()
+        .default(false)
+        .describe('At least one player in the squad must be true. Omit for the rest.'),
+    isPkKicker: z
+        .boolean()
+        .default(false)
+        .describe('At least one player in the squad must be true. Omit for the rest.'),
+});
+/**
+ * The constraints POST /api/teams enforces, in the agent's own vocabulary.
+ *
+ * Every number here is asserted against packages/engine/src/validator.ts by
+ * `__tests__/gameFacts.test.ts` — an agent treats a tool description as fact and
+ * reasons on top of it, so a stale rule here does not merely cost a retry, it
+ * makes the agent rule out squads that are actually legal.
+ *
+ * The scarcity caps are TEAM-WIDE, not per player: a per-player cap would be
+ * dead code, since a player total of 29 already cannot hold four 10s.
+ */
+const SQUAD_RULES = [
+    'Exactly 11 players, with slotIndex 0-10 each used exactly once.',
+    'The four attributes across the whole squad must sum to exactly 212.',
+    'Each attribute is 1-10; each player total is 10-29.',
+    'Across the whole squad: at most 3 attributes equal to 10, and at most 5 equal to 8 or 9.',
+    'Exactly one GK, plus at least one each of DF, DMF, OMF, FW.',
+    'At least one free-kick taker (isFkKicker) and at least one penalty taker (isPkKicker) — ' +
+        'the same player may be both. Both default to false, so name the two you want and leave ' +
+        'them off everyone else.',
+    'Names are max 10 characters and unique within the squad.',
+].join(' ');
+/**
+ * Matches `catch_up` looks through by default. A cup day alone can produce
+ * seven, and the endpoint caps at 200; 50 covers a normal absence without
+ * spending the context of a full career.
+ */
+const DEFAULT_HISTORY_LIMIT = 50;
+/** Leaderboard rows returned when the caller does not ask for a number. */
+const DEFAULT_LEADERBOARD_ROWS = 20;
+/**
+ * Tool results are model-facing, so they are billed as context on every call.
+ * Compact JSON rather than indented: indentation is roughly a third of the bytes
+ * on the wide, shallow shapes this API returns (a 174-nation list, a 100-row
+ * board), and a model reads compact JSON just as reliably. The trade is
+ * human readability while debugging — pipe through `jq` when that matters.
+ */
+function ok(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value) }] };
+}
+function fail(err) {
+    // A rejection that says WHEN to come back is a schedule; one that does not is
+    // a reason to guess. The server names the moment on every 429 — as a header,
+    // and for the playoff cooldown as an exact timestamp — so pass it through
+    // instead of making the agent spend another call to rediscover it.
+    const timing = err instanceof ApiError
+        ? [
+            err.retryAt !== undefined ? `Try again at ${err.retryAt}.` : null,
+            err.retryAfterSeconds !== undefined && err.retryAt === undefined
+                ? `Try again in ${String(err.retryAfterSeconds)}s.`
+                : null,
+            err.remaining !== undefined ? `${String(err.remaining)} requests left this minute.` : null,
+        ]
+            .filter((p) => p !== null)
+            .join(' ')
+        : '';
+    const text = err instanceof ApiError
+        ? `API ${err.status} on ${err.path}: ${err.message}${timing ? ` ${timing}` : ''}`
+        : err instanceof Error
+            ? err.message
+            : String(err);
+    return { content: [{ type: 'text', text }], isError: true };
+}
+export function buildServer(opts = {}) {
+    const client = opts.client ?? new PogClient();
+    // Resolved lazily so constructing the server never writes a key to disk —
+    // tests and `--help` should not mint a wallet as a side effect.
+    let wallet = opts.wallet ?? null;
+    // Whether THIS process minted the key, kept rather than discarded.
+    //
+    // Creating a real Solana key is the single most consequential thing this
+    // server does, and it used to happen in silence: the operator got
+    // "Signed in." and no hint that a phrase now existed, where it was, or that
+    // losing it is terminal. A one-time notice is the only moment we get.
+    let mintedHere = false;
+    const getWallet = () => {
+        if (wallet === null) {
+            const loaded = loadOrCreateWallet();
+            wallet = loaded.wallet;
+            mintedHere = loaded.created;
+        }
+        return wallet;
+    };
+    const server = new McpServer({ name: 'proof-of-goal', version: '0.1.0' });
+    server.registerTool('login', {
+        title: 'Sign in to Proof of Goal',
+        description: 'Create or reuse this machine\'s Solana wallet and complete the Sign-In-With-Solana handshake. ' +
+            'Call this once before any tool that writes. Returns the wallet address and session expiry. ' +
+            'The recovery phrase is stored locally so the agent returns as the same manager after a restart.',
+        inputSchema: {},
+        // Not idempotent: each call burns a nonce, creates a new session row, and
+        // replaces the credential this client is holding. A client that retried a
+        // lost response would quietly invalidate the session it already had, and
+        // enough retries hit the auth route's per-minute limit.
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async () => {
+        try {
+            const w = getWallet();
+            const session = await client.login(w.mnemonic, w.address);
+            const created = mintedHere;
+            mintedHere = false; // say it once, not on every login of the process
+            return ok({
+                walletAddress: session.walletAddress,
+                expiresAt: session.expiresAt,
+                // Not a secret, and the operator cannot back up what they cannot find.
+                walletFile: walletFilePath(),
+                note: created
+                    ? `Signed in. A NEW recovery phrase was just created at ${walletFilePath()} — it is ` +
+                        'the only copy, and it owns this squad and anything it earns. Tell whoever you ' +
+                        'work for to back it up now: the file holds 12 words that import into Phantom or ' +
+                        'Solflare. Delete it and the account is gone; there is no reset. ' +
+                        'Squad and match tools are now available.'
+                    : 'Signed in. Squad and match tools are now available.',
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('whoami', {
+        title: 'Show this agent’s wallet and session',
+        description: 'Report the wallet address this server plays as and whether a session is currently held. ' +
+            'Never reveals the recovery phrase, and never creates a wallet — if none exists yet this ' +
+            'says so, and `login` is what creates one.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        try {
+            // Deliberately NOT getWallet(): that generates a phrase and writes it to
+            // disk. A tool advertised as readOnlyHint may be auto-approved by the
+            // client, and a real Solana key appearing as a side effect of asking
+            // "who am I" is not something the user consented to.
+            //
+            // POG_MCP_MNEMONIC wins here exactly as it does in login, and its
+            // address is DERIVED rather than read back from disk. Reporting the old
+            // file's address — or "no wallet" — while login is about to use a
+            // different one would have an operator fund or whitelist the wrong
+            // Solana account off a tool that presents itself as authoritative.
+            // VALIDATE before deriving. Seed derivation does not check the BIP39
+            // checksum, so a typo'd phrase still yields a perfectly well-formed
+            // address — and login, which does validate, then refuses the same value.
+            // Reporting that address as fundable is how an operator sends assets to
+            // an account nobody can ever sign for.
+            const imported = process.env['POG_MCP_MNEMONIC']?.trim();
+            const importValid = imported !== undefined && imported !== '' && isValidMnemonic(imported);
+            // A valid import is not the same as a SELECTED one. login refuses to
+            // replace a wallet already on this machine, so when the file holds a
+            // different phrase the imported address is the one address login will
+            // NOT use — and reporting it is how an operator funds an account this
+            // server can never sign for. Which was the whole point of deriving it
+            // here instead of reading the file: report what login will do.
+            const stored = readWallet();
+            // existsSync, not `stored !== null`: readWallet also returns null for a
+            // file it cannot parse, and login refuses on EXISTENCE — so a corrupt or
+            // truncated wallet made this report the imported address as fundable
+            // while login would not start at all. The same distinction the import
+            // path itself had to make.
+            const importConflicts = importValid && (stored?.mnemonic !== imported || stored === null)
+                ? existsSync(walletFilePath())
+                : false;
+            const w = wallet ?? (importValid && !importConflicts
+                ? { mnemonic: imported, address: addressFromMnemonic(imported) }
+                : stored);
+            const badImport = imported !== undefined && imported !== '' && !importValid;
+            const s = client.currentSession();
+            return ok({
+                walletAddress: w?.address ?? null,
+                hasWallet: w !== null,
+                // Where the phrase lives. The path is not a secret, and an agent that
+                // cannot name it cannot tell its operator what to back up.
+                walletFile: walletFilePath(),
+                signedIn: s !== null,
+                sessionExpiresAt: s?.expiresAt ?? null,
+                ...(badImport
+                    ? {
+                        note: 'POG_MCP_MNEMONIC is set but is not a valid BIP39 phrase — login will refuse ' +
+                            'it. Any address shown here comes from the wallet file, not from it.',
+                    }
+                    : importConflicts
+                        ? {
+                            note: 'POG_MCP_MNEMONIC is a valid phrase but a DIFFERENT wallet is already stored ' +
+                                'on this machine, so login REFUSES to run rather than replace it — that file ' +
+                                'is probably the only copy of a key holding a squad and assets. The address ' +
+                                'above is the stored one, which is what login would use if you unset the ' +
+                                'variable. To use the imported phrase instead, point POG_MCP_WALLET_FILE at ' +
+                                'another path.',
+                        }
+                        : w === null
+                            ? {
+                                note: existsSync(walletFilePath())
+                                    ? // Something IS there — corrupt, truncated, a FIFO — and login
+                                        // refuses to replace it rather than destroy a phrase it cannot
+                                        // read. Saying "login creates one" sent the operator to run the
+                                        // one command that cannot work, and hid the file that needs
+                                        // looking at. It may still contain the recovery phrase.
+                                        `${walletFilePath()} exists but cannot be read as a wallet, so login ` +
+                                            'refuses to start rather than replace it — it may still contain a ' +
+                                            'recovery phrase in plain text, so open it before doing anything else. ' +
+                                            'Move or delete it to start over, or point POG_MCP_WALLET_FILE elsewhere.'
+                                    : 'No wallet on this machine yet. login creates one.',
+                            }
+                            : {}),
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('get_game_rules', {
+        title: 'Game rules and squad constraints',
+        description: 'The rules a squad must satisfy, plus how the daily cup works. Read this before building a squad.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        // Whether friendlies age your players depends on the deployment: growth is
+        // only recorded when the FA market is enabled. Stating it unconditionally
+        // would scare an agent off the sample sizes it needs on a deployment where
+        // friendlies really are free.
+        // Fail to UNKNOWN, never to "free". Equating a failed lookup with OFF told
+        // the agent friendlies cost nothing while the friendly endpoint stayed up
+        // and tracking was actually on — and career_matches does not come back.
+        let growthTracked = null;
+        try {
+            const market = (await client.marketStatus());
+            growthTracked = market.marketEnabled === true;
+        }
+        catch {
+            growthTracked = null;
+        }
+        return ok({
+            squad: SQUAD_RULES,
+            cup: 'The PoG Cup opens daily at 04:00 UTC with a 48-team field: 12 groups of four, then ' +
+                'the top two of each group plus the eight best third-placed teams advance to a Round ' +
+                'of 32, then R16, quarter-finals, semi-finals, third-place playoff, and the final. ' +
+                'YOU DO NOT ENTER IT DIRECTLY. Entrants are auto-enrolled from DIVISION 1 of the ' +
+                'weekly playoff ladder and the rest of the field is filled with AI teams. A new squad ' +
+                'starts in the bottom division (4), and the top 3 of a division are promoted at the ' +
+                'end of each ISO week — so reaching the cup takes at least three good weeks of ' +
+                'play_playoff. Until then get_cup shows you other managers\u2019 matches, not yours; ' +
+                'do not wait for fixtures that are not coming. ' +
+                'A cup is created by the SCHEDULER, which is a separate process from this API. ' +
+                'Against a deployment running without it — a bare local server, for instance — no cup ' +
+                'is ever created and get_cup answers `cup: null` for every date forever. That is the ' +
+                'deployment, not a wait: play friendlies instead of checking again.',
+            simulation: 'Matches are simulated off-chain by a deterministic engine seeded per match, so the same match always replays identically. You do not control players during a match — the squad you build decides the outcome.',
+            currency: 'POG',
+            growthTracking: growthTracked === true
+                ? 'ON for asset-backed squads. If your players are player-asset-backed, every ' +
+                    'match — friendlies included — permanently increments their tenure and ' +
+                    'career_matches, and a higher career count lowers their remaining growth ' +
+                    'ceiling for good; budget friendlies rather than bulk-running them. A legacy ' +
+                    'squad with no player assets records nothing and is unaffected.'
+                : growthTracked === false
+                    ? 'OFF on this deployment. Friendlies cost nothing and can be run freely to ' +
+                        'measure a squad change.'
+                    : 'UNKNOWN — the market status could not be read. Assume it is ON and treat ' +
+                        'friendlies as costly: being wrong the other way permanently ages your ' +
+                        'players, and that cannot be undone.',
+        });
+    });
+    server.registerTool('list_nations', {
+        title: 'List selectable nations',
+        description: 'Nation codes accepted by create_squad. Nation is identity only — it does not affect player ability. ' +
+            'Returns code and name for every nation. Pass a nationCode to also get that nation’s ' +
+            'given-name and surname pools, which is what the game draws plausible player names from.',
+        inputSchema: {
+            nationCode: z
+                .string()
+                .length(3)
+                .optional()
+                .describe('FIFA 3-letter code. Narrows to one nation and includes its name pools.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ nationCode }) => {
+        try {
+            const { nations } = await client.nations();
+            if (nationCode) {
+                const wanted = nationCode.toUpperCase();
+                const hit = nations.find((n) => n.code.toUpperCase() === wanted);
+                if (!hit)
+                    return fail(new Error(`Unknown nation code "${nationCode}". Call list_nations with no argument to see valid codes.`));
+                return ok(hit);
+            }
+            // Project away the name pools and emit a code→name map. The raw payload
+            // is ~55 kB / ~14k tokens, nearly all of it names the agent did not ask
+            // for; a lookup map of the two fields that matter is ~4 kB. An agent that
+            // wants names asks for one nation.
+            return ok({
+                count: nations.length,
+                nations: Object.fromEntries(nations.map((n) => [n.code, n.name])),
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('create_squad', {
+        title: 'Create a squad',
+        description: `Register an 11-player squad for this agent's wallet. Requires login. ${SQUAD_RULES} ` +
+            'On rejection the error names the specific rule that failed, so fix and retry rather than guessing. ' +
+            'A wallet holds at most one squad — if you already have one, use update_squad instead.',
+        inputSchema: {
+            name: z
+                .string()
+                .min(1)
+                .max(TEAM_NAME_MAX)
+                .describe(`Team name — unique across all teams, at most ${String(TEAM_NAME_MAX)} characters`),
+            // Uppercased before it leaves here. list_nations accepts a lowercase code
+            // and says so, but the API compares this field case-sensitively — so
+            // "kor" passed every check on this side and came back "Unknown nation
+            // code". Two tools, one contract.
+            nationCode: z
+                .string()
+                .length(3)
+                .transform((code) => code.toUpperCase())
+                .describe('FIFA 3-letter code, e.g. KOR, BRA (see list_nations). Case-insensitive.'),
+            players: z.array(PlayerSchema).length(11),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async ({ name, nationCode, players }) => {
+        try {
+            return ok(await client.createTeam({ name, nationCode, players }));
+        }
+        catch (err) {
+            // The one-per-wallet guard answers 409 `{error:"team_exists", teamId}`.
+            // Left raw that reads as a dead end; it is really a redirect, and the id
+            // the agent needs is sitting in the body.
+            // Two DIFFERENT conflicts share status 409. Collapsing them tells an
+            // agent whose only problem was a duplicate team name to go call
+            // update_squad with a teamId it does not have — a dead end, when the fix
+            // was simply to pick another name.
+            if (err instanceof ApiError && err.status === 409) {
+                if (err.teamId !== undefined || /team_exists/i.test(err.message)) {
+                    const existing = err.teamId ?? '(see my_squads)';
+                    return fail(new Error(`This wallet already owns a squad (${existing}). A wallet holds at most one. ` +
+                        'Call update_squad with that teamId to change the lineup.'));
+                }
+                if (/TEAM_NAME_TAKEN/i.test(err.message)) {
+                    return fail(new Error(`The team name "${name}" is already used by another manager. Team names are unique ` +
+                        'across the whole game — retry create_squad with a different name. ' +
+                        'Your squad itself was fine.'));
+                }
+            }
+            return fail(err);
+        }
+    });
+    server.registerTool('update_squad', {
+        title: 'Replace a squad’s lineup',
+        description: 'Rewrite the lineup of a squad you own — this is how you iterate after a friendly. ' +
+            `Requires login. The same rules apply: ${SQUAD_RULES} ` +
+            'The edit applies to the next not-yet-simulated match; completed matches are never rewritten. ' +
+            'nationCode cannot change. ' +
+            'MINTED players are partly immutable, and the two halves fail differently. ' +
+            'Renaming one is REJECTED — the whole save fails with a 409, because the name is the ' +
+            'on-chain NFT\u2019s. Submitted position and attribute changes are IGNORED instead: the ' +
+            'persisted asset wins and the squad comes back looking like your edit applied when it ' +
+            'did not. Move a minted player by giving its playerId a different slotIndex; only ' +
+            'unminted players can be renamed or restatted.',
+        inputSchema: {
+            teamId: z.string().min(1).describe('A squad this agent owns — see my_squads'),
+            players: z.array(PlayerSchema).length(11),
+            name: z
+                .string()
+                .min(1)
+                .max(TEAM_NAME_MAX)
+                .optional()
+                .describe('Rename the team. Omit to keep the current name.'),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    }, async ({ teamId, players, name }) => {
+        try {
+            return ok(await client.updateTeam(teamId, { players, ...(name === undefined ? {} : { name }) }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('my_squads', {
+        title: 'List this agent’s squads',
+        description: 'Squads owned by the signed-in wallet. Requires login.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        try {
+            return ok(await client.myTeams());
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('catch_up', {
+        title: 'What happened since last time',
+        description: 'One call for everything about this manager: squads, league rank, playoff standing and ' +
+            'cooldown, finished matches with their results and timestamps, next fixture, honours, and ' +
+            'career record. Requires login. ' +
+            'Call this FIRST whenever you return to the game after any gap — cups run daily and finish ' +
+            'hours after they start, so results almost always land while you are away. ' +
+            'sinceIso MARKS, it does not filter: every match in the window comes back, each with ' +
+            'isNew relative to your cursor. Nothing is hidden because a cup or league match reports ' +
+            'its scheduled kickoff rather than when it actually finished, so a late result can carry ' +
+            'an old timestamp and arrive with isNew false. Track the matchIds you have processed and ' +
+            'skip those; do not rely on the timestamp alone.',
+        inputSchema: {
+            sinceIso: z
+                .string()
+                .optional()
+                .describe('ISO-8601 timestamp, usually the finishedAt of the newest match you saw last ' +
+                'session. Marks each match isNew relative to it; nothing is removed.'),
+            historyLimit: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe(`How many recent matches to look through. Defaults to ${String(DEFAULT_HISTORY_LIMIT)}, ` +
+                'at most 200 — a hard ceiling, since the history endpoint has no cursor. Results ' +
+                'older than the newest 200 cannot be reached through this tool at all.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ sinceIso, historyLimit }) => {
+        try {
+            const snapshot = (await client.dashboard());
+            // The dashboard's own teamHistory is capped at five rows — fewer than a
+            // single cup day produces — so an agent returning after a cup would
+            // silently lose the older half of what it came back to read. Re-fetch
+            // the history from the endpoint that paginates.
+            const teamId = snapshot.teamHistory?.teamId ?? (snapshot.teams?.teams ?? [])[0]?.teamId ?? null;
+            // A null teamId means "no squad" ONLY if the dashboard could actually
+            // look. Its team read can time out, and treating that as absence told an
+            // agent its squad and history had vanished — and invited it to create
+            // another one.
+            const teamLookupFailed = typeof snapshot.teams?.error === 'string' ||
+                typeof snapshot.teamHistory?.error === 'string';
+            const squadUnknown = teamId === null && teamLookupFailed;
+            const limit = historyLimit ?? DEFAULT_HISTORY_LIMIT;
+            let fetched = null;
+            let historyError = null;
+            if (teamId !== null) {
+                try {
+                    fetched = await client.teamHistory(teamId, limit);
+                }
+                catch (err) {
+                    fetched = null;
+                    historyError = err instanceof Error ? err.message : String(err);
+                }
+            }
+            // The dashboard's copy of history is a FALLBACK, and a thinner one: its
+            // rows carry neither resultBasis nor shootoutPossible. The note below
+            // tells agents to tell a definitive group draw from a possible shootout
+            // using exactly those fields, so serving these rows silently would have
+            // them answer that question from a row that never said.
+            const usedFallback = fetched === null && (snapshot.teamHistory?.matches?.length ?? 0) > 0;
+            const all = (fetched?.matches ?? snapshot.teamHistory?.matches ?? []).map(
+            // Standings are re-reported per row and dominate the payload; rank is
+            // already in `playoff`/`leaderboard` at the top level.
+            ({ teamLeagueStanding: _t, opponentLeagueStanding: _o, ...keep }) => keep);
+            const cutoff = sinceIso === undefined ? null : Date.parse(sinceIso);
+            if (cutoff !== null && Number.isNaN(cutoff)) {
+                return fail(new Error(`sinceIso is not a valid timestamp: "${sinceIso}"`));
+            }
+            // The cursor MARKS matches; it does not drop them.
+            //
+            // `finishedAt` is the completion time only for playoff matches — for cup
+            // and league ones the API reports the scheduled kickoff (playoff.ts:
+            // `m.finalizedAt ?? m.kickoffAt`), and no completion time is persisted
+            // for them at all. So a match finished late carries a timestamp that can
+            // sit behind any cursor, by any margin: a fixed lookback just moves the
+            // outage length at which results start vanishing.
+            //
+            // Since this side cannot know completion order, it does not pretend to.
+            // Every match in the window is returned with `isNew` relative to the
+            // cursor. Showing a result twice costs an agent nothing; never showing it
+            // loses the only reason it had to change the squad.
+            //
+            // Which is why the note tells agents to de-duplicate by matchId rather
+            // than to trust this flag: a late-finished match is marked isNew:false
+            // by exactly the timestamp problem described above, so an agent that
+            // filtered on it would throw away the results this window was widened to
+            // keep. The flag is a hint about the timestamp, not a claim about what
+            // the agent has seen.
+            const matches = all.map((m) => ({
+                ...m,
+                ...(cutoff === null ? {} : { isNew: Date.parse(m.finishedAt) > cutoff }),
+            }));
+            const newCount = cutoff === null ? all.length : matches.filter((m) => m.isNew).length;
+            return ok({
+                ...snapshot,
+                teamHistory: { teamId, matches },
+                history: {
+                    ...(sinceIso === undefined
+                        ? {}
+                        : {
+                            sinceIso,
+                            newCount,
+                            note: 'finishedAt is the scheduled kickoff for cup and league matches, not the ' +
+                                'completion time, so a late-finished match can carry a timestamp older than ' +
+                                'your cursor — and is then marked isNew:false even though you have never ' +
+                                'seen it. Nothing is filtered out, so decide what is unseen by MATCHID ' +
+                                'against the ones you have already processed; isNew is a timestamp hint, ' +
+                                'not the answer. Acting on it alone discards exactly the late results this ' +
+                                'unfiltered window exists to preserve. ' +
+                                'This window is the newest `limit` matches and there is no way to page ' +
+                                'past it, so after an absence of more than that many matches the older ' +
+                                'ones are gone — raise historyLimit (max 200) and visit more often. ' +
+                                'Each result comes from the recorded score (resultBasis), which already ' +
+                                'includes extra-time goals but NOT a shootout. Only a D on a row with ' +
+                                'shootoutPossible:true can be hiding one — knockout ties, and friendlies ' +
+                                'played without allowDraw. On shootoutPossible:false (cup GROUP matches, and ' +
+                                'friendlies that asked for draws) a D is a real draw: do not spend a ' +
+                                'get_match on it, and do not discount it as undecided.' +
+                                (usedFallback
+                                    ? ' THESE ROWS ARE THE FALLBACK COPY and carry neither field, so every D ' +
+                                        'here is unresolved: check get_match before drawing any conclusion from ' +
+                                        'one, or call catch_up again once the history endpoint answers.'
+                                    : ''),
+                        }),
+                    returned: matches.length,
+                    fetched: all.length,
+                    limit,
+                    // Three states, not two. A full page means older matches exist
+                    // beyond this window; a FAILED fetch means there may be more we
+                    // could not see, and saying false there is the one answer that
+                    // stops an agent from retrying. But a manager with NO SQUAD has
+                    // nothing to fetch — reporting that as truncated would have it
+                    // retry forever against an empty career.
+                    mayHaveMore: squadUnknown ? true : teamId === null ? false : fetched === null ? true : all.length >= limit,
+                    source: squadUnknown
+                        ? 'unknown — the dashboard could not read your teams'
+                        : teamId === null
+                            ? 'no squad yet'
+                            : fetched === null
+                                ? 'dashboard (capped at 5)'
+                                : 'team history',
+                    ...(squadUnknown
+                        ? {
+                            warning: 'The dashboard could not read your teams, so this cannot tell whether you ' +
+                                'have a squad. Do NOT create another one on the strength of this — call ' +
+                                'catch_up again, or my_squads.',
+                        }
+                        : historyError === null || teamId === null
+                            ? {}
+                            : {
+                                warning: `Match history could not be read (${historyError}), so this shows only the ` +
+                                    'five rows the dashboard carries. A cup day produces more than that — ' +
+                                    'call catch_up again before concluding anything from it.',
+                            }),
+                },
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('get_squad', {
+        title: 'Read any squad',
+        description: 'Public squad details by id — use it to scout an opponent before a friendly.',
+        inputSchema: { teamId: z.string().min(1) },
+        annotations: { readOnlyHint: true },
+    }, async ({ teamId }) => {
+        try {
+            return ok(await client.team(teamId));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('play_friendly', {
+        title: 'Play a friendly match',
+        description: 'Simulate a friendly between two squads and return the result with its event stream. ' +
+            'Instant, and moves no standing. Requires login, and homeTeamId must be a squad you own. ' +
+            'MAY NOT BE FREE: where growth tracking applies, each friendly permanently increments ' +
+            'tenure and career_matches for all eleven players on YOUR side (the away squad is ' +
+            'untouched), and a higher career count lowers a player’s remaining growth ceiling for ' +
+            'good. Check get_game_rules → growthTracking before bulk-running friendlies to chase ' +
+            'statistical confidence; when it reports OFF they really are free. ' +
+            'By DEFAULT a level score goes to penalties and someone wins — pass allowDraw=true if ' +
+            'you want draws to stay draws, which is what you usually want when comparing squads.',
+        inputSchema: {
+            homeTeamId: z.string().min(1).describe('Your own squad — see my_squads'),
+            awayTeamId: z.string().min(1).describe('Any other squad — see get_leaderboard or get_cup'),
+            allowDraw: z
+                .boolean()
+                .optional()
+                .describe('Defaults to FALSE: a level score is decided by penalties unless you pass true.'),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async ({ homeTeamId, awayTeamId, allowDraw }) => {
+        try {
+            return ok(await client.playFriendly({
+                homeTeamId,
+                awayTeamId,
+                ...(allowDraw === undefined ? {} : { allowDraw }),
+            }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('play_playoff', {
+        title: 'Play a ranked playoff match',
+        description: 'Play one match on the weekly playoff ladder. Requires login and a squad. ' +
+            'Unlike a friendly this COUNTS: it moves you up or down the ladder, and promotion or ' +
+            'relegation between divisions is decided by where you finish the week. ' +
+            'Your first call also enters you onto the ladder — until you make it you are not in the ' +
+            'competitive season at all. The server picks the opponent. ' +
+            'One match per 5 MINUTES per squad — that is the floor, and calling faster is answered ' +
+            '429, not queued. If you run on a schedule, once an hour is the recommended default ' +
+            '(24 ranked matches a day); every 5 minutes is the fastest the server allows. Take the ' +
+            'next allowed moment from catch_up, which reports playoff.cooldown.nextMatchAt, rather ' +
+            'than from a fixed timer.',
+        inputSchema: {},
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async () => {
+        try {
+            return ok(await client.playPlayoff());
+        }
+        catch (err) {
+            // Two different things answer 429 here: the ladder cooldown, and the
+            // generic per-wallet rate limiter that guards every route. Telling an
+            // agent to wait for playoff.cooldown.nextMatchAt when it actually just
+            // sent too many requests points it at a timestamp that will never
+            // explain the rejection.
+            if (err instanceof ApiError && err.status === 429) {
+                const isCooldown = /cooldown/i.test(err.message);
+                // Re-thrown as an ApiError, not a bare Error, so fail() can still
+                // append the timing the server sent. Wrapping it in `new Error` threw
+                // that away and left the advice "call catch_up and read nextMatchAt" —
+                // a whole extra round trip to learn what this rejection already said.
+                return fail(new ApiError(err.status, err.path, isCooldown
+                    ? `${err.message} You are on cooldown between playoff matches. ` +
+                        'Friendlies are rate-limited separately and do not affect the ladder.'
+                    : `${err.message} This is the request rate limit, not the ladder cooldown — ` +
+                        'slow down and retry shortly.', undefined, {
+                    ...(err.retryAfterSeconds !== undefined
+                        ? { retryAfterSeconds: err.retryAfterSeconds }
+                        : {}),
+                    ...(err.retryAt !== undefined ? { retryAt: err.retryAt } : {}),
+                    ...(err.remaining !== undefined ? { remaining: err.remaining } : {}),
+                }));
+            }
+            return fail(err);
+        }
+    });
+    server.registerTool('get_match', {
+        title: 'Read a match',
+        description: 'Match result and ordered event stream by id. Replays are deterministic.',
+        inputSchema: { matchId: z.string().min(1) },
+        annotations: { readOnlyHint: true },
+    }, async ({ matchId }) => {
+        try {
+            return ok(await client.match(matchId));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('get_cup', {
+        title: 'Read a daily cup',
+        description: 'Result and fixtures for a cup date (YYYY-MM-DD, UTC). The cup opens at 04:00 UTC. ' +
+            'Without a stage you get the champion, the final score, and how many matches each stage ' +
+            'holds. Pass a stage to get those fixtures with their teamIds and scores — a full cup is ' +
+            '104 matches, so they are not all returned at once.',
+        inputSchema: {
+            date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+            stage: z
+                .enum(CUP_STAGES)
+                .optional()
+                .describe('qualifier (a mini-league that only runs when more than 48 teams enter), ' +
+                'group, r32, r16, qf, sf, 3rd, or final.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ date, stage }) => {
+        try {
+            // "There was no cup that day" is an ANSWER, not a failure. The summary
+            // endpoint 404s whenever the bracket is missing — a date that never ran,
+            // a day still ahead, or a deployment with no scheduler at all — and
+            // surfacing that as an MCP error had the agent read a settled fact as a
+            // transient outage and retry it forever. Non-404s still propagate: those
+            // really are outages.
+            let summary = null;
+            try {
+                summary = await client.cup(date);
+            }
+            catch (err) {
+                if (!(err instanceof ApiError) || err.status !== 404)
+                    throw err;
+            }
+            if (summary === null) {
+                return ok({
+                    date,
+                    cup: null,
+                    fixtures: null,
+                    note: 'No cup on this date. Either it never ran (a date before this deployment, or one ' +
+                        'still ahead), or nothing creates cups here — they come from the SCHEDULER, a ' +
+                        'separate process from this API. Check another date before concluding anything; ' +
+                        'if every date answers this, the scheduler is not running and no amount of ' +
+                        'waiting will change it.',
+                });
+            }
+            // The cup endpoint has no fixtures in it at all, despite the tool being
+            // the obvious place an agent looks for opponents. Read the bracket too.
+            //
+            // Only a 404 means "this cup has no bracket" — a pending cup, a date
+            // that never ran. Anything else is an outage, and swallowing it would
+            // report a completed cup as having no inspectable fixtures, so the agent
+            // moves on instead of retrying.
+            let bracket = null;
+            try {
+                bracket = await client.cupBracket(date);
+            }
+            catch (err) {
+                if (!(err instanceof ApiError) || err.status !== 404)
+                    throw err;
+            }
+            if (bracket === null) {
+                return ok({
+                    ...summary,
+                    fixtures: null,
+                    note: 'No bracket for this cup — it has not been drawn yet.',
+                });
+            }
+            // `matchIds` repeats every matches[].matchId — pure duplication on a
+            // surface where the response is billed as context.
+            const { matchIds: _ignored, matches, ...rest } = bracket;
+            const stages = {};
+            for (const m of matches)
+                stages[m.matchType] = (stages[m.matchType] ?? 0) + 1;
+            if (stage === undefined) {
+                return ok({
+                    ...summary,
+                    ...rest,
+                    stages,
+                    note: 'Call again with a stage to get those fixtures.',
+                });
+            }
+            return ok({
+                ...summary,
+                stage,
+                stages,
+                matches: matches.filter((m) => m.matchType === stage),
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool('get_leaderboard', {
+        title: 'Read the leaderboard',
+        description: 'Current standings across managers, best first. A row\u2019s topTeamId is the squad id to ' +
+            'pass as awayTeamId in play_friendly. Rows whose team has since been deleted carry ' +
+            'topTeamId null and playable:false — skip those. ' +
+            'Returns the top 20 by default. For your OWN rank use catch_up, which reports it directly ' +
+            'however far down the board you are.',
+        inputSchema: {
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(LEADERBOARD_MAX_LIMIT)
+                .optional()
+                .describe(`How many rows from the top. Defaults to 20, at most ${String(LEADERBOARD_MAX_LIMIT)}.`),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ limit }) => {
+        try {
+            // Ask for exactly what was requested. The API enriches every returned
+            // row through teamStore.getTeam, so always pulling the 500-row maximum
+            // would turn a routine top-20 question into 500 team lookups.
+            const want = limit ?? DEFAULT_LEADERBOARD_ROWS;
+            const fetched = await client.leaderboard(want);
+            // A deleted team leaves its manager on the board with topTeamId null.
+            // Marking those rows keeps the promise that topTeamId is a usable
+            // opponent — an agent that picks one otherwise gets rejected locally
+            // for a reason the board never mentioned.
+            const rows = fetched.map((r) => r.topTeamId === null ? { ...r, playable: false } : r);
+            // A full page means the board did not end here — it is a window, not a
+            // population. Reporting rows.length as a total would tell an agent the
+            // game has exactly 20 managers.
+            return ok({
+                rows,
+                returned: rows.length,
+                requested: want,
+                mayHaveMore: rows.length >= want,
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map