<div align="center">
  <img src="https://3dawn.xyz/logo-mark.png" alt="3Dawn MCP" width="80" />
  <h1>3Dawn MCP Server</h1>
  <p><strong>Control the 3Dawn AI 3D marketplace from Claude, ChatGPT, or any MCP-compatible AI</strong></p>

  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  [![Python](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://python.org)
  [![MCP](https://img.shields.io/badge/Protocol-MCP%201.9-blueviolet)](https://modelcontextprotocol.io)
  [![Live](https://img.shields.io/badge/Platform-3dawn.xyz-00a041.svg)](https://3dawn.xyz)
</div>

---

## What is this?

The **3Dawn MCP Server** exposes the full 3Dawn platform to any AI assistant via the
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

Connect it to **Claude**, **ChatGPT**, **Cursor**, or any MCP client and ask your AI to:

> *"Generate a cartoon robot 3D model and mint it as an NFT"*
> *"List all assets in my wallet and put the best one on the marketplace for 0.1 ETH"*
> *"What drops are active right now? How much have I earned from embeds?"*

Transport: **Streamable HTTP** — works with remote Claude.ai integrations and local clients.

---

## 🛠️ Available Tools

### 🎨 Generation

| Tool | Description |
|------|-------------|
| `generate_3d_from_text` | Start a text → 3D job (Meshy AI backend) |
| `get_generation_status` | Poll a job until `succeeded` or `failed` |
| `refine_3d_asset` | Apply a refinement pass to an existing model |

### 📦 Assets

| Tool | Description |
|------|-------------|
| `list_my_assets` | All 3D assets owned by a wallet |
| `get_asset_details` | Full details for a specific asset |
| `browse_featured_assets` | Trending / featured assets on the platform |
| `get_embed_code` | Get iframe embed code (earns $0.02/view) |
| `get_embed_analytics` | View count + earnings analytics for an asset |

### 🛒 Marketplace

| Tool | Description |
|------|-------------|
| `browse_marketplace` | Browse listings — filter by ETH or stock payment |
| `get_listing_details` | Full details for a specific listing |

### 🎰 Drops

| Tool | Description |
|------|-------------|
| `browse_drops` | Browse drops by status (active / sold_out / ended) |
| `get_drop_details` | Bonding curve, slots, countdown for a specific drop |

### 👤 User & Earnings

| Tool | Description |
|------|-------------|
| `get_user_profile` | Creator stats: assets, mints, listings, drops |
| `get_user_earnings` | Detailed earnings: embed yield, sales, drops |

### 📊 Platform

| Tool | Description |
|------|-------------|
| `get_platform_stats` | Live platform-wide statistics |
| `get_activity_feed` | Latest mints, sales, drops across the platform |
| `list_available_stocks` | All tokenized stocks with live prices |

---

## 🚀 Quick Start

### Prerequisites

- Python 3.11+
- pip

### Install

```bash
git clone https://github.com/3DawnRH/3dawn-mcp.git
cd 3dawn-mcp
pip install -r requirements.txt
```

### Configure

```bash
cp .env.example .env
```

Edit `.env`:

```env
# Required — point at the live platform or your self-hosted instance
3DAWN_API_URL=https://3dawn.xyz

# Optional — override the default port (8000)
# PORT=8000
```

> ✅ **No API keys needed** to run the MCP server itself.
> The server talks to the public 3Dawn REST API.

### Run

```bash
python server.py
```

The server listens on `http://0.0.0.0:8000/mcp` (Streamable HTTP transport).

---

## 🔌 Connect to Claude.ai

1. Go to **Claude.ai → Settings → Integrations → Add MCP Server**
2. Enter your server URL: `https://your-host:8000/mcp`
3. Click Connect

For local testing, use a tunnel:

```bash
# Using ngrok
ngrok http 8000
# Then add the ngrok URL to Claude
```

---

## 🔌 Connect to Cursor / Local Clients

Add to your `~/.cursor/mcp.json` (or equivalent):

```json
{
  "mcpServers": {
    "3dawn": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

---

## 💡 Example Prompts

Once connected to Claude or another AI:

```
Generate a sci-fi spaceship 3D model in realistic style for my wallet 0x1234…
```

```
Browse the 3Dawn marketplace and find the cheapest ETH listing. Show me its 3D model.
```

```
How many total assets have been created on 3Dawn? What are the top creators earning?
```

```
List all my assets at wallet 0xABCD… and tell me which ones are listed for sale.
```

```
Check the embed analytics for asset ID 42 — how much has it earned so far?
```

---

## 🏗️ Architecture

```
3dawn-mcp/
├── server.py       # FastMCP server — all 18 tools defined here
├── client.py       # Async HTTP client wrapping the 3Dawn REST API
├── requirements.txt
└── .env.example
```

**Dependencies:**

| Package | Purpose |
|---------|---------|
| `mcp[cli]` | Model Context Protocol SDK |
| `httpx` | Async HTTP for API calls |
| `python-dotenv` | `.env` file loading |

---

## 🧪 Testing Tools Manually

```bash
# Install MCP inspector
npx @modelcontextprotocol/inspector http://localhost:8000/mcp
```

Or use `curl`:

```bash
# List all tools
curl http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

---

## 🔧 Self-Hosting 3Dawn

To point the MCP server at your own 3Dawn instance:

```env
3DAWN_API_URL=https://your-3dawn-instance.com
```

See [3dawn-app](https://github.com/3DawnRH/3dawn-app) for self-hosting instructions.

---

## 🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome — especially new tools!

---

## 🔐 Security

See [SECURITY.md](SECURITY.md) for vulnerability reporting.

---

## 📄 License

MIT — see [LICENSE](LICENSE)

---

<div align="center">
  <a href="https://3dawn.xyz">3dawn.xyz</a> ·
  <a href="https://github.com/3DawnRH/3dawn-app">Main App</a> ·
  <a href="https://github.com/3DawnRH/3dawn-contracts">Contracts</a> ·
  <a href="https://x.com/3DawnRH">@3DawnRH</a>
</div>