@defipipe/mcp 0.1.0 → 0.1.1

package/dist/http.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/http.js

@@ -0,0 +1,49 @@
+/** Remote MCP entry (mcp.defipipe.io): stateless Streamable HTTP behind Caddy.
+ * A fresh server+transport per request (SDK stateless guidance) so concurrent
+ * clients cannot cross request ids; the catalog cache is module-level in
+ * server.ts and survives across requests. */
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { buildServer } from "./server.js";
+const PORT = Number(process.env.MCP_PORT ?? 3002);
+const httpServer = createServer(async (req, res) => {
+    const path = new URL(req.url ?? "/", "http://localhost").pathname;
+    if (path === "/health") {
+        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true }));
+        return;
+    }
+    if (path !== "/" && path !== "/mcp") {
+        res.writeHead(404).end();
+        return;
+    }
+    if (req.method !== "POST") {
+        res
+            .writeHead(405, { "content-type": "application/json", allow: "POST" })
+            .end(JSON.stringify({ error: "stateless MCP endpoint: POST JSON-RPC here", docs: "https://defipipe.io/docs#mcp" }));
+        return;
+    }
+    try {
+        const chunks = [];
+        for await (const c of req)
+            chunks.push(c);
+        const body = JSON.parse(Buffer.concat(chunks).toString() || "{}");
+        const server = buildServer();
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    }
+    catch (e) {
+        if (!res.headersSent) {
+            res
+                .writeHead(500, { "content-type": "application/json" })
+                .end(JSON.stringify({ error: e.message }));
+        }
+    }
+});
+httpServer.listen(PORT, "127.0.0.1", () => {
+    console.error(`defipipe mcp: streamable http on 127.0.0.1:${PORT}`);
+});

package/dist/index.js

@@ -1,133 +1,5 @@
 #!/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";
+/** stdio entry (npx @defipipe/mcp): local MCP for Claude Code/Desktop/Cowork. */
 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());
+import { buildServer } from "./server.js";
+await buildServer().connect(new StdioServerTransport());

package/dist/server.d.ts

@@ -0,0 +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,
+ * and tier entitlements. Set DEFIPIPE_API_KEY for keyed tiers; the free tier
+ * works without one. */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function buildServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,157 @@
+/** 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 { 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.1";
+function headers() {
+    return KEY ? { authorization: `Bearer ${KEY}` } : {};
+}
+/** Fetch a defipipe endpoint. Non-2xx returns the API's JSON error body as a
+ * tool error (tier/upgrade/retry hints intact); network-level failures return
+ * an equally actionable error instead of a bare "fetch failed". Agents recover
+ * from actionable errors; they flail on bare ones. */
+async function apiGet(url) {
+    try {
+        const res = await fetch(url, { headers: headers() });
+        const text = await res.text();
+        return { ok: res.ok, text };
+    }
+    catch (e) {
+        return { ok: false, text: networkError(url, e) };
+    }
+}
+function networkError(url, e) {
+    const cause = e.cause?.code ?? e.message;
+    return JSON.stringify({
+        error: "network_unreachable",
+        endpoint: url,
+        cause,
+        hint: "The defipipe API could not be reached from this environment. If you are in a " +
+            "sandbox, its network allowlist likely blocks api.defipipe.io/defipipe.io; " +
+            "otherwise retry, and check https://defipipe.io/docs if it persists.",
+    });
+}
+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;
+}
+export function buildServer() {
+    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 }) => {
+        let datasets;
+        try {
+            datasets = await loadCatalog();
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: networkError(`${SITE}/api/search-index`, e) }], isError: true };
+        }
+        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" }] };
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defipipe/mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",