# MCP Global Events

A TypeScript MCP server that dynamically sources global technology events, communities, and niche networking mixers from Luma, Eventbrite, Meetup-style sources, and fallback search blueprints.

The server runs as a hosted SSE MCP server by default and can also run over stdio for local Claude Desktop or Inspector testing.

## HTTP Endpoints

- `GET /`: server metadata
- `GET /health`: deployment health check
- `GET /sse`: MCP SSE connection endpoint
- `POST /messages?sessionId=<session-id>`: MCP client message endpoint created by the SSE handshake

## Tools

### `search_global_tech_events`

Broad search for technology events across global platforms.

Inputs:

- `location`: city or region worldwide
- `topic`: technology niche such as `AI`, `Web3`, `Crypto`, or `DevOps`
- `event_type`: `Summit`, `Community Meetup`, `Networking Mixer`, `General Tech`, or `All`
- `time_frame`: natural language timeline such as `this week`, `next month`, or `current`

### `discover_tech_communities`

Finds recurring developer groups, ecosystem hubs, and local technology associations.

Inputs:

- `location`: city or region
- `topic`: technology niche

### `get_trending_niche_mixers`

Focused search for informal mixers, hacker house gatherings, social meetups, side events, and casual networking for volatile niches.

Inputs:

- `location`: city name globally
- `niche`: `AI`, `Web3`, or `Crypto`
- `days_ahead`: number of days to search ahead

## Install

```powershell
npm.cmd install
npm.cmd run build
```

## Run

```powershell
npm.cmd start
```

By default, `npm start` runs the hosted SSE server on `PORT` or `3000`.

For local stdio mode:

```powershell
npm.cmd run start:stdio
```

For explicit hosted SSE mode:

```powershell
npm.cmd run start:sse
```

## Test With MCP Inspector

```powershell
npm.cmd run build
npm.cmd run inspect
```

Open the local URL printed by Inspector. Use the Tools panel to list and call:

- `search_global_tech_events`
- `discover_tech_communities`
- `get_trending_niche_mixers`

Example Inspector arguments for `get_trending_niche_mixers`:

```json
{
  "location": "Nairobi",
  "niche": "Web3",
  "days_ahead": 30
}
```

## Claude Desktop Configuration

Claude Desktop normally launches local MCP servers over stdio. Use this mode for local testing.

Build the server first:

```powershell
npm.cmd run build
```

Then add this to your Claude Desktop MCP config. On Windows, the file is usually:

```text
%APPDATA%\Claude\claude_desktop_config.json
```

Example:

```json
{
  "mcpServers": {
    "global-events": {
      "command": "node",
      "args": ["D:\\mcp-event-manager\\dist\\index.js", "--stdio"],
      "env": {
        "EVENT_SOURCE_TIMEOUT_MS": "10000"
      }
    }
  }
}
```

Restart Claude Desktop after saving the config.

## Deploy To Render

This repo includes `render.yaml`.

1. Push the repository to GitHub.
2. In Render, choose **New Web Service**.
3. Connect the GitHub repository.
4. Render should detect the `render.yaml` settings.
5. Add optional API keys in Render environment variables.
6. Deploy.

The public MCP SSE endpoint will be:

```text
https://your-render-service.onrender.com/sse
```

The health check endpoint is:

```text
https://your-render-service.onrender.com/health
```

## Deploy To Railway

Railway can use the included `Procfile`.

1. Push the repository to GitHub.
2. Create a new Railway project from the GitHub repo.
3. Set the start command to `npm start` if Railway does not detect it.
4. Add optional API keys in Railway variables.
5. Deploy.

The public MCP SSE endpoint will be:

```text
https://your-railway-domain.up.railway.app/sse
```

## Vercel Note

This server uses long-lived SSE connections. Render and Railway are better defaults for this transport. Vercel serverless functions may close long-running streams depending on the plan and runtime settings.

## Optional API Keys

The server works without API keys by returning clearly marked fallback discovery leads with source-specific search URLs. Add keys for richer live results:

```json
{
  "EVENTBRITE_API_KEY": "your-eventbrite-token",
  "LUMA_API_KEY": "your-luma-token",
  "MEETUP_API_KEY": "your-meetup-token",
  "SERPER_API_KEY": "your-serper-token"
}
```

You can place those values inside the Claude Desktop `env` object or set them in the environment before launching the server.

## Package For Local Testing

```powershell
npm.cmd pack
```

This creates a `.tgz` package in the project directory that can be installed or moved for local testing.

## Development

```powershell
npm.cmd run dev
```

Build before using Claude Desktop:

```powershell
npm.cmd run build
```