Kxcoscan AI Tools

БесплатноHosted

A production-ready MCP server that wraps the Kxcoscan blockchain explorer API into structured endpoints for AI agents. It enables users to query wallet balances

автор: KeralPatel

GitHub

Описание

A production-ready MCP server that wraps the Kxcoscan blockchain explorer API into structured endpoints for AI agents. It enables users to query wallet balances, transaction histories, token transfers, and contract details via natural language.

README

A production-ready AI tool server that wraps the Kxcoscan blockchain explorer API into clean, structured endpoints that any AI agent (Claude, GPT-4, etc.) can call directly.

Built with Next.js 14, deployed on Vercel, and includes an MCP (Model Context Protocol) server.

Architecture

kxcoscan-ai-tools/
├── app/
│   ├── api/
│   │   ├── balance/          GET  /api/balance
│   │   ├── transactions/     GET  /api/transactions
│   │   ├── token-transfers/  GET  /api/token-transfers
│   │   ├── tx/               GET  /api/tx
│   │   ├── contract/         GET  /api/contract
│   │   ├── logs/             GET  /api/logs
│   │   ├── token-info/       GET  /api/token-info
│   │   ├── wallet-summary/   GET  /api/wallet-summary
│   │   └── mcp/              POST /api/mcp  (MCP JSON-RPC)
│   ├── page.tsx              Interactive frontend dashboard
│   └── layout.tsx
├── components/
│   ├── ApiTester.tsx         Interactive tool tester (client)
│   └── JsonDisplay.tsx       Syntax-highlighted JSON viewer
├── lib/
│   ├── kxcoscan.ts           Core API wrapper + utilities
│   └── cache.ts              Edge cache response helpers
├── mcp/
│   └── server.ts             MCP tool definitions
├── config/
│   └── modules.json          Supported modules & AI tool manifest
├── types/
│   └── explorer.ts           Full TypeScript types
└── vercel.json

Key design decisions

Concern	Solution
No API key needed	Open requests with a descriptive `User-Agent`
Parallel fetches	`Promise.allSettled` — one failed upstream call won't break the response
AI-friendly output	Wei → KXCO conversion, ISO timestamps, human-readable status strings
Caching	Vercel edge `Cache-Control: s-maxage` headers (10s–1hr by tier)
MCP	Stateless JSON-RPC 2.0 handler — no persistent process needed on Vercel
CORS	`` on all `/api/` routes so any AI agent can call from any origin

API Reference

All endpoints return JSON. All require a GET request with query parameters.

`GET /api/balance`

Param	Required	Description
`address`	✅	Wallet address `0x...`

{
  "wallet": "0xABC...",
  "balance": "102.345678",
  "symbol": "KXCO",
  "balanceRaw": "102345678000000000000"
}

`GET /api/transactions`

Param	Required	Default	Description
`address`	✅	—	Wallet address
`page`		1	Page number
`offset`		10	Results per page (max 100)
`sort`		desc	`asc` or `desc`
`startblock`		—	Filter from block
`endblock`		—	Filter to block

`GET /api/token-transfers`

Param	Required	Description
`address`	✅	Wallet address
`contractaddress`		Filter to a specific token
`page`		Page number
`offset`		Results per page

`GET /api/tx`

Param	Required	Description
`txhash`	✅	Transaction hash `0x...` (64 hex chars)

Returns status: "success" | "failed" | "pending".

`GET /api/contract`

Param	Required	Description
`address`	✅	Contract address

Returns abi, sourceCode, contractName, isVerified.

`GET /api/logs`

Param	Required	Description
`address`	✅	Contract address
`fromBlock`		Start block (default: 0)
`toBlock`		End block (default: latest)
`topic0`		Event signature hash filter

`GET /api/token-info`

Param	Required	Description
`contractaddress`	✅	Token contract address

Returns name, symbol, decimals, totalSupply, totalSupplyFormatted.

`GET /api/wallet-summary` ⭐ AI-optimised

Param	Required	Description
`address`	✅	Wallet address

Returns balance + last 5 transactions + last 5 token transfers + a natural-language summary string.

MCP Server

The /api/mcp endpoint implements Model Context Protocol over stateless HTTP.

Available tools

Tool	Description
`wallet_balance`	Get native KXCO balance
`wallet_transactions`	List transactions
`token_transfers`	List token transfers
`wallet_summary`	Full wallet overview
`transaction_info`	Tx status by hash
`contract_abi`	Contract ABI + source
`token_info`	Token metadata
`event_logs`	Contract event logs

Claude Desktop configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kxcoscan": {
      "url": "https://your-app.vercel.app/api/mcp",
      "transport": "http"
    }
  }
}

Manual JSON-RPC call

# List tools
curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call a tool
curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 1,
    "params": {
      "name": "wallet_summary",
      "arguments": { "address": "0xYOUR_ADDRESS" }
    }
  }'

Deployment

Deploy to Vercel (recommended)

# 1. Install Vercel CLI
npm i -g vercel

# 2. Clone and install
git clone <this-repo>
cd kxcoscan-ai-tools
npm install

# 3. Deploy
vercel

# Follow prompts — no environment variables required.
# The API is open (no key needed).

Local development

npm install
npm run dev
# → http://localhost:3000

Build check

npm run build
npm run type-check

How AI agents call these tools

Option 1 — Direct HTTP (any agent framework)

import httpx

BASE = "https://your-app.vercel.app"

# Get wallet summary
r = httpx.get(f"{BASE}/api/wallet-summary", params={"address": "0xABC..."})
data = r.json()
print(data["summary"])  # Natural language overview

Option 2 — Claude tool use (Anthropic SDK)

import anthropic, httpx

client = anthropic.Anthropic()

def wallet_summary(address: str) -> dict:
    return httpx.get(
        "https://your-app.vercel.app/api/wallet-summary",
        params={"address": address}
    ).json()

tools = [{
    "name": "wallet_summary",
    "description": "Get a comprehensive overview of a KXCO wallet",
    "input_schema": {
        "type": "object",
        "properties": {
            "address": {"type": "string", "description": "Wallet address 0x..."}
        },
        "required": ["address"]
    }
}]

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    tools=tools,
    messages=[{
        "role": "user",
        "content": "Analyse wallet 0xABC..."
    }]
)

# Handle tool_use blocks
for block in response.content:
    if block.type == "tool_use" and block.name == "wallet_summary":
        result = wallet_summary(block.input["address"])
        # Continue conversation with result...

Option 3 — MCP (Claude Desktop / Claude Code)

See MCP Server section above.

Adding new tools

Add the new module/action to config/modules.json
Create app/api/<tool-name>/route.ts following the existing pattern
Add the tool definition to mcp/server.ts
Add the tool card to components/ApiTester.tsx

The config/modules.json file serves as the canonical manifest — you can also parse it programmatically to auto-discover available tools.

Caching tiers

Tier	`s-maxage`	`stale-while-revalidate`	Used for
`realtime`	10s	30s	Live data
`short`	60s	120s	Balances, transactions
`medium`	5min	10min	Token metadata
`long`	1hr	2hr	Contract ABIs (immutable)

License

MIT

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "kxcoscan-ai-tools": {
      "command": "npx",
      "args": []
    }
  }
}

Kxcoscan AI Tools

Описание

README

Architecture

Key design decisions

API Reference

`GET /api/balance`

`GET /api/transactions`

`GET /api/token-transfers`

`GET /api/tx`

`GET /api/contract`

`GET /api/logs`

`GET /api/token-info`

`GET /api/wallet-summary` ⭐ AI-optimised

MCP Server

Available tools

Claude Desktop configuration

Manual JSON-RPC call

Deployment

Deploy to Vercel (recommended)

Local development

Build check

How AI agents call these tools

Option 1 — Direct HTTP (any agent framework)

Option 2 — Claude tool use (Anthropic SDK)

Option 3 — MCP (Claude Desktop / Claude Code)

Adding new tools

Caching tiers

License

Как установить

Похожие MCP

Fetch

AWS KB Retrieval

Spring AI MCP Server

llm-analysis-assistant

Command Palette

Kxcoscan AI Tools

Описание

README

Architecture

Key design decisions

API Reference

GET /api/balance

GET /api/transactions

GET /api/token-transfers

GET /api/tx

GET /api/contract

GET /api/logs

GET /api/token-info

GET /api/wallet-summary ⭐ AI-optimised

MCP Server

Available tools

Claude Desktop configuration

Manual JSON-RPC call

Deployment

Deploy to Vercel (recommended)

Local development

Build check

How AI agents call these tools

Option 1 — Direct HTTP (any agent framework)

Option 2 — Claude tool use (Anthropic SDK)

Option 3 — MCP (Claude Desktop / Claude Code)

Adding new tools

Caching tiers

License

Как установить

Похожие MCP

Fetch

AWS KB Retrieval

Spring AI MCP Server

llm-analysis-assistant

`GET /api/balance`

`GET /api/transactions`

`GET /api/token-transfers`

`GET /api/tx`

`GET /api/contract`

`GET /api/logs`

`GET /api/token-info`

`GET /api/wallet-summary` ⭐ AI-optimised