mcp-server-near-snapshot-taker 1.0.0

package/README.md

@@ -0,0 +1,37 @@
+# mcp-server-near-snapshot-taker
+
+MCP Server - NEAR Snapshot taker
+
+## Install & Setup
+
+Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-near-snapshot-taker": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-server-near-snapshot-taker"
+      ]
+    }
+  }
+}
+```
+
+## Available Tools
+
+- `take_account_snapshot`
+- `take_token_balance_snapshot`
+- `take_block_snapshot`
+- `take_contract_state_snapshot`
+- `take_validators_snapshot`
+- `ft_balance_of`
+
+## Build from Source
+
+```bash
+npm install && npm run build
+node dist/index.js
+```

package/index.js

@@ -0,0 +1,30 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { tools, callTool } from './tools.js';
+
+const server = new Server(
+  { name: 'mcp-server-near-snapshot-taker', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    const result = await callTool(name, args ?? {});
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('mcp-server-near-snapshot-taker MCP server running on stdio');
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "mcp-server-near-snapshot-taker",
+  "version": "1.0.0",
+  "description": "MCP Server - NEAR Snapshot taker",
+  "main": "index.js",
+  "bin": {
+    "mcp-server-near-snapshot-taker": "index.js"
+  },
+  "scripts": {
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "near-api-js": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { tools, callTool } from './tools.js';
+
+const server = new Server(
+  { name: 'mcp-server-near-snapshot-taker', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    const result = await callTool(name, args ?? {});
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('mcp-server-near-snapshot-taker MCP server running on stdio');
+}
+
+main().catch(console.error);

package/src/tools.ts

@@ -0,0 +1,207 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+
+const NEAR_RPC_URL = "https://rpc.mainnet.near.org";
+
+async function nearRpc(method: string, params: unknown): Promise<unknown> {
+  const response = await fetch(NEAR_RPC_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: "mcp", method, params }),
+  });
+  if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  const data = (await response.json()) as { result?: unknown; error?: { message: string } };
+  if (data.error) throw new Error(`RPC error: ${data.error.message}`);
+  return data.result;
+}
+
+export const tools: Tool[] = [
+  {
+    name: "take_account_snapshot",
+    description: "Take a snapshot of a NEAR account's state including balance, storage, and staking at a specific block.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        account_id: { type: "string", description: "NEAR account ID (e.g. alice.near)" },
+        block_id: { type: ["string", "number"], description: "Block height or hash (optional, defaults to latest)" },
+      },
+      required: ["account_id"],
+    },
+  },
+  {
+    name: "take_token_balance_snapshot",
+    description: "Take a snapshot of a NEP-141 fungible token balance for an account at a specific block.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        account_id: { type: "string", description: "NEAR account to check balance for" },
+        token_contract: { type: "string", description: "NEP-141 token contract account ID" },
+        block_id: { type: ["string", "number"], description: "Block height or hash (optional, defaults to latest)" },
+      },
+      required: ["account_id", "token_contract"],
+    },
+  },
+  {
+    name: "take_block_snapshot",
+    description: "Take a snapshot of a NEAR block including hash, height, timestamp, and gas information.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        block_id: { type: ["string", "number"], description: "Block height or block hash (defaults to latest finalized)" },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "take_contract_state_snapshot",
+    description: "Take a snapshot of a NEAR smart contract's on-chain state keys and values.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        contract_id: { type: "string", description: "Contract account ID" },
+        prefix_base64: { type: "string", description: "Base64-encoded key prefix to filter state (optional)" },
+        block_id: { type: ["string", "number"], description: "Block height or hash (optional, defaults to latest)" },
+      },
+      required: ["contract_id"],
+    },
+  },
+  {
+    name: "take_validators_snapshot",
+    description: "Take a snapshot of current NEAR validators including stake, seats, and epoch information.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        epoch_id: { type: "string", description: "Epoch ID to query validators for (optional, defaults to current)" },
+      },
+      required: [],
+    },
+  },
+];
+
+function buildBlockRef(block_id?: unknown): { finality: string } | { block_id: string | number } {
+  if (block_id === undefined || block_id === null || block_id === "") {
+    return { finality: "final" };
+  }
+  return { block_id: block_id as string | number };
+}
+
+export async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  const timestamp = new Date().toISOString();
+
+  switch (name) {
+    case "take_account_snapshot": {
+      const { account_id, block_id } = args;
+      const result = await nearRpc("query", {
+        request_type: "view_account",
+        account_id,
+        ...buildBlockRef(block_id),
+      }) as Record<string, unknown>;
+      return {
+        snapshot_type: "account",
+        timestamp,
+        account_id,
+        block_height: result.block_height,
+        block_hash: result.block_hash,
+        data: {
+          amount_yocto: result.amount,
+          locked_yocto: result.locked,
+          storage_usage_bytes: result.storage_usage,
+          code_hash: result.code_hash,
+        },
+      };
+    }
+
+    case "take_token_balance_snapshot": {
+      const { account_id, token_contract, block_id } = args;
+      const argsBase64 = Buffer.from(JSON.stringify({ account_id })).toString("base64");
+      const result = await nearRpc("query", {
+        request_type: "call_function",
+        account_id: token_contract,
+        method_name: "ft_balance_of",
+        args_base64: argsBase64,
+        ...buildBlockRef(block_id),
+      }) as Record<string, unknown>;
+      const resultBytes = result.result as number[];
+      const balance = JSON.parse(Buffer.from(resultBytes).toString("utf8"));
+      return {
+        snapshot_type: "token_balance",
+        timestamp,
+        account_id,
+        token_contract,
+        block_height: result.block_height,
+        block_hash: result.block_hash,
+        data: { balance_raw: balance },
+      };
+    }
+
+    case "take_block_snapshot": {
+      const { block_id } = args;
+      const result = await nearRpc("block", buildBlockRef(block_id)) as Record<string, unknown>;
+      const header = result.header as Record<string, unknown>;
+      return {
+        snapshot_type: "block",
+        timestamp,
+        data: {
+          block_height: header.height,
+          block_hash: header.hash,
+          prev_hash: header.prev_hash,
+          timestamp_nanosec: header.timestamp_nanosec,
+          epoch_id: header.epoch_id,
+          gas_price: header.gas_price,
+          total_supply: header.total_supply,
+          validator_proposals: header.validator_proposals,
+        },
+      };
+    }
+
+    case "take_contract_state_snapshot": {
+      const { contract_id, prefix_base64, block_id } = args;
+      const result = await nearRpc("query", {
+        request_type: "view_state",
+        account_id: contract_id,
+        prefix_base64: prefix_base64 ?? "",
+        ...buildBlockRef(block_id),
+      }) as Record<string, unknown>;
+      const values = result.values as Array<{ key: string; value: string }>;
+      return {
+        snapshot_type: "contract_state",
+        timestamp,
+        contract_id,
+        block_height: result.block_height,
+        block_hash: result.block_hash,
+        data: {
+          entry_count: values.length,
+          entries: values.map((v) => ({
+            key_base64: v.key,
+            key_utf8: Buffer.from(v.key, "base64").toString("utf8"),
+            value_base64: v.value,
+          })),
+        },
+      };
+    }
+
+    case "take_validators_snapshot": {
+      const { epoch_id } = args;
+      const result = await nearRpc("validators", epoch_id ? [epoch_id] : [null]) as Record<string, unknown>;
+      const current = result.current_validators as Array<Record<string, unknown>>;
+      return {
+        snapshot_type: "validators",
+        timestamp,
+        data: {
+          epoch_height: result.epoch_height,
+          epoch_start_height: result.epoch_start_height,
+          validator_count: current.length,
+          validators: current.map((v) => ({
+            account_id: v.account_id,
+            stake_yocto: v.stake,
+            shards: v.shards,
+            num_produced_blocks: v.num_produced_blocks,
+            num_expected_blocks: v.num_expected_blocks,
+          })),
+        },
+      };
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": [
+      "ES2020"
+    ],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}