[!IMPORTANT] 本项目不试图绕过或破坏 D2L 或 SMU 施加的认证和访问限制，而是选择在通过 Chrome 完成正规认证后直接使用 D2L API。本项目与 SMU 或 D2L 没有任何关联。如有任何问题，请直接联系我或创建一个 issue。

SMU eLearn MCP

一个面向 SMU 的 D2L Brightspace 部署的本地、只读 Model Context Protocol 服务器。它提供课程、置顶课程、每周模块、课程文档、最近的上传/更改、内容搜索、元数据和文件下载等功能。

这是一个本地、单用户的 stdio 服务。它不打算作为网络服务器对外暴露，也不打算在用户之间共享。

使用此 MCP 的最佳方式是通过 Codex 或 Claude，我已在 plugin-package/ 文件夹下将其打包为可安装的插件。

功能

该实现使用 D2L 官方文档记载的只读 API 路由。它不会抓取可见的主页，也不会修改课程、置顶状态、提交、成绩、消息或内容。

Related MCP server: D2L Brightspace MCP Server

环境要求

• Node.js 22 或更高版本

• Google Chrome

• 一个有权访问 eLearn 的 SMU 账户

安装与认证

cd elearn-mcp
npm ci
npm run auth

npm run auth 会打开一个专用的 Chrome 配置文件。完成常规的 SMU Microsoft 登录和 MFA 流程。一分钟后，该命令会自动检查 eLearn API；如果登录仍未完成，它会每 15 秒检查一次，最长持续五分钟。成功后，它会保存 Playwright 浏览器会话状态，将状态文件的权限限制为仅所有者可读写（0600），并关闭 Chrome。整个过程无需任何终端输入。

配置文件默认位于 ~/.elearn-mcp/browser-profile，保存的状态默认位于 ~/.elearn-mcp/storage-state.json。状态中包含会话 Cookie，并可能包含按来源（origin）划分的 Web 存储，因此请将这两个位置都视为机密：不要提交、同步或共享它们。MCP 绝不会要求或存储你的密码或 MFA 响应。

验证类型安全、单元测试和干净的生产构建：

npm run check

完成认证后，运行完整的 MCP 实测：

npm run test:full

完整运行会执行类型检查和单元测试，构建生产服务器，通过 MCP stdio 进行连接，针对 eLearn 真实数据验证全部 11 个工具，将一个真实文件下载到由操作系统提供的隔离临时目录中，验证该文件，并在 finally 清理中删除该临时目录。它绝不会在 eLearn 中提交或更改任何数据。

MCP 客户端配置

请先构建项目，然后配置你的 MCP 客户端，使其启动编译后的 stdio 服务器：

{
  "mcpServers": {
    "smu-elearn": {
      "command": "node",
      "args": [
        "/absolute/path/to/elearn-mcp/dist/src/server.js"
      ],
      "env": {
        "ELEARN_BASE_URL": "https://elearn.smu.edu.sg",
        "ELEARN_LP_VERSION": "1.49",
        "ELEARN_LE_VERSION": "1.49",
        "ELEARN_COURSE_ORG_UNIT_TYPE_ID": "3"
      }
    }
  }
}

这个 JSON 的确切位置取决于所用的 MCP 客户端。更改配置后，请重启客户端。

生产运行

服务器基于锁定依赖集构建。在验证过程中，测试会经过类型检查并被执行，但它们被排除在 dist/ 和可分发包之外。

如需一个最小的本地运行环境：

npm ci
npm run check
npm prune --omit=dev
npm start

精简开发依赖后，请在重新构建或运行单元测试之前再次运行 npm ci。项目附带的 GitHub Actions 工作流会在 Node.js 22 上执行相同的锁定安装与验证。需要认证的实测被排除在 CI 之外，因为它需要交互式的 SMU 账户和 MFA。

构建 Codex 和 Claude 插件

src/ 下的 TypeScript 文件是 MCP 实现的唯一事实来源。Codex 和 Claude Code 使用各自的插件清单和 MCP 启动元数据，而两者接收的是相同的生成运行时：

plugin-package/
├── codex/smu-elearn/
│   ├── .codex-plugin/plugin.json
│   ├── .mcp.json
│   └── mcp/
└── claude/smu-elearn/
    ├── .claude-plugin/plugin.json
    ├── .mcp.json
    └── mcp/

使用以下命令构建两个全新的、自包含的插件包：

npm run build:plugins

npm run build:plugin 仍然是同一命令的别名。该构建会编译一次 src/，从根 lockfile 推导出精确的生产依赖版本，在隔离的暂存目录中安装一次生产依赖，并且只有在完整的暂存副本通过验证之后，才会替换各个 mcp/ 目录。请勿手动编辑任一生成的运行时。

对于 Claude Code 开发，可以直接验证并加载该插件包：

claude plugin validate ./plugin-package/claude/smu-elearn --strict
claude --plugin-dir ./plugin-package/claude/smu-elearn

在 Claude Code 中，运行 /mcp 以检查自带的服务器。如需持久化的本地安装，请先构建插件包，然后添加此仓库的 marketplace：

claude plugin marketplace add /absolute/path/to/elearn-mcp
claude plugin install smu-elearn@smu-local --scope user

marketplace 目录清单存储在 .claude-plugin/marketplace.json。Claude 会将完整插件包复制到其插件缓存中，因此生成的 mcp/ 运行时必须在安装之前存在。开发时请使用 --plugin-dir 绕过缓存并就地加载插件包。

配置

“周”的解读方式

• elearn_get_week_documents 将 week 解释为课程的教学内容模块，例如 Week 3。它会递归包含嵌套子模块中的文件。

• elearn_get_recent_documents 将一周解释为日历日期范围，并按主题的 D2L LastModifiedDate 进行过滤。如果省略 since 和 until，则使用当前本地时间的周一至周日。

这种区别是有意为之：存放在“Week 3”中的文件可能是在另一个日历周上传的。

认证生命周期

elearn_authenticate MCP 工具和 npm run auth 命令会启动专用 Chrome 配置文件，用于由用户控制的 SSO 和 MFA。它们会在第一次自动检查前等待一分钟，如有需要会短暂轮询，验证 D2L API，并写入权限为 0600 的 Playwright 存储状态文件。服务器会使用该状态启动一个独立的无头（headless）Chrome 上下文，并通过它发送同源（same-origin）API 请求。这样既保留了 SMU 和 Microsoft 对交互式认证的控制，又允许 MCP 进程重启。当机构会话过期时，请调用 elearn_authenticate 或重新运行 npm run auth。

有关本地部署边界、凭据处理指南和发布检查，请参阅 SECURITY.md。