Rustici LRS MCP Server v2.0

A Model Context Protocol (MCP) server that provides powerful tools for interacting with Rustici LRS (Learning Record Store) via xAPI, with enhanced analytics and aggregation capabilities.

🚀 What's New in v2.0

Enhanced Analytics Tools

• Built-in Aggregations - Get instant insights without manual data processing
• Completion Statistics - Track course completions with daily breakdowns
• Assessment Analytics - Pass rates, score distributions, and performance metrics
• User Activity Summaries - Comprehensive learner behavior analysis
• Flexible Search - Text-based filtering with partial matching
• Timeline Analysis - Activity trends by hour, day, week, or month
• Verb Statistics - Understand learning action patterns

Features

This MCP server provides the following tools for Rustici LRS:

📊 Analytics & Insights (NEW in v2.0)

• rustici_get_statements_with_analytics - Get statements with automatic aggregations and breakdowns
• rustici_get_completion_stats - Course completion statistics with daily trends
• rustici_get_assessment_stats - Assessment performance with pass rates and score distributions
• rustici_get_user_activity - Comprehensive user activity summary
• rustici_get_verb_stats - Verb usage statistics across all statements
• rustici_search_statements - Flexible text-based search with partial matching
• rustici_get_activity_timeline - Activity trends grouped by time periods

📝 xAPI Statement Tools

• rustici_get_statements - Query xAPI statements with filters (agent, verb, activity, time range)
• rustici_post_statement - Post new xAPI statements to track learning activities

🔐 Credential Management

• rustici_get_credential - Get information about the current credential
• rustici_list_credentials - List all xAPI credentials for the tenant

🏢 Tenant Management

• rustici_get_tenant - Get information about a specific tenant
• rustici_list_tenants - List all available tenants

📚 Activity Data

• rustici_get_state - Get activity state data for learners
• rustici_get_activity_profile - Get activity/course metadata
• rustici_get_agent_profile - Get learner profile data

🏥 Health Check

• rustici_health_check - Verify Rustici LRS connection

What is Rustici LRS?

Rustici LRS is a Learning Record Store that implements the xAPI (Experience API) specification. It stores learning activity data in the form of xAPI statements, which track:

• Course completions
• Assessment scores
• Learning progress
• User interactions
• Custom learning events

Use Cases

For Learning Analytics

• Quick Insights - Get completion rates, pass rates, and engagement metrics instantly
• Trend Analysis - Identify patterns in learning behavior over time
• Performance Tracking - Monitor assessment scores and success rates
• User Segmentation - Understand different learner behaviors

For QA Testing

• Verify xAPI statement tracking in learning applications
• Test LRS integrations
• Debug xAPI implementations

For Data Analysis

• Query learning activity data for reporting
• Export data for further analysis
• Create custom dashboards

For Monitoring

• Check LRS health and connectivity
• Track system usage patterns
• Identify anomalies

Installation

See SETUP_INSTRUCTIONS.md for detailed setup instructions.

Quick Start

1. Install dependencies:

   npm install
   

2. Build the server:

   npm run build
   

3. Configure environment variables (see SETUP_INSTRUCTIONS.md)

4. Add to Cline MCP settings

Configuration

Required environment variables:

• RUSTICI_CREDENTIAL_ID - Your Rustici credential ID
• RUSTICI_CREDENTIAL_SECRET - Your Rustici credential secret
• RUSTICI_BASE_URL - Rustici Engine base URL
• RUSTICI_TENANT_NAME - Tenant name (e.g., latam-qa, ana-qa)

Example Usage

Once configured, you can use these tools in Cline:

Analytics Examples (NEW!)

"Get completion statistics for course XYZ from last month"
"Show me assessment performance with pass rates"
"Analyze user activity for learner ABC"
"What are the most common learning actions?"
"Search for statements containing 'quiz'"
"Show me activity timeline by day for last week"

Traditional Queries

"Get recent xAPI statements for a learner"
"Check Rustici LRS health"
"Post a completion statement for a course"
"Get activity state for a specific user"

Enhanced Analytics Features

1. Statements with Analytics

Get statements plus automatic aggregations:

• Total statement count
• Unique actors, verbs, activities
• Verb breakdown
• Activity breakdown
• Time range analysis

2. Completion Statistics

Track course completions:

• Total completions
• Unique users
• Daily completion trends
• Time range filtering

3. Assessment Performance

Analyze assessment results:

• Total attempts
• Pass/fail counts
• Pass rate percentage
• Average score
• Score distribution (0-20%, 21-40%, etc.)

4. User Activity Summary

Comprehensive learner analysis:

• Total activities
• Verb breakdown
• Activities accessed
• Top 10 activities
• First and last activity timestamps

5. Verb Statistics

Understand learning actions:

• Total statements analyzed
• Unique verb count
• Verb breakdown with percentages
• Sorted by frequency

6. Flexible Search

Text-based filtering:

• Search by actor name (partial match)
• Search by verb display (e.g., "completed")
• Search by activity name (partial match)
• Combine multiple filters

7. Activity Timeline

Trend analysis:

• Group by hour, day, week, or month
• Statement counts per period
• Sorted chronologically
• Time range filtering

Common xAPI Verbs

The server recognizes standard xAPI verbs:

• http://adlnet.gov/expapi/verbs/completed - Course completion
• http://adlnet.gov/expapi/verbs/passed - Assessment passed
• http://adlnet.gov/expapi/verbs/failed - Assessment failed
• http://adlnet.gov/expapi/verbs/answered - Question answered
• http://adlnet.gov/expapi/verbs/attempted - Assessment attempted
• http://adlnet.gov/expapi/verbs/experienced - Content experienced
• http://adlnet.gov/expapi/verbs/launched - Course launched

Best Practices

Query Optimization

• Use specific time ranges to limit result sets
• Use analytics tools for aggregated insights
• For large datasets, consider the rustici-db-server for direct database access
• Limit statement queries to reasonable sizes (< 1000 statements)

Analytics Usage

• Use rustici_get_statements_with_analytics for quick overviews
• Use rustici_get_completion_stats for course performance tracking
• Use rustici_get_assessment_stats for assessment analysis
• Use rustici_search_statements for flexible text-based queries
• Use rustici_get_activity_timeline for trend analysis

Time Ranges

Always specify time ranges for better performance:

• ISO 8601 format: 2026-06-01T00:00:00Z
• Relative: Use date calculations in your queries

Documentation

• Rustici Engine API Documentation
• xAPI Specification
• MCP Documentation

Version History

v2.0.0 (June 18, 2026)

• ✨ Added 7 new analytics tools
• 📊 Built-in aggregations and statistics
• 🔍 Flexible search capabilities
• 📈 Timeline and trend analysis
• 🎯 Assessment performance metrics
• 👥 User activity summaries
• 📉 Verb usage statistics

v1.0.0

• Initial release with basic xAPI operations
• Statement retrieval and posting
• Credential and tenant management
• Activity state and profile access
• Health check functionality

License

MIT