Arkea Arena MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to the Arkea Arena API. Query events, artists, venue information, FAQs, and more through a standardized interface.

Features

• 24 MCP Tools for querying events, artists, articles, FAQs, and venue information
• 8 Resource URIs for direct content access (e.g., event://metallica-concert-2024)
• 6 Pre-configured Prompts for common workflows
• Intelligent Caching with configurable TTLs to minimize API calls
• Error Handling with automatic retry logic and exponential backoff
• Full TypeScript implementation with type safety

Quick Start

Installation

Option 1: Use with npx (Recommended - No installation required)

Simply reference the package in your Claude Desktop config:

{
  "mcpServers": {
    "arkea-arena": {
      "command": "npx",
      "args": ["-y", "arkea-arena-mcp-server"]
    }
  }
}

Option 2: Install globally

npm install -g arkea-arena-mcp-server

Option 3: Install from source

# Clone the repository
git clone https://github.com/yourusername/arkea-mcp-server.git
cd arkea-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

The server connects to https://content.arkeaarena.com by default - no configuration needed!

Optionally, you can set environment variables for authentication or enhanced search:

# Optional: Authentication token for protected endpoints (wishlist)
ARKEA_API_TOKEN=your-jwt-token-here

# Optional: Typesense search configuration
TYPESENSE_HOST=search.arkeaarena.com
TYPESENSE_PORT=443
TYPESENSE_KEY=your-typesense-key
TYPESENSE_SCHEME=https

Usage with Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (Recommended):

{
  "mcpServers": {
    "arkea-arena": {
      "command": "npx",
      "args": ["-y", "arkea-arena-mcp-server"]
    }
  }
}

Using global install:

{
  "mcpServers": {
    "arkea-arena": {
      "command": "arkea-arena-mcp"
    }
  }
}

Using local source:

{
  "mcpServers": {
    "arkea-arena": {
      "command": "node",
      "args": ["/absolute/path/to/arkea-mcp-server/build/index.js"]
    }
  }
}

With authentication (for wishlist features):

{
  "mcpServers": {
    "arkea-arena": {
      "command": "npx",
      "args": ["-y", "arkea-arena-mcp-server"],
      "env": {
        "ARKEA_API_TOKEN": "your-jwt-token"
      }
    }
  }
}

Restart Claude Desktop to load the server.

Usage with Other MCP Clients

The server communicates via standard input/output (stdio):

node build/index.js

Available Tools

Event Tools

• list_events - List and filter events by genre, tags, artist, or date
• get_event - Get detailed information about a specific event
• search_events - Full-text search across event titles and descriptions
• get_related_events - Find related events based on tags and genre

Artist Tools

• list_artists - List artists with optional filtering
• get_artist - Get detailed artist information with events
• search_artists - Search artists by name or biography

Content Tools

• list_faqs - Get frequently asked questions (searchable)
• get_faq - Get a specific FAQ by ID
• list_articles - List news articles and blog posts
• get_article - Get a specific article
• get_page - Get a content page by slug
• get_homepage - Get homepage content and layout

Venue Tools

• list_hotels - Get partner hotels near the venue
• get_hotel - Get hotel details
• list_partners - Get arena partners and sponsors
• get_active_announcements - Get current site-wide announcements

Organization Tools

• list_tags - Get available filtering tags
• list_producers - List event producers
• get_producer - Get producer details

Wishlist Tools (Requires Authentication)

• get_wishlist - Get user's saved events
• add_to_wishlist - Add event to wishlist
• remove_from_wishlist - Remove event from wishlist

Resources

Access content directly via URI:

event://metallica-concert-2024        # Event by slug
event://id/abc123xyz                   # Event by document ID
artist://metallica                     # Artist by slug
article://arena-news-2024              # Article by slug
page://access                          # Page by slug
homepage://                            # Homepage content
faqs://                                # All FAQs
announcements://active                 # Active announcements

Prompts

Pre-configured workflows for common tasks:

• find_event - Help users find events matching criteria
• event_details - Get comprehensive event information
• upcoming_events - Show upcoming events with filters
• artist_info - Get artist information and their events
• venue_info - Get venue access, hotels, and announcements
• answer_faq - Answer questions using the FAQ database

Development

Build

npm run build        # Compile TypeScript
npm run watch        # Watch mode for development

Testing

Test the MCP server interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

Example test request:

{
  "method": "tools/call",
  "params": {
    "name": "list_events",
    "arguments": {
      "genre": "Concert",
      "upcoming": true,
      "limit": 5
    }
  }
}

Project Structure

arkea-mcp-server/
�� src/
   �� index.ts        # Main MCP server
   �� api-client.ts   # Strapi API client with retry logic
   �� cache.ts        # Caching layer with TTL support
   �� handlers.ts     # Tool implementation handlers
   �� tools.ts        # Tool definitions
   �� types.ts        # TypeScript type definitions
�� build/              # Compiled JavaScript (generated)
�� knowledge/          # API and MCP specifications
�� package.json
�� tsconfig.json
�� README.md

API Integration

This server integrates with the Arkea Arena Strapi CMS backend. Key features:

• Strapi v5 REST API with advanced filtering
• Deep population of related content (artists, sessions, images, tags)
• Automatic retry with exponential backoff for failed requests
• Smart caching with different TTLs per content type
• Optional Typesense integration for enhanced search

Caching Strategy

| Content Type | Cache TTL | |--------------|-----------| | Events | 5 minutes | | Artists | 15 minutes | | FAQs | 1 hour | | Pages | 30 minutes | | Homepage | 5 minutes | | Announcements | 2 minutes | | Articles | 15 minutes | | Hotels | 1 hour | | Partners | 1 hour | | Tags | 30 minutes |

Error Handling

The server handles errors gracefully:

• Network errors: Automatic retry with exponential backoff (max 3 attempts)
• 404 Not Found: Clear "not found" messages
• 400 Bad Request: Parameter validation errors
• 401 Unauthorized: Authentication required messages
• 500 Server Error: User-friendly error messages

Errors are returned in JSON format:

{
  "error": "Event not found: invalid-slug"
}

Authentication

Some endpoints (wishlist tools) require authentication. Set the ARKEA_API_TOKEN environment variable with a valid JWT token from the Arkea Arena authentication system.

Without authentication:

• All read-only tools work normally
• Wishlist tools will return authentication errors

Examples

Finding Upcoming Concerts

// Tool: list_events
{
  "genre": "Concert",
  "upcoming": true,
  "limit": 10,
  "sort": "date_asc"
}

Searching for an Event

// Tool: search_events
{
  "query": "metallica",
  "limit": 5
}

Getting Event Details

// Tool: get_event
{
  "identifier": "metallica-concert-2024",
  "id_type": "slug"
}

// Or via Resource URI
// event://metallica-concert-2024

Finding Related Events

// Tool: get_related_events
{
  "event_id": "abc123xyz",
  "limit": 5
}

Getting Artist Information

// Tool: get_artist
{
  "identifier": "metallica",
  "id_type": "slug",
  "include_events": true
}

// Or via Resource URI
// artist://metallica

Searching FAQs

// Tool: list_faqs
{
  "query": "parking",
  "limit": 10
}

Getting Venue Information

// Tool: get_page
{
  "slug": "access"
}

// Combined with
// Tool: list_hotels
// Tool: get_active_announcements

Troubleshooting

Server not connecting

• Ensure the server is built: npm run build
• Check the path in your MCP client configuration
• Verify environment variables are set correctly
• Check stderr output for error messages

Authentication errors

• Verify ARKEA_API_TOKEN is set for wishlist operations
• Ensure the token is valid and not expired
• Check token has correct permissions

Cache issues

The cache is in-memory and clears when the server restarts. To manually clear cache, restart the server.

API rate limiting

The server includes automatic retry logic and caching to prevent rate limiting. If issues persist, increase cache TTLs in src/cache.ts.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

License

MIT License - see LICENSE file for details

Resources

• Model Context Protocol Documentation
• MCP TypeScript SDK
• Strapi Documentation
• Arkea Arena API Specification
• MCP Server Specification

Support

For issues and questions:

• Open an issue on GitHub
• Check the knowledge directory for detailed specifications
• Review the CLAUDE.md file for implementation details

Built with the Model Context Protocol >