convez.ai
MCP Server
jernejk

sugarlearning-mcp

jernejk/sugarlearning-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

Unofficial SugarLearning MCP server, CLI tools, and change tracker for AI agent integration

Instalação

$npx convez-ai jernejk/sugarlearning-mcp

1 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

Estrelas
2
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 4 meses
Versão
—
Issues abertas
9
Contribuidores
2

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:

  1. Open Chrome DevTools > Application > Local Storage > https://my.sugarlearning.com
  2. Find the refresh_token key 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 .env file — 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

CommandDescription
sl loginLaunch a headed browser and sniff the Bearer token (default, requires [browser] extra)
sl login --company CODESet company code (combine with any login flow)
sl login --manualPrint DevTools paste instructions
sl login -t TOKENAuthenticate with a Bearer token directly
sl login -r TOKENAuthenticate with refresh token (auto-renewal)
sl login --oauthOAuth PKCE flow (requires registered redirect URI)
sl <command> --jsonOutput as JSON instead of human-readable text
sl syncFetch data, create snapshot, show changes since last sync
sl diffShow the most recent diff
sl watch MODULE_IDShow current assignments and change history for a module
sl historyList all saved snapshots
sl backlogShow your learning backlog
sl search QUERYSearch modules and items (Qdrant or text fallback)
sl leaderboardShow 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_IDGet a learning item's full details and content
sl complete ITEM_IDMark a learning item as complete
sl note ITEM_ID CONTENTAdd or update a private note on a learning item
sl indexBuild/rebuild Qdrant vector index
sl mcpStart 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:

ToolDescription
list_modulesList all learning modules with metadata
get_moduleGet detailed info about a specific module
get_module_usersGet users assigned to a module with progress
get_module_groupsGet groups assigned to a module
get_module_itemsGet learning items within a module
get_itemGet a learning item's full details and content
complete_itemMark a learning item as complete
save_noteAdd or update a private note on a learning item
get_backlogGet a user's learning backlog
get_recent_changesGet recent change diffs from local tracking
search_learningSemantic search across learning content
get_module_listGet module list (employee view)
get_leaderboardGet company leaderboard rankings
get_user_profileGet a user's profile with badges
get_user_badgesGet 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 using uv run instead, 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:

VariableDefaultDescription
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_URLhttps://my.sugarlearning.comSugarLearning API base URL
SL_IDENTITY_AUTHORITYhttps://identity.ssw.com.auOAuth identity server
SL_CLIENT_IDssw-sugarlearning-clientOAuth client ID
SL_QDRANT_URLhttp://localhost:6333Qdrant server URL
SL_QDRANT_COLLECTIONsugarlearningQdrant collection name

Running Tests

uv run --extra dev pytest

License

MIT

Ver o original no GitHub

Bom para

Relacionados