sbor-mcp 1.0.0 → 1.1.0

package/README.md

@@ -1,7 +1,19 @@
 # SBOR MCP server
 
-Call [SBOR](https://sbor.xyz), the benchmark lending rate for Stacks, as a tool
-from Claude or any MCP client.
+Check a lending rate before your agent borrows.
+
+Bitcoin DeFi has no benchmark lending rate. [SBOR](https://sbor.xyz) starts with
+Stacks, where the market is: one borrow and one supply rate per currency, read
+from lending contract state and published daily. This server exposes it as tools
+for Claude, Cowork, Cursor or any MCP client.
+
+## Quick check
+
+```bash
+npx -y sbor-mcp
+```
+
+It starts and waits silently. That is success. Ctrl+C to exit.
 
 ## Install
 
@@ -10,7 +22,7 @@ from Claude or any MCP client.
   "mcpServers": {
     "sbor": {
       "command": "npx",
-      "args": ["-y", "@sbor/mcp"]
+      "args": ["-y", "sbor-mcp"]
     }
   }
 }
@@ -24,15 +36,34 @@ Claude Desktop: add that to `claude_desktop_config.json` and restart.
 |---|---|
 | `get_rate` | What does capital cost on Stacks right now |
 | `compare_rate` | Is this offer above or below the market, and by how much |
-| `list_markets` | Which venues make up the rate, with utilisation and depth |
+| `list_markets` | Which venues make up the rate, with utilization and depth |
 | `get_history` | How has the rate moved |
-| `compare_chains` | How does Stacks compare with Aave on Ethereum |
+| `compare_chains` | How Stacks compares with Ethereum, Base, Hyperliquid, Solana and SOFR |
 | `get_methodology` | How the number is built, and what it excludes |
 
-## Behaviour worth knowing
+## Recommended use
+
+**Use SBOR to stop, never to start.** Before borrowing, call `compare_rate`. If
+the offer is more than 50 basis points above the benchmark, stop and ask a
+human. A wrong reading under that rule costs a pause, not a trade.
+
+## Behavior worth knowing
+
+**It refuses rather than guesses.** `compare_rate` returns an error, not a
+verdict, when the data is more than 48 hours old, when the fixing timestamp
+cannot be read, when the index is not published, or when a rate is missing. An
+error means there is no trustworthy answer, not that the rate is bad. Fall back
+to your own logic.
+
+**It checks units.** Rates are percentages: 4.2 means 4.2%. Anything outside 0
+to 100 is rejected. Below 0.5 is answered, because rates that low genuinely
+occur, but with a warning that you may have passed a fraction.
+
+**It never averages across a methodology change.** `get_history` gives a mean
+per methodology version when a window spans more than one.
 
-**It never guesses.** If SBOR is unreachable the tool says so and tells you to
-fall back to your own logic rather than substituting an estimate.
+**It never guesses when SBOR is down.** If SBOR is unreachable or slower than 10
+seconds, the tool says so rather than substituting an estimate.
 
 **It reports omissions.** When a market cannot be read, SBOR omits the index
 rather than publishing a figure that is not real. The tool explains that instead
@@ -44,7 +75,7 @@ venue, not a market average, and `get_rate` says so.
 **It reads the same public endpoints as everyone else.** No key, no state, no
 writes, no telemetry. Set `SBOR_BASE` to point at a different host.
 
-## Licence
+## License
 
 MIT. The published fixing is free to read. See
 [llms.txt](https://sbor.xyz/llms.txt) for the full integration policy.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sbor-mcp",
-  "version": "1.0.0",
-  "description": "MCP server for SBOR, the benchmark lending rate for Stacks",
+  "version": "1.1.0",
+  "description": "Check a lending rate before your agent borrows. The benchmark rate for Stacks, read from contract state. Free, no key, no rate limit.",
   "type": "module",
   "bin": {
     "sbor-mcp": "./server.mjs"
@@ -11,15 +11,22 @@
   "homepage": "https://sbor.xyz",
   "repository": {
     "type": "git",
-    "url": "https://github.com/sborxyz/sbor"
+    "url": "git+https://github.com/sborxyz/sbor.git"
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "stacks",
     "bitcoin",
+    "bitcoin-defi",
+    "btcfi",
     "defi",
+    "lending",
     "interest-rates",
     "benchmark",
+    "ai-agents",
+    "agents",
+    "sbtc",
     "sbor"
   ],
   "dependencies": {

package/server.mjs

@@ -2,44 +2,70 @@
 /**
  * SBOR MCP server.
  *
- * Exposes the Stacks Bitcoin Offered Rate as tools any MCP client can call:
- * Claude, an agent framework, or anything else that speaks the protocol.
+ * Exposes SBOR, the benchmark lending rate for Stacks, as tools any MCP client
+ * can call: Claude, an agent framework, or anything else that speaks the
+ * protocol.
  *
  * Reads the same public endpoints as everyone else. No key, no state, no
- * writes. If SBOR is unreachable the tools say so rather than guessing.
+ * writes. If SBOR cannot give a trustworthy answer, the tools say so rather
+ * than guessing. That matters most in compare_rate, which an agent may consult
+ * before borrowing: a wrong verdict there is worse than no verdict.
  *
- * Run:  npx -y @sbor/mcp
+ * Run:  npx -y sbor-mcp
  * Or:   node mcp/server.mjs
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 
+const VERSION = "1.1.0";
 const BASE = process.env.SBOR_BASE || "https://sbor.xyz";
-const UA = "sbor-mcp/1.0";
+const UA = `sbor-mcp/${VERSION}`;
+const TIMEOUT_MS = 10_000;
+const STALE_AFTER_HOURS = 48;
+const INDICES = ["SBOR-USD", "SBOR-BTC", "SBOR-STX"];
 
 /* Small cache so an agent asking three questions in a row makes one request. */
 const cache = new Map();
 async function getJson(path, ttlMs = 60_000){
   const hit = cache.get(path);
   if (hit && Date.now() - hit.at < ttlMs) return hit.data;
-  const r = await fetch(`${BASE}${path}`, { headers: { accept:"application/json", "user-agent":UA } });
+  const r = await fetch(`${BASE}${path}`, {
+    headers: { accept: "application/json", "user-agent": UA },
+    signal: AbortSignal.timeout(TIMEOUT_MS)
+  });
   if (!r.ok) throw new Error(`${path} responded ${r.status}`);
   const data = await r.json();
   cache.set(path, { at: Date.now(), data });
   return data;
 }
 
-const text = t => ({ content: [{ type:"text", text: t }] });
-const fail = e => ({ isError: true, content: [{ type:"text",
-  text: `SBOR is unreachable or returned something unexpected: ${e.message}. `
-      + `Do not substitute an estimate. Fall back to your own logic or try again.` }] });
+const text = t => ({ content: [{ type: "text", text: t }] });
+const refuse = t => ({ isError: true, content: [{ type: "text", text: t }] });
+const fail = e => refuse(
+  (e?.name === "TimeoutError"
+    ? `SBOR did not respond within ${TIMEOUT_MS / 1000} seconds.`
+    : `SBOR is unreachable or returned something unexpected: ${e?.message}.`)
+  + ` Do not substitute an estimate. Fall back to your own logic or try again.`);
 
-const pct = n => (typeof n === "number" ? n.toFixed(2) + "%" : "not published");
-const usd = n => n >= 1e9 ? "$" + (n/1e9).toFixed(2) + "B"
-                          : "$" + (n/1e6).toFixed(1) + "M";
+const pct = n => (typeof n === "number" && Number.isFinite(n) ? n.toFixed(2) + "%" : "not published");
+const usd = n => !Number.isFinite(n) ? "n/a"
+  : n >= 1e9 ? "$" + (n / 1e9).toFixed(2) + "B" : "$" + (n / 1e6).toFixed(1) + "M";
 
-const server = new McpServer({ name: "sbor", version: "1.0.0" });
+/* Age of a fixing in hours, or null when the timestamp cannot be parsed. An
+   unparseable timestamp must read as unusable, never as fresh. */
+function ageHours(iso){
+  const t = Date.parse(iso);
+  return Number.isFinite(t) ? (Date.now() - t) / 36e5 : null;
+}
+function freshness(d){
+  const a = ageHours(d.fixing);
+  if (a === null) return `Fixing timestamp "${d.fixing}" could not be read. Treat this data as unusable.`;
+  if (a > STALE_AFTER_HOURS) return `STALE: the last fixing is ${a.toFixed(1)} hours old. Rates may have moved. Do not act on it.`;
+  return `Fixing ${d.fixing}, ${a.toFixed(1)} hours old, methodology ${d.methodologyVersion}.`;
+}
+
+const server = new McpServer({ name: "sbor", version: VERSION });
 
 /* ------------------------------------------------------------------ */
 /* 1. the current fixing                                               */
@@ -51,38 +77,38 @@ server.registerTool("get_rate", {
     "lending contract state. Use this to judge whether a lending offer is good: " +
     "borrowing above the SBOR borrow rate means paying more than the market, " +
     "supplying below the supply rate means earning less. Returns every currency " +
-    "index unless one is named.",
+    "index unless one is named. Always read the freshness line first.",
   inputSchema: {
-    index: z.enum(["SBOR-USD","SBOR-BTC","SBOR-STX"]).optional()
-      .describe("Currency index. Omit for all of them.")
+    index: z.enum(INDICES).optional().describe("Currency index. Omit for all of them.")
   }
 }, async ({ index }) => {
   try {
     const d = await getJson("/api/v1/latest.json");
-    const wanted = index ? { [index]: d.indices[index] } : d.indices;
     if (index && !d.indices[index])
       return text(`${index} is not published in the current fixing. `
         + `When a market cannot be read, SBOR omits the index rather than publishing `
-        + `a figure that is not real. Published today: ${Object.keys(d.indices).join(", ")}.`);
+        + `a figure that is not real. Treat it as unknown, never as zero. `
+        + `Published today: ${Object.keys(d.indices).join(", ")}.`);
 
+    const wanted = index ? { [index]: d.indices[index] } : d.indices;
     const lines = Object.entries(wanted).map(([label, ix]) => {
-      const conc = `${ix.venues.length} ${ix.venues.length === 1 ? "venue" : "venues"}`
-        + `, largest ${(ix.largestConstituentWeight*100).toFixed(0)}% of depth`;
-      const allIn = ix.allInSupplyDiffers
-        ? `, ${pct(ix.allInSupply)} all in with protocol yield` : "";
+      const n = ix.venues.length;
+      const conc = `${n} ${n === 1 ? "venue, so a reading of that venue rather than a market average" : "venues"}`
+        + `, largest ${(ix.largestConstituentWeight * 100).toFixed(0)}% of depth`;
+      const allIn = ix.allInSupplyDiffers ? `, ${pct(ix.allInSupply)} all in with protocol yield` : "";
       return `${label}: borrow ${pct(ix.borrow)}, supply ${pct(ix.supply)}${allIn} (${conc})`;
     });
 
-    const omitted = ["SBOR-USD","SBOR-BTC","SBOR-STX"].filter(l => !d.indices[l]);
+    const omitted = INDICES.filter(l => !d.indices[l]);
     return text([
-      `SBOR fixing ${d.fixing}, methodology ${d.methodologyVersion}`,
+      freshness(d),
       ...lines,
       omitted.length ? `Not published: ${omitted.join(", ")}. A market that cannot be read is omitted, not estimated.` : "",
-      d.poxReference ? `PoX staking yield ${pct(d.poxReference.apy)}, a staking yield and not a lending rate.` : "",
+      d.poxReference ? `Proof of Transfer staking yield ${pct(d.poxReference.apy)}. A staking yield, not a lending rate. Never add it to one.` : "",
       `Basis: ${d.basis}`,
       `Source: ${BASE}/api/v1/latest.json`
     ].filter(Boolean).join("\n"));
-  } catch(e){ return fail(e); }
+  } catch (e) { return fail(e); }
 });
 
 /* ------------------------------------------------------------------ */
@@ -92,24 +118,46 @@ server.registerTool("compare_rate", {
   title: "Compare a rate against the SBOR benchmark",
   description:
     "Given a rate you have been offered, say whether it is above or below the " +
-    "market for that currency, and by how much. This is the main reason SBOR exists.",
+    "market for that currency, and by how much. This is the main reason SBOR exists. " +
+    "Recommended use: if a borrow offer is more than 50 basis points above the " +
+    "benchmark, stop and ask a human. Use SBOR to stop, never to start. " +
+    "This tool refuses rather than guesses: an error result means there is no " +
+    "trustworthy answer, not that the rate is bad.",
   inputSchema: {
-    rate: z.number().describe("The rate offered, as a percentage. 4.2 means 4.2%."),
-    side: z.enum(["borrow","supply"]).describe("Whether you would be borrowing or supplying."),
-    index: z.enum(["SBOR-USD","SBOR-BTC","SBOR-STX"]).describe("Which currency.")
+    rate: z.number().gt(0).lte(100)
+      .describe("The rate offered, as a percentage between 0 and 100. 4.2 means 4.2%, not 0.042."),
+    side: z.enum(["borrow", "supply"]).describe("Whether you would be borrowing or supplying."),
+    index: z.enum(INDICES).describe("Which currency.")
   }
 }, async ({ rate, side, index }) => {
   try {
+    if (!Number.isFinite(rate) || rate <= 0 || rate > 100)
+      return refuse(`The rate must be a percentage between 0 and 100, got ${rate}. 4.2% is 4.2, not 0.042.`);
+
     const d = await getJson("/api/v1/latest.json");
+
+    /* A verdict an agent may act on must not rest on data SBOR cannot stand behind. */
+    const a = ageHours(d.fixing);
+    if (a === null)
+      return refuse(`The fixing timestamp "${d.fixing}" could not be read, so the age of the data is unknown. No verdict. Fall back to your own logic.`);
+    if (a > STALE_AFTER_HOURS)
+      return refuse(`The last fixing is ${a.toFixed(1)} hours old, past the ${STALE_AFTER_HOURS} hour limit. No verdict on stale data. Fall back to your own logic.`);
+
     const ix = d.indices[index];
-    if (!ix) return text(`${index} is not published in the current fixing, so there is no benchmark to compare against today.`);
+    if (!ix)
+      return refuse(`${index} is not published in the current fixing, so there is no benchmark to compare against. `
+        + `Treat this as unknown, not as zero. Published today: ${Object.keys(d.indices).join(", ")}.`);
+
     const bench = ix[side];
-    if (typeof bench !== "number") return text(`${index} has no published ${side} rate today.`);
+    if (typeof bench !== "number" || !Number.isFinite(bench))
+      return refuse(`${index} has no usable ${side} rate in the current fixing. Treat this as unknown, not as zero.`);
 
     const diff = rate - bench;
+    if (!Number.isFinite(diff)) return refuse(`Could not compute a difference. No verdict.`);
     const bps = Math.round(Math.abs(diff) * 100);
+
     let verdict;
-    if (Math.abs(diff) < 0.01) verdict = "at the market";
+    if (bps < 1) verdict = "at the market";
     else if (side === "borrow") verdict = diff > 0
       ? `above the market. You would be paying ${bps} basis points more than the benchmark`
       : `below the market. You would be paying ${bps} basis points less than the benchmark`;
@@ -117,18 +165,30 @@ server.registerTool("compare_rate", {
       ? `above the market. You would be earning ${bps} basis points more than the benchmark`
       : `below the market. You would be earning ${bps} basis points less than the benchmark`;
 
-    const cheapest = [...ix.markets].sort((a,b) =>
-      side === "borrow" ? a.borrow - b.borrow : b.supply - a.supply)[0];
+    /* A fraction passed as a percentage cannot be caught with certainty,
+       because rates this low genuinely occur on Stacks. So it is answered, and
+       flagged loudly enough that it cannot be missed. */
+    const unitsWarning = rate < 0.5
+      ? `CHECK UNITS FIRST: this was read as ${rate}%, not ${(rate * 100).toFixed(1)}%. Rates this low do occur, so it has been answered as given. If you meant ${(rate * 100).toFixed(1)}%, ask again with ${(rate * 100).toFixed(1)}.`
+      : "";
+
+    const best = [...ix.markets]
+      .filter(m => typeof m[side] === "number" && Number.isFinite(m[side]))
+      .sort((p, q) => side === "borrow" ? p[side] - q[side] : q[side] - p[side])[0];
+
+    const stop = side === "borrow" && diff * 100 > 50
+      ? `This is more than 50 basis points above the benchmark. Recommended: stop and ask a human before borrowing.`
+      : "";
 
     return text([
+      unitsWarning,
       `${index} ${side} benchmark is ${pct(bench)}. Your ${rate.toFixed(2)}% is ${verdict}.`,
-      `Best constituent today: ${cheapest.venue} ${cheapest.asset} at ${pct(cheapest[side])}, `
-        + `utilisation ${pct(cheapest.utilization)}.`,
-      ix.venues.length === 1
-        ? `Note: this index covers one venue, so it is a reading of that venue rather than a market average.`
-        : ""
+      stop,
+      best ? `Best constituent today: ${best.venue} ${best.asset} at ${pct(best[side])}, utilization ${pct(best.utilization)}.` : "",
+      ix.venues.length === 1 ? `Note: this index covers one venue, so it is a reading of that venue rather than a market average.` : "",
+      freshness(d)
     ].filter(Boolean).join("\n"));
-  } catch(e){ return fail(e); }
+  } catch (e) { return fail(e); }
 });
 
 /* ------------------------------------------------------------------ */
@@ -138,10 +198,9 @@ server.registerTool("list_markets", {
   title: "List the lending markets behind a rate",
   description:
     "Every venue and asset in an index, with its borrow rate, supply rate, " +
-    "utilisation, depth and weight. Utilisation explains why a rate sits where it does.",
+    "utilization, depth and weight. Utilization explains why a rate sits where it does.",
   inputSchema: {
-    index: z.enum(["SBOR-USD","SBOR-BTC","SBOR-STX"]).optional()
-      .describe("Currency index. Omit for all of them.")
+    index: z.enum(INDICES).optional().describe("Currency index. Omit for all of them.")
   }
 }, async ({ index }) => {
   try {
@@ -149,16 +208,16 @@ server.registerTool("list_markets", {
     const entries = index
       ? (d.indices[index] ? [[index, d.indices[index]]] : [])
       : Object.entries(d.indices);
-    if (!entries.length) return text(`${index} is not published in the current fixing.`);
+    if (!entries.length) return text(`${index} is not published in the current fixing. Treat it as unknown, not as zero.`);
 
     const out = entries.map(([label, ix]) =>
       `${label}\n` + ix.markets.map(m =>
         `  ${m.venue} ${m.asset}: borrow ${pct(m.borrow)}, supply ${pct(m.supply)}, `
-        + `utilisation ${pct(m.utilization)}, depth ${usd(m.depthUsd)}, weight ${(m.weight*100).toFixed(1)}%`
-        + (m.protocolYield ? `, plus ${pct(m.protocolYield)} protocol yield from the asset itself` : "")
+        + `utilization ${pct(m.utilization)}, depth ${usd(m.depthUsd)}, weight ${(m.weight * 100).toFixed(1)}%`
+        + (m.protocolYield ? `, plus ${pct(m.protocolYield)} protocol yield from holding the asset, not from the loan` : "")
       ).join("\n")).join("\n\n");
-    return text(out + `\n\nSource: ${BASE}/api/v1/latest.json`);
-  } catch(e){ return fail(e); }
+    return text([freshness(d), "", out, "", `Source: ${BASE}/api/v1/latest.json`].join("\n"));
+  } catch (e) { return fail(e); }
 });
 
 /* ------------------------------------------------------------------ */
@@ -168,58 +227,93 @@ server.registerTool("get_history", {
   title: "Get the SBOR history",
   description:
     "Daily fixings since the index began. Use this to see whether a rate is " +
-    "unusual, or how the cost of capital has moved.",
+    "unusual, or how the cost of capital has moved. Means are given per " +
+    "methodology version, never across a change in how the number is built.",
   inputSchema: {
-    index: z.enum(["SBOR-USD","SBOR-BTC","SBOR-STX"]).describe("Which currency."),
-    days: z.number().int().min(1).max(365).optional().describe("How many days back. Default 30.")
+    index: z.enum(INDICES).describe("Which currency."),
+    days: z.number().int().min(1).max(200).optional().describe("How many days back, up to 200. Default 30.")
   }
 }, async ({ index, days = 30 }) => {
   try {
     const h = await getJson("/api/v1/history.json", 300_000);
-    const cutoff = new Date(Date.now() - days*864e5).toISOString().slice(0,10);
-    const rows = h.filter(r => r.date >= cutoff && r[index]);
+    const cutoff = new Date(Date.now() - days * 864e5).toISOString().slice(0, 10);
+    const rows = h.filter(r => r.date >= cutoff && r[index]).sort((p, q) => p.date.localeCompare(q.date));
     if (!rows.length) return text(`No ${index} fixings in the last ${days} days.`);
 
     const lines = rows.map(r => {
       const e = r[index];
       if (e.withdrawn) return `${r.date}: withdrawn. ${e.reason}`;
-      return `${r.date}: borrow ${pct(e.borrow)}, supply ${pct(e.supply)}`;
+      return `${r.date}: borrow ${pct(e.borrow)}, supply ${pct(e.supply)}${r.methodologyVersion ? `  (v${r.methodologyVersion})` : "  (version not recorded)"}`;
     });
-    const withdrawn = rows.filter(r => r[index].withdrawn).length;
-    const valid = rows.filter(r => !r[index].withdrawn && typeof r[index].borrow === "number");
-    const avg = valid.length
-      ? (valid.reduce((a,r)=>a+r[index].borrow,0)/valid.length).toFixed(2) : null;
+
+    const valid = rows.filter(r => !r[index].withdrawn && Number.isFinite(r[index].borrow));
+    const withdrawn = rows.length - rows.filter(r => !r[index].withdrawn).length;
+
+    /* A mean across a methodology change averages two different definitions of
+       the same number, so it is given per version instead. */
+    const byVersion = {};
+    for (const r of valid) {
+      const v = r.methodologyVersion ?? "not recorded";
+      (byVersion[v] ||= []).push(r[index].borrow);
+    }
+    const versions = Object.keys(byVersion);
+    const means = versions.map(v => {
+      const xs = byVersion[v];
+      return `  v${v}: ${(xs.reduce((a, b) => a + b, 0) / xs.length).toFixed(2)}% over ${xs.length} fixing${xs.length > 1 ? "s" : ""}`;
+    });
+
     return text([
       `${index}, last ${days} days, ${rows.length} fixings`,
       ...lines,
-      withdrawn ? `\n${withdrawn} fixing${withdrawn>1?"s":""} in this window ${withdrawn>1?"were":"was"} withdrawn and ${withdrawn>1?"are":"is"} excluded from the mean. Withdrawn fixings stay in the record rather than being deleted.` : "",
-      avg ? `\nSimple mean borrow over the period: ${avg}%. For a compounded term average use get_rate, which carries termAverages once a full window exists.` : ""
+      withdrawn ? `\n${withdrawn} withdrawn fixing${withdrawn > 1 ? "s are" : " is"} kept in the record and excluded from every mean.` : "",
+      versions.length > 1
+        ? `\nThis window spans ${versions.length} methodology versions, so there is no single mean. Mean borrow by version:\n${means.join("\n")}`
+        : valid.length ? `\nSimple mean borrow over the period: ${means[0].split(": ")[1]}` : "",
+      `\nFor a compounded term average use get_rate, which carries termAverages once a full window exists.`
     ].filter(Boolean).join("\n"));
-  } catch(e){ return fail(e); }
+  } catch (e) { return fail(e); }
 });
 
 /* ------------------------------------------------------------------ */
 /* 5. how does Stacks compare                                          */
 /* ------------------------------------------------------------------ */
 server.registerTool("compare_chains", {
-  title: "Compare Stacks rates against the largest lending market elsewhere",
+  title: "Compare Stacks rates against the same markets on other chains",
   description:
-    "Reference rates from Aave V3 on Ethereum for the same asset classes, " +
-    "published beside the Stacks indices. Context only: these are never " +
-    "constituents of an SBOR index.",
-  inputSchema: {}
-}, async () => {
+    "The same asset classes on the largest lending markets on Ethereum, Base, " +
+    "Hyperliquid and Solana, plus SOFR, the US repo rate. Context only: none of " +
+    "these is ever a constituent of an SBOR index, and the other chains come from " +
+    "DefiLlama rather than contract state, so small differences are expected.",
+  inputSchema: {
+    index: z.enum(INDICES).optional().describe("Only markets comparable to this index. Omit for all.")
+  }
+}, async ({ index }) => {
   try {
     const d = await getJson("/api/v1/latest.json");
-    if (!d.externalReference) return text("No external reference in the current fixing.");
-    const ext = d.externalReference.markets.map(m =>
-      `${m.venue} ${m.asset}: borrow ${pct(m.borrow)}, supply ${pct(m.supply)}, `
-      + `utilisation ${pct(m.utilization)}, depth ${usd(m.depthUsd)} (compare with ${m.comparableTo})`
-    ).join("\n");
-    const stacks = Object.entries(d.indices).map(([l,ix]) =>
-      `${l}: borrow ${pct(ix.borrow)}, supply ${pct(ix.supply)}`).join("\n");
-    return text(`Stacks\n${stacks}\n\nElsewhere\n${ext}\n\n${d.externalReference.note}`);
-  } catch(e){ return fail(e); }
+    const all = d.externalReference?.markets ?? [];
+    const ext = (index ? all.filter(m => m.comparableTo === index) : all).map(m =>
+      `  ${m.venue} ${m.asset}: borrow ${pct(m.borrow)}, supply ${pct(m.supply)}, `
+      + `utilization ${pct(m.utilization)}, depth ${usd(m.depthUsd)}`
+    );
+    const stacks = Object.entries(d.indices)
+      .filter(([l]) => !index || l === index)
+      .map(([l, ix]) => `  ${l}: borrow ${pct(ix.borrow)}, supply ${pct(ix.supply)}`);
+
+    const s = d.context?.sofr;
+    const sofr = s && (!index || index === "SBOR-USD")
+      ? `SOFR, the overnight US repo rate secured by US government debt: ${pct(s.rate)} for ${s.effectiveDate}.`
+        + (Number.isFinite(s.average30day) ? ` Averages: 30 day ${pct(s.average30day)}, 90 day ${pct(s.average90day)}, 180 day ${pct(s.average180day)}.` : "")
+        + ` A cheaper rate on Stacks reflects lower utilization, not lower risk.`
+      : "";
+
+    return text([
+      freshness(d), "",
+      "Stacks", ...stacks, "",
+      ext.length ? "Elsewhere" : "", ...ext, ext.length ? "" : "",
+      sofr,
+      d.externalReference?.note ?? ""
+    ].filter((x, i, arr) => x !== "" || (arr[i - 1] !== "" && i > 0)).join("\n").trim());
+  } catch (e) { return fail(e); }
 });
 
 /* ------------------------------------------------------------------ */
@@ -234,10 +328,13 @@ server.registerTool("get_methodology", {
   inputSchema: {}
 }, async () => {
   try {
-    const r = await fetch(`${BASE}/llms.txt`, { headers:{ "user-agent":UA } });
+    const r = await fetch(`${BASE}/llms.txt`, {
+      headers: { "user-agent": UA },
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    });
     if (!r.ok) throw new Error(`llms.txt responded ${r.status}`);
     return text(await r.text());
-  } catch(e){ return fail(e); }
+  } catch (e) { return fail(e); }
 });
 
 await server.connect(new StdioServerTransport());