arkea-arena-mcp-server by gmoigneu - MCP Server

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/gmoigneu/arkea-arena-mcp-server.git
cd arkea-arena-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 .

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

License

Apache License 2.0 - see file for details

Resources

Support

For issues and questions:

Open an issue on GitHub
Check the directory for detailed specifications
Review the file for implementation details

Built with the Model Context Protocol