@lendwise/mcp 0.1.0

package/dist/core/optimizer.js

@@ -0,0 +1,77 @@
+import { OPTIMIZER_ENDPOINT } from './config.js';
+import { ApiError, postJson } from './http.js';
+/**
+ * Map the solver's positional result back onto the productIds it was built
+ * from. `apys[i]` must be the APY of `productIds[i]` — that invariant is the
+ * caller's to hold, and `buildApyVector` is the only supported way to get it.
+ */
+export function mapAllocations(productIds, apys, allocations, amountUsd) {
+    return allocations.flatMap((a) => {
+        const productId = productIds[a.vault_index];
+        const apy = apys[a.vault_index];
+        // A vault_index outside the array we sent means the request and response
+        // disagree about the market set. Dropping it is the only safe move — the
+        // alternative is attributing money to an unknown market.
+        if (productId === undefined || apy === undefined)
+            return [];
+        return [
+            {
+                productId,
+                apy,
+                allocationPercent: a.allocation_percent,
+                amountUsd: amountUsd * (a.allocation_percent / 100),
+            },
+        ];
+    });
+}
+/**
+ * Build the positional APY vector for `productIds`, in that exact order.
+ * Products with no finite APY in the snapshot are reported as missing rather
+ * than defaulted to 0 — a 0 would silently tell the solver "this market is
+ * worthless" instead of "we don't know".
+ */
+export function buildApyVector(productIds, latestApyByProduct) {
+    const apys = [];
+    const found = [];
+    const missing = [];
+    for (const id of productIds) {
+        const apy = latestApyByProduct.get(id);
+        if (apy === undefined || !Number.isFinite(apy)) {
+            missing.push(id);
+            continue;
+        }
+        apys.push(apy);
+        found.push(id);
+    }
+    return { apys, found, missing };
+}
+/** Blended APY of an allocation — the portfolio's weighted mean. */
+export function blendedApy(allocations) {
+    const totalPercent = allocations.reduce((a, x) => a + x.allocationPercent, 0);
+    if (totalPercent === 0)
+        return 0;
+    return (allocations.reduce((a, x) => a + x.apy * x.allocationPercent, 0) /
+        totalPercent);
+}
+/**
+ * Call the solver through the Lendwise proxy — never optimizer.lendwise.fi directly.
+ *
+ * The response is VALIDATED, not cast. A solver that answers 200 with
+ * `success: false` (or without `allocations` at all) would otherwise blow up
+ * inside `mapAllocations`, or — worse — be reported to the user as a valid
+ * allocation of $0 across their markets.
+ */
+export async function optimizeVaults(apy, diversification) {
+    const body = await postJson(OPTIMIZER_ENDPOINT, { endpoint: '/optimize/vaults', data: { apy, diversification } }, 'The optimizer');
+    if (body.success !== true) {
+        throw new ApiError('The optimizer could not find an allocation for these markets.');
+    }
+    if (!Array.isArray(body.allocations)) {
+        throw new ApiError('The optimizer returned a malformed allocation.');
+    }
+    return {
+        success: true,
+        allocations: body.allocations,
+        resulting_diversification: body.resulting_diversification ?? diversification,
+    };
+}

package/dist/core/server.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Register the five tools on a server instance.
+ *
+ * Both transports go through this one function: the stdio binary builds its own
+ * server, while mcp-handler hands us one it constructed. If registration lived in
+ * only one of those paths, the hosted and local servers would drift apart in what
+ * they expose.
+ */
+export declare function registerTools(server: McpServer): McpServer;
+/** Build a fully-registered server. Used by the stdio entrypoint. */
+export declare function createServer(): McpServer;

package/dist/core/server.js

@@ -0,0 +1,115 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { RateLimitedError } from './graphql/client.js';
+import { findBestMarkets, findBestMarketsArgs, } from './tools/find-best-markets.js';
+import { getMarketDetails, getMarketDetailsArgs, } from './tools/get-market-details.js';
+import { getMarketHistory, getMarketHistoryArgs, } from './tools/get-market-history.js';
+import { listMarketUniverse, listMarketUniverseArgs, } from './tools/list-market-universe.js';
+import { optimizeAllocation, optimizeAllocationArgs, } from './tools/optimize-allocation.js';
+const VERSION = '0.1.0';
+/**
+ * Run a tool and render its result as MCP text content.
+ *
+ * A 429 is surfaced as an explicitly retryable error carrying the wait — the
+ * agent has to back off, not hammer the endpoint the rate limit exists to
+ * protect. Everything else is returned as `isError` text so the model can read
+ * what went wrong and correct itself, rather than the transport throwing.
+ */
+async function run(handler, args) {
+    try {
+        const result = await handler(args);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (error) {
+        if (error instanceof RateLimitedError) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: 'rate_limited',
+                            retryable: true,
+                            retryAfterSeconds: error.retryAfterSeconds,
+                            message: error.message,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: 'tool_failed',
+                        retryable: false,
+                        message: error instanceof Error ? error.message : String(error),
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Register the five tools on a server instance.
+ *
+ * Both transports go through this one function: the stdio binary builds its own
+ * server, while mcp-handler hands us one it constructed. If registration lived in
+ * only one of those paths, the hosted and local servers would drift apart in what
+ * they expose.
+ */
+export function registerTools(server) {
+    // Every tool is read-only and non-destructive, but reaches the public internet.
+    const readOnly = {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    };
+    server.registerTool('list_market_universe', {
+        title: 'List the market universe',
+        description: 'List every asset, chain and protocol that Lendwise actually tracks, ' +
+            'with market counts. Call this FIRST — the filter values for ' +
+            'find_best_markets must come from here, not from memory.',
+        inputSchema: listMarketUniverseArgs,
+        annotations: readOnly,
+    }, (args) => run(listMarketUniverse, args));
+    server.registerTool('find_best_markets', {
+        title: 'Find the best supply markets',
+        description: 'Rank current supply markets by net APY. Filtering and sorting run ' +
+            'server-side against the latest snapshot. Defaults to markets with at ' +
+            'least $1M TVL, because a thin market’s headline APY is mostly noise.',
+        inputSchema: findBestMarketsArgs,
+        annotations: readOnly,
+    }, (args) => run(findBestMarkets, args));
+    server.registerTool('get_market_details', {
+        title: 'Get market details',
+        description: 'Full detail for one market: protocol metadata, accepted collaterals, ' +
+            'and the current APY split into base / rewards / fees with individual ' +
+            'reward items.',
+        inputSchema: getMarketDetailsArgs,
+        annotations: readOnly,
+    }, (args) => run(getMarketDetails, args));
+    server.registerTool('get_market_history', {
+        title: 'Get market APY history',
+        description: 'Daily net-APY history for one market plus mean / stddev / min / max. ' +
+            'Use this before committing to a market over a long horizon: it is what ' +
+            'separates a durable yield from a temporary reward spike.',
+        inputSchema: getMarketHistoryArgs,
+        annotations: readOnly,
+    }, (args) => run(getMarketHistory, args));
+    server.registerTool('optimize_allocation', {
+        title: 'Optimize an allocation',
+        description: 'Split an amount across chosen markets to maximise yield at a target ' +
+            'diversification, returning per-market amounts, the blended APY and a ' +
+            'projected 6-month yield.',
+        inputSchema: optimizeAllocationArgs,
+        annotations: readOnly,
+    }, (args) => run(optimizeAllocation, args));
+    return server;
+}
+/** Build a fully-registered server. Used by the stdio entrypoint. */
+export function createServer() {
+    return registerTools(new McpServer({ name: 'lendwise', version: VERSION }));
+}

package/dist/core/stats.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Descriptive stats over a daily APY series.
+ *
+ * This is the whole point of `get_market_history`: over a 6-month horizon, a
+ * durable 6% and a 12% that is a reward spike ending next week look identical
+ * from a single snapshot. Standard deviation is what separates them.
+ */
+export interface Stats {
+    mean: number;
+    stddev: number;
+    min: number;
+    max: number;
+    /** Number of finite observations the stats were computed from. */
+    count: number;
+}
+/**
+ * Drop non-finite values. Postgres `double precision` can hold NaN (a bad
+ * upstream APR→APY conversion lands there), and NaN poisons every downstream
+ * number — a mean of NaN is worse than a missing mean, because it looks like an
+ * answer.
+ */
+export declare function finiteOnly(values: readonly (number | null | undefined)[]): number[];
+/** Population standard deviation. Returns null when there is nothing finite to describe. */
+export declare function stats(values: readonly (number | null | undefined)[]): Stats | null;

package/dist/core/stats.js

@@ -0,0 +1,31 @@
+/**
+ * Descriptive stats over a daily APY series.
+ *
+ * This is the whole point of `get_market_history`: over a 6-month horizon, a
+ * durable 6% and a 12% that is a reward spike ending next week look identical
+ * from a single snapshot. Standard deviation is what separates them.
+ */
+/**
+ * Drop non-finite values. Postgres `double precision` can hold NaN (a bad
+ * upstream APR→APY conversion lands there), and NaN poisons every downstream
+ * number — a mean of NaN is worse than a missing mean, because it looks like an
+ * answer.
+ */
+export function finiteOnly(values) {
+    return values.filter((v) => typeof v === 'number' && Number.isFinite(v));
+}
+/** Population standard deviation. Returns null when there is nothing finite to describe. */
+export function stats(values) {
+    const xs = finiteOnly(values);
+    if (xs.length === 0)
+        return null;
+    const mean = xs.reduce((a, b) => a + b, 0) / xs.length;
+    const variance = xs.reduce((acc, x) => acc + (x - mean) ** 2, 0) / xs.length;
+    return {
+        mean,
+        stddev: Math.sqrt(variance),
+        min: Math.min(...xs),
+        max: Math.max(...xs),
+        count: xs.length,
+    };
+}

package/dist/core/tools/find-best-markets.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export declare const findBestMarketsArgs: {
+    asset: z.ZodOptional<z.ZodString>;
+    chainId: z.ZodOptional<z.ZodNumber>;
+    protocol: z.ZodOptional<z.ZodEnum<{
+        aave: "aave";
+        morpho: "morpho";
+        compound: "compound";
+    }>>;
+    minTvlUsd: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+};
+/**
+ * Current best supply markets by net APY. Reads the server-side latest-snapshot
+ * query, so the ranking and the TVL floor are both applied in Postgres — this
+ * never pages the catalogue and reduces client-side.
+ */
+export declare function findBestMarkets(raw: unknown): Promise<{
+    disclaimer: string;
+    warning?: string | undefined;
+    hint?: string | undefined;
+    query: {
+        asset: string | undefined;
+        chainId: number | undefined;
+        protocol: "aave" | "morpho" | "compound" | undefined;
+        minTvlUsd: number;
+        limit: number;
+    };
+    matched: number;
+    returned: number;
+    markets: import("./shared.js").DescribedMarket[];
+}>;

package/dist/core/tools/find-best-markets.js

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { DEFAULT_MIN_TVL_USD, NOT_ADVICE } from '../config.js';
+import { gql } from '../graphql/client.js';
+import { LATEST_SUPPLY_APY, } from '../graphql/queries.js';
+import { describeRow, isUnreliable } from './shared.js';
+export const findBestMarketsArgs = {
+    asset: z
+        .string()
+        .optional()
+        .describe('Asset symbol, e.g. USDC. Must come from list_market_universe.'),
+    chainId: z.number().int().optional().describe('Chain ID, e.g. 1 for Ethereum.'),
+    protocol: z
+        .enum(['aave', 'morpho', 'compound'])
+        .optional()
+        .describe('Protocol provider.'),
+    minTvlUsd: z
+        .number()
+        .nonnegative()
+        .default(DEFAULT_MIN_TVL_USD)
+        .describe('Minimum supplied TVL in USD. Defaults to $1M — in a thinner market the ' +
+        'headline APY is mostly noise. Lower it deliberately, not by accident.'),
+    limit: z.number().int().min(1).max(50).default(10),
+};
+const Args = z.object(findBestMarketsArgs);
+/**
+ * Current best supply markets by net APY. Reads the server-side latest-snapshot
+ * query, so the ranking and the TVL floor are both applied in Postgres — this
+ * never pages the catalogue and reduces client-side.
+ */
+export async function findBestMarkets(raw) {
+    const { asset, chainId, protocol, minTvlUsd, limit } = Args.parse(raw);
+    const data = await gql(LATEST_SUPPLY_APY, {
+        filters: { asset, chainId, protocol, minTvlUsd },
+        first: limit,
+    });
+    const { items, pagination } = data.latestSupplyApy;
+    const markets = items.map(describeRow);
+    return {
+        query: { asset, chainId, protocol, minTvlUsd, limit },
+        matched: pagination.countTotal,
+        returned: markets.length,
+        markets,
+        ...(markets.length === 0
+            ? {
+                hint: 'No market matched. Check the filter values against ' +
+                    'list_market_universe, or lower minTvlUsd.',
+            }
+            : {}),
+        ...(markets.some(isUnreliable)
+            ? {
+                warning: 'Some markets are flagged unreliable (incomplete data for the ' +
+                    'current hour). Treat their APY as provisional.',
+            }
+            : {}),
+        disclaimer: NOT_ADVICE,
+    };
+}

package/dist/core/tools/get-market-details.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+export declare const getMarketDetailsArgs: {
+    productId: z.ZodString;
+};
+/** Full picture of one market: registry entry, collaterals, and the APY breakdown. */
+export declare function getMarketDetails(raw: unknown): Promise<{
+    productId: string;
+    found: boolean;
+    hint: string;
+    disclaimer: string;
+} | {
+    disclaimer: string;
+    warning?: string | undefined;
+    found: boolean;
+    product: {
+        productId: string;
+        kind: string;
+        asset: {
+            symbol: string;
+            name: string;
+            address: string;
+            decimals: number;
+        };
+        protocol: {
+            provider: string;
+            market: string;
+            type: string;
+            version: string;
+            chain: {
+                id: number;
+                name: string;
+            };
+            address: string;
+            meta: unknown;
+        };
+        collaterals: {
+            symbol: string;
+            name: string;
+            ltv: number | null;
+            lltv: number;
+            canBeCollateral: boolean;
+        }[] | null;
+    };
+    current: {
+        rewardItems: {
+            token: string;
+            apy: number | null;
+            source: string;
+            program: string | null;
+        }[];
+        productId: string;
+        asset: string;
+        chain: string;
+        chainId: number;
+        protocol: string;
+        market: string;
+        apy: {
+            net: number | null;
+            base: number | null;
+            rewards: number | null;
+            fees: number | null;
+        };
+        tvlUsd: number | null;
+        utilizationRate: number | null;
+        asOf: string;
+        quality: {
+            status: string;
+            slots: string;
+            reliable: boolean;
+        };
+    } | null;
+    productId?: undefined;
+    hint?: undefined;
+}>;

package/dist/core/tools/get-market-details.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { NOT_ADVICE } from '../config.js';
+import { gql } from '../graphql/client.js';
+import { MARKET_DETAILS, } from '../graphql/queries.js';
+import { describeRow, finite } from './shared.js';
+export const getMarketDetailsArgs = {
+    productId: z
+        .string()
+        .min(1)
+        .describe('Exact productId from find_best_markets, e.g. ' +
+        'aave:v3:ethereum:reserve:0x…:supply'),
+};
+const Args = z.object(getMarketDetailsArgs);
+/** Full picture of one market: registry entry, collaterals, and the APY breakdown. */
+export async function getMarketDetails(raw) {
+    const { productId } = Args.parse(raw);
+    const data = await gql(MARKET_DETAILS, { productId });
+    const product = data.products.items[0];
+    // A productId is either a supply or a borrow product; exactly one of these
+    // carries a row. Taking only the supply side would flag every healthy borrow
+    // market as a stalled pipeline.
+    const snapshot = data.latestSupplyApy.items[0] ?? data.latestBorrowApy.items[0];
+    if (!product) {
+        return {
+            productId,
+            found: false,
+            hint: 'No product with that id. productIds are exact — take one from ' +
+                'find_best_markets rather than composing it by hand.',
+            disclaimer: NOT_ADVICE,
+        };
+    }
+    return {
+        found: true,
+        product: {
+            productId: product.id,
+            kind: product.kind,
+            asset: product.asset,
+            protocol: {
+                provider: product.protocol.provider,
+                market: product.protocol.name,
+                type: product.protocol.type,
+                version: product.protocol.version,
+                chain: product.protocol.chain,
+                address: product.protocol.address,
+                meta: product.protocol.meta,
+            },
+            collaterals: product.collaterals,
+        },
+        // A product with no reading in the last 6 hours has a stale or stalled
+        // pipeline; report the absence rather than an old number.
+        current: snapshot
+            ? {
+                ...describeRow(snapshot),
+                rewardItems: (snapshot.apy.rewardItems ?? []).map((r) => ({
+                    token: r.token.symbol,
+                    apy: finite(r.apy),
+                    source: r.source,
+                    program: r.program,
+                })),
+            }
+            : null,
+        ...(snapshot
+            ? {}
+            : {
+                warning: 'No APY snapshot in the last 6 hours for this product — its data ' +
+                    'pipeline may have stalled. Do not assume a previous value still holds.',
+            }),
+        disclaimer: NOT_ADVICE,
+    };
+}

package/dist/core/tools/get-market-history.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+export declare const getMarketHistoryArgs: {
+    productId: z.ZodString;
+    range: z.ZodDefault<z.ZodEnum<{
+        "7d": "7d";
+        "30d": "30d";
+        "90d": "90d";
+        "180d": "180d";
+    }>>;
+};
+/**
+ * Daily net-APY series plus its mean / stddev / min / max.
+ *
+ * The stats are the deliverable, not the series. A snapshot cannot distinguish a
+ * durable 6% from a 12% reward spike that ends next week; a 180-day standard
+ * deviation can. That is the signal a 6-month horizon actually needs.
+ */
+export declare function getMarketHistory(raw: unknown): Promise<{
+    productId: string;
+    range: "7d" | "30d" | "90d" | "180d";
+    observations: number;
+    hint: string;
+    disclaimer: string;
+    netApy?: undefined;
+    interpretation?: undefined;
+    series?: undefined;
+} | {
+    productId: string;
+    range: "7d" | "30d" | "90d" | "180d";
+    observations: number;
+    netApy: {
+        mean: number;
+        stddev: number;
+        min: number;
+        max: number;
+    };
+    interpretation: string;
+    series: {
+        date: string;
+        net: number | null;
+    }[];
+    disclaimer: string;
+    hint?: undefined;
+}>;

package/dist/core/tools/get-market-history.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { NOT_ADVICE } from '../config.js';
+import { gql } from '../graphql/client.js';
+import { MARKET_HISTORY } from '../graphql/queries.js';
+import { stats } from '../stats.js';
+export const getMarketHistoryArgs = {
+    productId: z.string().min(1).describe('Exact productId from find_best_markets.'),
+    range: z
+        .enum(['7d', '30d', '90d', '180d'])
+        .default('90d')
+        .describe('How far back to look. Use 180d for a 6-month horizon.'),
+};
+const Args = z.object(getMarketHistoryArgs);
+/**
+ * Daily net-APY series plus its mean / stddev / min / max.
+ *
+ * The stats are the deliverable, not the series. A snapshot cannot distinguish a
+ * durable 6% from a 12% reward spike that ends next week; a 180-day standard
+ * deviation can. That is the signal a 6-month horizon actually needs.
+ */
+export async function getMarketHistory(raw) {
+    const { productId, range } = Args.parse(raw);
+    const data = await gql(MARKET_HISTORY, { productId, range });
+    const items = data.supplyApyDaily.items;
+    // Non-finite APYs (Postgres double precision can hold NaN) are dropped, not
+    // returned — a NaN in a series poisons every stat computed from it.
+    const netStats = stats(items.map((d) => d.apy.net));
+    if (!netStats) {
+        return {
+            productId,
+            range,
+            observations: 0,
+            hint: 'No usable daily history for this product in that range. It may be ' +
+                'newly tracked — try a shorter range.',
+            disclaimer: NOT_ADVICE,
+        };
+    }
+    return {
+        productId,
+        range,
+        observations: netStats.count,
+        netApy: {
+            mean: netStats.mean,
+            stddev: netStats.stddev,
+            min: netStats.min,
+            max: netStats.max,
+        },
+        interpretation: netStats.mean > 0 && netStats.stddev / Math.abs(netStats.mean) > 0.5
+            ? 'Volatile: the spread is large relative to the mean, so the current ' +
+                'APY is a poor predictor of what you would actually earn.'
+            : 'Relatively stable over this window.',
+        series: items.map((d) => ({
+            date: d.date,
+            net: Number.isFinite(d.apy.net) ? d.apy.net : null,
+        })),
+        disclaimer: NOT_ADVICE,
+    };
+}

package/dist/core/tools/list-market-universe.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+export declare const listMarketUniverseArgs: {
+    kind: z.ZodDefault<z.ZodEnum<{
+        supply: "supply";
+        borrow: "borrow";
+    }>>;
+};
+/**
+ * The discovery call. Every other tool takes an asset / chain / protocol filter,
+ * and an agent that guesses those gets an empty result and no idea why. This
+ * returns the values that actually exist, with counts, so it never has to guess.
+ */
+export declare function listMarketUniverse(raw: unknown): Promise<{
+    kind: "supply" | "borrow";
+    totalProducts: number;
+    assets: {
+        symbol: string;
+        markets: number;
+    }[];
+    chains: {
+        chainId: number;
+        name: string;
+        markets: number;
+    }[];
+    protocols: {
+        name: string;
+        markets: number;
+    }[];
+    usage: string;
+    disclaimer: string;
+}>;

package/dist/core/tools/list-market-universe.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { NOT_ADVICE } from '../config.js';
+import { gql } from '../graphql/client.js';
+import { PRODUCT_FACETS } from '../graphql/queries.js';
+export const listMarketUniverseArgs = {
+    kind: z
+        .enum(['supply', 'borrow'])
+        .default('supply')
+        .describe('Which side of the market to enumerate.'),
+};
+const Args = z.object(listMarketUniverseArgs);
+/**
+ * The discovery call. Every other tool takes an asset / chain / protocol filter,
+ * and an agent that guesses those gets an empty result and no idea why. This
+ * returns the values that actually exist, with counts, so it never has to guess.
+ */
+export async function listMarketUniverse(raw) {
+    const { kind } = Args.parse(raw);
+    const data = await gql(PRODUCT_FACETS, {
+        filters: { kind, active: true },
+    });
+    const { assets, chains, protocols } = data.productFacets;
+    return {
+        kind,
+        totalProducts: protocols.reduce((a, p) => a + p.count, 0),
+        assets: assets.map((a) => ({ symbol: a.symbol, markets: a.count })),
+        chains: chains.map((c) => ({ chainId: c.id, name: c.name, markets: c.count })),
+        protocols: protocols.map((p) => ({ name: p.name, markets: p.count })),
+        usage: 'Use these exact values as the asset / chainId / protocol filters for ' +
+            'find_best_markets. Any other value will match nothing.',
+        disclaimer: NOT_ADVICE,
+    };
+}