# MCP Kynhood Events Server

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with the Kynhood Events API. This server provides tools for listing events and retrieving detailed event information.

## Features

- **Automatic Token Management**: Fetches and caches guest tokens automatically
- **Smart Retry Logic**: Handles 401 errors by refreshing tokens
- **Type-Safe**: Built with TypeScript for robust error handling
- **Production-Ready**: Comprehensive logging and error handling

## Tools Available

### 1. `listEvents`
List events from the Kynhood API with pagination support.

**Parameters:**
- `skip` (optional, default: 0): Number of events to skip
- `limit` (optional, default: 10): Maximum number of events to return

**Returns:** Array of events with metadata

### 2. `getEventById`
Get detailed information about a specific event.

**Parameters:**
- `id` (required): The event ID (24-character hex string)

**Returns:** Complete event details

## Installation

### Prerequisites
- Node.js 18+
- npm or yarn
- Claude Desktop app

### Steps

1. **Clone or create the project directory:**
```bash
mkdir mcp-kynhood-events
cd mcp-kynhood-events
```

2. **Install dependencies:**
```bash
npm install
```

3. **Configure environment (optional):**
```bash
cp .env.example .env
```

Edit `.env` if you need to customize settings:
```env
API_BASE_URL=https://***.****.com/api
DEFAULT_SKIP=0
DEFAULT_LIMIT=10
DEBUG=false
```

## Running the Server

### Development Mode
```bash
npm start
```

### Build TypeScript
```bash
npm run build
```

### Watch Mode (Auto-restart)
```bash
npm run dev
```

## Connecting to Claude Desktop

### Configuration

Add this server to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "kynhood-events": {
      "command": "node",
      "args": [
        "G:\\projects\\mcp\\event\\dist\\index.js"
      ],
      "env": {
        "API_BASE_URL": "https://***.****.com/api"
      }
    }
  }
}
```

**Alternative: Using TypeScript directly (no build required):**
```json
{
  "mcpServers": {
    "kynhood-events": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "G:\\projects\\mcp\\event\\src\\index.ts"
      ],
      "env": {
        "API_BASE_URL": "https://***.****.com/api"
      }
    }
  }
}
```

**Note**: Update the path to match your actual installation directory.

### Restart Claude Desktop

After updating the configuration, completely quit and restart Claude Desktop for changes to take effect.

## Usage Examples

Once connected to Claude Desktop, you can use natural language to interact with the Kynhood Events API:

### Example Queries

**List trending events:**
```
Show me the latest events from Kynhood
```

**Get specific event details:**
```
Get details for event 68cd87381ea5
```

**List with pagination:**
```
Show me events 10-20 from Kynhood (skip 10, limit 10)
```

**Multiple operations:**
```
List the first 5 events, then show me details for the first one
```

## Architecture

### Project Structure
```
mcp-kynhood-events/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── api/
│   │   ├── token.ts          # Token fetching logic
│   │   └── events.ts         # Events API calls
│   ├── tools/
│   │   ├── listEvents.ts     # List events tool
│   │   └── getEventById.ts   # Get event by ID tool
│   └── utils/
│       ├── http.ts           # HTTP client with retry logic
│       ├── logger.ts         # Logging utility
│       └── tokenCache.ts     # In-memory token cache
├── package.json
├── tsconfig.json
└── README.md
```

### Token Management Flow

1. **First Request**: Server checks token cache (empty)
2. **Fetch Token**: Calls `GET /api/token` to get guest token
3. **Cache Token**: Stores token with 55-minute TTL
4. **Use Token**: Attaches to all subsequent API requests
5. **Handle 401**: If token expires, automatically fetches new token and retries

### Error Handling

- **Network Errors**: Logged and returned to Claude with context
- **401 Unauthorized**: Automatically retries once with fresh token
- **Invalid Responses**: Validates response structure and provides meaningful errors
- **Missing Parameters**: Validates required parameters before API calls

## API Endpoints Used

### 1. Get Guest Token
```
GET https://***.****.com/api/token
```
Returns JWT token for guest authentication.

### 2. List Events
```
POST https://***.****.com/api/events?skip=0&limit=10
Authorization: Bearer <token>
Body: {}
```
Returns paginated list of events.

### 3. Get Event by ID
```
GET https://***.****.com/api/events/:eventId
Authorization: Bearer <token>
```
Returns detailed event information.

## Development

### Adding New Tools

1. Create tool file in `src/tools/`
2. Define input/output interfaces
3. Implement tool function
4. Export tool definition
5. Register in `src/index.ts`

### Debugging

Enable debug logging:
```env
DEBUG=true
```

Logs are output to stderr (visible in Claude Desktop logs).

## Troubleshooting

### Server Not Appearing in Claude Desktop

1. Check configuration file path is correct
2. Verify JSON syntax in `claude_desktop_config.json`
3. Ensure file paths use absolute paths
4. Restart Claude Desktop completely

### Token Errors

- Server automatically handles token refresh
- Check API_BASE_URL is correct
- Verify network connectivity to api.kynhood.com

### Build Errors

```bash
# Clean and reinstall
rm -rf node_modules dist
npm install
npm run build
```

## Testing the API Manually

You can test the Kynhood API endpoints directly:

```bash
# Get token
curl https://***.****.com/api/token

# List events (replace TOKEN with actual token)
curl -X POST "https://***.****.com/api/events?skip=0&limit=10" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d "{}"

# Get event by ID
curl "https://***.****.com/api/events/68cd8a9496a5" \
  -H "Authorization: Bearer TOKEN"
```

## License

MIT

## Support

For issues or questions:
- Check the logs in Claude Desktop
- Verify API connectivity: `curl https://***.****.com/api/token`
- Review this README for configuration steps