@battlegrid/mcp-server 31.2.11 → 31.2.13

package/README.md

@@ -1041,7 +1041,7 @@ Nine skills ship from this repo, all inside the npm tarball (`SKILL.md`, `skills
 **`battlegrid`** (repo root) is the connection skill and is authored here: how to connect, the
 `{ account, request }` envelope, the two scopes, and where to go for everything else.
 
-The eight `skills/battlegrid-*` are **exported from BattleGrid's server repository** — they are the
+The nine `skills/battlegrid-*` are **exported from BattleGrid's server repository** — they are the
 same instructions BattleGrid's own in-app Commander runs on, which is why they name the same tools
 you reach over MCP:
 
@@ -1055,6 +1055,7 @@ you reach over MCP:
 | `battlegrid-strategy-doctor` | Diagnose an agent that is not doing what was expected — why it has not traded, why it stopped, whether it is healthy — from typed fields, then rank the fixes with the exact lever each needs |
 | `battlegrid-strategy-examples` | Full-surface composition patterns: custom report sections and header grammar, benchmark sections, condition trees with verdicts and enforcement gates, tiered signal weights and the aggregate gate math, routing gates, ATR trade levels, position management, plus validated desk-grade playbooks and TradingView process ports |
 | `battlegrid-trade-analysis` | Read your own trading position: where the money is, whether each agent is doing its job, what is open and how close it sits to its protections, and whether the automation is actually running |
+| `battlegrid-trade-proposal` | Find and stage a trade for one of your agents: check what is already held, scan every active coin against the agent's own gates, propose on one through the agent's own conversational turn, present the outcome with its conviction, and approve or decline only on your word |
 
 > **`skills/battlegrid-*` is generated — do not edit it here.** It is written by
 > `server/scripts/export-mcp-skills.mjs` in `playbattlegrid/battlegrid-app` and arrives by pull

package/SKILL.md

@@ -7,10 +7,10 @@ description: MCP skill for BattleGrid — play crypto prediction games (Market G
 
 BattleGrid is a real-time cryptocurrency prediction gaming and trading platform. This MCP server gives AI agents access to play games, author trading strategies, and run strategy-bound intelligence agents.
 
-## The other eight skills
+## The other nine skills
 
 This skill covers **connection**: how to reach BattleGrid, the request envelope, and what each scope
-grants. Everything about *using* the platform lives in the eight skills installed beside it, exported
+grants. Everything about *using* the platform lives in the nine skills installed beside it, exported
 from BattleGrid's own server so they name exactly the tools you reach here:
 
 | For | Activate |
@@ -22,9 +22,10 @@ from BattleGrid's own server so they name exactly the tools you reach here:
 | Putting an agent on standing duty (Radar, Arena presets) | `battlegrid-radar-deployment` |
 | Reading the market — regime, funding, leaders, a coin deep-dive | `battlegrid-market-analysis` |
 | Reading your own position, agents, and open trades | `battlegrid-trade-analysis` |
+| Finding and staging a trade for one of your agents — scan its coins, propose on one, approve or decline on your word | `battlegrid-trade-proposal` |
 | Working out why an agent has not traded or has stopped | `battlegrid-strategy-doctor` |
 
-Those eight carry the working arcs and the exact contracts. What follows here is the minimum needed
+Those nine carry the working arcs and the exact contracts. What follows here is the minimum needed
 to connect and to know which one to open.
 
 ## Discover the live surface first

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.11";
+export declare const PACKAGE_VERSION = "31.2.13";
 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.11';
+export const PACKAGE_VERSION = '31.2.13';
 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.11",
+  "version": "31.2.13",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/EXPORT.json

@@ -12,6 +12,7 @@
     "battlegrid-strategy-examples/references/playbooks.md": "35c543c090d00ba19e4bcf0a80502afac7a4954643fc535de0b24381c91ecbf4",
     "battlegrid-strategy-examples/references/recipes.md": "53887daece17995543e7d3fe1bf2577fc41a6254c291acacde48d7de63853641",
     "battlegrid-strategy-examples/references/tradingview-ports.md": "1ff63367de1f9a9fbbcd7ecd5367137800373df47aaeb1d61fb1298d3a1924f4",
-    "battlegrid-trade-analysis/SKILL.md": "32573a67e55d735e6ee4e36b3b48c815694102704bc453c4d1c13db39551b3da"
+    "battlegrid-trade-analysis/SKILL.md": "32573a67e55d735e6ee4e36b3b48c815694102704bc453c4d1c13db39551b3da",
+    "battlegrid-trade-proposal/SKILL.md": "0a4586f660f605281c7775523c9e41422c6e52646ce52bf0688254af4619e46c"
   }
 }

package/skills/battlegrid-trade-proposal/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: battlegrid-trade-proposal
+description: Find and stage a trade for one of the player's agents, for the player to approve. Activate whenever the player asks which coins fit an agent right now, wants a trade found or proposed for an agent, asks the agent to evaluate a coin, or wants to approve or decline a proposal it made. The scan is the agent's own gates over every active coin; the proposal is the agent's own conversational turn; approval is always the player's word.
+---
+
+# Trade Proposal
+
+You are finding and staging a trade for an agent the player configured — never placing one. Every
+step below reads what the server decided and puts it to the player in their terms; nothing here
+re-sorts a list, re-derives a verdict, or approves on the player's behalf.
+
+## 0. What is already held — before anything else
+
+- `list_pending_approvals` and `list_user_active_positions` first, every time.
+- A proposal holds the player's live-position slot for that coin across **all** their agents until
+  it is accepted, cancelled or expires. **Never propose on a coin the player already holds a pending
+  or live position on** — say why, and name the decision or position that holds it.
+
+## 1. Which coins fit the agent right now
+
+- `scan_agent_coins` for the agent. The rows arrive server-ranked: qualifying coins first by score,
+  then the rest with their first failing gate, then coins that could not be scored with the reason.
+- Read the rows **as written**: the rank, the verdict, the first failing gate, the unscorable
+  label. Never re-sort them and never re-derive a verdict from its numbers — the server's ranking
+  is the answer.
+- A refused scan (`RATE_LIMITED`) is a refusal: say the scan was refused and when it can be retried
+  (`retryAfterSeconds`). Never say "nothing fits".
+
+## 2. Propose
+
+- `propose_entry_decision` **only** on the coins the player named, or on the top qualifying row
+  when they asked for the best fit. One coin per call.
+- `userMessage` is the player's own words for the turn. Mint a **fresh UUID** `idempotencyKey` per
+  proposal; a retry with the same key replays the recorded result and never runs a second turn.
+- The call is synchronous and may take the turn's full LLM latency. Do not retry while it is in
+  flight; a same-key call during that time is refused with `CONFLICT`.
+
+## 3. Report the outcome in the player's terms
+
+- `type: "recommendation"` — the PROPOSED decision, awaiting approval. State the direction, the
+  entry, stop and take-profit levels, the position size, the **`convictionPercent`**, and the
+  expiry (`expiresAt`). No conviction floor was applied on this surface: the conviction is the
+  agent's own reading, and the player judges it.
+- `type: "no_trade"` — the reason (`reasonCode`) and the next coins worth asking about.
+- `type: "error"` — the engine's block or a post-billing failure, with its remedy:
+  `OPEN_POSITION_CONFLICT` means a position already holds the slot (see step 0);
+  `LLM_CREDITS_EXHAUSTED` means top up when `topupAvailable` is true; a `SURFACE` / `LLM_FAILURE`
+  means the model was billed and produced nothing usable — retry **with a new key**, since the
+  same key replays this failure.
+- A refused proposal (`RATE_LIMITED`) is a refusal with its retry-after. Never "nothing to do".
+
+## 4. Approve or decline — only on the player's word
+
+- Present the decision and **ask**. `accept_entry_decision` only after the player explicitly
+  approves; `cancel_entry_decision` only after they explicitly decline.
+- Never accept because the conviction reads high, because the scan ranked the coin first, or
+  because the player asked you to "find a trade" — finding is not approving. `get_entry_decision`
+  re-reads the row if the conversation moved on before they answered.