# Luma Events MCP Server

A Model Context Protocol (MCP) server that provides access to tech events from [Luma](https://lu.ma). Built with [mcp-lite](https://github.com/fiberplane/mcp-lite) and deployed on Cloudflare Workers.

## Features

- 🎯 **Search Tech Events**: Discover upcoming tech events, conferences, and meetups
- 🚀 **Serverless**: Runs on Cloudflare's global edge network
- ⚡ **Fast**: Built with mcp-lite for minimal overhead
- 🔧 **MCP Compatible**: Works with any MCP client (Claude Desktop, etc.)

## Prerequisites

Before you begin, make sure you have:

- **Node.js** 18+ installed
- **pnpm** package manager (or npm/yarn)
- **Cloudflare account** (free tier works fine)
- **Wrangler CLI** (installed automatically with dependencies)

## Installation

### 1. Clone or Navigate to Project

```bash
cd mv-mcp-lite
```

### 2. Install Dependencies

```bash
pnpm install
```

This will install:

- `mcp-lite` - MCP server framework
- `hono` - Web framework for Cloudflare Workers
- `axios` - HTTP client for API requests
- `zod` - Schema validation
- `wrangler` - Cloudflare Workers CLI

### 3. Set Up Authentication (Optional)

If you need to authenticate with Cloudflare:

```bash
pnpm wrangler login
```

This will open a browser window to authorize Wrangler with your Cloudflare account.

## Local Development

### Start Development Server

```bash
pnpm dev
```

This starts a local Cloudflare Workers development server at `http://localhost:8787`.

### Test the Server

1. **Health Check**: Visit `http://localhost:8787/` in your browser

   - Should display: "Luma MCP Server (Apify) – connect via /mcp"

2. **MCP Endpoint**: The MCP server is available at `http://localhost:8787/mcp`

### Configure MCP Client

To use this server with an MCP client like Claude Desktop, add this to your MCP configuration file:

**macOS/Linux**: `~/.cursor/mcp.json` or `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "luma-events": {
      "url": "http://localhost:8787/mcp",
      "transport": "http"
    }
  }
}
```

> **Note**: For local development, use `localhost:8787`. After deployment, replace with your Cloudflare Workers URL.

## Deployment to Cloudflare

### 1. Deploy to Cloudflare Workers

```bash
pnpm deploy
```

This command:

- Bundles your code
- Minifies for production
- Deploys to Cloudflare's global network
- Provides you with a live URL (e.g., `https://luma-events-mcp.your-subdomain.workers.dev`)

### 2. Get Your Deployment URL

After deployment, Wrangler will display your Worker's URL:

```
Published luma-events-mcp (X.XX sec)
  https://luma-events-mcp.your-subdomain.workers.dev
```

### 3. Update MCP Client Configuration

Update your MCP configuration to use the production URL:

```json
{
  "mcpServers": {
    "luma-events": {
      "url": "https://luma-events-mcp.your-subdomain.workers.dev/mcp",
      "transport": "http"
    }
  }
}
```

### 4. Restart Your MCP Client

Restart Claude Desktop or your MCP client to connect to the deployed server.

## Usage

Once configured, you can use the following tool through your MCP client:

### Available Tools

#### `search_luma_events`

Searches for tech events on Luma.

**Parameters:**

- `city` (optional): City name (currently not implemented in filtering)
- `country` (optional): Country name (currently not implemented in filtering)
- `query` (optional): Search keyword or topic (e.g., "hackathon", "AI", "web3")

**Example prompts in Claude:**

- "Find tech events on Luma"
- "Search for AI events on Luma"
- "Show me upcoming hackathons from Luma"
- "What tech events are happening soon?"

**Example Response:**
The tool returns a JSON array of events with details like:

- Event name and description
- Date and time
- Location (physical or virtual)
- Number of attendees
- Registration link
- Host information

## Configuration

### Environment Variables

For local development, create a `.dev.vars` file in the project root:

```bash
# .dev.vars (for local development only)
# Add any API keys or secrets here
# EXAMPLE_API_KEY=your-key-here
```

For production secrets:

```bash
# Set production secrets
pnpm wrangler secret put EXAMPLE_API_KEY
```

### Wrangler Configuration

Edit `wrangler.jsonc` to customize:

```jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "luma-events-mcp", // Worker name
  "main": "src/index.ts", // Entry point
  "compatibility_date": "2025-10-07" // Cloudflare compatibility date
}
```

## Project Structure

```
mv-mcp-lite/
├── src/
│   └── index.ts              # Main MCP server code
├── package.json              # Dependencies and scripts
├── wrangler.jsonc            # Cloudflare Workers config
├── tsconfig.json             # TypeScript configuration
├── .dev.vars                 # Local environment variables (gitignored)
└── README.md                 # This file
```

## Development

### Available Scripts

```bash
# Start local development server
pnpm dev

# Deploy to Cloudflare Workers
pnpm deploy

# Generate TypeScript types for Cloudflare bindings
pnpm cf-typegen
```

### Adding New Tools

To add new MCP tools, edit `src/index.ts`:

```typescript
mcp.tool("your_tool_name", {
  description: "What your tool does",
  inputSchema: z.object({
    param1: z.string().describe("Description"),
    param2: z.number().optional(),
  }),
  handler: async (args) => {
    // Your tool logic here
    return {
      content: [
        {
          type: "text",
          text: "Your response",
        },
      ],
    };
  },
});
```

### Adding Resources

Resources provide URI-identified content:

```typescript
mcp.resource(
  "events://upcoming",
  {
    name: "Upcoming Events",
    description: "List of upcoming tech events",
    mimeType: "application/json",
  },
  async (uri) => ({
    contents: [
      {
        uri: uri.href,
        type: "text",
        text: JSON.stringify({ events: [] }),
        mimeType: "application/json",
      },
    ],
  })
);
```

## Troubleshooting

### Issue: "Module not found" errors

**Solution**: Make sure dependencies are installed:

```bash
pnpm install
```

### Issue: Wrangler login fails

**Solution**: Try logging in with a different method:

```bash
pnpm wrangler login --browser=false
```

### Issue: Deployment fails

**Solution**: Check your Cloudflare account limits and verify authentication:

```bash
pnpm wrangler whoami
```

### Issue: MCP client can't connect

**Solution**:

1. Verify the URL is correct (include `/mcp` path)
2. Check if the server is running (visit the URL in browser)
3. Restart your MCP client after configuration changes
4. Check MCP client logs for connection errors

### Issue: CORS errors

**Solution**: If accessing from a web client, add CORS middleware to `src/index.ts`:

```typescript
import { cors } from "hono/cors";

app.use(
  "/mcp",
  cors({
    origin: ["https://your-client-domain.com"],
    credentials: true,
  })
);
```

## Technical Details

### Built With

- **[mcp-lite](https://github.com/fiberplane/mcp-lite)**: Lightweight MCP server framework
- **[Hono](https://hono.dev/)**: Fast web framework for edge computing
- **[Cloudflare Workers](https://workers.cloudflare.com/)**: Serverless execution environment
- **[Zod](https://zod.dev/)**: TypeScript-first schema validation

### Architecture

```
┌─────────────────┐
│   MCP Client    │
│ (Claude, etc.)  │
└────────┬────────┘
         │ HTTP/SSE
         ▼
┌─────────────────┐
│  Cloudflare     │
│    Workers      │
│  (Edge Runtime) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   mcp-lite      │
│   McpServer     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Luma API      │
│  (lu.ma/tech)   │
└─────────────────┘
```

## Resources

- **mcp-lite Documentation**: https://github.com/fiberplane/mcp-lite
- **Model Context Protocol**: https://modelcontextprotocol.io/
- **Cloudflare Workers Docs**: https://developers.cloudflare.com/workers/
- **Luma Platform**: https://lu.ma

## License

[Add your license here]

## Contributing

Contributions welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions:

1. Check the [Troubleshooting](#troubleshooting) section
2. Review [mcp-lite examples](https://github.com/fiberplane/mcp-lite/tree/main/examples)
3. Open an issue in this repository

---

**Built with ❤️ using mcp-lite**