sugarlearning-mcp
jernejk/sugarlearning-mcp
Unofficial SugarLearning MCP server, CLI tools, and change tracker for AI agent integration
Instalação
npx convez-ai jernejk/sugarlearning-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Unofficial SugarLearning CLI + MCP
Unofficial community-built CLI tools, change tracker, and MCP server for SugarLearning.
This project is not affiliated with or endorsed by SugarLearning. It uses the existing SugarLearning API with your own credentials.
SugarLearning is a learning management system for tracking employee training modules and learning items.
What it does
- MCP Server — Exposes SugarLearning data to AI agents (Claude Code, VS Code Copilot, Codex, LM Studio) via the Model Context Protocol
- One-Command Login — Headed-browser login via Playwright captures a Bearer token automatically — no OAuth redirect URI required
- Change Tracking — Takes periodic snapshots of modules, items, and assignments, then computes diffs to detect changes over time
- Module Monitoring — Watch specific modules for assignment changes (who was added/removed)
- Semantic Search — Optional Qdrant vector index for natural language search across all learning content
Prerequisites
- Python 3.12+
- uv (recommended) or pip
- A SugarLearning account with admin access
- (Optional) Playwright for the one-command browser login
- (Optional) Docker for Qdrant vector search
Quick Start
1. Install globally (Recommended)
git clone https://github.com/jernejk/sugarlearning-mcp.git
cd sugarlearning-mcp
uv tool install .
This makes the sl command available system-wide — run it from any directory.
To update after pulling new changes:
cd sugarlearning-mcp
git pull
uv tool install --force --reinstall .
To uninstall:
uv tool uninstall sugarlearning-tools
git clone https://github.com/jernejk/sugarlearning-mcp.git
cd sugarlearning-mcp
uv sync
Then prefix all commands with uv run:
uv run sl login
uv run sl sync
uv run sl search "training"
2. Authenticate
Recommended: one-command browser login. Install the browser extra once, then run sl login — a real Chromium window opens, you log in to SugarLearning normally, and the CLI sniffs the Bearer token from the first API request. No OAuth redirect URI registration required.
uv pip install -e '.[browser]' # or: uv tool install '.[browser]' for global
playwright install chromium
sl login --company YourCompany # company code is saved to config
sl login # subsequent logins
The browser window closes automatically once a token is captured.
Manual paste — print DevTools instructions and paste a token yourself:
sl login --manual
sl login -t "$(pbpaste)" # after copying the Authorization header
Refresh token (for auto-renewal — longer-lived than access tokens):
sl login -r YOUR_REFRESH_TOKEN
To grab a refresh token from the browser:
- Open Chrome DevTools > Application > Local Storage >
https://my.sugarlearning.com - Find the
refresh_tokenkey and copy its value
Full OAuth PKCE flow (requires a registered CLI redirect URI):
sl login --oauth
Your user ID is auto-detected from the token. Credentials are stored at ~/.config/sugarlearning/config.json.
Advanced: You can also configure via
.envfile — see Configuration.
3. First sync
sl sync
This fetches all modules, items, and assignments, then saves a snapshot. Run it again later to detect changes.
CLI Reference
| Command | Description |
|---|---|
sl login | Launch a headed browser and sniff the Bearer token (default, requires [browser] extra) |
sl login --company CODE | Set company code (combine with any login flow) |
sl login --manual | Print DevTools paste instructions |
sl login -t TOKEN | Authenticate with a Bearer token directly |
sl login -r TOKEN | Authenticate with refresh token (auto-renewal) |
sl login --oauth | OAuth PKCE flow (requires registered redirect URI) |
sl <command> --json | Output as JSON instead of human-readable text |
sl sync | Fetch data, create snapshot, show changes since last sync |
sl diff | Show the most recent diff |
sl watch MODULE_ID | Show current assignments and change history for a module |
sl history | List all saved snapshots |
sl backlog | Show your learning backlog |
sl search QUERY | Search modules and items (Qdrant or text fallback) |
sl leaderboard | Show company leaderboard rankings |
sl badges [USER] | Show badges earned by a user |
sl profile [USER] | Show user profile with rank and stats |
sl get ITEM_ID | Get a learning item's full details and content |
sl complete ITEM_ID | Mark a learning item as complete |
sl note ITEM_ID CONTENT | Add or update a private note on a learning item |
sl index | Build/rebuild Qdrant vector index |
sl mcp | Start the MCP server (stdio) |
Most commands support --limit N and --skip N for pagination:
sl search "training" --limit 5
sl backlog --limit 10 --skip 5
sl watch 6307 --limit 20
sl history --limit 5
Status Filtering
Filter your backlog by completion status:
sl backlog --status outstanding # Items you still need to do
sl backlog --status completed # Items you've finished
sl backlog --status blocked # Items that are blocked
Combine status filtering with search to find specific items in your backlog:
sl search "training" --status completed # Completed training items
sl search "security" --status outstanding # Outstanding security items
Leaderboard, Badges & Profile
See how you and your team are tracking:
sl leaderboard # Company rankings (hides 0% users)
sl leaderboard --all # Include users with 0% progress
sl leaderboard --group 5 --limit 10 # Top 10 in a specific group
sl badges # Your earned badges
sl badges jk # Another user's badges
sl profile # Your profile with rank & stats
sl profile jk # Another user's profile
JSON Output
Add --json to any command for machine-readable output:
sl backlog --status outstanding --json
sl search "training" --json
sl watch 6307 --json
sl diff --json
sl leaderboard --json
sl profile --json
Examples
Watch for assignment changes on the "Spec Reviews" module:
sl watch 6307
Search for training-related content (includes clickable URLs for each result):
sl search "training conferences"
Fetch the full body of a specific item:
sl get 8291
sl get 8291 --json
sl get 8291 --user jk
Complete a learning item (auto-detects if approval is needed):
sl complete 15108
sl complete 15108 --note "Reviewed all 3 rules"
sl complete 15108 --comment "Done" --json
Add a private note to an item:
sl note 15108 "Key takeaway: use back pressure for AI agents"
Show your outstanding backlog items with URLs:
sl backlog --status outstanding --limit 10
MCP Server
The MCP server exposes SugarLearning data to AI agents via stdio transport. It provides these tools:
| Tool | Description |
|---|---|
list_modules | List all learning modules with metadata |
get_module | Get detailed info about a specific module |
get_module_users | Get users assigned to a module with progress |
get_module_groups | Get groups assigned to a module |
get_module_items | Get learning items within a module |
get_item | Get a learning item's full details and content |
complete_item | Mark a learning item as complete |
save_note | Add or update a private note on a learning item |
get_backlog | Get a user's learning backlog |
get_recent_changes | Get recent change diffs from local tracking |
search_learning | Semantic search across learning content |
get_module_list | Get module list (employee view) |
get_leaderboard | Get company leaderboard rankings |
get_user_profile | Get a user's profile with badges |
get_user_badges | Get badges earned by a user |
Claude Code
Add to your Claude Code MCP settings (~/.claude/settings.json):
{
"mcpServers": {
"sugarlearning": {
"command": "sl",
"args": ["mcp"]
}
}
}
Note: This requires the global install (
uv tool install .). If usinguv runinstead, use"command": "uv", "args": ["run", "--directory", "/path/to/sugarlearning-mcp", "sl", "mcp"].
Then ask Claude things like:
- "What modules are available in SugarLearning?"
- "Who is assigned to the Spec Reviews module?"
- "What's in my learning backlog?"
- "Have there been any recent changes to learning modules?"
- "Who's leading the company leaderboard?"
- "What badges has jk earned?"
- "Show me my SugarLearning profile and rank"
VS Code (Copilot / Continue)
Add to your VS Code settings (.vscode/settings.json or user settings):
{
"mcp": {
"servers": {
"sugarlearning": {
"command": "sl",
"args": ["mcp"]
}
}
}
}
Codex (OpenAI CLI)
Codex supports MCP servers via its config. Add to your Codex config:
{
"mcpServers": {
"sugarlearning": {
"command": "sl",
"args": ["mcp"]
}
}
}
LM Studio
LM Studio supports MCP servers in its agent mode. Configure a new MCP server:
- Name: SugarLearning
- Command:
sl - Arguments:
mcp - Transport: stdio
Qdrant Vector Search (Optional)
For semantic search across all learning content:
1. Start Qdrant
docker run -p 6333:6333 qdrant/qdrant
2. Build the index
sl index
This embeds all module names, descriptions, and learning items using all-MiniLM-L6-v2 (runs locally, no API key needed).
3. Search
sl search "training conferences"
The MCP server's search_learning tool will also use Qdrant when available, falling back to text matching otherwise.
Change Tracking
Each sl sync creates a timestamped JSON snapshot in data/snapshots/. When a previous snapshot exists, it computes a diff detecting:
- New/removed modules
- Changed module properties (name, description, manager, etc.)
- User assignment changes (who was added/removed from each module)
- Group assignment changes
- Learning item additions/removals/changes
Diffs are saved to data/diffs/ and can be reviewed with sl diff or accessed via the MCP get_recent_changes tool.
Automated syncing
Set up a cron job or scheduled task to run sl sync periodically:
# Every hour
0 * * * * cd /path/to/sugarlearning-mcp && sl sync >> /tmp/sl-sync.log 2>&1
Project Structure
sugarlearning-mcp/
├── src/sugarlearning_tools/
│ ├── auth.py # OAuth PKCE + token management
│ ├── cli.py # Click CLI entry point
│ ├── client.py # SugarLearning API client
│ ├── config.py # Pydantic settings (.env)
│ ├── mcp_server.py # FastMCP server
│ ├── models.py # Pydantic models
│ ├── qdrant_index.py # Qdrant vector indexing
│ └── sync.py # Snapshot + diff engine
├── tests/ # pytest test suite
├── data/
│ ├── snapshots/ # JSON snapshots (gitignored)
│ └── diffs/ # Change diffs (gitignored)
├── .env.example # Configuration template
└── pyproject.toml # Project definition
Configuration
All settings use the SL_ prefix and can be set via environment variables or .env file:
| Variable | Default | Description |
|---|---|---|
SL_COMPANY_CODE | (required) | Your SugarLearning company/tenant code |
SL_USER_ID | (auto-detected) | Your user identifier (extracted from login token if not set) |
SL_BASE_URL | https://my.sugarlearning.com | SugarLearning API base URL |
SL_IDENTITY_AUTHORITY | https://identity.ssw.com.au | OAuth identity server |
SL_CLIENT_ID | ssw-sugarlearning-client | OAuth client ID |
SL_QDRANT_URL | http://localhost:6333 | Qdrant server URL |
SL_QDRANT_COLLECTION | sugarlearning | Qdrant collection name |
Running Tests
uv run --extra dev pytest
License
MIT