propline-mcp 0.37.0 → 0.39.0

package/README.md

@@ -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
@@ -151,7 +152,12 @@ var PropLineClient = class {
   getOddsClosing(sportKey, eventId, opts = {}) {
     return this.request(
       `/v1/sports/${sportKey}/events/${eventId}/odds/closing`,
-      { markets: opts.markets, bookmakers: opts.bookmakers, period: opts.period }
+      {
+        markets: opts.markets,
+        bookmakers: opts.bookmakers,
+        period: opts.period,
+        opening_window: opts.openingWindow
+      }
     );
   }
   /**
@@ -173,6 +179,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
@@ -301,14 +321,19 @@ var PropLineClient = class {
 };
 
 // src/server.ts
-var VERSION = "0.37.0";
+var VERSION = "0.39.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() {
@@ -321,10 +346,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;
@@ -509,7 +533,7 @@ var tools = [
   {
     name: "propline_get_odds_closing",
     title: "Get opening & closing lines",
-    description: "Hobby+ endpoint. Returns the OPENING and CLOSING line per (book, market, outcome) for an event. Closing = the last snapshot at or before commence_time (price/point/closing_at); opening = the first snapshot in the same 14-day pre-kickoff window (opening_price/opening_point/opening_at). Canonical CLV-tracking helper; one call returns both data points your bet should be measured against, instead of fetching full history and post-processing. Compare the POINTS as well as the prices \u2014 on spreads and totals the number moves as much as the price, so a price-only comparison mis-measures those markets. opening_age_seconds says how long before kickoff the opener was recorded: the archive starts 2026-04, so a small value means PropLine started polling late and this is not the book's true open. Free tier returns redacted structure with upgrade pointer.",
+    description: "Hobby+ endpoint. Returns the OPENING and CLOSING line per (book, market, outcome) for an event. Closing = the last snapshot at or before commence_time (price/point/closing_at); opening = the first snapshot PropLine holds for the outcome, however far before kickoff the book posted it (opening_price/opening_point/opening_at); pass opening_window to limit that lookback. Canonical CLV-tracking helper; one call returns both data points your bet should be measured against, instead of fetching full history and post-processing. Compare the POINTS as well as the prices \u2014 on spreads and totals the number moves as much as the price, so a price-only comparison mis-measures those markets. opening_age_seconds says how long before kickoff the opener was recorded: the archive starts 2026-04, so a small value means PropLine started polling late and this is not the book's true open. Free tier returns redacted structure with upgrade pointer.",
     inputSchema: {
       type: "object",
       properties: {
@@ -523,6 +547,10 @@ var tools = [
         period: {
           type: "string",
           description: "Game-period filter. Omitted = full-game markets only. Canonical codes (q1..q4, h1/h2, p1..p3, i1..i9, f3/f5/f7), comma-separated, or 'all'."
+        },
+        opening_window: {
+          type: ["string", "number"],
+          description: "Limit the opening lookback to this many days before kickoff (1-3650), or 'all' (default: the first snapshot held). 14 matches the resolved-props export's opening columns."
         }
       },
       required: ["sport_key", "event_id"],
@@ -534,7 +562,8 @@ var tools = [
       {
         markets: args.markets,
         bookmakers: args.bookmakers,
-        period: args.period
+        period: args.period,
+        openingWindow: args.opening_window === void 0 ? void 0 : String(args.opening_window)
       }
     )
   },
@@ -764,7 +793,7 @@ var tools = [
   {
     name: "propline_get_nhl_daily_goals_total",
     title: "Get NHL daily goals total",
-    description: "Free-tier endpoint. Returns the synthetic daily NHL goals total (hockey's equivalent of the MLB Grand Salami) for a given UTC date \u2014 total goals scored across every NHL game on the slate (including OT/SO) plus each book's implied Daily Goals Total line (median of per-game primary totals across our NHL books). No retail sportsbook quotes this as a single market. Useful for: 'what's the total goal line for tonight's full NHL slate', 'did the Daily Goals Total go over yesterday', 'historical NHL daily-goals results for backtesting'.",
+    description: "Free-tier endpoint. Returns the synthetic daily NHL goals total (hockey's equivalent of the MLB Grand Salami) for a given US Eastern date \u2014 total goals scored across every NHL game on the slate (including OT/SO) plus each book's implied Daily Goals Total line (median of per-game primary totals across our NHL books). No retail sportsbook quotes this as a single market. Useful for: 'what's the total goal line for tonight's full NHL slate', 'did the Daily Goals Total go over yesterday', 'historical NHL daily-goals results for backtesting'.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1158,11 +1187,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;
 }
@@ -1177,14 +1252,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
       }
     }))
@@ -1201,13 +1276,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)
       };
     }
   });
@@ -1231,6 +1306,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",
@@ -1256,7 +1336,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",
@@ -1312,6 +1394,7 @@ httpServer.listen(PORT, () => {
   );
 });
 export {
+  endUserIp,
   extractApiKey
 };
 //# sourceMappingURL=http.js.map