@defipipe/mcp 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @defipipe/mcp
+
+MCP server for [defipipe](https://defipipe.io): historical, point-in-time DeFi contract
+state. What read functions returned at every Ethereum block (Aave rates, Uniswap prices,
+Lido supply), served as canonical per-block time series.
+
+Gives any MCP client (Claude Code, Claude Desktop, Cursor, ...) tools to search the dataset
+catalog and query aligned time series without leaving the conversation. The free tier works
+with no API key.
+
+## Setup
+
+```sh
+claude mcp add defipipe -- npx -y @defipipe/mcp
+```
+
+Or in any MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "defipipe": {
+      "command": "npx",
+      "args": ["-y", "@defipipe/mcp"],
+      "env": { "DEFIPIPE_API_KEY": "dp_..." }
+    }
+  }
+}
+```
+
+`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
+[dashboard](https://defipipe.io/dashboard); tiers are on the
+[pricing page](https://defipipe.io/pricing).
+
+## Tools
+
+| 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. |
+
+Plus a `defipipe://docs` resource with the full API reference as markdown.
+
+## Series IDs
+
+Every series is named by one canonical ID:
+
+```
+{chain}:{protocol}:{version}:{instance}[/{scope}]:{kind}:{metric}
+```
+
+For example, the Aave V3 WETH variable borrow rate:
+
+```
+eth:aave:v3:0x87870bca3f3fd6335c3f4ce8392d69350b4fa4e2/weth:call:getreservedata[currentvariableborrowrate]
+```
+
+Use `search_datasets` to find IDs, or browse the [catalog](https://defipipe.io/datasets).
+
+## Environment
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DEFIPIPE_API_KEY` | none (free tier) | Bearer token for Analyst/Quant tiers |
+| `DEFIPIPE_API_URL` | `https://api.defipipe.io` | API base override |
+| `DEFIPIPE_SITE_URL` | `https://defipipe.io` | Catalog/docs base override |
+
+## Related
+
+- [API docs](https://defipipe.io/docs) ([markdown](https://defipipe.io/docs.md))
+- Python SDK: `pip install defipipe`

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/** MCP server for defipipe (stdio). Thin wrapper over the public HTTPS API:
+ * search the dataset catalog, query aligned time series, raw per-block rows,
+ * and tier entitlements. Set DEFIPIPE_API_KEY for keyed tiers; the free tier
+ * works without one. */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+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.1.0";
+function headers() {
+    return KEY ? { authorization: `Bearer ${KEY}` } : {};
+}
+/** Fetch a defipipe endpoint; on non-2xx return the API's JSON error body as a
+ * tool error so agents see tier/upgrade/retry hints instead of a bare throw. */
+async function apiGet(url) {
+    const res = await fetch(url, { headers: headers() });
+    const text = await res.text();
+    return { ok: res.ok, text };
+}
+function toolResult(r) {
+    return {
+        content: [{ type: "text", text: r.text }],
+        isError: !r.ok,
+    };
+}
+let catalogCache = null;
+async function loadCatalog() {
+    if (catalogCache && Date.now() - catalogCache.at < 5 * 60_000)
+        return catalogCache.datasets;
+    const res = await fetch(`${SITE}/api/search-index`);
+    if (!res.ok)
+        throw new Error(`catalog fetch failed: ${res.status}`);
+    const body = (await res.json());
+    catalogCache = { at: Date.now(), datasets: body.datasets };
+    return body.datasets;
+}
+const server = new McpServer({ name: "defipipe", version: VERSION });
+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.",
+    inputSchema: {
+        query: z
+            .string()
+            .optional()
+            .describe("Case-insensitive match against protocol, label, category, and metrics (e.g. 'aave', 'borrow rate', 'lending')"),
+    },
+}, async ({ query }) => {
+    const datasets = await loadCatalog();
+    const q = query?.toLowerCase().trim();
+    const hits = !q
+        ? datasets
+        : datasets.filter((d) => [d.ns, d.label, d.category, ...d.metrics, ...d.series.map((s) => s.metric)]
+            .join(" ")
+            .toLowerCase()
+            .includes(q));
+    const out = hits.map((d) => ({
+        dataset: `${d.ns} · ${d.label}`,
+        category: d.category,
+        page: `${SITE}${d.href}`,
+        series: d.series,
+    }));
+    return {
+        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). Each value " +
+        "is the last observation at or before the interval boundary: no interpolation, no " +
+        "lookahead, safe for backtests. Free tier: 5m resolution and coarser, trailing 90 days.",
+    inputSchema: {
+        series: z.array(z.string()).min(1).max(10).describe("Canonical series IDs (from search_datasets)"),
+        freq: z.enum(["1m", "5m", "15m", "1h", "4h", "1d", "7d"]).optional().describe("Bar size, default 1h. 1m requires an API key."),
+        from: z.string().optional().describe("ISO 8601 start, default: to minus 7 days"),
+        to: z.string().optional().describe("ISO 8601 end, default: now"),
+    },
+}, async ({ series, freq, from, to }) => {
+    const p = new URLSearchParams({ series: series.join(",") });
+    if (freq)
+        p.set("freq", freq);
+    if (from)
+        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().optional().describe("ISO 8601 start, default: to minus 24 hours"),
+        to: z.string().optional().describe("ISO 8601 end, default: now"),
+        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 (limit !== undefined)
+        p.set("limit", String(limit));
+    const qs = p.size ? `?${p}` : "";
+    return toolResult(await apiGet(`${API}/v1/series/${encodeURIComponent(id)}${qs}`));
+});
+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 " +
+        "large pulls instead of discovering limits through 429s.",
+    inputSchema: {},
+}, async () => toolResult(await apiGet(`${API}/v1/limits`)));
+server.registerResource("docs", "defipipe://docs", {
+    title: "defipipe API reference",
+    description: "Full API reference as markdown: series-ID grammar, endpoints, tiers, errors, Python SDK.",
+    mimeType: "text/markdown",
+}, async (uri) => {
+    const res = await fetch(`${SITE}/docs.md`);
+    return { contents: [{ uri: uri.href, text: await res.text(), mimeType: "text/markdown" }] };
+});
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@defipipe/mcp",
+  "version": "0.1.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",
+  "bin": {
+    "defipipe-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "mcp",
+    "defi",
+    "historical-data",
+    "time-series",
+    "ethereum"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^5.9.3"
+  },
+  "homepage": "https://defipipe.io/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yosefcevallos/defipipe.git",
+    "directory": "packages/mcp"
+  }
+}