Sugarlearning MCP

非官方SugarLearning CLI+MCP

非官方 社区构建的CLI工具、变更跟踪器和MCP服务器 SugarLearning. 本项目不隶属于SugarLearning或得到SugarLearning的认可。它使用现有的SugarLearning API和您自己的证书。

SugarLearning是一个学习管理系统，用于跟踪员工培训模块和学习项目。

它做什么

• MCP服务器 --通过以下方式将SugarLearning数据暴露给AI代理（Claude Code、VS Code Copilot、Codex、LM Studio） 模型上下文协议
• 一个命令登录 --通过Playwright登录的浏览器会自动捕获Bearer令牌，无需OAuth重定向URI
• 更改跟踪 --定期对模块、项目和分配进行快照，然后计算差异以检测随时间的变化
• 模块监控 --观察特定模块的任务更改（添加/删除了谁）
• 语义搜索 --可选的Qdrant矢量索引，用于在所有学习内容中进行自然语言搜索

先决条件

• Python 3.12+
• 紫外线 （推荐）或pip
• 具有管理员权限的SugarLearning帐户
• （可选） 剧作家 对于单命令浏览器登录
• （可选） 码头工人 用于Qdrant矢量搜索

快速开始

1.全局安装（推荐）

git clone https://github.com/jernejk/sugarlearning-mcp.git
cd sugarlearning-mcp
uv tool install .

这使得 sl 命令available system wide--从任何目录运行它。

在拉取新更改后进行更新：

cd sugarlearning-mcp
git pull
uv tool install --force --reinstall .

要卸载，请执行以下操作：

uv tool uninstall sugarlearning-tools

Alternative: Run from project directory without global install

git clone https://github.com/jernejk/sugarlearning-mcp.git
cd sugarlearning-mcp
uv sync

然后在所有命令前加上 uv run:

uv run sl login
uv run sl sync
uv run sl search "training"

2.身份验证

建议：一个命令浏览器登录。 安装 browser 多一次，然后跑 sl login -一个真正的Chromium窗口打开，您正常登录SugarLearning，CLI从第一个API请求中嗅探Bearer令牌。不需要OAuth重定向URI注册。

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

捕获令牌后，浏览器窗口会自动关闭。

Alternative login flows

手动粘贴 --打印DevTools说明并自己粘贴一个令牌：

sl login --manual
sl login -t "$(pbpaste)"   # after copying the Authorization header

刷新令牌 （用于自动续订-比访问令牌寿命更长）：

sl login -r YOUR_REFRESH_TOKEN

要从浏览器中获取刷新令牌，请执行以下操作：

1. 打开Chrome DevTools>应用程序>本地存储> https://my.sugarlearning.com
2. 查找 refresh_token 键入并复制其值

完整的OAuth PKCE流程 （需要注册的CLI重定向URI）：

sl login --oauth

您的用户ID将从令牌中自动检测到。凭据存储在 ~/.config/sugarlearning/config.json.

高级： 您还可以通过以下方式进行配置 .env 文件--请参见 配置.

3.首次同步

sl sync

这将获取所有模块、项目和分配，然后保存快照。稍后再次运行以检测更改。

CLI 参考

大多数命令支持 --limit N 和 --skip N 对于分页：

sl search "training" --limit 5
sl backlog --limit 10 --skip 5
sl watch 6307 --limit 20
sl history --limit 5

状态筛选

按完成状态筛选您的待办事项列表：

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

将状态过滤与搜索相结合，在待办事项列表中查找特定项目：

sl search "training" --status completed     # Completed training items
sl search "security" --status outstanding   # Outstanding security items

排行榜、徽章和个人资料

查看您和您的团队如何跟踪：

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输出

添加 --json 对于任何用于机器可读输出的命令：

sl backlog --status outstanding --json
sl search "training" --json
sl watch 6307 --json
sl diff --json
sl leaderboard --json
sl profile --json

例子

注意“规格审查”模块上的作业更改：

sl watch 6307

搜索与培训相关的内容（包括每个结果的可点击URL）：

sl search "training conferences"

获取特定项目的完整内容：

sl get 8291
sl get 8291 --json
sl get 8291 --user jk

完成学习项目（自动检测是否需要批准）：

sl complete 15108
sl complete 15108 --note "Reviewed all 3 rules"
sl complete 15108 --comment "Done" --json

向项目添加私人注释：

sl note 15108 "Key takeaway: use back pressure for AI agents"

使用URL显示未完成的待办事项：

sl backlog --status outstanding --limit 10

MCP服务器

MCP服务器通过stdio传输将SugarLearning数据暴露给AI代理。它提供了以下工具：

克劳德代码

添加到您的Claude Code MCP设置中(~/.claude/settings.json):

{
  "mcpServers": {
    "sugarlearning": {
      "command": "sl",
      "args": ["mcp"]
    }
  }
}

注： 这需要全局安装(uv tool install .).如果使用 uv run 相反，使用 "command": "uv", "args": ["run", "--directory", "/path/to/sugarlearning-mcp", "sl", "mcp"].

然后问克劳德这样的问题：

• “SugarLearning提供了哪些模块？”
• “谁被分配到规格审查模块？”
• “我的学习积压中有什么？”
• “最近学习模块有什么变化吗？”
• “谁在领导公司排行榜？”
• “jk获得了什么徽章？”
• “显示我的SugarLearning个人资料和排名”

VS代码（复制/继续）

添加到您的VS代码设置(.vscode/settings.json 或用户设置）：

{
  "mcp": {
    "servers": {
      "sugarlearning": {
        "command": "sl",
        "args": ["mcp"]
      }
    }
  }
}

Codex（OpenAI CLI）

Codex通过其配置支持MCP服务器。添加到您的Codex配置中：

{
  "mcpServers": {
    "sugarlearning": {
      "command": "sl",
      "args": ["mcp"]
    }
  }
}

LM 工作室

LM Studio以代理模式支持MCP服务器。配置新的MCP服务器：

• 名字：SugarLearning
• 命令: sl
• 参数: mcp
• 运输标准： stdio

Qdrant矢量搜索（可选）

对于所有学习内容的语义搜索：

1.启动Qdrant

docker run -p 6333:6333 qdrant/qdrant

2.建立指数

sl index

这将使用以下命令嵌入所有模块名称、描述和学习项 all-MiniLM-L6-v2 （在本地运行，不需要API密钥）。

3.搜索

sl search "training conferences"

MCP服务器的 search_learning 该工具还将在可用时使用Qdrant，否则将回退到文本匹配。

更改跟踪

每 sl sync 在中创建带时间戳的JSON快照 data/snapshots/当存在前一个快照时，它会计算一个差异检测：

• 新建/删除模块
• 更改了模块属性（名称、描述、管理器等）
• 用户分配更改（每个模块中添加/删除了谁）
• 组分配更改
• 学习项目添加/删除/更改

差异保存到 data/diffs/ 并且可以通过以下方式进行审核 sl diff 或通过MCP访问 get_recent_changes 工具。

自动同步

设置要运行的cron作业或计划任务 sl sync 定期地：

# Every hour
0 * * * * cd /path/to/sugarlearning-mcp && sl sync >> /tmp/sl-sync.log 2>&1

项目结构

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

配置

所有设置都使用 SL_ 前缀，可以通过环境变量或 .env 文件：

运行测试

uv run --extra dev pytest

许可证

麻省理工学院