# Citadelle MCP Server

An official [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for **Citadelle Options** - allowing AI agents (like Claude, Cursor, and Windsurf) to securely interact with decentralized US Stock options markets on the EVM / Robinhood Chain.

## 🌟 Features

This MCP server equips AI Assistants with three powerful, context-aware tools:

- **`get_markets_liquidity`**: Fetches all available US Stock options markets (e.g., AAPL, TSLA, NVDA) from the Citadelle Indexer and filters them by available liquidity. The AI instantly knows which markets are active, what the current strike prices are, and whether there is enough liquidity to execute a trade.
- **`get_wallet_portfolio`**: Fetches the open Long and Short (Written) US Stock options positions for any provided EVM wallet address.
- **`generate_trade_link`**: Safely prepares a transaction URL. Instead of having the AI sign a transaction directly with private keys (which is a massive security risk), the AI returns a secure deep-link to the Citadelle Web UI. The user can then review and sign the transaction safely using their browser wallet (MetaMask, Rabby, etc.).

## 🚀 Usage Examples (Prompts)

Once the MCP Server is connected to your AI Assistant, you can use natural language to interact with Citadelle. Try these prompts:

**Exploring Markets:**
> *"I want to trade US Stocks on Citadelle. What AAPL options are currently available and have liquidity?"*
> *"Show me all available Call options for TSLA."*

**Checking Portfolio:**
> *"Show me my open options portfolio for wallet 0xYourWalletAddress..."*
> *"Do I have any active put options for NVDA in my wallet?"*

**Executing Trades:**
> *"Buy 100 AAPL Call Options for me."* 
*(The AI will find the best market, generate a secure trade link, and provide it to you to click and sign).*
> *"I want to write a Put option for TSLA to earn some premium. Generate a transaction link for me."*

## 📦 Installation & Configuration

You can run this server directly via `npx` in any compatible MCP client without needing to install or clone the repository locally!

### Configuring in Cursor / Windsurf
1. Open **Settings -> MCP**.
2. Add a new MCP Server.
3. **Name**: `Citadelle`
4. **Type**: `command`
5. **Command**: `npx`
6. **Args**: `-y citadelle-mcp@latest` *(This ensures the AI always fetches the newest protocol updates)*.
7. Set the Environment Variables within the Cursor UI (see the *Environment Variables* section below).

### Configuring in Claude Desktop
Add the following configuration to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "citadelle": {
      "command": "npx",
      "args": ["-y", "citadelle-mcp@latest"],
      "env": {
        "RPC_URL": "https://api.citadelleoption.tech/api/rpc",
        "WEB_UI_BASE_URL": "https://citadelleoption.tech",
        "API_BASE_URL": "https://api.citadelleoption.tech/api",
        "CONTRACT_ADDRESS": "0xe268a55dD2672Ddb6d7727283B27d9BE601c421a"
      }
    }
  }
}
```

## ⚙️ Environment Variables

To ensure the AI routes your requests to the correct network and API, you must configure the following environment variables:

| Variable | Description | Default / Example |
|----------|-------------|-------------------|
| `RPC_URL` | Your EVM RPC endpoint (use the Backend Proxy for security) | `https://api.citadelleoption.tech/api/rpc` |
| `WEB_UI_BASE_URL` | The domain of the Citadelle Web UI for deep-links | `https://citadelleoption.tech` |
| `API_BASE_URL` | The URL of the Citadelle API Indexer | `https://api.citadelleoption.tech/api` |
| `CONTRACT_ADDRESS` | The EVM address of the Citadelle Options smart contract | `0xe268a55dD2672Ddb6d7727283B27d9BE601c421a` |

## 🛠️ Local Development

If you wish to contribute or run the MCP server locally from source:

1. Clone the repository and install dependencies:
   ```bash
   npm install
   ```
2. Create a `.env` file from the example:
   ```bash
   cp .env.example .env
   ```
3. Build the TypeScript code:
   ```bash
   npm run build
   ```
4. To link it locally to an MCP client like Cursor, point the MCP settings to your local `dist/index.js` file:
   - **Command**: `node`
   - **Args**: `/absolute/path/to/citadelle-mcp/dist/index.js`

## 🔄 Troubleshooting

If your AI assistant is returning outdated market data or generating incorrect links, it may be using a cached version of the MCP Server.
To force an update:
- **Claude Desktop**: Quit the application completely (Cmd+Q / Ctrl+Q) and reopen it. This forces `npx` to fetch the `@latest` version.
- **Cursor/Windsurf**: Restart the MCP Server from the settings panel, or manually run `npx clear-npx-cache` in your terminal before restarting.

## License
MIT