@defipipe/mcp 0.2.0 → 0.3.0

package/README.md

@@ -28,8 +28,8 @@ Or in any MCP client config:
 }
 ```
 
-`DEFIPIPE_API_KEY` is optional: without it you run on the free tier (aligned queries at 5m
-resolution and coarser, trailing 90 days, no raw rows). Keys come from the
+`DEFIPIPE_API_KEY` is optional: without it you run on the free tier (5m resolution and
+coarser, trailing 90 days). Keys come from the
 [dashboard](https://defipipe.io/dashboard); tiers are on the
 [pricing page](https://defipipe.io/pricing).
 
@@ -38,9 +38,8 @@ resolution and coarser, trailing 90 days, no raw rows). Keys come from the
 | Tool | What it does |
 |---|---|
 | `search_datasets` | Search the catalog (protocol, metric, category). Returns datasets with their canonical series IDs. |
-| `get_aligned` | Up to 10 series resampled onto one shared UTC time axis. Last value at or before each boundary: no interpolation, no lookahead, safe for backtests. |
-| `get_series_raw` | Raw per-block rows for one series: `[block_number, block_timestamp, value_raw, value_decimal]` with the exact uint256 value as a string. Requires an API key. |
-| `get_limits` | Machine-readable entitlements for the current credential: rate limits, allowed frequencies, history window. |
+| `get_data` | Up to 10 series on one shared UTC time grid at any granularity (block to 1d). Every point is a real on-chain observation and returns both the exact raw integer (uint256-safe string) and the unit-scaled float, plus the scaling metadata (unit, decimals) so the arithmetic is auditable. Pages via a `next` cursor. |
+| `get_limits` | Machine-readable entitlements for the current credential: rate limits, allowed frequencies, history window, page size. |
 
 Plus a `defipipe://docs` resource with the full API reference as markdown.
 

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 /** MCP server for defipipe (stdio). Thin wrapper over the public HTTPS API:
- * search the dataset catalog, query aligned time series, raw per-block rows,
+ * search the dataset catalog, query observations for one or more series on a
+ * shared time grid (raw integers + curated floats, self-describing units),
  * and tier entitlements. Set DEFIPIPE_API_KEY for keyed tiers; the free tier
  * works without one. */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/server.js

@@ -1,5 +1,6 @@
 /** MCP server for defipipe (stdio). Thin wrapper over the public HTTPS API:
- * search the dataset catalog, query aligned time series, raw per-block rows,
+ * search the dataset catalog, query observations for one or more series on a
+ * shared time grid (raw integers + curated floats, self-describing units),
  * and tier entitlements. Set DEFIPIPE_API_KEY for keyed tiers; the free tier
  * works without one. */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -7,7 +8,7 @@ import { z } from "zod";
 const API = process.env.DEFIPIPE_API_URL ?? "https://api.defipipe.io";
 const SITE = process.env.DEFIPIPE_SITE_URL ?? "https://defipipe.io";
 const KEY = process.env.DEFIPIPE_API_KEY;
-const VERSION = "0.2.0";
+const VERSION = "0.3.0";
 function headers() {
     return KEY ? { authorization: `Bearer ${KEY}` } : {};
 }
@@ -58,14 +59,15 @@ export function buildServer() {
     server.registerTool("search_datasets", {
         title: "Search defipipe datasets",
         description: "Search the defipipe catalog of historical per-block DeFi datasets. Returns matching " +
-            "datasets with their canonical series IDs, which are the inputs to get_aligned and " +
-            "get_series_raw. Omit the query to list every dataset.",
+            "datasets with their canonical series IDs, which are the inputs to get_data. " +
+            "Omit the query to list every dataset.",
         inputSchema: {
             query: z
                 .string()
                 .optional()
                 .describe("Case-insensitive match against protocol, label, category, and metrics (e.g. 'aave', 'borrow rate', 'lending')"),
         },
+        annotations: { readOnlyHint: true },
     }, async ({ query }) => {
         let datasets;
         try {
@@ -91,20 +93,31 @@ export function buildServer() {
             content: [{ type: "text", text: JSON.stringify({ count: out.length, datasets: out }, null, 2) }],
         };
     });
-    server.registerTool("get_aligned", {
-        title: "Query aligned time series",
-        description: "Resample up to 10 series onto one shared UTC time axis (GET /v1/aligned). Timeframe " +
-            "and granularity are explicit: pick from/to and a freq from the ladder; freq=block " +
-            "returns one row per sampled block (max ~16h per request, API key required). Each " +
-            "value is the last observation at or before the boundary: no interpolation, no " +
-            "lookahead, safe for backtests. Free tier: 5m and coarser, trailing 90 days.",
+    server.registerTool("get_data", {
+        title: "Query historical DeFi data",
+        description: "Observations for up to 10 series on one shared UTC time grid (GET /v1/data). " +
+            "Timeframe and granularity are explicit: pick from/to and a freq from the ladder; " +
+            "freq=block returns one row per sampled block. Every point at every freq is a real " +
+            "on-chain observation (last observation at or before each boundary; never an " +
+            "average): no interpolation, no lookahead, safe for backtests. Each series returns " +
+            "values (unit-scaled floats), raw (the exact on-chain integers as strings — " +
+            "uint256-safe), blocks (per-point source block), and its scaling metadata " +
+            "(unit, decimals, note), so the arithmetic behind every float is auditable. " +
+            "Derived series (kind=derived) are computed at query time and expose their formula " +
+            "instead of raw. Windows larger than one page return a `next` cursor: pass it back " +
+            "as `cursor` and keep the other params identical until next is null. " +
+            "Free tier: 5m and coarser, trailing 90 days; block/1m need an API key; full " +
+            "history needs quant.",
         inputSchema: {
             series: z.array(z.string()).min(1).max(10).describe("Canonical series IDs (from search_datasets)"),
             freq: z.enum(["block", "1m", "5m", "15m", "1h", "4h", "1d", "7d"]).describe("Granularity. block and 1m require an API key."),
-            from: z.string().describe("ISO 8601 start of the timeframe, e.g. 2026-07-07"),
+            from: z.string().describe("ISO 8601 start of the timeframe, e.g. 2026-07-09"),
             to: z.string().describe("ISO 8601 end of the timeframe, e.g. 2026-07-12"),
+            cursor: z.string().optional().describe("The `next` value from the previous page, verbatim"),
+            limit: z.number().int().min(1).optional().describe("Points per page (capped by tier page size)"),
         },
-    }, async ({ series, freq, from, to }) => {
+        annotations: { readOnlyHint: true },
+    }, async ({ series, freq, from, to, cursor, limit }) => {
         const p = new URLSearchParams({ series: series.join(",") });
         if (freq)
             p.set("freq", freq);
@@ -112,40 +125,19 @@ export function buildServer() {
             p.set("from", from);
         if (to)
             p.set("to", to);
-        return toolResult(await apiGet(`${API}/v1/aligned?${p}`));
-    });
-    server.registerTool("get_series_raw", {
-        title: "Query raw per-block rows",
-        description: "Raw per-block rows for one series (GET /v1/series/:id). Each row is " +
-            "[block_number, block_timestamp, value_raw, value_decimal]; value_raw is the exact " +
-            "uint256-safe on-chain value as a string. Requires an API key (DEFIPIPE_API_KEY). " +
-            "Paginate by passing the response's next_after_block as after_block.",
-        inputSchema: {
-            id: z.string().describe("Canonical series ID"),
-            from: z.string().describe("ISO 8601 start of the timeframe, e.g. 2026-07-11"),
-            to: z.string().describe("ISO 8601 end of the timeframe, e.g. 2026-07-12"),
-            after_block: z.number().int().optional().describe("Pagination cursor: only rows with a strictly greater block number"),
-            limit: z.number().int().min(1).max(10000).optional().describe("Rows per page, default 1,000"),
-        },
-    }, async ({ id, from, to, after_block, limit }) => {
-        const p = new URLSearchParams();
-        if (from)
-            p.set("from", from);
-        if (to)
-            p.set("to", to);
-        if (after_block !== undefined)
-            p.set("after_block", String(after_block));
+        if (cursor)
+            p.set("cursor", cursor);
         if (limit !== undefined)
             p.set("limit", String(limit));
-        const qs = p.size ? `?${p}` : "";
-        return toolResult(await apiGet(`${API}/v1/series/${encodeURIComponent(id)}${qs}`));
+        return toolResult(await apiGet(`${API}/v1/data?${p}`));
     });
     server.registerTool("get_limits", {
         title: "Check tier entitlements",
         description: "Machine-readable entitlements for the current credential (GET /v1/limits): rate " +
-            "limits, allowed frequencies, raw-row access, and history window. Call this before " +
+            "limits, allowed frequencies, history window, and page size. Call this before " +
             "large pulls instead of discovering limits through 429s.",
         inputSchema: {},
+        annotations: { readOnlyHint: true },
     }, async () => toolResult(await apiGet(`${API}/v1/limits`)));
     server.registerResource("docs", "defipipe://docs", {
         title: "defipipe API reference",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defipipe/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server for defipipe: historical, point-in-time DeFi contract state per block. Search datasets, query aligned time series and raw per-block rows.",
   "license": "MIT",
   "type": "module",