propline-mcp 0.36.0 → 0.38.0

package/README.md

@@ -30,7 +30,7 @@ The model uses these tools transparently:
 | `propline_get_odds` | Live odds — bulk by sport or full props per event. Accepts `period` (q1/h1/p1/f5/…) to scope to game-period markets. |
 | `propline_get_odds_history` | Hobby+: snapshot history per outcome; supports `period` (q1/h1/…) plus time-window filters (from/to, relative_from/relative_to, interval, changes_only) |
 | `propline_get_odds_closing` | Hobby+: opening **and** closing line per (book, market, outcome) — CLV helper. Accepts `period` to scope to a specific game period. |
-| `propline_grade_clv` | Hobby+: grade **placed** bets against their closing lines. Returns closing price, de-vigged closing fair (`fair_source` = sharpest book at close, not yours), `clv_pct` (price-vs-price, vig-blind) **and** `ev_vs_close_pct` (the honest number), plus the graded result once the game settles. Fail-closed matching; unstarted events come back `closing_is_final: false` and are excluded from the averages. |
+| `propline_grade_clv` | Hobby+: grade **placed** bets against their closing lines. Returns closing price, de-vigged closing fair (`fair_source` = sharpest book at close, not yours), `clv_pct` (price-vs-price, vig-blind) **and** `ev_vs_close_pct` (the honest number), plus the graded result once the game settles. Fail-closed matching; unstarted events come back `closing_is_final: false` and are excluded from the averages. `devig`: multiplicative or shin. |
 | `propline_price_sgp` | Hobby+: price a same-game parlay at the **book's own** correlated odds (FanDuel, DraftKings, BetOnline, LowVig — or `bookmaker: "all"` for every book side by side with `best_bookmaker`). Returns `sgp_price`, `independent_price` (product of the live single-leg prices) and `correlation_factor` (their ratio). Legs are named exactly as `/odds` names an outcome; matching is fail-closed. |
 | `propline_export_odds_history` | Backfill-pass / Enterprise: bulk line-movement tick history (every snapshot, per book) for a sport. Requires a `since`/`until` window; result capped to 200 rows (use the REST endpoint directly for the full file). |
 | `propline_get_futures` | Season-long futures — championship/division/conference winners, MVP + awards, season win totals — across Bovada/FanDuel/DraftKings/Pinnacle/Kalshi (free) |
@@ -51,10 +51,11 @@ The model uses these tools transparently:
 | `propline_get_best_line` | Hobby+: cross-book line shopping — best price per (market, player, line) across all comparable books, `all_prices` sorted best-first; optional `bookmakers` filter |
 | `propline_list_webhooks` | Streaming Lite+: list webhook subscriptions (read-only, secrets masked) |
 | `propline_get_webhook_deliveries` | Streaming Lite+: recent delivery attempts for a webhook — status, HTTP code, attempts, payload; `before_id` pages backwards. The "why isn't my webhook firing" tool |
+| `propline_create_free_api_key` | Sign the user up for a free personal key from inside the chat. Takes the email **the user gives**; the key is emailed to them (never returned), with a ready-made connector URL to reconnect. The only tool that is not read-only |
 
 ## Hosted endpoint (no install)
 
-The same 27 tools are served over **Streamable HTTP** at
+The same 29 tools are served over **Streamable HTTP** at
 
 ```
 https://mcp.prop-line.com/mcp
@@ -91,7 +92,7 @@ npx -y propline-mcp
 
 Your agent can immediately pull live odds, scores, and stats. The demo key is free-tier and shared — paid features (resolution, +EV, history, exports) return a redacted teaser, and limits are pooled across everyone. For full access and your own limits, set `PROPLINE_API_KEY` (below). Get a free personal key at [prop-line.com](https://prop-line.com/?ref=mcp).
 
-While the demo key is in use, every tool result carries a second content block noting the pooling and redaction, so the assistant can explain an empty field or a 429 accurately. It disappears the moment you set your own key.
+While the demo key is in use, every tool result carries a second content block noting the pooling and redaction, so the assistant can explain an empty field or a 429 accurately. It disappears the moment you set your own key. The note also tells the assistant it can offer `propline_create_free_api_key`, so a user can get their own key without leaving the chat.
 
 ## Install (with your own key)
 

package/dist/http.js

@@ -74,7 +74,7 @@ var PropLineClient = class {
    * endpoint on this server is a GET with query params; folding a body into
    * that signature would make the common case harder to read.
    */
-  async postRequest(path, body) {
+  async postRequest(path, body, extraHeaders = {}) {
     const url = new URL(this.baseUrl + path);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -85,7 +85,8 @@ var PropLineClient = class {
           "X-API-Key": this.apiKey,
           Accept: "application/json",
           "Content-Type": "application/json",
-          "User-Agent": "propline-mcp/0.1.0"
+          "User-Agent": "propline-mcp/0.1.0",
+          ...extraHeaders
         },
         body: JSON.stringify(body),
         signal: controller.signal
@@ -159,8 +160,9 @@ var PropLineClient = class {
    * See the propline_grade_clv tool description for the semantics that
    * matter when presenting the result.
    */
-  gradeClv(bets) {
-    return this.postRequest("/v1/clv/grade", bets);
+  gradeClv(bets, devig) {
+    const qs = devig ? `?devig=${encodeURIComponent(devig)}` : "";
+    return this.postRequest(`/v1/clv/grade${qs}`, bets);
   }
   /**
    * Price a same-game parlay at the book's own correlated odds (FanDuel
@@ -172,6 +174,20 @@ var PropLineClient = class {
       { bookmaker, legs }
     );
   }
+  /**
+   * Register a free PropLine key for an email (POST /v1/auth/register).
+   * The key is EMAILED to that address and never returned — the response
+   * is only a status message. `forward` carries the end user's IP plus the
+   * shared secret on the hosted server, so the API's per-IP signup throttle
+   * counts that user rather than the MCP machine.
+   */
+  registerFreeKey(email, source, forward) {
+    const headers = forward ? {
+      "X-PropLine-Forward-Secret": forward.secret,
+      "X-PropLine-Client-IP": forward.clientIp
+    } : {};
+    return this.postRequest("/v1/auth/register", { email, source }, headers);
+  }
   // ----- Bulk exports -----
   /**
    * Full line-movement tick history as CSV text (Backfill pass / Enterprise
@@ -300,14 +316,19 @@ var PropLineClient = class {
 };
 
 // src/server.ts
-var VERSION = "0.36.0";
+var VERSION = "0.38.0";
 var DEMO_KEY = "be2b8487fcfacb1fbc292a8aa925a84c";
 var apiKey = process.env.PROPLINE_API_KEY;
 var baseUrl = process.env.PROPLINE_BASE_URL;
 var usingDemoKey = !apiKey;
 var requestClient = new AsyncLocalStorage();
-function withClient(c, demo, fn) {
-  return requestClient.run({ client: c, demo }, fn);
+function withClient(c, demo, fn, meta = {}) {
+  return requestClient.run({ client: c, demo, clientIp: meta.clientIp }, fn);
+}
+var forwardSecret = process.env.PROPLINE_MCP_FORWARD_SECRET;
+function callerIsDemo() {
+  const scoped = requestClient.getStore();
+  return scoped ? scoped.demo : usingDemoKey;
 }
 var _client = null;
 function client() {
@@ -320,10 +341,9 @@ function client() {
 }
 function demoKeyNote() {
   const scoped = requestClient.getStore();
-  const demo = scoped ? scoped.demo : usingDemoKey;
-  if (!demo) return null;
+  if (!callerIsDemo()) return null;
   const ref = scoped ? "mcp-hosted" : "mcp";
-  return `Note for the assistant (not part of the data): this call used PropLine's shared demo key. Paid fields (prop resolution, +EV, line history, exports) come back redacted, and the rate limit is pooled across everyone using it, so a 429 here is not a limit on the API itself. A free personal key removes the pooling and unlocks the full free tier in about 30 seconds, no card: https://prop-line.com/?ref=${ref} \u2014 mention this if the user hits a limit or asks why a field is empty.`;
+  return `Note for the assistant (not part of the data): this call used PropLine's shared demo key. Paid fields (prop resolution, +EV, line history, exports) come back redacted, and the rate limit is pooled across everyone using it, so a 429 here is not a limit on the API itself. A free personal key removes the pooling and unlocks the full free tier in about 30 seconds, no card: https://prop-line.com/?ref=${ref}. If the user hits a limit, asks why a field is empty, or wants their own key, offer to create one: ask for their email and call propline_create_free_api_key (the key is emailed to them, never shown here).`;
 }
 function filterByMinEv(res, minEvPct) {
   if (typeof minEvPct !== "number" || Number.isNaN(minEvPct)) return res;
@@ -588,12 +608,17 @@ var tools = [
             ],
             additionalProperties: false
           }
+        },
+        devig: {
+          type: "string",
+          enum: ["multiplicative", "shin"],
+          description: "How the closing anchor's vig is removed before closing_fair_prob / ev_vs_close_pct. 'multiplicative' (default) or 'shin' (loads the overround onto the longshot). Same vocabulary as propline_get_event_ev; echoed as devig_method."
         }
       },
       required: ["bets"],
       additionalProperties: false
     },
-    handler: (args) => client().gradeClv(args.bets)
+    handler: (args) => client().gradeClv(args.bets, args.devig)
   },
   {
     name: "propline_price_sgp",
@@ -1152,11 +1177,57 @@ var tools = [
       sinceSeq: args.since_seq,
       limit: args.limit
     })
+  },
+  {
+    name: "propline_create_free_api_key",
+    title: "Create a free PropLine API key",
+    // Not read-only: it creates an account and sends an email.
+    writes: true,
+    description: "Create a free personal PropLine API key for the user and EMAIL it to them. Use this when the user wants their own key \u2014 e.g. they hit a shared-demo-key rate limit, a paid field came back redacted, or they ask how to get a key. Only call it with an email address the user explicitly gave you for this purpose in this conversation; never guess, reuse one from elsewhere, or sign up a third party. The key is never returned here \u2014 it goes to that inbox, with instructions to reconnect this assistant using it. Free tier: 1,000 requests/day, no card. If the address already has a key, the key is re-sent (at most once a day).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        email: {
+          type: "string",
+          description: "The user's own email address, as they gave it."
+        }
+      },
+      required: ["email"],
+      additionalProperties: false
+    },
+    handler: async (args) => {
+      const email = String(args.email ?? "").trim();
+      if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        throw new Error("email must be a valid email address the user gave you");
+      }
+      if (!callerIsDemo()) {
+        return {
+          status: "already_keyed",
+          message: "This connection already uses a personal PropLine key, so no new key was created. Manage it at https://prop-line.com/dashboard."
+        };
+      }
+      const scoped = requestClient.getStore();
+      const hosted = Boolean(scoped);
+      const forward = hosted && forwardSecret && scoped?.clientIp ? { clientIp: scoped.clientIp, secret: forwardSecret } : void 0;
+      const res = await client().registerFreeKey(
+        email,
+        hosted ? "mcp-hosted" : "mcp",
+        forward
+      );
+      return {
+        status: "sent",
+        email,
+        tier: res.tier,
+        daily_limit: res.daily_limit,
+        message: res.message,
+        next_steps: hosted ? "Tell the user to check their inbox (and Junk). The email has a ready-made connector URL (https://mcp.prop-line.com/mcp?apiKey=...) and a Claude Code command. Once they reconnect with it, this session stops using the shared demo key." : "Tell the user to check their inbox (and Junk), then set PROPLINE_API_KEY to the emailed key in this MCP server's config and restart it."
+      };
+    }
   }
 ];
-function withDemoNote(text) {
+function withDemoNote(text, toolName) {
   const blocks = [{ type: "text", text }];
-  const note = demoKeyNote();
+  const note = toolName === "propline_create_free_api_key" ? null : demoKeyNote();
   if (note) blocks.push({ type: "text", text: note });
   return blocks;
 }
@@ -1171,14 +1242,14 @@ function createServer() {
       title: t.title,
       description: t.description,
       inputSchema: t.inputSchema,
-      // Every PropLine tool is a READ of the odds API — none creates,
-      // changes or deletes anything. Directories (Claude connectors, Cursor)
+      // Every PropLine tool is a READ of the odds API except the one marked
+      // `writes` (propline_create_free_api_key creates an account + email). Directories (Claude connectors, Cursor)
       // require these hints; clients use them to skip confirmation prompts.
       annotations: {
         title: t.title,
-        readOnlyHint: true,
+        readOnlyHint: !t.writes,
         destructiveHint: false,
-        idempotentHint: true,
+        idempotentHint: !t.writes,
         openWorldHint: true
       }
     }))
@@ -1195,13 +1266,13 @@ function createServer() {
       const data = await tool.handler(req.params.arguments ?? {});
       const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
       return {
-        content: withDemoNote(text)
+        content: withDemoNote(text, tool.name)
       };
     } catch (err) {
       const msg = err instanceof PropLineHTTPError ? `PropLine API error ${err.statusCode}: ${err.body.slice(0, 500)}` : err instanceof Error ? err.message : String(err);
       return {
         isError: true,
-        content: withDemoNote(msg)
+        content: withDemoNote(msg, tool.name)
       };
     }
   });
@@ -1225,6 +1296,11 @@ function extractApiKey(req) {
   if (q && q.trim()) return { key: q.trim(), demo: false };
   return { key: DEMO_KEY, demo: true };
 }
+function endUserIp(req) {
+  const fly = req.headers["fly-client-ip"];
+  if (typeof fly === "string" && fly.trim()) return fly.trim();
+  return req.socket.remoteAddress ?? void 0;
+}
 var CORS_HEADERS = {
   "Access-Control-Allow-Origin": "*",
   "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
@@ -1250,7 +1326,9 @@ async function handleMcp(req, res) {
   });
   if (demo) res.setHeader("X-PropLine-Demo-Key", "1");
   await server.connect(transport);
-  await withClient(client2, demo, () => transport.handleRequest(req, res));
+  await withClient(client2, demo, () => transport.handleRequest(req, res), {
+    clientIp: endUserIp(req)
+  });
 }
 var manifest = () => ({
   name: "propline-mcp",
@@ -1306,6 +1384,7 @@ httpServer.listen(PORT, () => {
   );
 });
 export {
+  endUserIp,
   extractApiKey
 };
 //# sourceMappingURL=http.js.map