# MCP Server: NEAR Smart Contract Interaction

An MCP (Model Context Protocol) server that allows Claude to read NEAR smart contract state, call view methods, decode transactions, and understand contract interfaces.

## Features

- **Contract Metadata**: Fetch code hash, storage usage, and detect implemented standards (NEP-141, NEP-171, etc.)
- **View Method Calls**: Call any read-only method on any NEAR contract
- **Transaction Decoding**: Decode and explain transaction actions, gas usage, and outcomes
- **State Reading**: Read raw contract state with optional key prefix filtering
- **Interface Explanation**: AI-friendly explanation of contract purpose and functions

## Installation

```bash
npm install @near-mcp/contract-interaction
```

Or run directly:

```bash
npx @near-mcp/contract-interaction
```

## Claude Desktop Configuration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "near-contract": {
      "command": "npx",
      "args": ["@near-mcp/contract-interaction"]
    }
  }
}
```

## Available Tools

### 1. `get_contract_metadata`

Fetches contract metadata including code hash, storage usage, and detected methods/standards.

**Input:**
```json
{
  "contract_id": "wrap.near",
  "network": "mainnet"
}
```

**Output:**
```json
{
  "contract_id": "wrap.near",
  "network": "mainnet",
  "code_hash": "ABC123...",
  "storage_usage_bytes": 12345,
  "storage_usage_near": "0.12345 NEAR",
  "detected_methods": ["ft_transfer", "ft_balance_of", "ft_metadata"],
  "detected_standards": ["NEP-141 (Fungible Token Standard)"]
}
```

### 2. `call_view_method`

Calls a view (read-only) method on any NEAR smart contract.

**Input:**
```json
{
  "contract_id": "wrap.near",
  "method_name": "ft_balance_of",
  "args": { "account_id": "example.near" },
  "network": "mainnet"
}
```

**Output:**
```json
{
  "contract_id": "wrap.near",
  "method": "ft_balance_of",
  "args": { "account_id": "example.near" },
  "result": "1000000000000000000000000",
  "blockHeight": 123456789,
  "blockHash": "ABC...",
  "logs": []
}
```

### 3. `decode_transaction`

Decodes and explains a NEAR transaction, including all actions and their effects.

**Input:**
```json
{
  "tx_hash": "ABC123...",
  "sender_id": "example.near",
  "network": "mainnet"
}
```

**Output:**
```json
{
  "hash": "ABC123...",
  "signerId": "example.near",
  "receiverId": "wrap.near",
  "actions": [
    {
      "type": "FunctionCall",
      "description": "Calls method \"ft_transfer\" with 0.0100 NEAR attached",
      "details": {
        "method_name": "ft_transfer",
        "args_decoded": { "receiver_id": "bob.near", "amount": "1000000" },
        "gas": 30000000000000,
        "deposit": "1"
      }
    }
  ],
  "outcome": {
    "status": "Success",
    "gasUsed": "2.5432 TGas",
    "tokensBurned": "0.000254 NEAR"
  }
}
```

### 4. `get_contract_state`

Reads raw contract state entries, optionally filtered by key prefix.

**Input:**
```json
{
  "contract_id": "example.near",
  "key_prefix": "",
  "network": "mainnet"
}
```

**Output:**
```json
{
  "contract_id": "example.near",
  "network": "mainnet",
  "total_entries": 42,
  "state_entries": [
    {
      "key": "base64...",
      "keyDecoded": "STATE",
      "value": "base64...",
      "valueDecoded": "{\"owner\": \"alice.near\"}"
    }
  ],
  "truncated": false
}
```

### 5. `explain_contract_interface`

Analyzes a contract and provides a human-readable explanation of its purpose and main functions.

**Input:**
```json
{
  "contract_id": "wrap.near",
  "network": "mainnet"
}
```

**Output:**
```json
{
  "contract_id": "wrap.near",
  "network": "mainnet",
  "summary": "Wrapped NEAR (wNEAR) - A fungible token contract implementing the NEP-141 standard...",
  "detected_standards": ["NEP-141 (Fungible Token Standard)", "NEP-145 (Storage Management)"],
  "main_functions": {
    "token_operations": ["ft_transfer", "ft_transfer_call"],
    "queries": ["ft_balance_of", "ft_total_supply", "ft_metadata"],
    "storage": ["storage_deposit", "storage_withdraw"]
  },
  "token_info": {
    "name": "Wrapped NEAR",
    "symbol": "wNEAR",
    "decimals": 24
  },
  "example_usage": [
    "Check token balance: call_view_method(\"wrap.near\", \"ft_balance_of\", {\"account_id\": \"user.near\"})",
    "Get token info: call_view_method(\"wrap.near\", \"ft_metadata\", {})"
  ]
}
```

## Supported Contract Standards

The server automatically detects contracts implementing:

- **NEP-141**: Fungible Token Standard
- **NEP-171**: Non-Fungible Token Standard  
- **NEP-145**: Storage Management
- **NEP-148**: Fungible Token Metadata

## Networks

Both mainnet and testnet are supported. Default is mainnet.

```json
{ "network": "testnet" }
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start
```

## License

MIT