@one-source/api-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BlockParty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# onesource-api-mcp
+
+MCP server for OneSource blockchain data. 34 named tools for balances, NFTs, transactions, events, and live chain queries via x402 micropayments.
+
+```
+npx onesource-api-mcp
+```
+
+## Install
+
+```sh
+# Claude Code
+claude mcp add onesource-api -- npx onesource-api-mcp
+
+# Claude Desktop / Cursor — add to MCP config:
+{
+  "mcpServers": {
+    "onesource-api": {
+      "command": "npx",
+      "args": ["-y", "onesource-api-mcp"]
+    }
+  }
+}
+```
+
+## Tools (34)
+
+### Indexed Data (12 tools) — OpenSearch, cheaper, slight sync delay
+
+| Tool | Description |
+|------|-------------|
+| `1s_address_txs` | Address transaction history |
+| `1s_block` | Block details by number |
+| `1s_contract_info` | Contract metadata |
+| `1s_erc1155_balance` | ERC1155 token balance |
+| `1s_erc20_balance` | ERC20 token balance |
+| `1s_erc20_transfers` | ERC20 transfer history |
+| `1s_events` | Event log search |
+| `1s_nft_media` | NFT processed media URLs |
+| `1s_nft_metadata` | NFT metadata and traits |
+| `1s_nft_owner` | NFT current owner |
+| `1s_tx_details` | Transaction with decoded events |
+| `1s_wallet_nfts` | Wallet NFT portfolio |
+
+### Live Chain Data (12 tools) — Direct RPC, real-time
+
+| Tool | Description |
+|------|-------------|
+| `1s_allowance_live` | ERC20 allowance check |
+| `1s_contract_info_live` | Contract type detection via ERC165 |
+| `1s_erc1155_balance_live` | ERC1155 balance via RPC |
+| `1s_erc20_balance_live` | ERC20 balance via balanceOf |
+| `1s_erc20_transfers_live` | ERC20 Transfer logs via eth_getLogs |
+| `1s_erc721_tokens_live` | ERC721 token enumeration |
+| `1s_events_live` | Event logs via eth_getLogs |
+| `1s_multi_balance_live` | ETH + multiple ERC20 balances |
+| `1s_nft_metadata_live` | NFT metadata via tokenURI |
+| `1s_nft_owner_live` | NFT owner via ownerOf |
+| `1s_total_supply_live` | Token total supply |
+| `1s_tx_details_live` | Transaction + receipt via RPC |
+
+### Chain Utilities (10 tools) — RPC only
+
+| Tool | Description |
+|------|-------------|
+| `1s_contract_code` | Contract bytecode |
+| `1s_ens_resolve` | ENS name/address resolution |
+| `1s_estimate_gas` | Gas estimation |
+| `1s_network_info` | Chain ID, block number, gas price |
+| `1s_nonce` | Transaction count |
+| `1s_pending_block` | Pending block from mempool |
+| `1s_proxy_detect` | Proxy contract detection |
+| `1s_simulate_call` | Simulate eth_call |
+| `1s_storage_read` | Read storage slot |
+| `1s_tx_receipt` | Transaction receipt |
+
+## Networks
+
+All tools accept an optional `network` parameter:
+
+| Network | Description |
+|---------|-------------|
+| `ethereum` | Ethereum mainnet (default) |
+| `sepolia` | Ethereum Sepolia testnet |
+| `avax` | Avalanche C-Chain |
+
+## Payment (x402)
+
+Endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When the backend has payments enabled, tool calls return a 402 with payment details. Agents using [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) handle this automatically.
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | Skills API endpoint |
+| `ONESOURCE_ANALYTICS` | `true` | Set `false` to disable analytics |
+| `ONESOURCE_ANALYTICS_URL` | — | Dashboard endpoint for event ingestion |
+| `ONESOURCE_ANALYTICS_KEY` | — | API key for the analytics dashboard |
+
+## Transport Modes
+
+```sh
+# stdio (default — for MCP clients)
+npx onesource-api-mcp
+
+# HTTP (for testing or remote access)
+npx onesource-api-mcp --http
+npx onesource-api-mcp --http --port=8080
+```
+
+HTTP mode binds to `127.0.0.1` by default.
+
+## Adding a New Tool
+
+When a new SKILL.md is added to `skills/OneSource*/`, a corresponding MCP tool file needs to be created here.
+
+**Step 1:** Create the SKILL.md in the skills repo (see the skills README for format).
+
+**Step 2:** Scaffold the tool file:
+
+```sh
+cd mcp/
+npm run new-tool
+```
+
+This prompts for:
+- **Tool name** — `1s_` prefix, snake_case (e.g. `1s_token_info`)
+- **Category** — `indexed` (OpenSearch), `live` (RPC with indexed counterpart), or `chain` (RPC-only utility)
+- **Description** — one-liner for the tool
+- **Endpoint** — REST API path (e.g. `/api/chain/my-endpoint`)
+- **Method** — GET or POST
+
+It generates a tool file in `src/tools/{category}/` with TODO markers.
+
+**Step 3:** Edit the generated file — fill in the Zod schema parameters and handler logic. Use the shared params from `src/types.ts` (`addressParam`, `txHashParam`, `tokenIdParam`, `hexDataParam`, `networkParam`, `limitParam`, `blockNumberParam`).
+
+**Step 4:** Build:
+
+```sh
+npm run build
+```
+
+This auto-regenerates the tool index and compiles. The new tool is immediately available in the MCP server.
+
+## License
+
+MIT

package/dist/analytics.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Analytics instrumentation for the MCP server.
+ *
+ * Three modes (selected via env vars):
+ *   - NoopAnalytics:      ONESOURCE_ANALYTICS=false
+ *   - StderrAnalytics:    default (structured JSON to stderr)
+ *   - DashboardAnalytics: ONESOURCE_ANALYTICS_URL is set (POSTs to dashboard)
+ */
+export interface ToolCallEvent {
+    type: 'tool_call';
+    service: string;
+    tool: string;
+    category: 'indexed' | 'live' | 'chain';
+    timestamp: string;
+    duration_ms: number;
+    success: boolean;
+    error_category?: string;
+    network?: string;
+    input_params: string[];
+    response_size: number;
+    version: string;
+    auth_method: 'x402' | 'none';
+    client_name?: string;
+    client_version?: string;
+    session_id?: string;
+    transport?: 'stdio' | 'http';
+}
+export interface HttpCallEvent {
+    type: 'http_call';
+    service: string;
+    tool: string;
+    http_status: number;
+    backend_latency_ms: number;
+    x402_required: boolean;
+    timestamp: string;
+    session_id?: string;
+}
+export interface ServiceEvent {
+    type: 'service_start' | 'service_stop' | 'service_error';
+    service: string;
+    timestamp: string;
+    version: string;
+    details?: string;
+}
+export interface Analytics {
+    trackTool(event: ToolCallEvent): void;
+    trackHttp(event: HttpCallEvent): void;
+    trackService(event: ServiceEvent): void;
+    flush(): Promise<void>;
+    stop(): void;
+}
+export declare function createAnalytics(): Analytics;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,eAAe,GAAG,cAAc,GAAG,eAAe,CAAC;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,IAAI,CAAC;CACd;AAkHD,wBAAgB,eAAe,IAAI,SAAS,CAY3C"}

package/dist/analytics.fix-verification.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Verification tests for DashboardAnalytics bug fixes:
+ *
+ *  1. Event preservation — events are restored to the buffer when flush fails,
+ *     so they can be retried on the next flush.
+ *
+ *  2. Flush timeout — flush() aborts after 3s via AbortSignal.timeout,
+ *     so shutdown never hangs indefinitely.
+ */
+export {};
+//# sourceMappingURL=analytics.fix-verification.test.d.ts.map

package/dist/analytics.fix-verification.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.fix-verification.test.d.ts","sourceRoot":"","sources":["../src/analytics.fix-verification.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/analytics.fix-verification.test.js

@@ -0,0 +1,146 @@
+/**
+ * Verification tests for DashboardAnalytics bug fixes:
+ *
+ *  1. Event preservation — events are restored to the buffer when flush fails,
+ *     so they can be retried on the next flush.
+ *
+ *  2. Flush timeout — flush() aborts after 3s via AbortSignal.timeout,
+ *     so shutdown never hangs indefinitely.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createAnalytics } from './analytics.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeToolEvent(overrides = {}) {
+    return {
+        type: 'tool_call',
+        service: 'mcp',
+        tool: 'test-tool',
+        category: 'indexed',
+        timestamp: new Date().toISOString(),
+        duration_ms: 50,
+        success: true,
+        input_params: [],
+        response_size: 128,
+        version: '1.0.0',
+        auth_method: 'none',
+        ...overrides,
+    };
+}
+// Drain the microtask queue — works regardless of timer mode.
+const drainMicrotasks = async () => {
+    for (let i = 0; i < 5; i++)
+        await Promise.resolve();
+};
+// ---------------------------------------------------------------------------
+// Setup: point createAnalytics() at DashboardAnalytics via env vars
+// ---------------------------------------------------------------------------
+beforeEach(() => {
+    process.env.ONESOURCE_ANALYTICS_URL = 'http://analytics.test';
+    process.env.ONESOURCE_ANALYTICS_KEY = 'test-key';
+    vi.spyOn(global, 'fetch');
+});
+afterEach(() => {
+    delete process.env.ONESOURCE_ANALYTICS_URL;
+    delete process.env.ONESOURCE_ANALYTICS_KEY;
+    vi.restoreAllMocks();
+});
+// ---------------------------------------------------------------------------
+// Fix 1: Events preserved on network failure
+// ---------------------------------------------------------------------------
+describe('Event preservation on network failure', () => {
+    it('events are restored to buffer on failure and retried on next flush', async () => {
+        vi.mocked(global.fetch).mockRejectedValue(new Error('Network failure'));
+        const analytics = createAnalytics();
+        for (let i = 0; i < 10; i++) {
+            analytics.trackTool(makeToolEvent());
+        }
+        // Let the auto-triggered flush run: splice(0) removes events, fetch rejects,
+        // catch restores them to the buffer via unshift.
+        await drainMicrotasks();
+        expect(global.fetch).toHaveBeenCalledOnce();
+        // Network is healthy again
+        vi.mocked(global.fetch).mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+        // Manually flush — the 10 events were preserved and are now sent
+        await analytics.flush();
+        // fetch called twice — once failed, once succeeded with the restored events
+        expect(global.fetch).toHaveBeenCalledTimes(2);
+    });
+    it('flush-in-progress guard prevents concurrent flushes, events preserved on failure', async () => {
+        let rejectFetch;
+        vi.mocked(global.fetch).mockImplementation(() => {
+            return new Promise((_, reject) => { rejectFetch = reject; });
+        });
+        const analytics = createAnalytics();
+        // First batch of 10 → triggers flush
+        for (let i = 0; i < 10; i++) {
+            analytics.trackTool(makeToolEvent());
+        }
+        await drainMicrotasks();
+        expect(global.fetch).toHaveBeenCalledOnce();
+        // Second batch of 10 arrives while flush is in-flight
+        // The flush-in-progress guard means these stay in the buffer —
+        // no second concurrent fetch fires
+        for (let i = 0; i < 10; i++) {
+            analytics.trackTool(makeToolEvent());
+        }
+        await drainMicrotasks();
+        // Still only 1 fetch — guard prevented a concurrent flush
+        expect(global.fetch).toHaveBeenCalledOnce();
+        // Fail the in-flight request — first 10 events restored via unshift
+        rejectFetch(new Error('timeout'));
+        await drainMicrotasks();
+        // Restore healthy network
+        vi.mocked(global.fetch).mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+        // Flush now sends all 20 events (10 restored + 10 buffered)
+        await analytics.flush();
+        // 2 calls total — one failed, one succeeded with all 20 events
+        expect(global.fetch).toHaveBeenCalledTimes(2);
+    });
+});
+// ---------------------------------------------------------------------------
+// Fix 2: Flush timeout prevents shutdown hang
+// ---------------------------------------------------------------------------
+describe('Flush timeout prevents shutdown hang', () => {
+    it('flush() resolves within timeout even when fetch hangs', async () => {
+        // Mock fetch that respects AbortSignal — hangs until aborted
+        vi.mocked(global.fetch).mockImplementation((_url, init) => {
+            return new Promise((_, reject) => {
+                const signal = init?.signal;
+                if (signal) {
+                    signal.addEventListener('abort', () => reject(signal.reason));
+                }
+            });
+        });
+        const analytics = createAnalytics();
+        analytics.trackTool(makeToolEvent());
+        let flushCompleted = false;
+        await Promise.race([
+            analytics.flush().then(() => { flushCompleted = true; }),
+            // 4s deadline — longer than the 3s AbortSignal.timeout in flush()
+            new Promise((resolve) => setTimeout(resolve, 4_000)),
+        ]);
+        // flush completed because AbortSignal.timeout aborted the hung fetch
+        expect(flushCompleted).toBe(true);
+    }, 10_000);
+    it('a single buffered event does not hang the process on shutdown', async () => {
+        vi.mocked(global.fetch).mockImplementation((_url, init) => {
+            return new Promise((_, reject) => {
+                const signal = init?.signal;
+                if (signal) {
+                    signal.addEventListener('abort', () => reject(signal.reason));
+                }
+            });
+        });
+        const analytics = createAnalytics();
+        analytics.trackTool(makeToolEvent());
+        const result = await Promise.race([
+            analytics.flush().then(() => 'completed'),
+            new Promise((resolve) => setTimeout(() => resolve('timed-out'), 4_000)),
+        ]);
+        // flush completes (via abort timeout) rather than hanging
+        expect(result).toBe('completed');
+    }, 10_000);
+});
+//# sourceMappingURL=analytics.fix-verification.test.js.map

package/dist/analytics.fix-verification.test.js.map

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

package/dist/analytics.js

@@ -0,0 +1,126 @@
+/**
+ * Analytics instrumentation for the MCP server.
+ *
+ * Three modes (selected via env vars):
+ *   - NoopAnalytics:      ONESOURCE_ANALYTICS=false
+ *   - StderrAnalytics:    default (structured JSON to stderr)
+ *   - DashboardAnalytics: ONESOURCE_ANALYTICS_URL is set (POSTs to dashboard)
+ */
+// --- Implementations ---
+class NoopAnalytics {
+    trackTool() { }
+    trackHttp() { }
+    trackService() { }
+    stop() { }
+    async flush() { }
+}
+class StderrAnalytics {
+    trackTool(event) {
+        console.error(JSON.stringify(event));
+    }
+    trackHttp(event) {
+        console.error(JSON.stringify(event));
+    }
+    trackService(event) {
+        console.error(JSON.stringify(event));
+    }
+    stop() { }
+    async flush() { }
+}
+class DashboardAnalytics {
+    static FLUSH_TIMEOUT_MS = 3_000;
+    static MAX_BUFFER = 1_000;
+    buffer = [];
+    flushPromise = null;
+    timer = null;
+    endpoint;
+    apiKey;
+    constructor(endpoint, apiKey) {
+        const parsed = new URL(endpoint);
+        if (!['https:', 'http:'].includes(parsed.protocol)) {
+            throw new Error('ONESOURCE_ANALYTICS_URL must use http or https');
+        }
+        this.endpoint = endpoint.replace(/\/+$/, '');
+        this.apiKey = apiKey;
+        // Auto-flush every 30 seconds
+        this.timer = setInterval(() => { void this.flush(); }, 30_000);
+        // Don't keep the process alive just for the flush timer
+        if (this.timer.unref)
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    trackTool(event) {
+        this.buffer.push(event);
+        if (this.buffer.length >= 10)
+            void this.flush();
+    }
+    trackHttp(event) {
+        this.buffer.push(event);
+        if (this.buffer.length >= 10)
+            void this.flush();
+    }
+    trackService(event) {
+        this.buffer.push(event);
+    }
+    async flush() {
+        // If a flush is already in-flight, await it instead of racing
+        if (this.flushPromise)
+            return this.flushPromise;
+        if (this.buffer.length === 0)
+            return;
+        this.flushPromise = this.doFlush();
+        try {
+            await this.flushPromise;
+        }
+        finally {
+            this.flushPromise = null;
+        }
+    }
+    async doFlush() {
+        const events = this.buffer.splice(0);
+        try {
+            const res = await fetch(`${this.endpoint}/api/events`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'x-402-receipt': this.apiKey,
+                },
+                body: JSON.stringify({ events }),
+                signal: AbortSignal.timeout(DashboardAnalytics.FLUSH_TIMEOUT_MS),
+            });
+            if (!res.ok) {
+                console.error(`[analytics] flush failed: HTTP ${res.status}`);
+                this.buffer = events.concat(this.buffer);
+            }
+        }
+        catch {
+            console.error(`[analytics] flush failed: ${events.length} events queued for retry`);
+            this.buffer = events.concat(this.buffer);
+        }
+        // Cap buffer to prevent unbounded growth — drop oldest first
+        if (this.buffer.length > DashboardAnalytics.MAX_BUFFER) {
+            const dropped = this.buffer.length - DashboardAnalytics.MAX_BUFFER;
+            this.buffer.splice(0, dropped);
+            console.error(`[analytics] buffer full: dropped ${dropped} oldest events`);
+        }
+    }
+}
+// --- Factory ---
+export function createAnalytics() {
+    if (process.env.ONESOURCE_ANALYTICS === 'false') {
+        return new NoopAnalytics();
+    }
+    const url = process.env.ONESOURCE_ANALYTICS_URL?.trim();
+    const key = process.env.X402_ANALYTICS_KEY?.trim();
+    if (url && key) {
+        return new DashboardAnalytics(url, key);
+    }
+    return new StderrAnalytics();
+}
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAoKA,OAAO,EAAE,CAAC"}