# 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](./SETUP_INSTRUCTIONS.md) for detailed setup instructions.

## Quick Start

1. Install dependencies:
   ```bash
   npm install
   ```

2. Build the server:
   ```bash
   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](https://rusticisoftware.com/api-reference/)
- [xAPI Specification](https://github.com/adlnet/xAPI-Spec)
- [MCP Documentation](https://modelcontextprotocol.io)

## 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