# research-mcp

MCP server that exposes ATLAS research capability to other agents: live tokenized stock data on Robinhood Chain, on-chain source-of-truth reads, and the research atlases published by the autonomous ATLAS agent. Any MCP capable client (Claude Code, Claude Desktop, custom agents) connects over stdio.

Works out of the box against the public Robinhood Chain testnet endpoints, no API keys needed.

## Tools

Market data:

- `list_markets`: the tokenized stocks on the chain, discovered by merging the Blockscout ERC-20 index (ranked by holders) with GeckoTerminal's trading pools (ranked by liquidity), each classified as equity or not
- `get_token_market`: price, 1h/24h change, market cap, liquidity, and volume for a ticker or contract address, via GeckoTerminal
- `chain_tvl`: the chain's TVL landscape from DefiLlama, with DEX venues and the RWA category called out

On-chain source of truth:

- `get_token_supply`: ERC-20 total supply read directly from chain JSON-RPC at the current block
- `verify_token_contract`: bytecode, on-chain name/symbol/decimals, block, and chain id for an address
- `get_token_holders`: holder count and top-10 concentration from the Blockscout index

Published research (set `ATLAS_API_URL` to a running ATLAS deployment):

- `list_research_atlases`: the agent's published research atlases, newest first
- `get_observation_history`: the agent's recorded time series for a ticker, `chain-tvl`, or a contract address
- `get_agent_status`: model, chain config, publish interval, and memory stats

Tickers resolve through discovery, so `TSLA` finds the tokenized Tesla contract without a hand written registry. Classification is a heuristic over symbol and name (issuer suffixes, tokenized-equity wording, and company-name corroboration for plain names like "Tesla"), so anything surprising can be verified on chain with `verify_token_contract`.

## Setup

```bash
npm install
npm run build
```

## Configuration

All optional, via environment variables:

| Variable | Default | Purpose |
| --- | --- | --- |
| `CHAIN_NAME` | `Robinhood Chain` | Display name used in tool output |
| `GECKOTERMINAL_NETWORK` | `robinhood` | GeckoTerminal network slug |
| `DEFILLAMA_CHAIN` | `Robinhood Chain` | DefiLlama chain name |
| `RPC_URL` | public testnet RPC | EVM JSON-RPC endpoint for on-chain reads |
| `BLOCKSCOUT_URL` | public testnet explorer | Blockscout instance for token index and holders |
| `ATLAS_API_URL` | unset | Base URL of an ATLAS deployment, enables research feed tools |

## Connect a client

Claude Code:

```bash
claude mcp add atlas-research -- node /path/to/research-mcp/dist/index.js
```

Or in any MCP client config:

```json
{
  "mcpServers": {
    "atlas-research": {
      "command": "node",
      "args": ["/path/to/research-mcp/dist/index.js"],
      "env": {
        "ATLAS_API_URL": "https://your-atlas-deployment"
      }
    }
  }
}
```