@battlegrid/mcp-server 31.2.13 → 31.2.15

package/README.md

@@ -413,6 +413,58 @@ refuse is now stored. Listed because a client that special-cased the refusal can
   a stored result" and "the signal did not fire" are different states, and leaving the key off that
   arm makes conflating them a type error rather than a convention.
 
+### Additive in the same span
+
+- **Two tools join the catalog for the agent trade flow** (52.1.0, `add-mcp-agent-trade-flow`).
+  `scan_agent_coins` evaluates every active coin against one of your agents in a single call and
+  returns them server-ranked, on the same use case, buckets and ranking the app's own TRADE-tab scan
+  serves. `propose_entry_decision` runs the conversational trade turn headlessly for one (agent,
+  coin) and returns its terminal in the stream's own vocabulary: `type: recommendation` carrying the
+  PROPOSED `TradingEntryDecisionDTO` row that `get_entry_decision` and `list_pending_approvals`
+  already publish, `type: no_trade`, or `type: error` carrying the turn's `TradeConvError` verbatim.
+  Nothing narrows and no existing schema hash moves; the 12-ticker `get_agent_coin_qualification`
+  stays as the spot-check probe.
+
+  **`idempotencyKey` is REQUIRED on `propose_entry_decision`** — it is the turn's own key, and a
+  same-key retry replays the recorded terminal rather than paying for a second inference. That
+  includes a post-billing `LLM_FAILURE`, which is returned as a value for precisely that reason.
+  Pre-engine faults are typed errors instead: `RATE_LIMITED`, `NOT_FOUND`, `CONFLICT` for a same-key
+  call still in flight, and `SERVICE_UNAVAILABLE` when the surface is switched off. Both tools
+  refuse with `RATE_LIMITED` carrying `retryAfterSeconds` under the same per-(user, agent) limit the
+  app itself enforces, so a scan is never served stale or partial.
+
+- **`get_regime_snapshot` publishes the evidence behind the verdict** (47.1.0,
+  `publish-regime-classification-evidence`). The snapshot gains `evidence`: the quantities the
+  classifier read, the gates it tested them against, the signed margin to the gate deciding whether
+  the current label survives, and the two decision facts only the classifier holds — `gateState`
+  (`cleared` / `held` / `dropped`) and `directionSource` (`di` / `ema`). Nothing narrows; a client
+  that ignores the field is unaffected.
+
+  Read `gateState` before you trust a trend label: **`held` means the ADX hysteresis buffer is
+  carrying the PREVIOUS bar's label rather than this bar re-confirming it** — a materially weaker
+  claim wearing the same word, and one no client could previously detect. `directionSource: 'ema'`
+  is the same shape of warning: the direction came from the fallback that fires precisely when the
+  DI spread is indecisive. The margin is signed so **positive always means "the current label
+  survives by this much"**, in every gate state, so it is safe to branch on its sign.
+
+  `conviction` is a BRANCH DISCRIMINATOR, not a confidence: it encodes *which* rule in the priority
+  ladder matched, not how comfortably it matched. The margins carry comfort. A client reading
+  conviction as a strength score is reading it wrong, and always was — this release just makes the
+  alternative available.
+
+- **Thirteen metric keys join the catalog** (47.1.0) — the `regime` family gains `REGIME_STATE`,
+  `REGIME_CONVICTION`, `REGIME_RUN_BARS`, `REGIME_TREND_GATE`, `REGIME_TREND_MARGIN`,
+  `REGIME_TREND_SOURCE`, `REGIME_DI_SPREAD`, `REGIME_VOL_ATR_RATIO`, `REGIME_VOL_BBW_RATIO`,
+  `REGIME_MOM_BULL_VOTES`, `REGIME_MOM_BEAR_VOTES`, `REGIME_CRASH_MARGIN` and `REGIME_CRASH_LATCH`,
+  making the composite regime and its evidence addressable in a report column or condition for the
+  first time. Only a client that switches exhaustively on `MetricKey` needs new branches.
+
+  Not a contract change, but worth knowing if you author conditions: the report grammar's regime
+  metrics now resolve from the **confirmed close** on every path. They previously resolved from the
+  forming bar when a report was rendered and the confirmed close when the scan swept, so the same
+  condition could read differently in preview than in production. Same wire shape; same bar
+  everywhere now.
+
 ## Contract history — v12 → v36
 
 > **The number in this heading is a CONTRACT version, not this package's version.** The npm badge at the top
@@ -565,38 +617,6 @@ Nothing in the proxy changes. No configuration, no environment variable, no call
 
 ### Additive in the same span
 
-- **`get_regime_snapshot` publishes the evidence behind the verdict** (47.1.0,
-  `publish-regime-classification-evidence`). The snapshot gains `evidence`: the quantities the
-  classifier read, the gates it tested them against, the signed margin to the gate deciding whether
-  the current label survives, and the two decision facts only the classifier holds — `gateState`
-  (`cleared` / `held` / `dropped`) and `directionSource` (`di` / `ema`). Nothing narrows; a client
-  that ignores the field is unaffected.
-
-  Read `gateState` before you trust a trend label: **`held` means the ADX hysteresis buffer is
-  carrying the PREVIOUS bar's label rather than this bar re-confirming it** — a materially weaker
-  claim wearing the same word, and one no client could previously detect. `directionSource: 'ema'`
-  is the same shape of warning: the direction came from the fallback that fires precisely when the
-  DI spread is indecisive. The margin is signed so **positive always means "the current label
-  survives by this much"**, in every gate state, so it is safe to branch on its sign.
-
-  `conviction` is a BRANCH DISCRIMINATOR, not a confidence: it encodes *which* rule in the priority
-  ladder matched, not how comfortably it matched. The margins carry comfort. A client reading
-  conviction as a strength score is reading it wrong, and always was — this release just makes the
-  alternative available.
-
-- **Thirteen metric keys join the catalog** (47.1.0) — the `regime` family gains `REGIME_STATE`,
-  `REGIME_CONVICTION`, `REGIME_RUN_BARS`, `REGIME_TREND_GATE`, `REGIME_TREND_MARGIN`,
-  `REGIME_TREND_SOURCE`, `REGIME_DI_SPREAD`, `REGIME_VOL_ATR_RATIO`, `REGIME_VOL_BBW_RATIO`,
-  `REGIME_MOM_BULL_VOTES`, `REGIME_MOM_BEAR_VOTES`, `REGIME_CRASH_MARGIN` and `REGIME_CRASH_LATCH`,
-  making the composite regime and its evidence addressable in a report column or condition for the
-  first time. Only a client that switches exhaustively on `MetricKey` needs new branches.
-
-  Not a contract change, but worth knowing if you author conditions: the report grammar's regime
-  metrics now resolve from the **confirmed close** on every path. They previously resolved from the
-  forming bar when a report was rendered and the confirmed close when the scan swept, so the same
-  condition could read differently in preview than in production. Same wire shape; same bar
-  everywhere now.
-
 `27.1.0` exit-policy authoring input on `compile_strategy_plan` · `19.2.0` `get_account_state` account identity · `19.1.0` Standing Orders marker authoring · `18.4.0` `list_gate_blocks` summary groups · `18.3.0` radar maintenance pause · `18.1.0` protection geometry · `17.2.0` break-even/trailing status · `17.1.0` `get_signal_log` condition evaluation · `13.1.0` four owner-scoped read tools · `12.1.0` cross-venue spot price metrics · `11.1.0` discoverable rate limit.
 
 ## v11 and earlier — contract history (v6 → v11)
@@ -706,33 +726,45 @@ The v3 authoring contract below is unchanged and still current:
 
 ## Quick Start
 
-### Single account (stdio transport)
+### Remote server, OAuth — start here
 
-```bash
-BATTLEGRID_API_KEY=bg_live_xxx npx @battlegrid/mcp-server
+```
+https://mcp.battlegrid.trade/mcp
 ```
 
-### Multiple accounts (stdio transport)
+Give that URL to your MCP client over its streamable-http (remote) transport and authorize: the
+client registers itself by Dynamic Client Registration, BattleGrid's consent page opens in your
+browser, and you sign in and click **Authorize**. No npm install, no API key. The grant is listed —
+and revocable — under **Profile → MCP → OAuth Sessions**.
 
-```bash
-BATTLEGRID_API_KEYS=bg_live_alice_key,bg_live_bob_key npx @battlegrid/mcp-server
-```
+### API key and the stdio proxy — the fallback
 
-When multiple keys are provided, the server discovers each account's identity and injects a required `account` parameter into every tool so the AI agent can choose which account to act as.
+Reach for a key when your client has no remote transport at all, when your agent runs headless or in
+CI and cannot open a browser to consent, or when one process drives several BattleGrid accounts. It
+is fully supported for each of those, and nothing about it is deprecated.
 
-### Remote server (streamable-http transport)
+**Single account (stdio transport):**
 
+```bash
+BATTLEGRID_API_KEY=bg_live_xxx npx @battlegrid/mcp-server
 ```
-https://mcp.battlegrid.trade/mcp
+
+**Multiple accounts (stdio transport):**
+
+```bash
+BATTLEGRID_API_KEYS=bg_live_alice_key,bg_live_bob_key npx @battlegrid/mcp-server
 ```
 
-No npm install required — connect directly from any MCP client that supports streamable-http.
+When multiple keys are provided, the server discovers each account's identity and injects a required `account` parameter into every tool so the AI agent can choose which account to act as. OAuth has no equivalent — one grant authorizes one account.
 
 ## Configuration
 
 ### Claude Desktop
 
-**Single account:**
+**OAuth (no key):** Settings → **Connectors** → **Add custom connector**. Paste
+`https://mcp.battlegrid.trade/mcp`, save, and authorize on the consent page Claude opens.
+
+**API key (fallback) — single account:**
 
 ```json
 {
@@ -748,7 +780,7 @@ No npm install required — connect directly from any MCP client that supports s
 }
 ```
 
-**Multiple accounts:**
+**API key (fallback) — multiple accounts:**
 
 ```json
 {
@@ -766,22 +798,44 @@ No npm install required — connect directly from any MCP client that supports s
 
 ### Claude Code
 
+**OAuth (no key):**
+
 ```bash
-claude mcp add battlegrid -- npx @battlegrid/mcp-server
+claude mcp add --transport http battlegrid https://mcp.battlegrid.trade/mcp
 ```
 
-Set your API key(s):
+Then start `claude`, run `/mcp`, select **battlegrid** and choose **Authenticate** — the consent page
+opens in your browser and the entry reads connected once you authorize.
+
+**API key (fallback):**
 
 ```bash
 # Single account
-export BATTLEGRID_API_KEY=bg_live_xxx
+claude mcp add battlegrid -e BATTLEGRID_API_KEY=bg_live_xxx -- npx @battlegrid/mcp-server
 
 # Multiple accounts
-export BATTLEGRID_API_KEYS=bg_live_alice_key,bg_live_bob_key
+claude mcp add battlegrid -e BATTLEGRID_API_KEYS=bg_live_alice_key,bg_live_bob_key -- npx @battlegrid/mcp-server
 ```
 
 ### Cursor
 
+**OAuth (no key):** Settings → **MCP** → **Add new global MCP server** opens `~/.cursor/mcp.json`.
+
+```json
+{
+  "mcpServers": {
+    "battlegrid": {
+      "url": "https://mcp.battlegrid.trade/mcp"
+    }
+  }
+}
+```
+
+Back in Settings → MCP, click **Needs login** on `battlegrid` and authorize on BattleGrid's consent
+page; the entry turns green once its tools load.
+
+**API key (fallback):** the same file, with the stdio proxy in place of the remote entry.
+
 ```json
 {
   "mcpServers": {
@@ -808,12 +862,16 @@ ChatGPT Desktop connects via **OAuth 2.1** — no npm package or API key needed.
 4. ChatGPT discovers OAuth endpoints, registers as a client (Dynamic Client Registration), and opens BattleGrid's consent page
 5. Log in to BattleGrid and click **Authorize**
 
-| | Claude Desktop / Cursor | ChatGPT Desktop |
+Authentication is a property of the **path**, not of the client — every client above reaches
+BattleGrid either way, so pick the row that matches your runtime rather than your client:
+
+| | Remote + OAuth | API key |
 |---|---|---|
-| **Transport** | stdio proxy (`@battlegrid/mcp-server`) | Direct HTTPS |
-| **Auth** | API key (`bg_live_*`) | OAuth 2.1 (Bearer token) |
-| **Setup** | npm package + env vars | URL + OAuth consent |
-| **Multi-account** | `BATTLEGRID_API_KEYS` env var | One OAuth grant per account |
+| **Transport** | streamable-http, direct to `mcp.battlegrid.trade` | stdio proxy (`@battlegrid/mcp-server`), or the same URL with a Bearer header |
+| **Auth** | OAuth 2.1 with Dynamic Client Registration | API key (`bg_live_*`) as a Bearer token |
+| **Setup** | paste the URL, authorize in the browser | npm package + env vars |
+| **Needs a browser** | yes, once, to consent | no — works headless and in CI |
+| **Multi-account** | one grant per account | `BATTLEGRID_API_KEYS`, several accounts through one proxy |
 
 ## Account management
 

package/dist/index.d.ts

@@ -49,7 +49,7 @@ import { type Implementation, type Prompt, type Resource } from '@modelcontextpr
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
  * correction. Never move it to track the server.
  */
-export declare const PACKAGE_VERSION = "31.2.13";
+export declare const PACKAGE_VERSION = "31.2.15";
 export declare const DEFAULT_URL = "https://mcp.battlegrid.trade/mcp";
 export interface EnvConfig {
     apiKeys: string[];

package/dist/index.js

@@ -52,7 +52,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema, ListPromptsRequestSchema
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
  * correction. Never move it to track the server.
  */
-export const PACKAGE_VERSION = '31.2.13';
+export const PACKAGE_VERSION = '31.2.15';
 export const DEFAULT_URL = 'https://mcp.battlegrid.trade/mcp';
 const MAX_RETRIES = 3;
 const RETRY_DELAYS_MS = [2000, 4000, 8000];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@battlegrid/mcp-server",
-  "version": "31.2.13",
+  "version": "31.2.15",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",