@one-source/api-mcp 1.0.0

package/dist/tools/live/nft-owner.js

@@ -0,0 +1,22 @@
+import { networkParam, formatResponse, addressParam, tokenIdParam } from '../../types.js';
+export const tool = {
+    name: '1s_nft_owner_live',
+    description: 'Get the current NFT owner via ownerOf(tokenId) RPC call. ' +
+        'Use this for real-time ownership verification; use 1s_nft_owner for cached lookups. ' +
+        'Only works for ERC721 tokens.',
+    category: 'live',
+    schema: {
+        contract: addressParam.describe('NFT contract address'),
+        token_id: tokenIdParam,
+        network: networkParam,
+    },
+    handler: async (input, client) => {
+        const res = await client.get('/api/chain/nft-owner', {
+            contract: input.contract,
+            token_id: input.token_id,
+            network: input.network,
+        });
+        return formatResponse(res);
+    },
+};
+//# sourceMappingURL=nft-owner.js.map

package/dist/tools/live/nft-owner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nft-owner.js","sourceRoot":"","sources":["../../../src/tools/live/nft-owner.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE1F,MAAM,CAAC,MAAM,IAAI,GAAY;IAC3B,IAAI,EAAE,mBAAmB;IACzB,WAAW,EACT,2DAA2D;QAC3D,sFAAsF;QACtF,+BAA+B;IACjC,QAAQ,EAAE,MAAM;IAChB,MAAM,EAAE;QACN,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,sBAAsB,CAAC;QACvD,QAAQ,EAAE,YAAY;QACtB,OAAO,EAAE,YAAY;KACtB;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QAC/B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,sBAAsB,EAAE;YACnD,QAAQ,EAAE,KAAK,CAAC,QAAkB;YAClC,QAAQ,EAAE,KAAK,CAAC,QAAkB;YAClC,OAAO,EAAE,KAAK,CAAC,OAA6B;SAC7C,CAAC,CAAC;QACH,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;CACF,CAAC"}

package/dist/tools/live/total-supply.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 1s_total_supply_live — Get total supply of a token via RPC.
+ */
+import type { ToolDef } from '../../types.js';
+export declare const tool: ToolDef;
+//# sourceMappingURL=total-supply.d.ts.map

package/dist/tools/live/total-supply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"total-supply.d.ts","sourceRoot":"","sources":["../../../src/tools/live/total-supply.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAG9C,eAAO,MAAM,IAAI,EAAE,OAkBlB,CAAC"}

package/dist/tools/live/total-supply.js

@@ -0,0 +1,20 @@
+import { networkParam, formatResponse, addressParam } from '../../types.js';
+export const tool = {
+    name: '1s_total_supply_live',
+    description: 'Get the total supply of an ERC20 or ERC721 token via totalSupply() RPC call. ' +
+        'Use this for real-time supply data. ' +
+        'Returns raw token units for ERC20 (divide by 10^decimals) or total count for ERC721.',
+    category: 'live',
+    schema: {
+        token: addressParam.describe('Token contract address'),
+        network: networkParam,
+    },
+    handler: async (input, client) => {
+        const res = await client.get('/api/chain/total-supply', {
+            token: input.token,
+            network: input.network,
+        });
+        return formatResponse(res);
+    },
+};
+//# sourceMappingURL=total-supply.js.map

package/dist/tools/live/total-supply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"total-supply.js","sourceRoot":"","sources":["../../../src/tools/live/total-supply.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE5E,MAAM,CAAC,MAAM,IAAI,GAAY;IAC3B,IAAI,EAAE,sBAAsB;IAC5B,WAAW,EACT,+EAA+E;QAC/E,sCAAsC;QACtC,sFAAsF;IACxF,QAAQ,EAAE,MAAM;IAChB,MAAM,EAAE;QACN,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,wBAAwB,CAAC;QACtD,OAAO,EAAE,YAAY;KACtB;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QAC/B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,yBAAyB,EAAE;YACtD,KAAK,EAAE,KAAK,CAAC,KAAe;YAC5B,OAAO,EAAE,KAAK,CAAC,OAA6B;SAC7C,CAAC,CAAC;QACH,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;CACF,CAAC"}

package/dist/tools/live/tx-details.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 1s_tx_details_live — Get full transaction data and receipt from the RPC node.
+ */
+import type { ToolDef } from '../../types.js';
+export declare const tool: ToolDef;
+//# sourceMappingURL=tx-details.d.ts.map

package/dist/tools/live/tx-details.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx-details.d.ts","sourceRoot":"","sources":["../../../src/tools/live/tx-details.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAG9C,eAAO,MAAM,IAAI,EAAE,OAiBlB,CAAC"}

package/dist/tools/live/tx-details.js

@@ -0,0 +1,19 @@
+import { networkParam, formatResponse, txHashParam, safePath } from '../../types.js';
+export const tool = {
+    name: '1s_tx_details_live',
+    description: 'Get full transaction data and receipt directly from the RPC node. ' +
+        'Use this for very recent or unindexed transactions; use 1s_tx_details for enriched indexed data. ' +
+        'Returns both transaction fields and receipt (status, gas used, logs).',
+    category: 'live',
+    schema: {
+        hash: txHashParam,
+        network: networkParam,
+    },
+    handler: async (input, client) => {
+        const res = await client.get(`/api/chain/tx/${safePath(input.hash)}`, {
+            network: input.network,
+        });
+        return formatResponse(res);
+    },
+};
+//# sourceMappingURL=tx-details.js.map

package/dist/tools/live/tx-details.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx-details.js","sourceRoot":"","sources":["../../../src/tools/live/tx-details.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAErF,MAAM,CAAC,MAAM,IAAI,GAAY;IAC3B,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EACT,oEAAoE;QACpE,mGAAmG;QACnG,uEAAuE;IACzE,QAAQ,EAAE,MAAM;IAChB,MAAM,EAAE;QACN,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,YAAY;KACtB;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QAC/B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,iBAAiB,QAAQ,CAAC,KAAK,CAAC,IAAc,CAAC,EAAE,EAAE;YAC9E,OAAO,EAAE,KAAK,CAAC,OAA6B;SAC7C,CAAC,CAAC;QACH,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;CACF,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared types for tool definitions.
+ */
+import { z } from 'zod';
+import type { OneSourceClient } from './client.js';
+/**
+ * API response envelope — discriminated union on the `error` field.
+ * Moved here from client.ts to avoid circular imports with formatResponse.
+ */
+export type ApiResponse<T = unknown> = {
+    data: T;
+    error?: undefined;
+    meta?: Record<string, unknown>;
+} | {
+    data?: undefined;
+    error: string;
+    meta?: Record<string, unknown>;
+};
+/**
+ * Every tool exports a ToolDef. The server factory iterates these to register tools.
+ */
+export interface ToolDef {
+    name: string;
+    description: string;
+    category: 'indexed' | 'live' | 'chain';
+    schema: z.ZodRawShape;
+    handler: (input: Record<string, unknown>, client: OneSourceClient) => Promise<string>;
+}
+/**
+ * Common parameter: optional network selection.
+ */
+export declare const networkParam: z.ZodOptional<z.ZodEnum<["ethereum", "sepolia", "avax"]>>;
+/**
+ * Common parameter: Ethereum address.
+ */
+export declare const addressParam: z.ZodString;
+/**
+ * Common parameter: optional Ethereum address.
+ */
+export declare const optionalAddressParam: z.ZodOptional<z.ZodString>;
+/**
+ * Common parameter: transaction hash.
+ */
+export declare const txHashParam: z.ZodString;
+/**
+ * Common parameter: token ID (for NFTs).
+ */
+export declare const tokenIdParam: z.ZodString;
+/**
+ * Common parameter: hex-encoded data.
+ */
+export declare const hexDataParam: z.ZodString;
+/**
+ * Common parameter: optional hex-encoded data.
+ */
+export declare const optionalHexParam: z.ZodOptional<z.ZodString>;
+/**
+ * Common parameter: result limit.
+ */
+export declare const limitParam: z.ZodOptional<z.ZodNumber>;
+/**
+ * Common parameter: block number.
+ */
+export declare const blockNumberParam: z.ZodOptional<z.ZodNumber>;
+/**
+ * Encode a value for safe interpolation into a URL path segment.
+ * Use this for any user-supplied value placed in a URL path.
+ */
+export declare function safePath(segment: string): string;
+/**
+ * Format an API response for the LLM. Returns text content.
+ */
+export declare function formatResponse(response: ApiResponse): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAC/B;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC9D;IAAE,IAAI,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACvC,MAAM,EAAE,CAAC,CAAC,WAAW,CAAC;IACtB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvF;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,2DAKtB,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,YAAY,aAGc,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,oBAAoB,4BAA0B,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,WAAW,aAGe,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,YAAY,aAGe,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,YAAY,aAGc,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,gBAAgB,4BAA0B,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,UAAU,4BAMqD,CAAC;AAE7E;;GAEG;AACH,eAAO,MAAM,gBAAgB,4BAKF,CAAC;AAE5B;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAQ5D"}

package/dist/types.js

@@ -0,0 +1,86 @@
+/**
+ * Shared types for tool definitions.
+ */
+import { z } from 'zod';
+/**
+ * Common parameter: optional network selection.
+ */
+export const networkParam = z
+    .enum(['ethereum', 'sepolia', 'avax'])
+    .optional()
+    .describe('Blockchain network: "ethereum" (default), "sepolia", "avax"');
+/**
+ * Common parameter: Ethereum address.
+ */
+export const addressParam = z
+    .string()
+    .regex(/^0x[a-fA-F0-9]{40}$/, 'Must be a valid 0x address (40 hex chars)')
+    .describe('Ethereum address (0x...)');
+/**
+ * Common parameter: optional Ethereum address.
+ */
+export const optionalAddressParam = addressParam.optional();
+/**
+ * Common parameter: transaction hash.
+ */
+export const txHashParam = z
+    .string()
+    .regex(/^0x[a-fA-F0-9]{64}$/, 'Must be a valid transaction hash (64 hex chars)')
+    .describe('Transaction hash (0x...)');
+/**
+ * Common parameter: token ID (for NFTs).
+ */
+export const tokenIdParam = z
+    .string()
+    .regex(/^\d+$/, 'Must be a numeric string')
+    .describe('Token ID (numeric string)');
+/**
+ * Common parameter: hex-encoded data.
+ */
+export const hexDataParam = z
+    .string()
+    .regex(/^0x[a-fA-F0-9]*$/, 'Must be a hex string (0x...)')
+    .describe('Hex-encoded data (0x...)');
+/**
+ * Common parameter: optional hex-encoded data.
+ */
+export const optionalHexParam = hexDataParam.optional();
+/**
+ * Common parameter: result limit.
+ */
+export const limitParam = z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe('Maximum results to return (1-100, default varies by endpoint)');
+/**
+ * Common parameter: block number.
+ */
+export const blockNumberParam = z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe('Block number');
+/**
+ * Encode a value for safe interpolation into a URL path segment.
+ * Use this for any user-supplied value placed in a URL path.
+ */
+export function safePath(segment) {
+    return encodeURIComponent(segment);
+}
+/**
+ * Format an API response for the LLM. Returns text content.
+ */
+export function formatResponse(response) {
+    if (response.error) {
+        return `Error: ${response.error}`;
+    }
+    if (response.meta) {
+        return JSON.stringify({ data: response.data, meta: response.meta }, null, 2);
+    }
+    return JSON.stringify(response.data, null, 2) ?? 'null';
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsBxB;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC;KAC1B,IAAI,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;KACrC,QAAQ,EAAE;KACV,QAAQ,CACP,6DAA6D,CAC9D,CAAC;AAEJ;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC;KAC1B,MAAM,EAAE;KACR,KAAK,CAAC,qBAAqB,EAAE,2CAA2C,CAAC;KACzE,QAAQ,CAAC,0BAA0B,CAAC,CAAC;AAExC;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC,QAAQ,EAAE,CAAC;AAE5D;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC;KACzB,MAAM,EAAE;KACR,KAAK,CAAC,qBAAqB,EAAE,iDAAiD,CAAC;KAC/E,QAAQ,CAAC,0BAA0B,CAAC,CAAC;AAExC;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC;KAC1B,MAAM,EAAE;KACR,KAAK,CAAC,OAAO,EAAE,0BAA0B,CAAC;KAC1C,QAAQ,CAAC,2BAA2B,CAAC,CAAC;AAEzC;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC;KAC1B,MAAM,EAAE;KACR,KAAK,CAAC,kBAAkB,EAAE,8BAA8B,CAAC;KACzD,QAAQ,CAAC,0BAA0B,CAAC,CAAC;AAExC;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,QAAQ,EAAE,CAAC;AAExD;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC;KACxB,MAAM,EAAE;KACR,GAAG,EAAE;KACL,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,QAAQ,EAAE;KACV,QAAQ,CAAC,+DAA+D,CAAC,CAAC;AAE7E;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,EAAE;KACR,GAAG,EAAE;KACL,GAAG,CAAC,CAAC,CAAC;KACN,QAAQ,EAAE;KACV,QAAQ,CAAC,cAAc,CAAC,CAAC;AAE5B;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,QAAqB;IAClD,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,OAAO,UAAU,QAAQ,CAAC,KAAK,EAAE,CAAC;IACpC,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC;AAC1D,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@one-source/api-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "MCP server for OneSource blockchain data — 34 named tools for balances, NFTs, transactions, events, and live chain queries via x402",
+  "bin": {
+    "onesource-api-mcp": "./dist/cli.js"
+  },
+  "main": "./dist/create-server.js",
+  "types": "./dist/create-server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/create-server.d.ts",
+      "default": "./dist/create-server.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "onesource",
+    "web3",
+    "blockchain",
+    "ethereum",
+    "x402",
+    "nft",
+    "erc20",
+    "transactions"
+  ],
+  "scripts": {
+    "gen": "node scripts/gen-tools-index.mjs",
+    "new-tool": "node scripts/new-tool.mjs",
+    "prebuild": "npm run gen",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "BlockParty",
+  "license": "MIT",
+  "homepage": "https://docs.onesource.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AnonDev-BlockParty/sre-services.git",
+    "directory": "skills/mcp"
+  }
+}