# nearblocks-mcp

A small, **remote MCP server** that exposes read-only **NEAR** on-chain wallet data by
wrapping the public [NearBlocks](https://nearblocks.io) API. It speaks MCP over
**Streamable HTTP**, so it has a plain `https://…/mcp` URL — which is exactly what the
[Agents Market](https://agents-market-v2-production.up.railway.app/) connector model
("Private MCP servers") expects.

> Why this exists: NEAR **RPC** (and RPC-based tools like `near-mcp`) only expose an
> account's *current state*, never its transaction history — history lives in an
> **indexer**. NearBlocks is that indexer. This server makes it available to marketplace
> agents (e.g. `wallet-activity-lookup`) as a proper HTTPS connector, converting raw
> chain units to human values and stripping the bulky base64 token icons before anything
> reaches the model.

## Tools

All tools take `accountId` (e.g. `alice.near`, a `.tg` name, or a 64-char implicit
address) and an optional `network` (`mainnet` default, or `testnet`). All are read-only.

| Tool | What it returns |
|---|---|
| `near_account_summary` | Current NEAR balance, staked amount, creation date/age, deletion status. |
| `near_account_transactions` | Paginated tx history (hash, ISO time, from/to, success, actions + NEAR deposits). |
| `near_account_activities` | Balance-change feed: direction (in/out), counterparty, cause, time. |
| `near_account_ft_transfers` | Fungible-token transfers: symbol, human amount, direction, counterparty, time. |
| `near_account_inventory` | Current holdings: FT balances + NFT contracts held now. |
| `near_wallet_activity_summary` | **One-shot report** — fetches state + a bounded window of txns/FT transfers/holdings and returns an aggregated, unit-converted summary (balance, in/out counts, NEAR value flow, top counterparties, top methods/contracts, token totals, holdings). |

Paginated tools accept `perPage` (1–50, default 25), `cursor` (from the previous
response), and `order` (`desc`/`asc`). `near_wallet_activity_summary` accepts `txPages`
(1–4, default 2). Figures in the summary cover the **retrieved recent window**, not the
account's lifetime — the response says so explicitly.

## Run locally

Requires Node ≥ 20.

```bash
npm install
npm run build
cp .env.example .env      # optionally set NEARBLOCKS_API_KEY; leave MCP_AUTH_TOKEN empty for local dev
npm start                 # POST http://localhost:8080/mcp  ·  GET /health
```

### Environment

| Var | Required | Purpose |
|---|---|---|
| `PORT` | no (default 8080) | HTTP listen port (Railway/Fly inject this). |
| `MCP_AUTH_TOKEN` | **in production** | Bearer token callers must send: `Authorization: Bearer <token>`. Empty = unauthenticated (dev only; logs a warning). |
| `NEARBLOCKS_API_KEY` | no | Raises NearBlocks rate limits. Works keyless at the free-tier limit. Server-side only. |
| `NEAR_DEFAULT_NETWORK` | no (default `mainnet`) | Network used when a tool call omits `network`. |

## Deploy

Any host that runs a container and gives you an HTTPS URL works (Railway, Fly, Render, …).

```bash
docker build -t nearblocks-mcp .
docker run -p 8080:8080 -e MCP_AUTH_TOKEN=$(openssl rand -hex 32) nearblocks-mcp
```

Set `MCP_AUTH_TOKEN` (and optionally `NEARBLOCKS_API_KEY`) as service secrets. Your MCP
URL is `https://<your-host>/mcp`.

## Wire it into the Agents Market

1. Deploy this server and copy its `https://<host>/mcp` URL and the `MCP_AUTH_TOKEN`.
2. On the platform, **Building → Connectors → add** a server:
   - **url:** `https://<host>/mcp`
   - **auth:** `static_token`, header empty (⇒ `Authorization: Bearer`), token = your `MCP_AUTH_TOKEN`
3. In an agent's `agent.yaml`, tick it under `private_mcp_servers`:

   ```yaml
   private_mcp_servers:
     - name: nearblocks
       url: https://<host>/mcp
       auth: static_token
       description: NearBlocks MCP — read-only NEAR wallet state, history, transfers, holdings.
   ```

The `wallet-activity-lookup` agent is the intended first consumer: it can call
`near_wallet_activity_summary` in a single tool round instead of hitting the REST API by
hand.

## MCP details

- Transport: **Streamable HTTP**, stateless (a fresh server + transport per request — no
  session state to lose, ideal for a horizontally-scaled connector).
- Endpoint: `POST /mcp`. `GET`/`DELETE /mcp` return 405 (no server-initiated streams in
  stateless mode). `GET /health` and `GET /` are unauthenticated.

## License

MIT — see [LICENSE](LICENSE).