obol-mcp 2.0.0

package/README.md

@@ -0,0 +1,195 @@
+# obol
+
+Pay the ferryman. Solana agent gateway via x402.
+
+Obol is a pay-per-use Solana API for AI agents. No API keys, no subscriptions — agents pay per request in USDC using the [x402 payment protocol](https://x402.org). Solana's sub-cent transaction costs make micropayments viable for the first time.
+
+Named after the coin placed on the tongue of the dead to pay Charon for passage across the River Styx. The original micropayment.
+
+## How it works
+
+1. Agent requests data from a paid endpoint
+2. Obol returns HTTP 402 with a payment requirement (amount, recipient, network)
+3. Agent sends USDC on Solana matching the requirement
+4. Agent retries with transaction proof in the `X-PAYMENT` header
+5. Obol verifies on-chain and returns the data
+
+No accounts. No tokens. No onboarding. Just pay and go.
+
+## Endpoints
+
+### Wallet Analytics
+| Endpoint | Price | Description |
+|----------|-------|-------------|
+| `GET /api/v1/wallet/:addr/overview` | $0.01 | SOL balance, token count, total value |
+| `GET /api/v1/wallet/:addr/portfolio` | $0.05 | Full holdings with prices, NFTs, breakdown |
+| `GET /api/v1/wallet/:addr/activity` | $0.05 | Transaction history with categorization |
+| `GET /api/v1/wallet/:addr/risk` | $0.10 | Multi-factor risk assessment |
+| `GET /api/v1/wallet/:addr/pnl` | $0.15 | Token flow analysis, current values, P&L |
+
+### Token Data
+| Endpoint | Price | Description |
+|----------|-------|-------------|
+| `GET /api/v1/token/:mint/price` | $0.005 | Real-time price via Jupiter |
+| `GET /api/v1/token/:mint/metadata` | $0.01 | Name, symbol, supply, decimals |
+
+### DeFi
+| Endpoint | Price | Description |
+|----------|-------|-------------|
+| `GET /api/v1/defi/swap/quote` | $0.005 | Jupiter swap quote with route planning |
+| `POST /api/v1/defi/swap/execute` | $0.25 | Jupiter swap transaction builder |
+| `GET /api/v1/defi/positions/:addr` | $0.10 | DeFi positions — LSTs, LPs, lending |
+| `GET /api/v1/defi/lst/yields` | $0.02 | LST yield comparison across Solana |
+
+### Free
+| Endpoint | Description |
+|----------|-------------|
+| `GET /` | API info and pricing |
+| `GET /health` | Service status |
+| `POST /api/v1/rpc` | Proxied Helius RPC (allowlisted methods) |
+
+## Agent Example
+
+See `examples/agent-client.ts` for a full reference implementation. The key flow:
+
+```typescript
+import { ObolAgent } from './examples/agent-client';
+
+const agent = new ObolAgent();
+await agent.discover();  // fetch pricing
+agent.loadWallet(process.env.AGENT_PRIVATE_KEY);
+
+// Auto-discovers price, pays, and returns data
+const price = await agent.fetch('/api/v1/token/USDC_MINT/price');
+```
+
+Run in discovery-only mode (no wallet needed):
+```bash
+npx tsx examples/agent-client.ts
+```
+
+## MCP Server
+
+Obol ships as an MCP server — any AI agent that supports the [Model Context Protocol](https://modelcontextprotocol.io) can discover and call Obol's tools natively.
+
+### Install from npm
+
+```bash
+npm install -g obol-mcp
+```
+
+### Claude Desktop / Claude Code
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "obol": {
+      "command": "npx",
+      "args": ["-y", "obol-mcp"],
+      "env": {
+        "OBOL_URL": "https://obol-production.up.railway.app"
+      }
+    }
+  }
+}
+```
+
+Or if developing locally:
+
+```json
+{
+  "mcpServers": {
+    "obol": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/obol/src/mcp.ts"],
+      "env": {
+        "OBOL_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `obol_wallet_overview` | SOL balance, token count, total value |
+| `obol_wallet_portfolio` | Full holdings with prices and breakdown |
+| `obol_wallet_activity` | Transaction history with categorization |
+| `obol_wallet_risk` | Multi-factor risk assessment |
+| `obol_wallet_pnl` | Token flow analysis and P&L |
+| `obol_token_price` | Real-time price via Jupiter |
+| `obol_token_metadata` | Name, symbol, supply, decimals |
+| `obol_swap_quote` | Jupiter swap quote with routing |
+| `obol_swap_execute` | Build swap transaction for signing |
+| `obol_defi_positions` | LSTs, LPs, lending positions |
+| `obol_lst_yields` | LST yield comparison |
+| `obol_health` | API health check (free) |
+| `obol_info` | Endpoint pricing and info (free) |
+
+### Run locally
+
+```bash
+npm run mcp
+```
+
+## Stack
+
+- **Fastify 5** — high-performance HTTP
+- **@x402/svm** — official x402 SDK for Solana
+- **Helius** — RPC + DAS API
+- **Jupiter** — token prices + swap execution
+- **Upstash Redis** — cache + payment receipts
+- **TypeScript** — full type safety
+- **Zod** — runtime validation
+
+## Setup
+
+```bash
+git clone https://github.com/halfkey/obol.git
+cd obol
+npm install
+cp .env.example .env
+# Edit .env with your Helius key and merchant wallet address
+npm run dev
+```
+
+## Testing
+
+```bash
+# Unit + integration tests (46 tests)
+npm test -- --run
+
+# Smoke test against live deployment
+npx tsx scripts/smoke-test.ts https://obol-production.up.railway.app
+
+# Manual payment test
+npx tsx scripts/test-payment.ts <tx-signature>
+```
+
+## Environment
+
+See `.env.example`. Key variables:
+
+- `PAYMENT_MODE` — `mock` (dev, auto-approve) or `onchain` (production)
+- `PAYMENT_RECIPIENT_ADDRESS` — your Solana wallet that receives USDC
+- `HELIUS_API_KEY` — Helius RPC access
+- `UPSTASH_REDIS_REST_URL` / `TOKEN` — cache layer
+
+## Roadmap
+
+- [x] 11 paid endpoints (wallet, token, DeFi, LST, P&L)
+- [x] On-chain USDC verification with replay prevention
+- [x] Test suite (46 vitest + 20-point smoke test)
+- [x] Agent client reference implementation
+- [x] GitHub Actions CI
+- [ ] WebSocket subscriptions for wallet monitoring
+- [ ] Dynamic congestion-based pricing
+- [ ] Multi-chain support
+
+## License
+
+MIT

package/dist/app.d.ts

@@ -0,0 +1,3 @@
+import type { FastifyInstance } from 'fastify';
+export declare function createApp(): Promise<FastifyInstance>;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAY/C,wBAAsB,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC,CAuI1D"}

package/dist/app.js

@@ -0,0 +1,130 @@
+import Fastify from 'fastify';
+import helmet from '@fastify/helmet';
+import cors from '@fastify/cors';
+import rateLimit from '@fastify/rate-limit';
+import { config } from './config/env.js';
+import { x402PaymentMiddleware } from './middleware/x402.js';
+import { endpointPricing } from './config/pricing.js';
+// Plugins
+import { walletPlugin } from './plugins/wallet/routes.js';
+import { tokenPlugin } from './plugins/token/routes.js';
+import { defiPlugin } from './plugins/defi/routes.js';
+export async function createApp() {
+    const app = Fastify({
+        logger: config.server.isDevelopment
+            ? { transport: { target: 'pino-pretty', options: { translateTime: 'HH:MM:ss', ignore: 'pid,hostname' } } }
+            : true,
+        disableRequestLogging: false,
+        requestIdHeader: 'x-request-id',
+        trustProxy: true,
+        requestTimeout: 30000,
+        connectionTimeout: 60000,
+    });
+    // ── Security ──
+    await app.register(helmet, {
+        contentSecurityPolicy: { directives: { defaultSrc: ["'none'"] } },
+    });
+    await app.register(cors, {
+        origin: config.server.isDevelopment ? '*'
+            : config.security.corsOrigins?.[0] === '*' ? '*'
+                : config.security.corsOrigins || false,
+        methods: ['GET', 'POST', 'OPTIONS'],
+        credentials: true,
+    });
+    await app.register(rateLimit, {
+        global: false,
+        max: config.security.rateLimitMaxRequests,
+        timeWindow: config.security.rateLimitWindowMs,
+        cache: 10000,
+        allowList: ['127.0.0.1'],
+        keyGenerator: (request) => request.ip || 'unknown',
+    });
+    // ── x402 Payment Gate (global preHandler) ──
+    app.addHook('preHandler', x402PaymentMiddleware);
+    // ── Free Endpoints ──
+    app.get('/health', async (_request, reply) => {
+        return reply.send({
+            status: 'ok',
+            timestamp: new Date().toISOString(),
+            uptime: process.uptime(),
+            environment: config.server.isDevelopment ? 'development' : 'production',
+        });
+    });
+    app.get('/', async (_request, reply) => {
+        return reply.send({
+            name: 'obol',
+            version: '2.0.0',
+            description: 'Pay the ferryman. Solana agent gateway via x402.',
+            paymentMode: config.payment.mode,
+            endpoints: Object.fromEntries(Object.entries(endpointPricing).map(([path, info]) => [
+                path,
+                { price: `${info.priceUSDC} USDC`, description: info.description },
+            ])),
+            freeEndpoints: ['GET /', 'GET /health', 'POST /api/v1/rpc'],
+            protocol: 'x402',
+            docs: 'https://github.com/halfkey/obol',
+        });
+    });
+    // ── RPC Proxy (free — for transaction creation) ──
+    app.post('/api/v1/rpc', async (request, reply) => {
+        const body = request.body;
+        const allowed = ['getAccountInfo', 'getLatestBlockhash', 'sendTransaction', 'getSignatureStatuses'];
+        if (!body?.method || !allowed.includes(body.method)) {
+            return reply.code(403).send({
+                error: 'Forbidden',
+                message: `RPC method '${body?.method ?? 'undefined'}' not allowed`,
+            });
+        }
+        if (!config.solana.rpcUrl) {
+            return reply.code(503).send({ error: 'Service Unavailable', message: 'RPC not configured' });
+        }
+        try {
+            const response = await fetch(config.solana.rpcUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    jsonrpc: '2.0', id: 1,
+                    method: body.method,
+                    params: body.params ?? [],
+                }),
+            });
+            const data = await response.json();
+            return reply.send(data);
+        }
+        catch (error) {
+            app.log.error({ error }, 'RPC proxy error');
+            return reply.code(500).send({ error: 'Internal Server Error', message: 'RPC proxy failed' });
+        }
+    });
+    // ── Register Endpoint Plugins ──
+    await app.register(walletPlugin);
+    await app.register(tokenPlugin);
+    await app.register(defiPlugin);
+    // ── 404 ──
+    app.setNotFoundHandler((_request, reply) => {
+        return reply.code(404).send({
+            error: 'Not Found',
+            message: 'Endpoint does not exist',
+        });
+    });
+    // ── Error Handler ──
+    app.setErrorHandler((error, _request, reply) => {
+        app.log.error(error);
+        const statusCode = error.statusCode ?? 500;
+        // In production, never leak internal error names or stack traces
+        if (config.server.isProduction) {
+            return reply.code(statusCode).send({
+                error: statusCode >= 500 ? 'Internal Server Error' : 'Error',
+                message: statusCode >= 500 ? 'An unexpected error occurred' : error.message,
+                statusCode,
+            });
+        }
+        return reply.code(statusCode).send({
+            error: error.name || 'InternalServerError',
+            message: error.message,
+            statusCode,
+        });
+    });
+    return app;
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/config/env.d.ts

@@ -0,0 +1,47 @@
+export declare const env: {
+    NODE_ENV: "development" | "test" | "production";
+    PORT: number;
+    HOST: string;
+    SOLANA_NETWORK: "mainnet-beta" | "devnet";
+    PAYMENT_MODE: "mock" | "onchain";
+    CORS_ORIGINS: string[];
+    RATE_LIMIT_WINDOW_MS: number;
+    RATE_LIMIT_MAX_REQUESTS: number;
+    LOG_LEVEL: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+    HELIUS_API_KEY?: string | undefined;
+    PAYMENT_RECIPIENT_ADDRESS?: string | undefined;
+    UPSTASH_REDIS_REST_URL?: string | undefined;
+    UPSTASH_REDIS_REST_TOKEN?: string | undefined;
+};
+export declare const config: {
+    readonly server: {
+        readonly port: number;
+        readonly host: string;
+        readonly isDevelopment: boolean;
+        readonly isProduction: boolean;
+        readonly isTest: boolean;
+    };
+    readonly solana: {
+        readonly network: "mainnet-beta" | "devnet";
+        readonly heliusApiKey: string;
+        readonly rpcUrl: string | undefined;
+    };
+    readonly payment: {
+        readonly mode: "mock" | "onchain";
+        readonly recipientAddress: string;
+    };
+    readonly redis: {
+        readonly restUrl: string | undefined;
+        readonly restToken: string | undefined;
+    };
+    readonly security: {
+        readonly corsOrigins: string[];
+        readonly rateLimitWindowMs: number;
+        readonly rateLimitMaxRequests: number;
+    };
+    readonly logging: {
+        readonly level: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+    };
+};
+export type Config = typeof config;
+//# sourceMappingURL=env.d.ts.map

package/dist/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAuCA,eAAO,MAAM,GAAG;;;;;;;;;;;;;;CAAc,CAAC;AAE/B,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BT,CAAC;AAEX,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC"}

package/dist/config/env.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import dotenv from 'dotenv';
+dotenv.config();
+const envSchema = z.object({
+    // Server
+    NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+    PORT: z.coerce.number().min(1).max(65535).default(3000),
+    HOST: z.string().default('0.0.0.0'),
+    // Solana
+    SOLANA_NETWORK: z.enum(['mainnet-beta', 'devnet']).default('mainnet-beta'),
+    HELIUS_API_KEY: z.string().min(1).optional(),
+    // x402 Payments
+    PAYMENT_MODE: z.enum(['mock', 'onchain']).default('mock'),
+    PAYMENT_RECIPIENT_ADDRESS: z.string().min(32).max(64).optional(),
+    // Upstash Redis
+    UPSTASH_REDIS_REST_URL: z.string().url().optional(),
+    UPSTASH_REDIS_REST_TOKEN: z.string().optional(),
+    // Security
+    CORS_ORIGINS: z.string().optional().transform(val => val ? val.split(',').map(s => s.trim()) : ['*']),
+    RATE_LIMIT_WINDOW_MS: z.coerce.number().default(60000),
+    RATE_LIMIT_MAX_REQUESTS: z.coerce.number().default(100),
+    // Logging
+    LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']).default('info'),
+});
+const parsed = envSchema.safeParse(process.env);
+if (!parsed.success) {
+    console.error('Invalid environment variables:', parsed.error.format());
+    throw new Error('Invalid environment configuration');
+}
+export const env = parsed.data;
+export const config = {
+    server: {
+        port: env.PORT,
+        host: env.HOST,
+        isDevelopment: env.NODE_ENV === 'development',
+        isProduction: env.NODE_ENV === 'production',
+        isTest: env.NODE_ENV === 'test',
+    },
+    solana: {
+        network: env.SOLANA_NETWORK,
+        heliusApiKey: env.HELIUS_API_KEY ?? '',
+        rpcUrl: env.HELIUS_API_KEY
+            ? `https://${env.SOLANA_NETWORK === 'mainnet-beta' ? 'mainnet' : 'devnet'}.helius-rpc.com/?api-key=${env.HELIUS_API_KEY}`
+            : undefined,
+    },
+    payment: {
+        mode: env.PAYMENT_MODE,
+        recipientAddress: env.PAYMENT_RECIPIENT_ADDRESS ?? '',
+    },
+    redis: {
+        restUrl: env.UPSTASH_REDIS_REST_URL,
+        restToken: env.UPSTASH_REDIS_REST_TOKEN,
+    },
+    security: {
+        corsOrigins: env.CORS_ORIGINS,
+        rateLimitWindowMs: env.RATE_LIMIT_WINDOW_MS,
+        rateLimitMaxRequests: env.RATE_LIMIT_MAX_REQUESTS,
+    },
+    logging: {
+        level: env.LOG_LEVEL,
+    },
+};
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"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"}

package/dist/config/pricing.d.ts

@@ -0,0 +1,12 @@
+/** Endpoint pricing configuration for x402 payment gates */
+export interface EndpointPrice {
+    priceUSDC: number;
+    description: string;
+}
+/** Registry of all paid endpoints and their prices */
+export declare const endpointPricing: Record<string, EndpointPrice>;
+/** Get price for an endpoint in USDC. Throws if no pricing exists. */
+export declare function getEndpointPrice(path: string): number;
+/** Check if an endpoint requires payment */
+export declare function requiresPayment(path: string): boolean;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/config/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/config/pricing.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,sDAAsD;AACtD,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAgDzD,CAAC;AAiCF,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOrD;AAED,4CAA4C;AAC5C,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAWrD"}

package/dist/config/pricing.js

@@ -0,0 +1,99 @@
+/** Endpoint pricing configuration for x402 payment gates */
+/** Registry of all paid endpoints and their prices */
+export const endpointPricing = {
+    // Phase 1: Core
+    '/api/v1/wallet/:address/overview': {
+        priceUSDC: 0.01,
+        description: 'Wallet overview — SOL balance, token count, total value',
+    },
+    '/api/v1/wallet/:address/portfolio': {
+        priceUSDC: 0.05,
+        description: 'Full portfolio — tokens with prices, NFTs, breakdown',
+    },
+    '/api/v1/wallet/:address/activity': {
+        priceUSDC: 0.05,
+        description: 'Transaction history with categorization',
+    },
+    '/api/v1/wallet/:address/risk': {
+        priceUSDC: 0.10,
+        description: 'Multi-factor risk assessment',
+    },
+    '/api/v1/token/:mint/price': {
+        priceUSDC: 0.005,
+        description: 'Real-time token price via Jupiter',
+    },
+    '/api/v1/token/:mint/metadata': {
+        priceUSDC: 0.01,
+        description: 'Token name, symbol, supply, holder count',
+    },
+    // Phase 2: DeFi
+    '/api/v1/defi/swap/quote': {
+        priceUSDC: 0.005,
+        description: 'Jupiter swap quote with route planning',
+    },
+    '/api/v1/defi/swap/execute': {
+        priceUSDC: 0.25,
+        description: 'Jupiter swap transaction builder — returns serialized tx for signing',
+    },
+    '/api/v1/defi/positions/:address': {
+        priceUSDC: 0.10,
+        description: 'DeFi positions — LSTs, LPs, lending, yield',
+    },
+    '/api/v1/defi/lst/yields': {
+        priceUSDC: 0.02,
+        description: 'LST yield comparison across Solana liquid staking',
+    },
+    '/api/v1/wallet/:address/pnl': {
+        priceUSDC: 0.15,
+        description: 'Wallet P&L — token flows, current values, transaction analysis',
+    },
+};
+/** Paths that never require payment */
+const FREE_PATHS = new Set(['/', '/health', '/api/v1/rpc']);
+/** Normalize a real URL path to its route pattern */
+function normalizeToRoute(path) {
+    // Strip query string
+    const cleanPath = path.split('?')[0] ?? path;
+    // /api/v1/wallet/<address>/overview → /api/v1/wallet/:address/overview
+    const walletMatch = cleanPath.match(/^\/api\/v1\/wallet\/[^/]+\/(overview|portfolio|activity|risk|pnl)$/);
+    if (walletMatch) {
+        return `/api/v1/wallet/:address/${walletMatch[1]}`;
+    }
+    // /api/v1/token/<mint>/price → /api/v1/token/:mint/price
+    const tokenMatch = cleanPath.match(/^\/api\/v1\/token\/[^/]+\/(price|metadata)$/);
+    if (tokenMatch) {
+        return `/api/v1/token/:mint/${tokenMatch[1]}`;
+    }
+    // /api/v1/defi/positions/<address> → /api/v1/defi/positions/:address
+    const defiPositionsMatch = cleanPath.match(/^\/api\/v1\/defi\/positions\/[^/]+$/);
+    if (defiPositionsMatch) {
+        return '/api/v1/defi/positions/:address';
+    }
+    // /api/v1/defi/swap/quote and /api/v1/defi/lst/yields are static routes — no normalization needed
+    return cleanPath;
+}
+/** Get price for an endpoint in USDC. Throws if no pricing exists. */
+export function getEndpointPrice(path) {
+    const route = normalizeToRoute(path);
+    const pricing = endpointPricing[route];
+    if (!pricing) {
+        throw new Error(`No pricing configured for: ${path}`);
+    }
+    return pricing.priceUSDC;
+}
+/** Check if an endpoint requires payment */
+export function requiresPayment(path) {
+    const cleanPath = path.split('?')[0] ?? path;
+    if (FREE_PATHS.has(cleanPath))
+        return false;
+    if (!cleanPath.startsWith('/api/'))
+        return false;
+    try {
+        getEndpointPrice(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=pricing.js.map

package/dist/config/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../../src/config/pricing.ts"],"names":[],"mappings":"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"}

package/dist/mcp.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * Obol MCP Server
+ *
+ * Exposes Obol's Solana data endpoints as MCP tools that any
+ * AI agent can discover and call. Runs over stdio transport.
+ *
+ * The MCP server proxies requests to either:
+ *   - A live Obol instance (default: production)
+ *   - A local dev instance
+ *
+ * In MCP mode, the server operates in "proxy" payment mode:
+ *   - If OBOL_URL points to a mock-mode instance, data is free
+ *   - If OBOL_URL points to an onchain instance, the MCP server
+ *     can optionally include a payment signature via AGENT_PRIVATE_KEY
+ *
+ * Usage:
+ *   npx tsx src/mcp.ts                              # stdio transport
+ *   OBOL_URL=http://localhost:3000 npx tsx src/mcp.ts  # local dev
+ *
+ * Claude Desktop config (~/.claude/claude_desktop_config.json):
+ *   {
+ *     "mcpServers": {
+ *       "obol": {
+ *         "command": "npx",
+ *         "args": ["tsx", "/path/to/obol/src/mcp.ts"],
+ *         "env": {
+ *           "OBOL_URL": "https://obol-production.up.railway.app"
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+export {};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG"}