@panoptic-eng/mcp 0.1.0

package/dist/server--YF2LHqv.js

@@ -0,0 +1,1140 @@
+import { DEFAULT_VEGOID, MAX_TICK, MIN_TICK, STANDARD_TICK_WIDTHS, WAD, createMemoryStorage, createTokenIdBuilder, decodeTokenId, getAccountBuyingPower, getAccountCollateral, getAccountGreeks, getAccountHistory, getAccountPremia, getChainDeployment, getDeltaHedgeParams, getLegDelta, getMarginBuffer, getNetLiquidationValues, getOpenPositionPreview, getPool, getPoolDeploymentBlock, getPoolLiquidities, getPositions, getTrackedPositionIds, hasLoanOrCredit, hasLongLeg, isCall, isCreditLeg, isLiquidatable, isLoanLeg, isShortOnly, isSpread, scanChunks, simulateClosePosition, syncPositions } from "@panoptic-eng/sdk/v2";
+import { createPublicClient, getAddress, http, isAddress, keccak256, toBytes, toHex } from "viem";
+import { base, mainnet, sepolia } from "viem/chains";
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+//#region src/config.ts
+/** viem chain definitions (carry the Multicall3 address the SDK reads rely on). */
+const VIEM_CHAINS = {
+	[mainnet.id]: mainnet,
+	[base.id]: base,
+	[sepolia.id]: sepolia
+};
+/** Chain ids Panoptic has deployments for (mainnet, Base, Sepolia). */
+const KNOWN_CHAIN_IDS = [
+	mainnet.id,
+	base.id,
+	sepolia.id
+];
+/**
+* Resolve an optional user-supplied chain-id string to a trusted known-chain
+* constant, falling back to `fallback` when omitted/blank. Matches on canonical
+* decimal form only (never Number(), so "1e0" is rejected) and throws on
+* unsupported ids.
+*/
+function resolveChainId(rawChainId, fallback) {
+	if (rawChainId === void 0 || rawChainId.trim() === "") return fallback;
+	const chainId = KNOWN_CHAIN_IDS.find((id) => id.toString() === rawChainId.trim());
+	if (chainId === void 0) throw new Error(`Unsupported chain id ${rawChainId}. Supported: ${KNOWN_CHAIN_IDS.join(", ")}.`);
+	return chainId;
+}
+var ConfigError = class extends Error {};
+/**
+* Resolve server config from CLI flags (`--rpc-url`, `--chain-id`,
+* `--subgraph-url`) layered over env (`PANOPTIC_RPC_URL`, `PANOPTIC_CHAIN_ID`,
+* `PANOPTIC_SUBGRAPH_URL`). CLI flags win. Throws a readable error when RPC URL
+* or chain id is missing or unsupported.
+*/
+function resolveConfig(argv, env) {
+	const flags = parseFlags(argv);
+	const rpcUrl = flags["rpc-url"] ?? env.PANOPTIC_RPC_URL;
+	if (!rpcUrl) throw new ConfigError("Missing RPC URL. Set PANOPTIC_RPC_URL or pass --rpc-url <url>.");
+	const rawChainId = flags["chain-id"] ?? env.PANOPTIC_CHAIN_ID;
+	if (!rawChainId) throw new ConfigError("Missing chain id. Set PANOPTIC_CHAIN_ID or pass --chain-id <id>.");
+	const chainId = KNOWN_CHAIN_IDS.find((id) => id.toString() === rawChainId.trim());
+	if (chainId === void 0 || getChainDeployment(chainId) === void 0) throw new ConfigError(`Unsupported chain id ${rawChainId}. Supported: ${KNOWN_CHAIN_IDS.join(", ")}.`);
+	const subgraphUrl = flags["subgraph-url"] ?? env.PANOPTIC_SUBGRAPH_URL ?? void 0;
+	return {
+		rpcUrl,
+		chainId,
+		subgraphUrl
+	};
+}
+/** Create the shared context (viem client + resolved deployment) for tools. */
+async function createContext(config) {
+	const deployment = getChainDeployment(config.chainId);
+	if (deployment === void 0) throw new ConfigError(`Unsupported chain id ${config.chainId}`);
+	const client = createPublicClient({
+		chain: VIEM_CHAINS[config.chainId],
+		transport: http(config.rpcUrl)
+	});
+	const rpcChainId = await client.getChainId();
+	if (rpcChainId !== config.chainId) throw new ConfigError(`RPC chain id ${rpcChainId} does not match configured chain id ${config.chainId}. Point PANOPTIC_RPC_URL at a chain-${config.chainId} endpoint or set PANOPTIC_CHAIN_ID to ${rpcChainId}.`);
+	return {
+		config,
+		client,
+		deployment
+	};
+}
+function parseFlags(argv) {
+	const flags = {};
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (!arg.startsWith("--")) continue;
+		const key = arg.slice(2);
+		const eq = key.indexOf("=");
+		if (eq !== -1) flags[key.slice(0, eq)] = key.slice(eq + 1);
+		else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) flags[key] = argv[++i];
+		else flags[key] = "true";
+	}
+	return flags;
+}
+
+//#endregion
+//#region src/address.ts
+/**
+* Validate and checksum-normalize a user-supplied account address, throwing the
+* shared "Invalid address" error on malformed input. Centralizes the identical
+* isAddress/getAddress dance every account-scoped tool performs.
+*/
+function parseAccountAddress(address) {
+	if (!isAddress(address)) throw new Error(`Invalid address: ${address}`);
+	return getAddress(address);
+}
+
+//#endregion
+//#region src/serialize.ts
+/**
+* Recursively convert a value into a JSON-safe form. The only Panoptic-specific
+* invariant here: **bigints become decimal strings** (never JS numbers), so
+* on-chain quantities survive serialization without precision loss. Functions
+* are dropped; everything else passes through. `_meta` blocks are ordinary
+* nested objects and are handled by the recursion.
+*/
+function toJsonSafe(value) {
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "function") return void 0;
+	if (Array.isArray(value)) return value.map((v) => {
+		const serialized = toJsonSafe(v);
+		return serialized === void 0 ? null : serialized;
+	});
+	if (value !== null && typeof value === "object") {
+		const out = {};
+		for (const [k, v] of Object.entries(value)) {
+			const serialized = toJsonSafe(v);
+			if (serialized !== void 0) out[k] = serialized;
+		}
+		return out;
+	}
+	return value;
+}
+/** MCP tool result wrapping a serialized value as pretty JSON text. */
+function jsonResult(value) {
+	const text = JSON.stringify(toJsonSafe(value), null, 2) ?? "null";
+	return { content: [{
+		type: "text",
+		text
+	}] };
+}
+/**
+* Deterministic JSON with sorted object keys, so an envelope always hashes to
+* the same value regardless of field insertion order.
+*/
+function canonicalStringify(value) {
+	if (Array.isArray(value)) return `[${value.map(canonicalStringify).join(",")}]`;
+	if (value !== null && typeof value === "object") {
+		const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonicalStringify(v)}`);
+		return `{${entries.join(",")}}`;
+	}
+	return JSON.stringify(value);
+}
+/**
+* Build the unsigned transaction envelope every build/write-like tool returns.
+* The server never signs; it hands back this object plus `envelopeHash` so a
+* downstream signer can verify it signs exactly what was simulated and shown.
+*/
+function buildEnvelope(input) {
+	const canonical = {
+		summary: input.summary,
+		risk: input.risk,
+		chainId: input.chainId.toString(),
+		to: input.to,
+		value: input.value.toString(),
+		data: input.data,
+		simulation: toJsonSafe(input.simulation)
+	};
+	const envelopeHash = keccak256(toBytes(canonicalStringify(canonical)));
+	return {
+		...canonical,
+		envelopeHash
+	};
+}
+
+//#endregion
+//#region src/tools/positions.ts
+const STABLE_SYMBOL = /^(usdc|usdt|usdbc|usds|usde|dai|frax|lusd|gusd|tusd|pyusd)$/i;
+/**
+* Resolve which token is the directional "asset" (non-numeraire). An explicit
+* override wins; otherwise the stablecoin side is treated as the numeraire and
+* the other token as the asset (defaulting to token0 if neither looks stable).
+*/
+function inferAssetIndex(pool, override) {
+	if (override !== void 0) return {
+		asset: override === 0 ? 0n : 1n,
+		inferred: false
+	};
+	if (STABLE_SYMBOL.test(pool.collateralTracker0.symbol)) return {
+		asset: 1n,
+		inferred: true
+	};
+	if (STABLE_SYMBOL.test(pool.collateralTracker1.symbol)) return {
+		asset: 0n,
+		inferred: true
+	};
+	return {
+		asset: 0n,
+		inferred: true
+	};
+}
+/**
+* Discover an account's open position ids on the configured pool via the SDK's
+* event-scan sync into a fresh in-memory store — no subgraph required. Returns
+* the populated storage so greeks reads (which read synced positions from
+* storage) can reuse it.
+*/
+const syncCache = new Map();
+async function syncAccountPositions(ctx, account, fromBlock) {
+	const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
+	const chainId = BigInt(ctx.config.chainId);
+	const cacheKey = `${chainId}:${poolAddress}:${account}:${fromBlock ?? "default"}`;
+	const cached = syncCache.get(cacheKey);
+	if (cached) return cached;
+	const pending = (async () => {
+		const storage = createMemoryStorage();
+		await syncPositions({
+			client: ctx.client,
+			chainId,
+			poolAddress,
+			account,
+			storage,
+			fromBlock
+		});
+		const tokenIds = await getTrackedPositionIds({
+			chainId,
+			poolAddress,
+			account,
+			storage
+		});
+		return {
+			poolAddress,
+			chainId,
+			tokenIds,
+			storage
+		};
+	})();
+	syncCache.set(cacheKey, pending);
+	pending.catch(() => syncCache.delete(cacheKey));
+	return pending;
+}
+
+//#endregion
+//#region src/tools/accountHealth.ts
+function registerAccountHealth(server, ctx) {
+	server.registerTool("account_health", {
+		title: "Assess Panoptic account health",
+		description: "An account's margin status on the configured pool — buying power, margin buffer / distance to liquidation, and whether the account is currently liquidatable. Discovers positions via an on-chain event scan (no subgraph).",
+		inputSchema: {
+			address: z.string().describe("The account address."),
+			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
+		}
+	}, async ({ address, fromBlock }) => {
+		const account = parseAccountAddress(address);
+		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
+		const { poolAddress, tokenIds } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		const [buyingPower, marginBuffer, liquidation] = await Promise.all([
+			getAccountBuyingPower({
+				client: ctx.client,
+				poolAddress,
+				account,
+				tokenIds
+			}),
+			getMarginBuffer({
+				client: ctx.client,
+				poolAddress,
+				account,
+				tokenIds,
+				queryAddress
+			}),
+			isLiquidatable({
+				client: ctx.client,
+				poolAddress,
+				account,
+				tokenIds
+			})
+		]);
+		return jsonResult({
+			account,
+			pool: poolAddress,
+			openTokenIds: tokenIds,
+			buyingPower,
+			marginBuffer,
+			liquidation
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/advisePosition.ts
+const NEAR_LIQUIDATION_TICKS = 500n;
+function analyzeLeg(leg, currentTick) {
+	const side = leg.isLong ? "long" : "short";
+	if (leg.width === 0n) return {
+		index: leg.index,
+		kind: isLoanLeg(leg) ? "loan" : isCreditLeg(leg) ? "credit" : "loan",
+		side,
+		strike: leg.strike,
+		width: leg.width,
+		tickLower: leg.tickLower,
+		tickUpper: leg.tickUpper,
+		inRange: null,
+		moneyness: null
+	};
+	const call = isCall(leg.tokenType, leg.asset === 0n);
+	const inRange = currentTick >= leg.tickLower && currentTick <= leg.tickUpper;
+	let moneyness;
+	if (currentTick === leg.strike) moneyness = "ATM";
+	else if (call) moneyness = currentTick > leg.strike ? "ITM" : "OTM";
+	else moneyness = currentTick < leg.strike ? "ITM" : "OTM";
+	return {
+		index: leg.index,
+		kind: call ? "call" : "put",
+		side,
+		strike: leg.strike,
+		width: leg.width,
+		tickLower: leg.tickLower,
+		tickUpper: leg.tickUpper,
+		inRange,
+		moneyness
+	};
+}
+function registerAdvisePosition(server, ctx) {
+	server.registerTool("advise_position", {
+		title: "Advise on managing a position",
+		description: "Given a position TokenId and its owner, pull live on-chain state and advise on managing it. Covers: short options that have gone ITM/underwater (roll vs close vs hold), long options (streamia decay, out-of-range/force-exercise exposure), whether the position can be closed right now (simulated, with the decoded reason if not), and collateral/liquidation risk. Always returns the grounded facts; adds a recommendation only when the situation is clear-cut.",
+		inputSchema: {
+			tokenId: z.string().describe("The position TokenId, as a 0x-hex or decimal string. Pass it verbatim."),
+			address: z.string().describe("The position owner address."),
+			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
+		}
+	}, async ({ tokenId, address, fromBlock }) => {
+		if (!isAddress(address)) throw new Error(`Invalid address: ${address}`);
+		const account = getAddress(address);
+		let id;
+		try {
+			id = BigInt(tokenId.trim());
+		} catch {
+			throw new Error(`Invalid tokenId (expected a 0x-hex or decimal string): ${tokenId}`);
+		}
+		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
+		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
+		const chainId = BigInt(ctx.config.chainId);
+		const pool = await getPool({
+			client: ctx.client,
+			poolAddress,
+			chainId,
+			stateViewAddress: ctx.deployment.infrastructure.stateView
+		});
+		const decoded = decodeTokenId(id);
+		const legs = decoded.legs.map((leg) => analyzeLeg(leg, pool.currentTick));
+		const { tokenIds } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		const owned = tokenIds.some((t) => t === id);
+		const idList = owned ? tokenIds : [...tokenIds, id];
+		const [{ positions }, premia, marginBuffer, liquidation] = await Promise.all([
+			getPositions({
+				client: ctx.client,
+				poolAddress,
+				owner: account,
+				tokenIds: [id]
+			}),
+			getAccountPremia({
+				client: ctx.client,
+				poolAddress,
+				account,
+				tokenIds: [id]
+			}),
+			getMarginBuffer({
+				client: ctx.client,
+				poolAddress,
+				account,
+				tokenIds: idList,
+				queryAddress
+			}),
+			isLiquidatable({
+				client: ctx.client,
+				poolAddress,
+				account,
+				tokenIds: idList
+			})
+		]);
+		const position = positions[0] ?? null;
+		let closeable = null;
+		let closeBlockedReason = null;
+		if (position) {
+			const sim = await simulateClosePosition({
+				client: ctx.client,
+				poolAddress,
+				account,
+				positionIdList: idList,
+				tokenId: id,
+				positionSize: position.positionSize,
+				tickLimitLow: MIN_TICK,
+				tickLimitHigh: MAX_TICK
+			});
+			closeable = sim.success;
+			if (!sim.success && sim.error) closeBlockedReason = {
+				name: sim.error.name,
+				message: sim.error.message
+			};
+		}
+		const recommendations = [];
+		if (!owned) recommendations.push(`Address ${account} does not appear to hold this TokenId (not in its open-position scan). Facts below reflect the decoded TokenId and pool, but position-level data may be empty.`);
+		if (liquidation.isLiquidatable) recommendations.push("Account is liquidatable RIGHT NOW — add collateral or reduce position size immediately to avoid liquidation.");
+		else if (marginBuffer.liquidationDistance !== null && marginBuffer.liquidationDistance < NEAR_LIQUIDATION_TICKS && marginBuffer.liquidationDistance > -NEAR_LIQUIDATION_TICKS) recommendations.push(`Close to a liquidation boundary (~${marginBuffer.liquidationDistance} ticks away). Consider adding collateral or trimming size before the price moves further.`);
+		if (closeable === false) recommendations.push(`This position cannot be closed at the moment${closeBlockedReason ? ` (${closeBlockedReason.name})` : ""}. For a long leg this usually means the in-range liquidity needed to unwind it has been withdrawn — check chunk_spread / liquidity_map and retry when liquidity returns; otherwise the pool may be in a restricted safety mode.`);
+		for (const leg of legs) {
+			if (leg.kind === "loan" || leg.kind === "credit") continue;
+			if (leg.side === "short" && leg.moneyness === "ITM") recommendations.push(`Leg ${leg.index}: your short ${leg.kind} is ITM (price moved through strike ${leg.strike}). You are paying out streamia and carry pin/assignment risk — consider rolling the strike out or closing if you don't want continued directional exposure.`);
+			else if (leg.side === "long" && leg.inRange === false) recommendations.push(`Leg ${leg.index}: your long ${leg.kind} is out-of-range/OTM. It is decaying (you pay streamia) and out-of-range longs can be force-exercised by others — consider closing to reclaim capital.`);
+		}
+		return jsonResult({
+			tokenId: id,
+			tokenIdHex: toHex(id),
+			owner: account,
+			owned,
+			pool: {
+				address: poolAddress,
+				currentTick: pool.currentTick,
+				tickSpacing: pool.tickSpacing,
+				health: pool.healthStatus,
+				token0: pool.collateralTracker0.symbol,
+				token1: pool.collateralTracker1.symbol
+			},
+			legs,
+			position,
+			streamia: {
+				shortPremium0: premia.shortPremium0,
+				shortPremium1: premia.shortPremium1,
+				longPremium0: premia.longPremium0,
+				longPremium1: premia.longPremium1,
+				note: "shortPremium = streamia earned by short legs; longPremium = streamia paid by long legs (token0/token1)."
+			},
+			health: {
+				isLiquidatable: liquidation.isLiquidatable,
+				liquidationDistanceTicks: marginBuffer.liquidationDistance,
+				lowerLiquidationTick: marginBuffer.lowerLiquidationTick,
+				upperLiquidationTick: marginBuffer.upperLiquidationTick,
+				buffer0: marginBuffer.buffer0,
+				buffer1: marginBuffer.buffer1
+			},
+			closeable,
+			closeBlockedReason,
+			recommendations
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/chunkSpread.ts
+const DEFAULT_TIMESCALE = "1D";
+const DEFAULT_SCAN_HALFSPAN = 6000n;
+/** WAD-scaled spread → a plain multiplier rounded to 4 dp (1e18 → 1.0). */
+function toMultiplier(spreadWad) {
+	return Number(spreadWad * 10000n / WAD) / 1e4;
+}
+function clampTick$1(tick) {
+	if (tick < MIN_TICK) return MIN_TICK;
+	if (tick > MAX_TICK) return MAX_TICK;
+	return tick;
+}
+/** Floor a tick to the nearest lower multiple of `step`. */
+function alignDown(tick, step) {
+	return tick - (tick % step + step) % step;
+}
+function registerChunkSpread(server, ctx) {
+	server.registerTool("chunk_spread", {
+		title: "Chunk spread multipliers",
+		description: "Per-chunk spread multiplier across a tick range of the configured pool, via the SDK's scanChunks. The spread multiplier is the premium multiplier applied to a chunk: 1.0x means no liquidity has been removed (lowest implied vol) — those chunks are the CHEAPEST to BUY. A higher multiplier means more liquidity is already utilized, so the chunk pays a richer premium — those chunks are the most PROFITABLE to SELL. Reported per token type (0 and 1). Chunk width defaults to a standard timescale width (1H/1D/1W/1M/1Y ≈ ±1%/±4%/±13%/±27%/±112% price range).",
+		inputSchema: {
+			timescale: z.enum([
+				"1H",
+				"1D",
+				"1W",
+				"1M",
+				"1Y"
+			]).optional().describe(`Standard chunk width by expiry profile (STANDARD_TICK_WIDTHS). Defaults to ${DEFAULT_TIMESCALE}. Ignored if 'width' is given.`),
+			width: z.number().int().positive().safe().optional().describe("Explicit chunk width in ticks (rounded down to a multiple of tick spacing). Overrides timescale."),
+			tickLower: z.string().optional().describe("Lower tick bound (decimal string). Defaults to a band below the current tick."),
+			tickUpper: z.string().optional().describe("Upper tick bound (decimal string). Defaults to a band above the current tick."),
+			vegoid: z.number().int().positive().optional().describe(`VEGOID constant used in the spread formula. Defaults to ${DEFAULT_VEGOID}.`)
+		}
+	}, async ({ timescale, width, tickLower, tickUpper, vegoid }) => {
+		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
+		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
+		const pool = await getPool({
+			client: ctx.client,
+			poolAddress,
+			chainId: BigInt(ctx.config.chainId),
+			stateViewAddress: ctx.deployment.infrastructure.stateView
+		});
+		const resolvedTimescale = timescale ?? DEFAULT_TIMESCALE;
+		const rawWidth = width !== void 0 ? BigInt(width) : STANDARD_TICK_WIDTHS[resolvedTimescale];
+		const chunkWidth = rawWidth < pool.tickSpacing ? pool.tickSpacing : rawWidth - rawWidth % pool.tickSpacing;
+		const vg = vegoid !== void 0 ? BigInt(vegoid) : DEFAULT_VEGOID;
+		const halfWidthsRaw = DEFAULT_SCAN_HALFSPAN / chunkWidth;
+		const halfWidths = halfWidthsRaw < 2n ? 2n : halfWidthsRaw;
+		const center = alignDown(pool.currentTick, chunkWidth);
+		const lower = tickLower !== void 0 ? alignDown(clampTick$1(BigInt(tickLower)), chunkWidth) : alignDown(clampTick$1(center - halfWidths * chunkWidth), chunkWidth);
+		const upper = tickUpper !== void 0 ? alignDown(clampTick$1(BigInt(tickUpper)), chunkWidth) : alignDown(clampTick$1(center + halfWidths * chunkWidth), chunkWidth);
+		const { chunks, _meta } = await scanChunks({
+			client: ctx.client,
+			poolAddress,
+			queryAddress,
+			tickLower: lower,
+			tickUpper: upper,
+			width: chunkWidth,
+			vegoid: vg
+		});
+		const rows = chunks.map((c) => ({
+			strike: c.strike,
+			distanceTicksFromCurrent: c.strike - pool.currentTick,
+			spreadMultiplier0: toMultiplier(c.spreadWad0),
+			spreadMultiplier1: toMultiplier(c.spreadWad1),
+			spreadWad0: c.spreadWad0,
+			spreadWad1: c.spreadWad1,
+			netLiquidity0: c.netLiquidity0,
+			removedLiquidity0: c.removedLiquidity0,
+			netLiquidity1: c.netLiquidity1,
+			removedLiquidity1: c.removedLiquidity1
+		}));
+		const peakMultiplier = (r) => Math.max(r.spreadMultiplier0, r.spreadMultiplier1);
+		const bestForSelling = [...rows].filter((r) => peakMultiplier(r) > 1).sort((a, b) => peakMultiplier(b) - peakMultiplier(a)).slice(0, 3).map((r) => ({
+			strike: r.strike,
+			peakMultiplier: peakMultiplier(r)
+		}));
+		const bestForBuying = [...rows].sort((a, b) => peakMultiplier(a) - peakMultiplier(b)).slice(0, 3).map((r) => ({
+			strike: r.strike,
+			peakMultiplier: peakMultiplier(r)
+		}));
+		return jsonResult({
+			pool: poolAddress,
+			currentTick: pool.currentTick,
+			tickSpacing: pool.tickSpacing,
+			timescale: width !== void 0 ? "custom" : resolvedTimescale,
+			width: chunkWidth,
+			vegoid: vg,
+			tickRange: {
+				lower,
+				upper
+			},
+			interpretation: "spreadMultiplier is the premium multiplier for the chunk. 1.0x = no liquidity removed (lowest IV) → cheapest to BUY. Higher = more liquidity utilized → richer premium → most profitable to SELL. token0/token1 suffixes are the two token types (put vs call side).",
+			recommendation: {
+				sellHere: bestForSelling.length ? bestForSelling : "No chunk currently carries a spread multiplier above 1.0x (no removed liquidity) — selling earns only the base premium everywhere in range.",
+				buyHere: bestForBuying
+			},
+			chunkCount: rows.length,
+			chunks: rows,
+			_meta
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/explainPosition.ts
+/** A coarse, human-readable label for the shape of a decoded position. */
+function classifyStrategy(tokenId, legCount) {
+	const parts = [`${legCount}-leg`];
+	if (isShortOnly(tokenId)) parts.push("short-only");
+	else if (hasLongLeg(tokenId)) parts.push("has-long-leg");
+	if (isSpread(tokenId)) parts.push("spread");
+	if (hasLoanOrCredit(tokenId)) parts.push("loan/credit");
+	return parts.join(" ");
+}
+function registerExplainPosition(server, _ctx) {
+	server.registerTool("explain_position", {
+		title: "Explain a Panoptic position",
+		description: "Decode a Panoptic TokenId into human-readable legs (asset, call/put, long/short, strike, width, ratio, risk partner) and a coarse strategy label. Pure decode — no RPC.",
+		inputSchema: { tokenId: z.string().describe("The position TokenId, as either a 0x-prefixed hex string (as seen on explorers / in calldata) or a decimal string. Pass it verbatim — do not convert.") }
+	}, async ({ tokenId }) => {
+		let id;
+		try {
+			id = BigInt(tokenId.trim());
+		} catch {
+			throw new Error(`Invalid tokenId (expected a 0x-hex or decimal string): ${tokenId}`);
+		}
+		if (id < 0n) throw new Error(`Invalid tokenId (must be non-negative): ${tokenId}`);
+		const decoded = decodeTokenId(id);
+		const strategy = classifyStrategy(id, decoded.legs.length);
+		return jsonResult({
+			tokenId: id,
+			tokenIdHex: toHex(id),
+			strategy,
+			decoded
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/getPortfolio.ts
+function registerGetPortfolio(server, ctx) {
+	server.registerTool("get_portfolio", {
+		title: "Get a Panoptic portfolio",
+		description: "An account's open positions on the configured pool — decoded legs, sizes, collateral balances, and net account greeks (delta/gamma/theta/vega). Discovers positions via an on-chain event scan (no subgraph).",
+		inputSchema: {
+			address: z.string().describe("The account address."),
+			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan. Defaults to the pool deployment block.")
+		}
+	}, async ({ address, fromBlock }) => {
+		const account = parseAccountAddress(address);
+		const { poolAddress, chainId, tokenIds, storage } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		const [positions, collateral, greeks] = await Promise.all([
+			getPositions({
+				client: ctx.client,
+				poolAddress,
+				owner: account,
+				tokenIds
+			}),
+			getAccountCollateral({
+				client: ctx.client,
+				poolAddress,
+				account
+			}),
+			getAccountGreeks({
+				client: ctx.client,
+				chainId,
+				poolAddress,
+				account,
+				storage
+			})
+		]);
+		return jsonResult({
+			account,
+			pool: poolAddress,
+			openTokenIds: tokenIds,
+			positions,
+			collateral,
+			greeks
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/hedgeParams.ts
+function registerHedgeParams(server, ctx) {
+	server.registerTool("hedge_params", {
+		title: "Delta-hedge parameters",
+		description: "Compute the SDK's delta-hedge parameters to reach a target delta (default delta-neutral). Two modes: whole-portfolio (pass `address` — current delta is read via getAccountGreeks over positions + deposited collateral) or single-position (pass `tokenId` + `positionSize`). Returns the hedge leg config, hedge amount, hedge type (loan), and whether to swap at mint. Read-only; it does not build or send anything.",
+		inputSchema: {
+			address: z.string().optional().describe("Account address for whole-portfolio hedging. Provide this OR tokenId."),
+			tokenId: z.string().optional().describe("TokenId (0x-hex or decimal) for single-position hedging. Requires positionSize."),
+			positionSize: z.string().optional().describe("Position size (decimal string). Required with tokenId."),
+			targetDelta: z.string().optional().describe("Target delta in asset smallest units. Defaults to 0 (delta-neutral)."),
+			assetIndex: z.union([z.literal(0), z.literal(1)]).optional().describe("Directional asset (0/1) for whole-portfolio mode. Defaults to inferring the non-stablecoin token."),
+			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
+		}
+	}, async ({ address, tokenId, positionSize, targetDelta, assetIndex, fromBlock }) => {
+		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
+		const chainId = BigInt(ctx.config.chainId);
+		let target;
+		try {
+			target = targetDelta !== void 0 ? BigInt(targetDelta) : 0n;
+		} catch {
+			throw new Error(`Invalid targetDelta (expected a decimal string): ${targetDelta}`);
+		}
+		if (tokenId !== void 0) {
+			if (positionSize === void 0) throw new Error("positionSize is required when hedging a single tokenId.");
+			let id;
+			let size;
+			try {
+				id = BigInt(tokenId.trim());
+			} catch {
+				throw new Error(`Invalid tokenId (expected a 0x-hex or decimal string): ${tokenId}`);
+			}
+			try {
+				size = BigInt(positionSize);
+			} catch {
+				throw new Error(`Invalid positionSize (expected a decimal string): ${positionSize}`);
+			}
+			const hedge$1 = await getDeltaHedgeParams({
+				client: ctx.client,
+				poolAddress,
+				chainId,
+				tokenId: id,
+				positionSize: size,
+				targetDelta: target
+			});
+			return jsonResult({
+				mode: "single",
+				tokenId: id,
+				positionSize: size,
+				targetDelta: target,
+				hedge: hedge$1
+			});
+		}
+		if (address === void 0) throw new Error("Provide either `address` (whole-portfolio) or `tokenId` + `positionSize` (single).");
+		if (!isAddress(address)) throw new Error(`Invalid address: ${address}`);
+		const account = getAddress(address);
+		const pool = await getPool({
+			client: ctx.client,
+			poolAddress,
+			chainId,
+			stateViewAddress: ctx.deployment.infrastructure.stateView
+		});
+		const { asset, inferred: assetInferred } = inferAssetIndex(pool, assetIndex);
+		let scanFromBlock;
+		try {
+			scanFromBlock = fromBlock ? BigInt(fromBlock) : void 0;
+		} catch {
+			throw new Error(`Invalid fromBlock (expected a decimal string): ${fromBlock}`);
+		}
+		const { tokenIds, storage } = await syncAccountPositions(ctx, account, scanFromBlock);
+		const greeks = await getAccountGreeks({
+			client: ctx.client,
+			chainId,
+			poolAddress,
+			account,
+			storage,
+			includeCollateral: true,
+			assetIndex: asset
+		});
+		const hedge = await getDeltaHedgeParams({
+			client: ctx.client,
+			poolAddress,
+			chainId,
+			currentDelta: greeks.totalDelta,
+			asset,
+			targetDelta: target
+		});
+		return jsonResult({
+			mode: "portfolio",
+			account,
+			pool: poolAddress,
+			assetIndex: asset,
+			assetSymbol: asset === 0n ? pool.collateralTracker0.symbol : pool.collateralTracker1.symbol,
+			assetInferred,
+			openTokenIds: tokenIds,
+			currentDelta: greeks.totalDelta,
+			targetDelta: target,
+			hedge
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/identifyAddress.ts
+function registerIdentifyAddress(server, ctx) {
+	server.registerTool("identify_address", {
+		title: "Identify a Panoptic address",
+		description: "Map an address to its role in a Panoptic deployment (pool, collateral tracker, factory, query, SFPM, risk engine, vault, manager, …) using the deployment registry. Returns \"unknown\" if unmatched.",
+		inputSchema: {
+			address: z.string().describe("The address to identify."),
+			chainId: z.string().optional().describe("Chain id (decimal string) to look up against. Defaults to the configured chain.")
+		}
+	}, async ({ address, chainId }) => {
+		const needle = parseAccountAddress(address);
+		const target = resolveChainId(chainId, ctx.config.chainId);
+		const dep = getChainDeployment(target);
+		if (dep === void 0) throw new Error(`Unsupported chain id ${target}`);
+		const candidates = {
+			panopticPool: dep.panoptic.pool.panopticPool,
+			collateralTracker0: dep.panoptic.pool.collateralTracker0,
+			collateralTracker1: dep.panoptic.pool.collateralTracker1,
+			...dep.panoptic.v2,
+			uniswapV3Factory: dep.infrastructure.uniswapV3Factory,
+			poolManager: dep.infrastructure.poolManager,
+			stateView: dep.infrastructure.stateView
+		};
+		const roles = Object.entries(candidates).filter(([, addr]) => isAddress(addr) && getAddress(addr) === needle).map(([role]) => role);
+		return jsonResult({
+			address: needle,
+			chainId: target,
+			roles: roles.length > 0 ? roles : ["unknown"]
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/liquidityMap.ts
+const DEFAULT_N_TICKS = 50n;
+function registerLiquidityMap(server, ctx) {
+	server.registerTool("liquidity_map", {
+		title: "Map pool liquidity",
+		description: "Tick liquidity distribution around a range of the configured pool. Defaults to a symmetric band centered on the current tick; override with startTick / nTicks.",
+		inputSchema: {
+			startTick: z.string().optional().describe("Starting tick (decimal string). Defaults to a band below the current tick."),
+			nTicks: z.string().optional().describe(`Number of ticks to query (decimal string). Defaults to ${DEFAULT_N_TICKS}.`)
+		}
+	}, async ({ startTick, nTicks }) => {
+		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
+		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
+		const chainId = BigInt(ctx.config.chainId);
+		const count = nTicks !== void 0 && nTicks.trim() !== "" ? BigInt(nTicks) : DEFAULT_N_TICKS;
+		const pool = await getPool({
+			client: ctx.client,
+			poolAddress,
+			chainId,
+			stateViewAddress: ctx.deployment.infrastructure.stateView
+		});
+		const start = startTick !== void 0 && startTick.trim() !== "" ? BigInt(startTick) : pool.currentTick - count / 2n * pool.tickSpacing;
+		const liquidities = await getPoolLiquidities({
+			client: ctx.client,
+			poolAddress,
+			queryAddress,
+			startTick: start,
+			nTicks: count
+		});
+		return jsonResult({
+			pool: poolAddress,
+			currentTick: pool.currentTick,
+			tickSpacing: pool.tickSpacing,
+			startTick: start,
+			nTicks: count,
+			liquidities
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/listPools.ts
+function registerListPools(server, ctx) {
+	server.registerTool("list_pools", {
+		title: "List Panoptic pools",
+		description: "The known Panoptic pool deployment for a chain (addresses from the deployment registry), hydrated with live on-chain state — tokens, current tick, collateral trackers, health — for the chain this server is configured against.",
+		inputSchema: { chainId: z.string().optional().describe("Chain id (decimal string) to look up. Defaults to the configured chain.") }
+	}, async ({ chainId }) => {
+		const target = resolveChainId(chainId, ctx.config.chainId);
+		const dep = getChainDeployment(target);
+		if (dep === void 0) throw new Error(`Unsupported chain id ${target}`);
+		const registry = {
+			chainId: target,
+			panopticPool: dep.panoptic.pool.panopticPool,
+			collateralTracker0: dep.panoptic.pool.collateralTracker0,
+			collateralTracker1: dep.panoptic.pool.collateralTracker1,
+			panopticQuery: dep.panoptic.v2.panopticQuery
+		};
+		if (target !== ctx.config.chainId) return jsonResult({
+			...registry,
+			note: `Live state unavailable: this server is configured for chain ${ctx.config.chainId}. Restart with --chain-id ${target} (and a matching RPC) to hydrate live state.`
+		});
+		const pool = await getPool({
+			client: ctx.client,
+			poolAddress: dep.panoptic.pool.panopticPool,
+			chainId: BigInt(target),
+			stateViewAddress: dep.infrastructure.stateView
+		});
+		return jsonResult({
+			...registry,
+			pool
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/positionScenario.ts
+const DEFAULT_SPAN = 2500n;
+const DEFAULT_POINTS = 25;
+function clampTick(tick) {
+	if (tick < MIN_TICK) return MIN_TICK;
+	if (tick > MAX_TICK) return MAX_TICK;
+	return tick;
+}
+/** Human token1-per-token0 price at a tick (display float; uses token decimals). */
+function priceAtTick(tick, decimals0, decimals1) {
+	return Math.pow(1.0001, Number(tick)) * 10 ** (Number(decimals0) - Number(decimals1));
+}
+function registerPositionScenario(server, ctx) {
+	server.registerTool("position_scenario", {
+		title: "Position payoff / NLV curve",
+		description: "An account's net liquidation value (NLV) across a band of hypothetical prices — the payoff curve that answers \"what is my P&L if price moves to X?\". Evaluates the on-chain NLV at each tick in a band (default ±2500 ticks ≈ ±28% around the current tick). NLV is returned in both token0 and token1 smallest units per point.",
+		inputSchema: {
+			address: z.string().describe("The account address."),
+			startTick: z.string().optional().describe("Band start tick (decimal string). Defaults to currentTick − 2500."),
+			endTick: z.string().optional().describe("Band end tick (decimal string). Defaults to currentTick + 2500."),
+			points: z.number().int().min(2).max(100).optional().describe(`Number of evenly spaced sample ticks. Defaults to ${DEFAULT_POINTS}.`),
+			includePendingPremium: z.boolean().optional().describe("Defaults to true."),
+			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
+		}
+	}, async ({ address, startTick, endTick, points, includePendingPremium, fromBlock }) => {
+		if (!isAddress(address)) throw new Error(`Invalid address: ${address}`);
+		const account = getAddress(address);
+		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
+		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
+		const pool = await getPool({
+			client: ctx.client,
+			poolAddress,
+			chainId: BigInt(ctx.config.chainId),
+			stateViewAddress: ctx.deployment.infrastructure.stateView
+		});
+		const { tokenIds } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		if (tokenIds.length === 0) return jsonResult({
+			account,
+			pool: poolAddress,
+			currentTick: pool.currentTick,
+			curve: [],
+			note: "Account has no open positions on this pool; nothing to evaluate."
+		});
+		const n = points ?? DEFAULT_POINTS;
+		const start = clampTick(startTick !== void 0 ? BigInt(startTick) : pool.currentTick - DEFAULT_SPAN);
+		const end = clampTick(endTick !== void 0 ? BigInt(endTick) : pool.currentTick + DEFAULT_SPAN);
+		const span = Number(end - start);
+		const atTicks = [];
+		for (let i = 0; i < n; i++) atTicks.push(clampTick(start + BigInt(Math.round(i * span / (n - 1)))));
+		const nlv = await getNetLiquidationValues({
+			client: ctx.client,
+			poolAddress,
+			account,
+			tokenIds,
+			atTicks,
+			includePendingPremium: includePendingPremium ?? true,
+			queryAddress
+		});
+		const dec0 = pool.collateralTracker0.decimals;
+		const dec1 = pool.collateralTracker1.decimals;
+		const curve = atTicks.map((tick, i) => ({
+			tick,
+			priceToken1PerToken0: priceAtTick(tick, dec0, dec1),
+			value0: nlv.values0[i],
+			value1: nlv.values1[i]
+		}));
+		return jsonResult({
+			account,
+			pool: poolAddress,
+			currentTick: pool.currentTick,
+			token0: pool.collateralTracker0.symbol,
+			token1: pool.collateralTracker1.symbol,
+			includePendingPremium: includePendingPremium ?? true,
+			note: "value0/value1 are net liquidation value at each tick, in token0/token1 smallest units. priceToken1PerToken0 is a display price derived from the tick.",
+			curve,
+			_meta: nlv._meta
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/previewPosition.ts
+function registerPreviewPosition(server, ctx) {
+	server.registerTool("preview_position", {
+		title: "Preview opening a position",
+		description: "Pre-trade quote for opening a position: read-only dry-run (eth_call, no broadcast) of a mint against the account's current state. Returns collateral required, post-mint collateral balances and requirements, and whether the account stays solvent. Takes a TokenId as input — construct it elsewhere; this tool is tokenId-in.",
+		inputSchema: {
+			address: z.string().describe("The account address."),
+			tokenId: z.string().describe("TokenId of the position to open, as a 0x-hex or decimal string."),
+			positionSize: z.string().describe("Position size to open, as a decimal string."),
+			tickLimitLow: z.string().optional().describe("Lower tick limit (decimal string). Defaults to MIN_TICK (no bound)."),
+			tickLimitHigh: z.string().optional().describe("Upper tick limit (decimal string). Defaults to MAX_TICK (no bound)."),
+			swapAtMint: z.boolean().optional().describe("Swap tokens at mint. Defaults to false."),
+			usePremiaAsCollateral: z.boolean().optional().describe("Defaults to false."),
+			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
+		}
+	}, async ({ address, tokenId, positionSize, tickLimitLow, tickLimitHigh, swapAtMint, usePremiaAsCollateral, fromBlock }) => {
+		if (!isAddress(address)) throw new Error(`Invalid address: ${address}`);
+		const account = getAddress(address);
+		let id;
+		let size;
+		try {
+			id = BigInt(tokenId.trim());
+		} catch {
+			throw new Error(`Invalid tokenId (expected a 0x-hex or decimal string): ${tokenId}`);
+		}
+		try {
+			size = BigInt(positionSize);
+		} catch {
+			throw new Error(`Invalid positionSize (expected a decimal string): ${positionSize}`);
+		}
+		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
+		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
+		const { tokenIds } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		const preview = await getOpenPositionPreview({
+			client: ctx.client,
+			poolAddress,
+			account,
+			existingPositionIds: tokenIds,
+			tokenId: id,
+			positionSize: size,
+			queryAddress,
+			tickLimitLow: tickLimitLow !== void 0 ? BigInt(tickLimitLow) : MIN_TICK,
+			tickLimitHigh: tickLimitHigh !== void 0 ? BigInt(tickLimitHigh) : MAX_TICK,
+			swapAtMint: swapAtMint ?? false,
+			usePremiaAsCollateral: usePremiaAsCollateral ?? false
+		});
+		const revert = preview.simulation.success === false && preview.simulation.error ? {
+			name: preview.simulation.error.name,
+			message: preview.simulation.error.message
+		} : null;
+		return jsonResult({
+			account,
+			pool: poolAddress,
+			tokenId: id,
+			positionSize: size,
+			isSolvent: preview.isSolvent,
+			amount0Required: preview.amount0Required,
+			amount1Required: preview.amount1Required,
+			postCollateral0: preview.postCollateral0,
+			postCollateral1: preview.postCollateral1,
+			postMintCollateralReqToken0: preview.postMintCollateralReqToken0,
+			postMintCollateralReqToken1: preview.postMintCollateralReqToken1,
+			currentBuyingPower: preview.currentBuyingPower,
+			revert
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/suggestDeltaHedge.ts
+/** Align a tick down to the nearest multiple of tickSpacing (matches buildUniqueLoan). */
+function alignStrike(tick, tickSpacing) {
+	const mod = (tick % tickSpacing + tickSpacing) % tickSpacing;
+	return tick - mod;
+}
+function registerSuggestDeltaHedge(server, ctx) {
+	server.registerTool("suggest_delta_hedge", {
+		title: "Suggest a delta-neutral hedge",
+		description: "Compute an account's net delta on the configured pool (option positions + deposited collateral) and suggest a Panoptic width=0 loan/credit leg that neutralizes it. A width=0 leg carries pure, spot-like directional delta (delta = ±size, no gamma): a LOAN borrowing the asset adds short delta, a CREDIT lending the asset adds long delta. If the account is net LONG the asset, the tool suggests a loan; if net SHORT, a credit. Returns an inspectable explicit-leg suggestion (tokenId + size) that can be handed to build_position; it does not execute anything.",
+		inputSchema: {
+			address: z.string().describe("The account address."),
+			assetIndex: z.union([z.literal(0), z.literal(1)]).optional().describe("Which token is the directional asset (0 or 1). Defaults to inferring the non-stablecoin token from pool symbols."),
+			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
+		}
+	}, async ({ address, assetIndex, fromBlock }) => {
+		if (!isAddress(address)) throw new Error(`Invalid address: ${address}`);
+		const account = getAddress(address);
+		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
+		const chainId = BigInt(ctx.config.chainId);
+		const pool = await getPool({
+			client: ctx.client,
+			poolAddress,
+			chainId,
+			stateViewAddress: ctx.deployment.infrastructure.stateView
+		});
+		const { asset, inferred: assetInferred } = inferAssetIndex(pool, assetIndex);
+		const assetSymbol = asset === 0n ? pool.collateralTracker0.symbol : pool.collateralTracker1.symbol;
+		const { tokenIds, storage } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		const greeks = await getAccountGreeks({
+			client: ctx.client,
+			chainId,
+			poolAddress,
+			account,
+			storage,
+			includeCollateral: true,
+			assetIndex: asset
+		});
+		const netDelta = greeks.totalDelta;
+		const facts = {
+			account,
+			pool: poolAddress,
+			assetIndex: asset,
+			assetSymbol,
+			assetInferred,
+			openTokenIds: tokenIds,
+			positionsDelta: greeks.positionsDelta,
+			collateralDelta: greeks.collateralDelta,
+			netDelta,
+			netDeltaNote: `Net delta is expressed in ${assetSymbol} smallest units (positive = net long the asset).`
+		};
+		if (netDelta === 0n) return jsonResult({
+			...facts,
+			hedge: null,
+			recommendation: "Account is already delta-neutral on this pool; no hedge needed."
+		});
+		const isLoan = netDelta > 0n;
+		const size = netDelta > 0n ? netDelta : -netDelta;
+		const strike = alignStrike(pool.currentTick, pool.tickSpacing);
+		const builder = createTokenIdBuilder(pool.poolId);
+		const legConfig = {
+			asset,
+			tokenType: asset,
+			strike
+		};
+		const hedgeTokenId = (isLoan ? builder.addLoan(legConfig) : builder.addCredit(legConfig)).build();
+		const hedgeLeg = decodeTokenId(hedgeTokenId).legs[0];
+		const hedgeLegDelta = getLegDelta(hedgeLeg, pool.currentTick, size, pool.tickSpacing, void 0, false, asset);
+		const residualDelta = netDelta + hedgeLegDelta;
+		return jsonResult({
+			...facts,
+			hedge: {
+				action: isLoan ? "open_loan" : "open_credit",
+				rationale: isLoan ? `Account is net long ${size} ${assetSymbol}; a width=0 loan borrowing ${assetSymbol} adds short delta to offset it.` : `Account is net short ${size} ${assetSymbol}; a width=0 credit lending ${assetSymbol} adds long delta to offset it.`,
+				tokenId: hedgeTokenId,
+				tokenIdHex: toHex(hedgeTokenId),
+				size,
+				strike,
+				asset,
+				tokenType: asset,
+				leg: hedgeLeg,
+				expectedHedgeDelta: hedgeLegDelta,
+				residualDelta
+			},
+			recommendation: `${isLoan ? "Open a loan (borrow" : "Open a credit (lend"} ${size} ${assetSymbol}) at strike tick ${strike} to bring net delta from ${netDelta} to ~${residualDelta}. Hand tokenId ${hedgeTokenId} + size to build_position to get an unsigned transaction envelope.`
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/tradeHistory.ts
+function registerTradeHistory(server, ctx) {
+	server.registerTool("trade_history", {
+		title: "Account trade history",
+		description: "An account's Panoptic trade history on the configured pool: mints and burns reconstructed from on-chain events, in chronological order (block, then log index), with sizes, ticks, and timestamps. This is event-level history only — it does NOT compute realized P&L or cost basis. Defaults to scanning from the pool deployment block.",
+		inputSchema: {
+			address: z.string().describe("The account address."),
+			fromBlock: z.string().optional().describe("Start block (decimal string). Defaults to the pool deployment block."),
+			toBlock: z.string().optional().describe("End block (decimal string). Defaults to latest.")
+		}
+	}, async ({ address, fromBlock, toBlock }) => {
+		const account = parseAccountAddress(address);
+		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
+		const hasFrom = fromBlock !== void 0 && fromBlock.trim() !== "";
+		const hasTo = toBlock !== void 0 && toBlock.trim() !== "";
+		const start = hasFrom ? BigInt(fromBlock) : await getPoolDeploymentBlock(ctx.client, poolAddress) ?? 0n;
+		const history = await getAccountHistory({
+			client: ctx.client,
+			poolAddress,
+			account,
+			fromBlock: start,
+			toBlock: hasTo ? BigInt(toBlock) : void 0
+		});
+		return jsonResult({
+			account,
+			pool: poolAddress,
+			fromBlock: start,
+			tradeCount: history.trades.length,
+			trades: history.trades,
+			_meta: history._meta
+		});
+	});
+}
+
+//#endregion
+//#region src/server.ts
+const SERVER_NAME = "panoptic-mcp";
+const require = createRequire(import.meta.url);
+const SERVER_VERSION = require("../package.json").version;
+/**
+* Build the Panoptic MCP server and register the v0 read-only tool catalog.
+* The transport (stdio locally; HTTP for a future hosted server) is wired by
+* the caller, so this factory is reusable across surfaces.
+*/
+function createServer(ctx) {
+	const server = new McpServer({
+		name: SERVER_NAME,
+		version: SERVER_VERSION
+	});
+	registerListPools(server, ctx);
+	registerExplainPosition(server, ctx);
+	registerIdentifyAddress(server, ctx);
+	registerGetPortfolio(server, ctx);
+	registerAccountHealth(server, ctx);
+	registerLiquidityMap(server, ctx);
+	registerChunkSpread(server, ctx);
+	registerSuggestDeltaHedge(server, ctx);
+	registerAdvisePosition(server, ctx);
+	registerPreviewPosition(server, ctx);
+	registerPositionScenario(server, ctx);
+	registerHedgeParams(server, ctx);
+	registerTradeHistory(server, ctx);
+	return server;
+}
+
+//#endregion
+export { KNOWN_CHAIN_IDS, SERVER_NAME, SERVER_VERSION, buildEnvelope, createContext, createServer, jsonResult, resolveConfig, toJsonSafe };