Advanced Cultural Intelligence & Bias Detection MCP Server - A sophisticated Model Context Protocol implementation combining Qloo's cultural API with comprehensive bias detection and compliance analysis.

CulturalTruth is a production-ready Model Context Protocol server that provides:

• 🛡️ Advanced Bias Detection - 50+ regex patterns across 5 bias categories with confidence scoring
• 🎭 Cultural Intelligence - Full integration with Qloo's API for cultural entity analysis
• 📊 Compliance Scoring - EU AI Act, GDPR, Section 508 risk assessment and reporting
• 🔄 Environment Modes - Hackathon (demo-friendly) and Production (strict validation) configurations
• ⚡ Production Features - Rate limiting, circuit breakers, LRU caching, and comprehensive audit trails
• 📈 Analytics & Reporting - Compliance reports, trend analysis, and batch processing

Detects bias across 5 major categories with 50+ patterns:

• Gender-Exclusive Language: "guys", "rockstar developer", "brotherhood"
• Age Discrimination: "young professional", "digital native", "overqualified"
• Racial/Geographic Proxies: specific zip codes, "ivy league", "urban"
• Cultural Assumptions: "native speaker", "american values", "easy to pronounce name"
• Accessibility Barriers: "perfect vision", "fast-paced environment", "must lift"

Each pattern includes severity levels, regulatory risk assessment, and suggested alternatives.

Full integration with Qloo's cultural database:

• Entity Search & Validation - Search 500M+ cultural entities across 10 official entity types
• Demographic Analysis - Age/gender-based cultural preferences
• Trending Content - Real-time cultural relevance data
• Geospatial Insights - Location-based cultural recommendations
• Audience Comparison - Compare cultural affinity between entity groups

• EU AI Act compliance scoring with bias risk assessment
• Section 508/ADA accessibility compliance validation
• GDPR data protection and demographic proxy detection
• Audit Trails - Comprehensive logging for compliance documentation
• Risk Level Classification - Automatic critical/high/medium/low risk scoring

graph TB
    A[Claude Desktop] --> B[CulturalTruth MCP]
    B --> C[Bias Detection Engine]
    B --> D[Qloo API Client]
    B --> E[Cache Layer]
    B --> F[Audit System]
    
    C --> G[50+ Regex Patterns]
    C --> H[Confidence Scoring]
    C --> I[Compliance Calculator]
    
    D --> J[Entity Search]
    D --> K[Demographic Analysis]  
    D --> L[Trending Data]
    
    E --> M[LRU Cache]
    E --> N[Rate Limiter]
    E --> O[Circuit Breaker]
    
    F --> P[Audit Trails]
    F --> Q[Compliance Reports]
    F --> R[Risk Assessment]

• Node.js 18+
• Qloo API Key - Get one at qloo.com/developers
• Claude Desktop or other MCP-compatible client

# Clone the repository
git clone https://github.com/jacksonkasi1/CulturalTruth-MCP.git
cd CulturalTruth-MCP

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Add your Qloo API key to .env
echo "QLOO_API_KEY=your_actual_api_key_here" >> .env

# Build the TypeScript code
npm run build

# Start the MCP server
npm start

Add to your Claude Desktop config:

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

{
  "mcpServers": {
    "cultural-truth": {
      "command": "node",
      "args": ["path/to/CulturalTruth-MCP/dist/index.js"],
      "env": {
        "QLOO_API_KEY": "your_actual_api_key_here"
      }
    }
  }
}

CulturalTruth MCP supports all 10 official Qloo entity types per the official documentation:

1. urn:entity:movie - Feature-length films and cinematic works
2. urn:entity:tv_show - Television content, series, reality shows
3. urn:entity:artist - Musicians, visual artists, performers
4. urn:entity:book - Written works, novels, non-fiction
5. urn:entity:place - Physical locations and venues
6. urn:entity:destination - Geographic destinations, cities, neighborhoods
7. urn:entity:podcast - Episodic audio series and shows
8. urn:entity:video_game - Interactive digital games
9. urn:entity:brand - Commercial brands, retail chains, products
10. urn:entity:person - Individual people (includes actors, authors, directors)

Note: Previously deprecated entity types (Actor, Author, Director) are now consolidated under the Person entity type as recommended by Qloo.

Comprehensive bias analysis with compliance scoring

// Analyzes text for bias patterns and cultural entities
// Returns: bias patterns, compliance scores, cultural entities, audit trail

Generate detailed compliance reports with trends and recommendations

// Creates compliance reports for specified time periods
// Includes: trend analysis, top issues, regulatory recommendations

Get cultural insights using Qloo's recommendation engine

// Search by entity type, popularity, release year, content rating
// Returns: culturally relevant entities with metadata

Demographic-aware cultural analysis

// Filter by age group, gender, audience segments
// Returns: demographic-specific cultural preferences

Search and validate entities in Qloo's database

// Search 500M+ entities by name, type, and filters
// Returns: validated entities with cultural data

Get currently trending cultural content

// Real-time trending data by category
// Returns: trending entities with popularity metrics

Location-based cultural recommendations

// Search by location, radius, price level, rating
// Returns: geographically relevant cultural venues

Compare cultural affinity between entity groups

// Analyze popularity delta, cultural overlap, affinity scores
// Returns: detailed comparison with strategic recommendations

Process multiple content pieces simultaneously

// Batch analysis up to 20 items with rate limiting
// Returns: aggregated results with summary statistics

Trending analysis with demographic filters

// Trending content by category, timeframe, demographics
// Returns: culturally relevant trending entities

Switch between Hackathon and Production modes

// Configure bias detection sensitivity, feature toggles
// Hackathon: Demo-friendly, lenient thresholds
// Production: Strict validation, full compliance

System health and performance metrics

// API calls, cache hit rates, circuit breaker status
// Memory usage, audit trail counts, compliance stats

Add real-time user interaction signals

// Track user interactions (view, like, share, purchase)
// Feeds into cultural intelligence algorithms

# Required
QLOO_API_KEY=your_qloo_api_key_here

# Performance Tuning
RATE_LIMIT_PER_MINUTE=50
MAX_CACHE_SIZE=1000
CACHE_TTL_MS=300000
CIRCUIT_BREAKER_THRESHOLD=5
CIRCUIT_BREAKER_TIMEOUT=30000

# Security
MAX_CONTENT_LENGTH=10000
ENABLE_DETAILED_LOGGING=true

# Audit & Compliance
MAX_AUDIT_TRAILS=1000
AUDIT_RETENTION_DAYS=30

# Environment Mode
CULTURAL_TRUTH_MODE=Hackathon  # or Production

• Bias Detection: Lenient thresholds, fewer patterns active
• Compliance Scoring: Higher tolerance for issues
• Features: Core functionality, optimized for demos
• Performance: Faster response, relaxed validation

• Bias Detection: Strict validation, all 50+ patterns active
• Compliance Scoring: Full regulatory assessment
• Features: All advanced features enabled
• Performance: Maximum accuracy, comprehensive auditing

Switch modes dynamically:

// Use the configure_environment tool in Claude
configure_environment({ mode: "Production", enableFullPotential: true })

• Response Time: < 400ms average (with caching)
• Throughput: 1000+ requests/hour per instance
• Bias Detection: 50+ patterns with confidence scoring
• Cache Hit Rate: 85%+ for entity lookups
• API Integration: Circuit breaker protected

• Input Sanitization: HTML/script tag removal, length limits
• API Protection: Rate limiting, circuit breakers, timeout handling
• Data Privacy: PII filtering, secure audit trails
• Environment Isolation: Configurable sensitivity levels

• Circuit Breaker: Automatic failover on API issues
• Rate Limiting: Token bucket algorithm prevents abuse
• LRU Caching: Memory-efficient entity caching
• Error Recovery: Graceful degradation with detailed logging

# Install dependencies
npm install

# Run with hot reload
npm run dev

# Run tests
npm test

# Type checking
npm run type-check

# Lint code
npm run lint

src/
├── index.ts                 # Main entry point
├── mcp/
│   └── server.ts           # MCP server implementation
├── bias-detector.ts        # Bias pattern detection engine
├── qloo-client.ts         # Enhanced Qloo API client
├── types/
│   └── index.ts           # TypeScript definitions
├── config/
│   └── environment.ts     # Environment configurations
└── utils/
    ├── circuit-breaker.ts # Fault tolerance
    ├── lru-cache.ts      # Memory caching  
    └── rate-limiter.ts   # API rate limiting

Extend the bias detection by editing src/bias-detector.ts:

private static readonly BIAS_PATTERNS = {
  // Add your custom pattern
  custom_bias: {
    type: 'cultural_insensitive',
    pattern: '\\b(your|custom|patterns)\\b',
    severity: 'medium',
    suggestions: ['alternative', 'suggestions'],
    regulation_risk: ['EU_AI_ACT'],
    detectionLevel: ['strict', 'moderate']
  }
  // ... existing patterns
};

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Test specific functionality
npm test -- --grep "bias detection"

Example test:

describe('Enhanced Bias Detection', () => {
  it('should detect gender-exclusive language with confidence', () => {
    const text = 'Looking for guys to join our rockstar development team';
    const patterns = EnhancedBiasDetector.detectBiasPatterns(text);
    
    expect(patterns).toHaveLength(2);
    expect(patterns[0].type).toBe('gender_exclusive');
    expect(patterns[0].confidence).toBeGreaterThan(0.7);
    expect(patterns[0].regulation_risk).toContain('EU_AI_ACT');
  });
});

// Analyze content for bias and get compliance score
const result = await analyzeContentBias({
  content: "Looking for young guys from top universities to join our fast-paced startup",
  user_id: "analyst_001"
});

// Result includes:
// - 4 bias patterns detected (age, gender, education, accessibility)
// - Compliance score: 23/100 (CRITICAL)
// - Regulatory risks: EU_AI_ACT, ADEA, EEOC
// - Suggested improvements for each issue

// Search for movie entities with demographic filtering
const movieInsights = await qlooBasicInsights({
  entity_type: "urn:entity:movie",
  popularity_min: 0.8,
  release_year_min: 2020,
  limit: 10
});

// Search for trending podcasts for young adults
const podcastInsights = await qlooBasicInsights({
  entity_type: "urn:entity:podcast",
  popularity_min: 0.7,
  limit: 5
});

// Find popular destinations for cultural events
const destinationInsights = await qlooBasicInsights({
  entity_type: "urn:entity:destination",
  popularity_min: 0.6,
  limit: 8
});

// Search for influential artists and creators
const artistInsights = await qlooBasicInsights({
  entity_type: "urn:entity:person",
  popularity_min: 0.8,
  limit: 10
});

// Returns culturally relevant entities with popularity metrics

// Generate 30-day compliance report
const report = await getComplianceReport({
  days_back: 30,
  format: "executive"
});

// Includes trend analysis, top bias issues, recommendations

The system supports dynamic environment switching:

// Switch to Production mode for strict validation
await configureEnvironment({
  mode: "Production",
  biasDetectionLevel: "strict",
  enabledFeatures: {
    demographicAnalysis: true,
    culturalTrends: true,
    geospatialInsights: true,
    batchProcessing: true,
    realtimeSignals: true
  }
});

// Switch to Hackathon mode for demos
await configureEnvironment({
  mode: "Hackathon",
  biasDetectionLevel: "lenient"
});

• Job Postings: Detect discriminatory language before publication
• Marketing Content: Ensure inclusive messaging across demographics
• Product Descriptions: Validate accessibility-friendly language

• Content Curation: Find culturally relevant movies, TV shows, books, and podcasts for specific audiences
• Market Research: Understand cultural preferences across all 10 entity types by demographics
• Trend Analysis: Track cultural movements and emerging preferences across destinations, artists, and brands
• Event Planning: Discover popular venues, destinations, and cultural personalities for events
• Influencer Marketing: Identify trending artists, creators, and cultural figures (person entities)
• Travel & Tourism: Find popular destinations and cultural places for targeted recommendations

• Regulatory Compliance: Meet EU AI Act, GDPR, ADA requirements
• Audit Documentation: Comprehensive trails for compliance reviews
• Risk Assessment: Proactive identification of bias risks

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Add tests for new bias patterns or functionality
4. Ensure all tests pass: npm test
5. Update documentation as needed
6. Submit a pull request

• New bias detection patterns for specific industries
• Additional cultural intelligence features
• Performance optimizations
• Integration with other cultural APIs
• Enhanced reporting capabilities

This project is licensed under the MIT License - see the LICENSE file for details.

• Qloo - Cultural intelligence API and data
• Anthropic - Model Context Protocol framework
• MCP Community - Examples, best practices, and inspiration

• GitHub Issues: Report bugs and request features
• Documentation: Comprehensive API docs and examples
• Community: Join discussions about responsible AI development

Built for responsible AI development and cultural intelligence.

CulturalTruth demonstrates how sophisticated bias detection and cultural intelligence can be integrated into AI workflows through the Model Context Protocol. Perfect for developers building inclusive, culturally-aware AI applications.