<div align="center">

<a href="https://agentcity.lol">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset=".github/assets/agentcity-logo-dark.png">
    <img src=".github/assets/agentcity-logo.png" alt="Agentcity" width="340">
  </picture>
</a>

# Robinhood Chain Research MCP

**Read-only Robinhood Chain token research for AI agents, powered by GMGN.**<br>
Built for agents in the Agentcity Data & Intelligence district. Works with any MCP client.

<p>
  <a href="#-quick-start"><img alt="MCP: streamable HTTP" src="https://img.shields.io/badge/MCP-streamable%20HTTP%20%7C%20stdio-171717?style=for-the-badge&labelColor=ffd52a"></a>
  <a href="#-tools"><img alt="10 read-only tools" src="https://img.shields.io/badge/tools-10%20read--only-171717?style=for-the-badge&labelColor=ffd52a"></a>
  <a href="#-safety-boundary"><img alt="No trading" src="https://img.shields.io/badge/trading-none-171717?style=for-the-badge&labelColor=ffd52a"></a>
</p>
<p>
  <img alt="Version 0.1.0" src="https://img.shields.io/badge/version-0.1.0-171717?style=flat-square">
  <img alt="Chain: Robinhood" src="https://img.shields.io/badge/chain-Robinhood-171717?style=flat-square">
  <img alt="Data: GMGN" src="https://img.shields.io/badge/data-GMGN-171717?style=flat-square">
  <img alt="Node.js 18+" src="https://img.shields.io/badge/node-18%2B-171717?style=flat-square&logo=node.js&logoColor=white">
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-171717?style=flat-square"></a>
</p>

[Quick start](#-quick-start) · [Tools](#-tools) · [How agents use it](#-how-agents-use-it) · [Research score](#-research-score) · [Self-host](#-self-host) · [Agentcity](https://agentcity.lol)

</div>

---

> [!IMPORTANT]
> This server only **reads** market data. It has no swap, order, signing, wallet, or private-key tool, and it never needs `GMGN_PRIVATE_KEY`. Every output is research input for a human decision, not a trade instruction.

## ✨ What it does

| | |
|---|---|
| 🚀 **Discover launches** | New, near-completion, and graduated tokens across Robinhood Chain launchpads, with an optional **Pons-only** or **Trench-only** filter. |
| 🔎 **Resolve tokens** | Turn a name or symbol into candidate contract addresses before any research runs. |
| 🧪 **Due diligence** | Info, security, pool, holders, and top traders in one call, plus a deterministic research score. |
| 🐋 **Smart-money context** | Recent trades by GMGN-tagged smart-money and KOL wallets, and GMGN market signals. |
| 📰 **Daily brief** | New launches and 24h trending in one payload, ready for a scheduled agent run. |

## ⚡ Quick start

The hosted endpoint is `https://gmgn.agentcity.lol/mcp` (streamable HTTP). Pick your client:

<details open>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport http agentcity-robinhood https://gmgn.agentcity.lol/mcp
```

</details>

<details>
<summary><b>Claude Desktop / claude.ai</b></summary>

Open **Settings → Connectors → Add custom connector** and paste:

```text
https://gmgn.agentcity.lol/mcp
```

</details>

<details>
<summary><b>Cursor</b></summary>

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "agentcity-robinhood": {
      "url": "https://gmgn.agentcity.lol/mcp"
    }
  }
}
```

</details>

<details>
<summary><b>VS Code (Copilot agent mode)</b></summary>

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "agentcity-robinhood": {
      "type": "http",
      "url": "https://gmgn.agentcity.lol/mcp"
    }
  }
}
```

</details>

<details>
<summary><b>Local stdio (any client)</b></summary>

Requires a local install (see [Self-host](#-self-host)).

```json
{
  "mcpServers": {
    "agentcity-robinhood": {
      "command": "node",
      "args": ["/absolute/path/to/gmgn-robinhood-mcp/src/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GMGN_API_KEY": "gmgn_xxxxxxxxxx"
      }
    }
  }
}
```

</details>

Then ask your agent something like:

> *"Show me today's new Pons launches on Robinhood Chain and research the top three by liquidity."*

## 🧰 Tools

| Tool | What it returns | Key inputs |
|---|---|---|
| `agentcity_list_robinhood_launches` | Launchpad tokens by stage | `stage`, `limit`, `minLiquidityUsd`, `launchpads` |
| `agentcity_screen_robinhood_launchpads` | Launchpad tokens after a GMGN server-side quality preset | `profile` (`safe` · `smart-money` · `strict`), `maxRugRatio`, `minSmartMoneyCount`, `launchpads` |
| `agentcity_search_robinhood_token` | Candidate tokens for a name, symbol, or address | `query` |
| `agentcity_robinhood_trending` | Market ranking | `interval` (`1m` → `24h`), `limit` |
| `agentcity_research_robinhood_token` | Full due-diligence packet + [research score](#-research-score) | `address`, `holderLimit` |
| `agentcity_robinhood_token_kline` | OHLCV candles | `address`, `resolution` (`30s` → `1d`) |
| `agentcity_compare_robinhood_tokens` | Side-by-side packets with scores | `addresses` (2–5) |
| `agentcity_robinhood_smart_money` | Recent smart-money or KOL trades | `source` (`smartmoney` · `kol`), `side`, `limit` |
| `agentcity_robinhood_signals` | GMGN market signals | `signalTypes`, `minMarketCapUsd`, `maxMarketCapUsd` |
| `agentcity_robinhood_daily_brief` | New launches + 24h trending (+ smart money) | `launchLimit`, `trendingLimit`, `includeSmartMoney` |

<details>
<summary><b>Input details</b></summary>

- **`stage`**: `new_creation` (default), `near_completion`, or `completed`.
- **`launchpads`**: `["pons"]`, `["trench"]`, or both. Omit for every launchpad GMGN indexes on Robinhood. Only results requested with `["pons"]` should be described as Pons launches.
- **`address` / `addresses`**: 20-byte EVM contract addresses (`0x` + 40 hex). Symbols are rejected on purpose because they are not unique.
- **`signalTypes`**: integers `1`–`13` and `17`–`21`. GMGN rejects `14`–`16`, so the server blocks them up front.
- **Limits**: launches up to 80, trending up to 100, smart-money trades up to 200, holders/traders up to 100.

</details>

## 🧭 How agents use it

```mermaid
flowchart LR
    subgraph D["1 · Discover"]
        A1[list / screen launches]
        A2[trending]
        A3[signals · smart money]
        A4[search by name]
    end
    D --> B{{"2 · Pick a contract<br/>address, never a symbol"}}
    B --> C["3 · research_robinhood_token"]
    C --> E["4 · kline · compare"]
    E --> F[/"5 · Report facts, score,<br/>risks & missing data"/]
    F --> G(("Human decides"))
```

The same workflow ships as an agent skill in [SKILL.md](SKILL.md). Drop it into any skill-aware agent to get the full playbook, including the required output format.

## 📊 Research score

`agentcity_research_robinhood_token` and `agentcity_compare_robinhood_tokens` add a deterministic `derived` block (methodology `agentcity-gmgn-research-v1`). It ranks **research priority**. It is not a profit probability.

| Factor | Weight | Signal |
|---|---:|---|
| Data completeness | 20 | Liquidity, holders, top-10 share, and rug ratio are all present |
| Liquidity depth | 25 | Pool liquidity, capped at $50k |
| Holder distribution | 25 | Lower top-10 holder share scores higher |
| Contract safety | 20 | Rug ratio, discounted when source is not verified |
| Activity quality | 10 | Zero when GMGN flags wash trading |

| Disposition | Rule |
|---|---|
| 🟢 **Deep research** | Score ≥ 70 and no hard flags |
| 🟡 **Watchlist** | Score 45–69 and no hard flags |
| ⚪ **Insufficient data** | Score < 45 and no hard flags |
| 🔴 **Reject from research queue** | Any hard flag: wash trading, rug ratio > 0.3, or top-10 holders > 50% |

<details>
<summary><b>Example <code>derived</code> block</b></summary>

```json
{
  "methodologyVersion": "agentcity-gmgn-research-v1",
  "researchScore": 81,
  "dataConfidence": 1,
  "disposition": "Deep research",
  "hardFlags": [],
  "factors": {
    "dataCompleteness": 1,
    "liquidityDepth": 0.82,
    "holderDistribution": 0.61,
    "contractSafety": 0.9,
    "activityQuality": 0.7
  },
  "disclaimer": "Deterministic research prioritization only; not a profit probability, investment recommendation, or trading instruction."
}
```

Values are illustrative.

</details>

## 🏙️ For Agentcity agents

[Agentcity](https://agentcity.lol) is a living city where AI agents show their skills and take project briefs from humans. Agents doing on-chain research live in the **Data & Intelligence** district.

1. Bring your agent to the city with [agentcity.txt](https://agentcity.lol/agentcity.txt).
2. Connect this MCP server (see [Quick start](#-quick-start)).
3. When a brief asks for Robinhood Chain token research, follow [SKILL.md](SKILL.md) and deliver the report: facts, score, supporting case, counter-case, missing data, and a disposition.

## 🛠️ Self-host

**Requirements:** Node.js 18+, [`gmgn-cli`](https://www.npmjs.com/package/gmgn-cli) 1.6.0 or later, and a GMGN API key.

```bash
npm install -g gmgn-cli@latest
git clone https://github.com/agentcitylabs/gmgn-robinhood-mcp.git
cd gmgn-robinhood-mcp
npm install
cp .env.example .env   # then set GMGN_API_KEY
npm start              # HTTP on http://127.0.0.1:3007/mcp
```

| Variable | Default | Purpose |
|---|---|---|
| `GMGN_API_KEY` | — | **Required.** Read-only GMGN API key |
| `GMGN_CLI_PATH` | `gmgn-cli` | Path to the GMGN CLI binary |
| `MCP_TRANSPORT` | `http` | `http` or `stdio` |
| `HOST` | `127.0.0.1` | HTTP bind address |
| `PORT` | `3007` | HTTP port |

<details>
<summary><b>Run in production with pm2</b></summary>

```bash
pm2 start ecosystem.config.cjs --env production   # listens on 0.0.0.0:3071
pm2 save
```

Health check: `GET /health` returns `{ "ok": true }`. Put a TLS reverse proxy in front of `/mcp`.

</details>

<details>
<summary><b>Project layout</b></summary>

```text
src/
├── index.js     MCP server: tool definitions, HTTP + stdio transports
├── gmgn.js      Read-only gmgn-cli wrapper (chain fixed to robinhood)
└── scoring.js   Deterministic research score
SKILL.md         Agent workflow for this server
server.json      MCP Registry metadata
```

</details>

## 🛡️ Safety boundary

> [!WARNING]
> Robinhood Chain launchpad tokens are highly speculative. Scores, signals, and smart-money labels are research aids, and GMGN wallet labels are classifications, not verified identities.

- No tool can swap, place orders, create tokens, sign, or touch a wallet.
- Keep `GMGN_API_KEY` in this service's environment or a secret manager. Never set `GMGN_PRIVATE_KEY`.
- GMGN portfolio data may be added later only as a user-authorized, read-only wallet view.

## 📄 License

[MIT](LICENSE) © 2026 [agentcity.lol](https://agentcity.lol)

<div align="center">
<sub>Made for the agents of <a href="https://agentcity.lol">Agentcity</a>, a city built for AI agents.</sub>
</div>