Devrilo/CulturAllyAI-MCP-Server

CulturAllyAI MCP Server

Model Context Protocol (MCP) server providing read-only tools for cultural event management.

This is an educational project created to understand the MCP architecture by implementing a simple server that exposes 4 tools for working with event data from the CulturAllyAI platform.

📋 Table of Contents

• Overview
• Features
• Architecture
• Available Tools
• Installation
• Usage
• Testing
• Development
• Deployment
• Project Structure
• License

🎯 Overview

CulturAllyAI MCP Server is a standalone MCP server that provides read-only access to:

• Event category lists (8 cultural event types)
• Age category lists (7 age groups)
• Event data validation with comprehensive business rules
• Date formatting utilities (ISO 8601 to YYYY-MM-DD)

This server is completely separate from the main CulturAllyAI application and contains no AI generation, database access, or authentication. It's designed as a learning exercise to understand MCP protocol implementation.

Key Characteristics

• ✅ Read-only operations - No data modification
• ✅ Stateless - No database connections
• ✅ Zero dependencies on main app - Completely isolated
• ✅ Type-safe - Full TypeScript with strict mode
• ✅ Well-tested - 114 unit tests with 93%+ coverage
• ✅ MCP-compliant - Uses official @modelcontextprotocol/sdk

✨ Features

1. Event Categories

Returns 8 cultural event categories with Polish labels:

• Koncerty (Concerts)
• Imprezy (Events)
• Teatr i taniec (Theater & Dance)
• Sztuka i wystawy (Art & Exhibitions)
• Literatura (Literature)
• Kino (Cinema)
• Festiwale (Festivals)
• Inne (Other)

2. Age Categories

Returns 7 age groups with Polish labels and age ranges:

• Wszystkie (All ages)
• Najmłodsi (0-3 years)
• Dzieci (4-12 years)
• Nastolatkowie (13-17 years)
• Młodzi dorośli (18-35 years)
• Dorośli (36-64 years)
• Osoby starsze (65+ years)

3. Event Data Validation

Comprehensive validation with Zod schemas:

• Title: 1-100 characters, trimmed
• City: 1-50 characters, trimmed
• Event Date: ISO 8601 format, must be today or future
• Category: Must be one of 8 event categories
• Age Category: Must be one of 7 age categories
• Key Information: 1-200 characters, trimmed

Returns structured validation results with Polish error messages.

4. Date Formatting

Converts ISO 8601 datetime strings to YYYY-MM-DD format:

• Validates date format
• Extracts date portion from datetime
• Returns formatted date or detailed error

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                          │
│            (Claude Desktop, Inspector, etc.)           │
└───────────────────────┬─────────────────────────────────┘
                        │
                        │ stdio transport
                        │ (JSON-RPC 2.0)
                        │
┌───────────────────────▼─────────────────────────────────┐
│              CulturAllyAI MCP Server                    │
│                                                         │
│  ┌─────────────────────────────────────────────────┐  │
│  │         Server (index.ts)                       │  │
│  │  - ListToolsRequestSchema handler               │  │
│  │  - CallToolRequestSchema handler                │  │
│  └───────────────────┬─────────────────────────────┘  │
│                      │                                 │
│  ┌───────────────────▼─────────────────────────────┐  │
│  │      Tool Router (handlers.ts)                  │  │
│  │  - handleToolCall (central dispatcher)          │  │
│  │  - handleGetEventCategories                     │  │
│  │  - handleGetAgeCategories                       │  │
│  │  - handleValidateEventData                      │  │
│  │  - handleFormatEventDate                        │  │
│  └───────────────────┬─────────────────────────────┘  │
│                      │                                 │
│  ┌──────────────────┬▼────────────────────────────┐   │
│  │                  │                             │   │
│  │  Utils           │  Validators                 │   │
│  │  - categories    │  - Zod schemas              │   │
│  │  - formatters    │  - Event validation         │   │
│  │  - date-helpers  │  - Error formatting         │   │
│  └──────────────────┴─────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Components

1. Server Entry Point (src/index.ts)

   • Initializes MCP Server with stdio transport
   • Registers request handlers for ListTools and CallTool
   • Manages server lifecycle

2. Tool Definitions (src/tools/definitions.ts)

   • JSON Schema definitions for all 4 tools
   • Parameter schemas with validation rules
   • Tool metadata (name, description)

3. Tool Handlers (src/tools/handlers.ts)

   • Central router (handleToolCall)
   • Individual tool execution functions
   • Error handling and response formatting

4. Utilities (src/utils/)

   • categories.ts: Static category data
   • formatters.ts: MCP response formatting
   • date-helpers.ts: Date conversion utilities
   • validators.ts: Zod validation schemas

🛠️ Available Tools

1. get-event-categories

Returns the list of available event categories.

Parameters: None

Response:

{
  "categories": [
    { "value": "koncerty", "label": "Koncerty" },
    { "value": "imprezy", "label": "Imprezy" },
    ...
  ]
}

2. get-age-categories

Returns the list of available age categories.

Parameters: None

Response:

{
  "categories": [
    { "value": "wszystkie", "label": "Wszystkie" },
    { "value": "najmlodsi", "label": "Najmłodsi (0-3 lata)" },
    ...
  ]
}

3. validate-event-data

Validates event data against comprehensive business rules.

Parameters:

{
  title: string;           // 1-100 characters
  city: string;            // 1-50 characters
  event_date: string;      // ISO 8601, today or future
  category: string;        // One of 8 event categories
  age_category: string;    // One of 7 age categories
  key_information: string; // 1-200 characters
}

Success Response:

{
  "valid": true,
  "data": {
    "title": "Koncert Chopina",
    "city": "Warszawa",
    "event_date": "2025-12-25T19:00:00Z",
    "category": "koncerty",
    "age_category": "dorosli",
    "key_information": "Wieczór muzyki klasycznej"
  }
}

Error Response:

{
  "valid": false,
  "errors": {
    "title": ["Tytuł jest wymagany"],
    "event_date": ["Data wydarzenia nie może być w przeszłości"]
  }
}

4. format-event-date

Converts ISO 8601 datetime to YYYY-MM-DD format.

Parameters:

{
  date: string; // ISO 8601 datetime
}

Success Response:

{
  "formatted": "2025-12-25",
  "original": "2025-12-25T19:00:00Z"
}

Error Response:

{
  "error": "Invalid date format",
  "details": "Expected ISO 8601 string (e.g., 2025-12-25T19:00:00Z)"
}

📦 Installation

Prerequisites

• Node.js: 22.14.0 or higher
• npm: 10.x or higher
• TypeScript: 5.7.2 (installed as dev dependency)

Setup

# Clone the repository
git clone https://github.com/Devrilo/CulturAllyAI-MCP-Server.git
cd CulturAllyAI-MCP-Server

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm test -- --coverage

Note: If you just want to use the server without cloning, you can access the production deployment directly at: https://culturallyai-mcp-server.marcin-szwajgier.workers.dev

🚀 Usage

Option 1: Production (Cloudflare Workers) 🌐

The easiest way to use the MCP server is via the deployed REST API:

# Get event categories
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/get-event-categories \
  -H "Content-Type: application/json" \
  -d '{}'

# Get age categories  
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/get-age-categories \
  -H "Content-Type: application/json" \
  -d '{}'

# Format event date
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/format-event-date \
  -H "Content-Type: application/json" \
  -d '{"date": "2025-12-25T19:00:00Z"}'

# Validate event data
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/validate-event-data \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Koncert Noworoczny",
    "city": "Warszawa",
    "event_date": "2025-12-31T20:00:00Z",
    "category": "koncerty",
    "age_category": "dorosli",
    "key_information": "Koncert orkiestry symfonicznej"
  }'

You can also test in the Cloudflare Dashboard:

1. Visit https://dash.cloudflare.com
2. Go to Workers & Pages → culturallyai-mcp-server
3. Click Edit code (Quick Edit)
4. Use the HTTP testing interface to send requests

Option 2: Local Development (stdio)

# Build the TypeScript code
npm run build

# Run the server (stdio mode)
node dist/index.js

Option 3: With MCP Inspector

MCP Inspector is a tool for testing MCP servers interactively.

# Install MCP Inspector globally (if not already installed)
npm install -g @modelcontextprotocol/inspector

# Run the inspector with your server
npx @modelcontextprotocol/inspector node dist/index.js

The inspector will open in your browser at http://localhost:5173 where you can:

• View available tools
• Test tool execution with custom parameters
• Inspect request/response payloads
• Debug MCP communication

For detailed testing instructions, see .

Option 4: With Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "culturallyai": {
      "command": "node",
      "args": ["/absolute/path/to/CulturAllyAI-MCP-Server/dist/index.js"]
    }
  }
}

Restart Claude Desktop, and the tools will be available in conversations.

🧪 Testing

Unit Tests

The project has comprehensive unit test coverage:

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage report
npm test -- --coverage

Test Coverage

Current coverage (as of last run):

• Statements: 93.65% (threshold: 80%)
• Branches: 73.91% (threshold: 70%)
• Functions: 100% (threshold: 80%)
• Lines: 93.33% (threshold: 80%)

Test Files

• src/__tests__/categories.test.ts - 11 tests for category utilities
• src/__tests__/formatters.test.ts - 19 tests for MCP response formatting
• src/__tests__/date-helpers.test.ts - 26 tests for date utilities
• src/__tests__/validators.test.ts - 30 tests for Zod validation
• src/__tests__/handlers.test.ts - 28 tests for tool handlers

Total: 114 tests

💻 Development

Scripts

npm run build      # Compile TypeScript to dist/
npm test           # Run unit tests
npm run lint       # Run ESLint
npm run format     # Format code with Prettier

Code Style

• TypeScript: Strict mode enabled
• ESLint: Configured for TypeScript
• Prettier: Code formatting
• Imports: Use .js extensions for ES modules

Adding a New Tool

1. Define tool schema in src/tools/definitions.ts

   {
     name: 'my-new-tool',
     description: 'Tool description',
     inputSchema: { /* JSON Schema */ }
   }
   

2. Create handler in src/tools/handlers.ts

   function handleMyNewTool(args: unknown): McpResponse {
     // Implementation
   }
   

3. Add to router in handleToolCall

   case 'my-new-tool':
     return handleMyNewTool(args);
   

4. Write tests in src/__tests__/handlers.test.ts

5. Update documentation in README.md

🚢 Deployment

Cloudflare Workers

This server is successfully deployed and running on Cloudflare Workers!

🌐 Live URL: https://culturallyai-mcp-server.marcin-szwajgier.workers.dev

Quick Deploy

# Login to Cloudflare (first time only)
npx wrangler login

# Build and deploy
npm run build
npx wrangler deploy

Available Endpoints

The deployed server provides REST API endpoints for all MCP tools:

• GET / - API documentation and examples
• GET /health - Health check endpoint
• GET /tools - List all available tools with schemas
• POST /tools/get-event-categories - Get event categories
• POST /tools/get-age-categories - Get age categories
• POST /tools/validate-event-data - Validate event data
• POST /tools/format-event-date - Format date from ISO 8601

Testing the Deployment

# Health check
curl https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/health

# Get event categories
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/get-event-categories \
  -H "Content-Type: application/json" \
  -d '{}'

# Validate event data
curl -X POST https://culturallyai-mcp-server.marcin-szwajgier.workers.dev/tools/validate-event-data \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Koncert",
    "city": "Warszawa",
    "event_date": "2025-12-25T19:00:00Z",
    "category": "koncerty",
    "age_category": "dorosli",
    "key_information": "Test"
  }'

Monitoring

Access the Cloudflare Dashboard to monitor your deployment:

1. Go to https://dash.cloudflare.com
2. Navigate to Workers & Pages
3. Select culturallyai-mcp-server
4. View metrics, logs, and performance data

For detailed deployment instructions, see .

Local Development (stdio)

For local MCP development with Claude Desktop or MCP Inspector, use the stdio transport:

# Run locally
node dist/index.js

# With MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Architecture Notes

• Production (Cloudflare): Uses HTTP/REST API (Worker fetch handler)
• Development (Local): Uses stdio transport (MCP protocol over stdin/stdout)
• Both versions share the same tool implementations and validation logic

Environment Variables

Currently, no environment variables are required (MVP). Future versions may add:

• API keys for authentication
• Database connection strings
• Feature flags

📁 Project Structure

CulturAllyAI-MCP-Server/
├── src/
│   ├── __tests__/              # Unit tests
│   │   ├── setup.ts
│   │   ├── categories.test.ts
│   │   ├── formatters.test.ts
│   │   ├── date-helpers.test.ts
│   │   ├── validators.test.ts
│   │   └── handlers.test.ts
│   ├── tools/                   # MCP tool definitions and handlers
│   │   ├── definitions.ts       # Tool schemas (JSON Schema)
│   │   └── handlers.ts          # Tool execution logic
│   ├── utils/                   # Utility modules
│   │   ├── categories.ts        # Static category data
│   │   ├── formatters.ts        # MCP response formatting
│   │   ├── date-helpers.ts      # Date conversion utilities
│   │   └── validators.ts        # Zod validation schemas
│   └── index.ts                 # Server entry point
├── dist/                        # Compiled JavaScript (gitignored)
├── coverage/                    # Test coverage reports (gitignored)
├── docs/                        # Documentation
│   ├── TESTING.md               # Testing guide
│   └── DEPLOYMENT.md            # Deployment guide
├── package.json                 # NPM dependencies and scripts
├── tsconfig.json                # TypeScript configuration
├── vitest.config.ts             # Vitest test configuration
├── wrangler.toml                # Cloudflare Workers config
└── README.md                    # This file

📚 Related Documentation

• - Detailed testing guide with MCP Inspector
• - Cloudflare Workers deployment instructions
• Model Context Protocol Docs - Official MCP documentation
• MCP SDK Reference - TypeScript SDK

🤝 Contributing

This is an educational project. Contributions are welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

MIT License - see LICENSE file for details

👨‍💻 Author

Created as a learning exercise to understand Model Context Protocol (MCP) architecture.

Related Project: CulturAllyAI - Main application for cultural event management

🙏 Acknowledgments

• Model Context Protocol - Protocol specification
• Anthropic - MCP creators and Claude Desktop
• Cloudflare Workers - Deployment platform
• Zod - TypeScript-first schema validation