@panoptic-eng/mcp 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @panoptic-eng/mcp
+
+A local [Model Context Protocol](https://modelcontextprotocol.io) server that
+exposes the Panoptic SDK to AI agents as read-only analytics tools. It runs
+as a stdio process against **your own RPC endpoint** — zero infra, zero auth, no
+private keys. The server only reads on-chain state; it never signs or sends
+transactions. Build/simulate tools that return **unsigned transaction
+envelopes** are planned for a future release (see the spec).
+
+See `packages/sdk/mcp-spec.md` for the full specification and roadmap.
+
+## Quickstart
+
+Every MCP client accepts the same `command` / `args` / `env` shape; only the
+config file location differs (Claude Code/Desktop use `.mcp.json`, Cursor uses
+its MCP settings, etc.).
+
+```jsonc
+{
+  "mcpServers": {
+    "panoptic": {
+      "command": "npx",
+      "args": ["-y", "@panoptic-eng/mcp"],
+      "env": {
+        "PANOPTIC_RPC_URL": "https://mainnet.base.org",
+        "PANOPTIC_CHAIN_ID": "8453",
+        // optional — enables enhanced analytics tools
+        "PANOPTIC_SUBGRAPH_URL": ""
+      }
+    }
+  }
+}
+```
+
+Configuration may also be passed as CLI flags, which override the env vars:
+
+```bash
+npx @panoptic-eng/mcp --rpc-url https://mainnet.base.org --chain-id 8453
+```
+
+Supported chains: Ethereum mainnet (`1`), Base (`8453`), Sepolia (`11155111`).
+
+## v0 tools (read-only, pure RPC)
+
+| Tool | What it does |
+| --- | --- |
+| `list_pools` | Known pool deployment + live pool state (tokens, tick, trackers, health). |
+| `explain_position` | Decode a TokenId into readable legs + a strategy label (no RPC). |
+| `identify_address` | Map an address to its role in a Panoptic deployment. |
+| `get_portfolio` | An account's open positions, collateral, and net greeks. |
+| `account_health` | Buying power, margin buffer, and liquidation status. |
+| `liquidity_map` | Tick liquidity distribution around the current tick. |
+| `chunk_spread` | Per-chunk spread multiplier (via `scanChunks`): ~1.0x chunks are cheapest to BUY (lowest IV), high-multiplier chunks are most profitable to SELL. Width defaults to a standard timescale (`STANDARD_TICK_WIDTHS`). |
+| `suggest_delta_hedge` | Net delta (positions + collateral) and a width=0 loan/credit leg sized to neutralize it. |
+| `advise_position` | Live facts + management advice for a position (ITM/OTM, streamia, closeable-now, liquidation risk). |
+| `preview_position` | Pre-trade quote (dry-run `eth_call`): collateral required, post-mint balances, solvency, for a given tokenId + size. |
+| `position_scenario` | Payoff / NLV curve — net liquidation value across a band of hypothetical prices. |
+| `hedge_params` | SDK-native delta-hedge parameters (`getDeltaHedgeParams`) to reach a target delta; whole-portfolio or single-position. |
+| `trade_history` | Chronological mints/burns from on-chain events (event-level only — no realized P&L). |
+
+`get_portfolio`, `account_health`, `suggest_delta_hedge`, `advise_position`,
+`preview_position`, `position_scenario`, and `hedge_params` discover positions
+via an on-chain event scan (the SDK's `syncPositions`) — no subgraph required.
+Pass `fromBlock` to bound the scan on chains with a distant deployment block.
+These account tools need an RPC that permits `eth_getLogs`; many free public
+endpoints throttle or block large log scans, so a private RPC is recommended.
+
+Build + simulate tools (`build_position`, `build_strategy`, `simulate_tx`, …)
+that return unsigned transaction envelopes are planned for a future release and
+are **not** shipped yet. All numeric on-chain quantities are serialized as
+**decimal strings**.
+
+## Development
+
+```bash
+pnpm --filter @panoptic-eng/mcp build       # tsdown → dist/
+pnpm --filter @panoptic-eng/mcp test        # vitest
+pnpm --filter @panoptic-eng/mcp typecheck   # tsc --noEmit
+pnpm --filter @panoptic-eng/mcp lint
+
+# Inspect locally against a real RPC:
+PANOPTIC_RPC_URL=https://mainnet.base.org PANOPTIC_CHAIN_ID=8453 \
+  npx @modelcontextprotocol/inspector node dist/cli.js
+```
+
+The server depends on `@panoptic-eng/sdk`; the SDK never depends on it.

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { SERVER_VERSION, createContext, createServer, resolveConfig } from "./server--YF2LHqv.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+//#region src/cli.ts
+async function main() {
+	const config = resolveConfig(process.argv.slice(2), process.env);
+	const ctx = await createContext(config);
+	const server = createServer(ctx);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	console.error(`panoptic-mcp v${SERVER_VERSION} ready (chain ${config.chainId})`);
+}
+main().catch((err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	console.error(`panoptic-mcp failed to start: ${message}`);
+	process.exit(1);
+});
+
+//#endregion

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+/// <reference types="node" />
+import { ChainDeployment } from "@panoptic-eng/sdk/v2";
+import { Address, Hex, PublicClient } from "viem";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/config.d.ts
+/** Chain ids Panoptic has deployments for (mainnet, Base, Sepolia). */
+/** Chain ids Panoptic has deployments for (mainnet, Base, Sepolia). */
+declare const KNOWN_CHAIN_IDS: readonly [1, 8453, 11155111];
+/**
+ * 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.
+ */
+
+interface ServerConfig {
+  rpcUrl: string;
+  chainId: number;
+  /** Optional indexer URL; enables enhanced analytics tools. */
+  subgraphUrl?: string;
+}
+interface PanopticContext {
+  config: ServerConfig;
+  client: PublicClient;
+  deployment: ChainDeployment;
+}
+/**
+ * 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.
+ */
+declare function resolveConfig(argv: string[], env: NodeJS.ProcessEnv): ServerConfig;
+/** Create the shared context (viem client + resolved deployment) for tools. */
+declare function createContext(config: ServerConfig): Promise<PanopticContext>;
+
+//#endregion
+//#region src/serialize.d.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.
+ */
+declare function toJsonSafe(value: unknown): unknown;
+/** MCP tool result wrapping a serialized value as pretty JSON text. */
+declare function jsonResult(value: unknown): {
+  content: {
+    type: 'text';
+    text: string;
+  }[];
+};
+type EnvelopeRisk = 'defined' | 'undefined' | 'info';
+interface UnsignedTxEnvelopeInput {
+  summary: string;
+  risk: EnvelopeRisk;
+  chainId: number | bigint;
+  to: Address;
+  value: bigint;
+  data: Hex;
+  simulation?: unknown;
+}
+interface UnsignedTxEnvelope {
+  summary: string;
+  risk: EnvelopeRisk;
+  chainId: string;
+  to: Address;
+  value: string;
+  data: Hex;
+  simulation?: unknown;
+  envelopeHash: Hex;
+}
+/**
+ * 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.
+ */
+declare function buildEnvelope(input: UnsignedTxEnvelopeInput): UnsignedTxEnvelope;
+
+//#endregion
+//#region src/server.d.ts
+declare const SERVER_NAME = "panoptic-mcp";
+declare const SERVER_VERSION: string;
+/**
+ * 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.
+ */
+declare function createServer(ctx: PanopticContext): McpServer;
+
+//#endregion
+export { KNOWN_CHAIN_IDS, PanopticContext, SERVER_NAME, SERVER_VERSION, ServerConfig, UnsignedTxEnvelope, buildEnvelope, createContext, createServer, jsonResult, resolveConfig, toJsonSafe };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { KNOWN_CHAIN_IDS, SERVER_NAME, SERVER_VERSION, buildEnvelope, createContext, createServer, jsonResult, resolveConfig, toJsonSafe } from "./server--YF2LHqv.js";
+
+export { KNOWN_CHAIN_IDS, SERVER_NAME, SERVER_VERSION, buildEnvelope, createContext, createServer, jsonResult, resolveConfig, toJsonSafe };