# Luma MCP Server (`luma-mcp`)

A Model Context Protocol (MCP) server for searching, discovering, and extracting upcoming Luma (`lu.ma`) events, tech talks, AI meetups, and hackathons with citation-ready line numbering.

Designed for seamless integration with LLM applications such as Claude Desktop, Cursor, and custom autonomous agents.

---

## Features

- **Dual-Mode Retrieval**:
  - **Keyword Search Mode**: Fast, lightweight keyword matching over title, tags, hosts, and descriptions.
  - **Live API Pagination Mode**: Direct real-time pagination from Luma's discover API.
- **Citation-Ready Line Numbering**: All event content is formatted into Markdown with line numbers (`   1|...`, `   2|...`), allowing LLMs to provide exact line citations.
- **ProseMirror-to-Markdown Engine**: Parses rich text descriptions, links, bullet lists, and agendas from Luma into clean GitHub-flavored Markdown.
- **Multi-Location & Category Filtering**: Built-in support for tech hubs including San Francisco, Berkeley, New York, Palo Alto, San Jose, and Shanghai, alongside category filters (`ai`, `crypto`, `tech`).
- **Date Range Constraints**: Filter events with strict date constraints (`MM:DD:YY` or `YYYY-MM-DD`).
- **Zero Heavy ML Dependencies**: Self-contained and fast to install with minimal external dependencies.
- **Dual Transport Support**: Usable as a standard Stdio MCP server or an optional standalone Express HTTP API.

---

## Architecture

```
                       ┌──────────────────────┐
                       │   LLM Client         │
                       │ (Claude / Cursor)    │
                       └──────────┬───────────┘
                                  │ stdio (MCP Protocol)
                       ┌──────────▼───────────┐
                       │   bin/mcp-server.js  │
                       └──────────┬───────────┘
                                  │
                       ┌──────────▼───────────┐
                       │    luma_engine.js    │
                       └─────┬──────────┬─────┘
                             │          │
        ┌────────────────────┴──┐    ┌──┴────────────────────┐
        │ Keyword Search Vault  │    │  Luma Live REST API   │
        │ (vault/index.json)    │    │ (api.luma.com)        │
        └───────────────────────┘    └───────────────────────┘
```

---

## Installation

### Prerequisites

- Node.js >= 18.0.0

### Setup

```bash
git clone https://github.com/MegaGimen/lumaMCP.git
cd lumaMCP
npm install
```

Verify your setup by running the test suite:

```bash
npm test
```

---

## MCP Client Configuration

### 1. Claude Desktop

Add the following to your `claude_desktop_config.json`:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "luma": {
      "command": "node",
      "args": ["/path/to/lumaMCP/bin/mcp-server.js"]
    }
  }
}
```

### 2. Cursor

In Cursor Settings -> Features -> MCP Servers, click **Add New MCP Server**:

- **Name**: `luma-mcp`
- **Type**: `command`
- **Command**: `node /path/to/lumaMCP/bin/mcp-server.js`

Alternatively, add it to `.cursor/mcp.json` in your workspace:

```json
{
  "mcpServers": {
    "luma": {
      "command": "node",
      "args": ["/path/to/lumaMCP/bin/mcp-server.js"]
    }
  }
}
```

---

## Tool Reference: `get_luma_events`

The server registers a single tool `get_luma_events`.

### Input Parameters

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `searchkeys` | string | `null` | Keywords to trigger title and content search over the event vault. When omitted, falls back to live API pagination. |
| `locations` | array of strings | `["san_francisco"]` | Target cities. Options: `'san_francisco'`, `'berkeley'`, `'new_york'`, `'palo_alto'`, `'san_jose'`, `'shanghai'`. |
| `categories` | array of strings | `[]` | Category filters. Options: `'tech'`, `'ai'`, `'crypto'`. Leave empty for all categories. |
| `start_date` | string | `null` | Start date filter in `MM:DD:YY` or `YYYY-MM-DD` format. |
| `end_date` | string | `null` | End date filter in `MM:DD:YY` or `YYYY-MM-DD` format. |
| `page` | integer | `1` | 1-indexed page number for live pagination (when `searchkeys` is omitted). |
| `limit` | integer | `5` | Maximum number of events to return in search mode. |

### Example Tool Calls

#### Keyword Search

```json
{
  "searchkeys": "autonomous agents hackathon",
  "locations": ["san_francisco", "berkeley"],
  "categories": ["ai", "tech"],
  "limit": 3
}
```

#### Live Pagination

```json
{
  "locations": ["san_francisco"],
  "categories": ["tech"],
  "page": 1
}
```

---

## Standalone HTTP API (Optional)

You can also run the service as an independent HTTP REST server:

```bash
npm start
```

Default port: `8004` (configurable via `PORT` environment variable).

### Endpoints

- `GET /health`: Returns service health and vault statistics.
- `GET /api/cities`: Lists supported city identifiers and coordinate mappings.
- `GET /api/events`: Fetches paginated live events in JSON.
- `GET /api/dump-markdown` / `POST /api/dump-markdown`: Returns line-numbered Markdown for LLM ingestion.
- `POST /api/vault/search`: Performs keyword title and content search over the local vault.
- `POST /api/vault/sync`: Triggers background synchronization of upcoming events into the local vault.
- `GET /api/vault/status`: Returns current synchronization status and cached event counts.

---

## Contributing & License

Contributions are welcome. Feel free to open issues or submit pull requests.

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.