@coinrithm/mcp-trading 0.7.11 → 0.7.12

package/CHANGELOG.md

@@ -5,6 +5,21 @@ ships two binaries — `coinrithm-mcp` (the MCP server) and `coinrithm-agent` (t
 self-host agent runner) — versioned together. The CoinRithm **API contract** is
 versioned separately (see `openapi.yaml` `info.version`, currently `1.7.0`).
 
+## 0.7.12 — 2026-09-15
+
+Clarify `whoami`, `cancel_spot_order` and `report_pm_opportunity` descriptions,
+removing execution-cost prose unrelated to these operations. Document actual
+authentication, side effects, result fields and retry behavior.
+
+Spot cancellation now advertises its existing idempotent behavior. Opportunity
+reporting no longer advertises unconditional idempotency: duplicate protection
+requires `decisionId` (or `agentTrace.decisionId`) under the same API key; the
+first stored record wins. Reporting remains a write despite requiring only the
+`read` scope, and its evidence remains explicitly self-reported.
+
+Tool names, accepted inputs and execution behavior are unchanged. This source
+entry does not establish registry publication, deployment or a new Glama score.
+
 ## 0.7.11 — 2026-09-15
 
 Fix opportunity reporting that previously treated resolved API failures as

package/README.md

@@ -42,16 +42,15 @@ This package ships two binaries:
 
 > **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
 
-## Version 0.7.11
-
-This patch corrects opportunity-report status: only a successful API result
-confirms submission. HTTP errors remain unconfirmed, and transport failures
-have an unknown outcome. Attempt evidence is available in
-`CycleResult.opportunityReport`; `opportunity` contains confirmed reports only.
-Trading behavior and the one-report-method-call-per-cycle limit are preserved. See
-[CHANGELOG.md](./CHANGELOG.md). Check `npm view @coinrithm/mcp-trading
-version` for the latest published version. Hosted deployments and npm releases
-are separate.
+## Version 0.7.12
+
+This patch clarifies `whoami`, `cancel_spot_order` and `report_pm_opportunity`
+for MCP clients. Cancellation is marked safe to repeat; opportunity reporting
+is a write whose duplicate protection requires a decision ID. Tool names,
+accepted inputs and execution behavior are unchanged. See [CHANGELOG.md](./CHANGELOG.md).
+This source entry does not establish publication. Check
+`npm view @coinrithm/mcp-trading version` for the latest published version;
+hosted deployments and npm releases are separate.
 
 Runner API operations have a 30-second total deadline, including response
 bodies and 429 retry waits. Timeout and cancellation results remain unconfirmed;

package/dist/tools.js

@@ -604,12 +604,14 @@ export function registerTools(server, client) {
     // ---------------- identity ----------------
     server.registerTool("whoami", {
         title: "Who am I (CoinRithm)",
-        description: "Return the identity behind the configured API key: userId, keyId, " +
-            "granted scopes, plus the key's agentName and agentModel (both null " +
-            "until set in Profile -> API Keys; agentModel is the self-reported " +
-            "model/runtime label shown on the public Agent Arena when opted in). " +
-            "Use this first to confirm what the key is allowed to do. " +
-            PAPER_NOTE,
+        description: "Check the caller's CoinRithm API-key identity and permissions before " +
+            "using account or trading tools. Returns userId, keyId, scopes, usage, " +
+            "and nullable agentName/agentModel labels; agentModel is self-reported, " +
+            "not verified runtime identity. Any valid configured or per-request key " +
+            "works; no additional scope is required. Missing or invalid keys return " +
+            "401. Omit agentTrace for a simple check. Does not change permissions " +
+            "or paper balances; requests update usage/last-used metadata and may " +
+            "be privately logged.",
         inputSchema: {
             agentTrace: AGENT_TRACE_SCHEMA,
         },
@@ -1176,16 +1178,26 @@ export function registerTools(server, client) {
     }, requestKey(extra))));
     server.registerTool("cancel_spot_order", {
         title: "Cancel spot order",
-        description: "Cancel an open spot order by id (releases frozen funds). Requires the " +
-            "trade:spot scope. " +
-            PAPER_NOTE,
+        description: "Cancel the unfilled remainder of your paper spot order and release " +
+            "its reserved funds. Requires trade:spot scope; get orderId from " +
+            "list_open_orders. Does not reverse filled trades. Safe to repeat with " +
+            "the same orderId: an order not open under your key returns " +
+            "body.alreadyClosed=true, which does not distinguish a fill from an " +
+            "earlier cancellation or an unknown order. Use get_my_trades to check " +
+            "fills. API failures return ok=false and httpStatus; on 429, respect " +
+            "retryAfterSeconds when provided.",
         inputSchema: {
-            orderId: z.number().int().positive().describe("Open order id."),
+            orderId: z
+                .number()
+                .int()
+                .positive()
+                .describe("Your paper spot order id from list_open_orders."),
             agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: mutatingAnnotations("Cancel spot order", {
             destructive: true,
+            idempotent: true,
         }),
     }, async ({ orderId, agentTrace }, extra) => present(await client.cancelSpotOrder(orderId, requestKey(extra), agentTrace)));
     server.registerTool("open_futures_position", {
@@ -1375,21 +1387,19 @@ export function registerTools(server, client) {
     }, requestKey(extra))));
     server.registerTool("report_pm_opportunity", {
         title: "Report a non-opened PM opportunity",
-        description: "Report a prediction-market opportunity you evaluated but did NOT open, so " +
-            "your PUBLIC evaluation reflects the FULL opportunity universe — not only " +
-            "the trades you took (otherwise an agent can look skilled by exposure " +
-            "choice alone). kind is one of: 'abstained' (you looked at markets and " +
-            "chose not to bet), 'forecast_only' (you formed your OWN probability but " +
-            "did not trade — forecastProbability is REQUIRED, 1-99), or 'quote_expired' " +
-            "(a bet you validated was rejected at open because the market moved). This " +
-            "is EVIDENCE, not a trade: it needs only the read scope, never moves funds, " +
-            "and is recorded as a durable, hashed decision artifact. It is a " +
-            "SELF-REPORT — CoinRithm records what you assert about your own reasoning; " +
-            "it does not independently verify that you truly evaluated the market. Put " +
-            "the breadth of what you weighed in cohort.universeSize (how many markets) " +
-            "and report ONCE per decision cycle, not once per market. Reuse decisionId " +
-            "to make a retry idempotent. " +
-            PAPER_NOTE,
+        description: "Save a durable SELF-REPORT of a prediction-market evaluation for a " +
+            "decision that did not open a position. This WRITES an evidence record " +
+            "but never moves paper funds; authorization requires the read scope. " +
+            "It does not independently verify your evaluation. Choose abstained, " +
+            "forecast_only (requires your own forecastProbability, 1-99), or " +
+            "quote_expired. Report once per decision cycle; cohort.universeSize " +
+            "records its breadth. Supply a non-empty decisionId and reuse it with " +
+            "the same API key on retries: the first stored record wins. " +
+            "agentTrace.decisionId is a fallback; omitting both creates separate " +
+            "records. Success returns " +
+            "body.decisionUuid and, on replay, body.idempotentReplay=true. Check " +
+            "ok/httpStatus before treating delivery as confirmed; a network error " +
+            "does not prove rejection. Use open_pm_position to place a paper trade.",
         inputSchema: {
             kind: z
                 .enum(["abstained", "forecast_only", "quote_expired"])
@@ -1410,8 +1420,8 @@ export function registerTools(server, client) {
                 .min(1)
                 .max(99)
                 .optional()
-                .describe("Your OWN probability (1-99) the chosen side wins. REQUIRED for " +
-                "forecast_only; omit for the other kinds. Never echo the market price."),
+                .describe("Your OWN forecast probability (1-99). REQUIRED for forecast_only; " +
+                "optional for other kinds. Never echo the market price."),
             marketProbability: z
                 .number()
                 .min(0)
@@ -1442,15 +1452,17 @@ export function registerTools(server, client) {
             decisionId: z
                 .string()
                 .optional()
-                .describe("Your own id for this decision — idempotency key within your API key."),
+                .describe("Non-empty id for this decision, unique within your API key. " +
+                "Reuse for retries. Falls back to agentTrace.decisionId; " +
+                "omitting both creates a new record on each call."),
             runId: z.string().optional().describe("Your own run id for grouping."),
             provenance: PROVENANCE_REPORT_SCHEMA,
             agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
-        annotations: mutatingAnnotations("Report a non-opened PM opportunity", {
-            idempotent: true,
-        }),
+        // Idempotency is conditional on decisionId; it is not a safe default
+        // for the entire tool because the field remains optional.
+        annotations: mutatingAnnotations("Report a non-opened PM opportunity"),
     }, async ({ kind, source, slug, outcomeExternalMarketId, forecastProbability, marketProbability, reasonCode, cohort, decisionId, runId, provenance, agentTrace, }, extra) => present(await client.reportPmOpportunity({
         kind,
         source,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinrithm/mcp-trading",
-  "version": "0.7.11",
+  "version": "0.7.12",
   "mcpName": "io.github.CoinRithm/mcp-trading",
   "description": "CoinRithm paper-trading toolkit: an MCP server (coinrithm-mcp) AND a self-host agent runner (coinrithm-agent) for spot, futures, and prediction markets with a user-minted API key.",
   "type": "module",