Unclaimed SOL Scanner

Instructions

Implementation Reference

• src/tools/scan.ts:47-103 (handler)

  The handler function `handleScan` implements the logic for `scan_claimable_sol`, which parses the input wallet address, performs a scan using `ScannerService`, and returns a formatted response.

  export async function handleScan(
    args: unknown,
    config: Config,
    scanner: ScannerService,
  ): Promise<{ content: { type: string; text: string }[]; isError?: boolean }> {
    try {
      const { wallet_address } = InputSchema.parse(args ?? {});
      const resolvedAddress =
        wallet_address || config.keypair?.publicKey.toBase58();
      if (!resolvedAddress) {
        return {
          content: [{ type: 'text', text: 'wallet_address is required.' }],
          isError: true,
        };
      }
      const { pubkey } = await validateWalletAddress(resolvedAddress);
      const wallet = pubkey.toBase58();
      const ref = config.claimEnabled ? 'ref=mcp-claim' : 'ref=mcp';
      const url = `${WEBSITE_URL}?${ref}`;
  
      // Check cache for main scan
      const cached = scanCache.get(wallet);
      let cacheAgeSec = 0;
      let data: { totalSol: number; maxSol: number; tokenCount: number; bufferCount: number };
  
      if (cached) {
        data = cached.data;
        cacheAgeSec = Math.round(cached.ageMs / 1000);
      } else {
        const summary = await scanner.getScanSummary(wallet);
        data = {
          totalSol: summary.totalClaimableSol,
          maxSol: summary.maxClaimableSol ?? summary.totalClaimableSol,
          tokenCount: summary.tokenCount || 0,
          bufferCount: summary.bufferCount || 0,
        };
        scanCache.set(wallet, data);
      }
  
      return buildResponse(data, config.claimEnabled, url, cacheAgeSec);
    } catch (err) {
      if (err instanceof WalletValidationError) {
        return { content: [{ type: 'text', text: err.message }], isError: true };
      }
      return {
        content: [
          {
            type: 'text',
            text:
              (err as Error).message ||
              'Scanner temporarily unavailable. Visit https://unclaimedsol.com directly.',
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:62-64 (registration)

  The tool is registered and linked to `handleScan` in the `CallToolRequestSchema` request handler in `src/index.ts`.

  if (name === 'scan_claimable_sol') {
    return handleScan(args, config, scanner);
  }

• src/tools/scan.ts:23-44 (schema)

  The tool definition, including the schema and description, is generated by `getScanToolDefinition`.

  export function getScanToolDefinition(keypairWallet?: string) {
    const walletDesc = keypairWallet
      ? `Solana wallet address (base58 public key). Defaults to configured keypair wallet: ${keypairWallet}`
      : 'Solana wallet address (base58 public key)';
  
    return {
      name: 'scan_claimable_sol',
      description:
        'Check how much SOL a Solana wallet can reclaim from dormant accounts. ' +
        'Returns total claimable amount. To claim, visit unclaimedsol.com or ' +
        'configure a local keypair for Vibe Claiming.',
      inputSchema: {
        type: 'object' as const,
        properties: {
          wallet_address: {
            type: 'string',
            description: walletDesc,
          },
        },
        ...(keypairWallet ? {} : { required: ['wallet_address'] }),
      },
    };