project_tracker_base: CINO Project Tracker:appf7fRQUvY9Iy7sL
project_tracker_table: Projects:tblchmbxSAavvJKaY
project_tracker_record: csa-skilljar:recbwfx6O30BboQNv
project_source: github:CloudSecurityAlliance-Internal/CINO-Projects/projects/CloudSecurityAlliance/csa-skilljar

csa-skilljar

一个用于 Skilljar 客户教育平台的 Python 库和本地 MCP 服务器，通过一套工具覆盖 Skilljar 的两个 REST API——v1 和 v2。

状态：Block 1 已实现，尚未发布。

在 v0.0.1 发布到 PyPI 之前，请从源码安装： pipx install git+https://github.com/CloudSecurityAlliance/csa-skilljar 服务器可以运行、认证并通过 stdio 应答，提供四个工具：check_access、 describe_capabilities、report_a_problem 和 list_courses。它尚未发布到 PyPI—— 一旦在真实的 Skilljar 组织上验证通过，v0.0.1 就会发布。 73 个工具的完整对等面将在 Block 2–9 中逐步交付；参见 ROADMAP.md。

从 Skilljar 官方 MCP 服务器开始

如果你想在 AI 客户端中使用 Skilljar，请使用 Skilljar 自己的 MCP 服务器。 这是正确的默认选择，我们毫无保留地推荐它。它是第一方、托管式的，由厂商维护，无需在你的机器上安装任何东西，以 73 个工具覆盖整个 v2 API，并使用 OAuth 和按操作划分的权限范围进行认证。Skilljar 正在积极开发 v2，因此它会按照他们的发布节奏变得更好，而不是我们的。

claude mcp add skilljar --transport http https://mcp.skilljar.com/mcp

先试试那个。对大多数人来说，它就是全部答案。

Related MCP server: sf-mcp

……但如果你需要更多

有些东西在 v2 API 中尚不存在，因此任何 v2 客户端都无法访问它们。v1 API 要大得多——340 个操作对 v2 的 82 个——而且目前它是获取以下内容的唯一途径：

• 按课程单元的学习进度——v2 仅报告课程级别的完成情况

• Webhooks——v2 完全没有事件通知

• 资源上传——v2 没有文件上传

• 学习路径、讲师引导培训以及商务栈 （优惠、促销代码、购买、培训积分）

csa-skilljar 就是为了填补这个空白而存在的。它精确复刻了官方工具面——相同的工具名称、相同的参数名称——然后在其旁边添加仅 v1 支持的能力，这样你就不必在两个 API 之间做选择，也不必运行两个服务器。

它还在本地通过 stdio 运行，这是某些组织需要的：你的 API 凭据留在你自己的机器上。

我们预计这个项目会随着时间推移而缩小，而这正是预期的结果。 Skilljar 已公开为 webhooks、路径、资源、标签和商务预留了 OAuth 权限范围。随着这些端点发布，这里对应的 v1 支持将被退役，转而使用 v2——工具名称保持不变，调用方不会注意到任何变化。

检查 Skilljar v2 API 的状态

Skilljar 的 v2 API 正在积极增长，官方 MCP 服务器紧跟其变化。这对所有人都是好消息——也意味着本项目中的覆盖地图有保质期。在假设这里记录的空白仍然是空白之前，请重新检查上游。

# 1. The published v2 surface
curl -s https://api.skilljar.com/v2/openapi.json | jq '.paths | keys | length'

# 2. The declared scope catalogue — a leading indicator of what is coming
curl -s https://api.skilljar.com/.well-known/oauth-authorization-server \
  | jq -r '.scopes_supported[]'

# 3. The official MCP server's live tool list
#    Connect it, then run /mcp in Claude Code.

在撰写本文时，权限范围目录宣传了 88 个权限范围，而已发布的 v2 规范只使用了 28 个——包括 webhooks、路径、资源、标签和商务在内的领域已预留了权限范围，但还没有端点。当这些端点发布时，本项目为它们提供的 v1 回退方案应该退役，转而使用 v2，并更新此说明。

scripts/check_upstream.py 将自动化以上所有三项，并对照 specs/ 中的快照报告漂移。在那之前，请运行上述命令。

凭据

两个独立的凭据，都是可选的。服务器可以使用其中一个、两个或都不使用来启动，并会告诉你哪些是可用的。

我们链接 Skilljar 自己的文档，而不是转述他们的仪表板导航，因为我们无法保持其最新。

将 v2 客户端的权限范围限定为你实际需要的范围。API 在每个操作上都声明了必需的权限范围，而敏感的操作是可以分离的——students:anonymize（不可逆）、students:deactivate 和 students:manage-password 都可以从用于内容创作的客户端中扣留。

它将覆盖什么

复刻全部 73 个官方工具，然后按以下顺序添加仅 v1 支持的功能族：

1. 学习进度——按课程单元的详细信息，v2 不报告这些

2. 资源与媒体——v2 没有文件上传

3. 商务——优惠、促销代码、购买、培训积分

4. 学习路径——路径、路径项、路径注册

5. 事件与 Webhooks——订阅和负载预览

6. 讲师引导培训——课程、讲师、注册

7. 标签与标记

明确不在范围内：目录页面构建、webhook 接收、缓存以及跨 API 的复合写入。原因在规范中。

项目文档

开发

始终使用虚拟环境。 解释器由 .python-version 固定。

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"

.venv/bin/python -m pytest -q          # offline suite: no network, no credentials
.venv/bin/ruff check src tests scripts
.venv/bin/mypy

./scripts/verify.sh                    # or just this: everything CI checks

命令刻意写成 .venv/bin/...——裸的 pytest 会解析到 PATH 上的任何东西，这就是测试套件在错误的依赖版本下通过的方式。

贡献遵循 CSA 的公共仓库标准： 每次更改都要分支和提 PR，必须通过 CI 门禁，不允许直接推送到 main。

许可证

Apache-2.0。

致谢

Skilljar 是 Gainsight 的产品。本项目与 Skilljar 或 Gainsight 没有关联，也未获得其认可；它是一个基于其公共 API 构建的独立客户端。specs/ 中的 API 快照取自 Skilljar 已发布、可公开访问的 OpenAPI 文档。