Somtoday (unofficial)

somtoday-mcp

面向 Somtoday 家长门户的只读 MCP 服务。它可让 Cursor 或 Claude Desktop 等 AI 助手通过你自己的家长账户查询孩子的课程表、作业和成绩。

它通过 stdio 在你的电脑上本地运行。除 Somtoday 外，不会向任何其他地方发送数据。

免责声明。 这是一个非官方的社区项目，与 Somtoday 或 Topicus 无关，也未获得其认可或支持。它通过与官方家长门户使用的未公开内部 Web API 进行互操作，因此可能随时停止工作或出现不同表现，恕不另行通知。本项目仅供使用你自己的账户，仅读取数据，并按“现状”提供，不作任何形式的保证（请参阅 LICENSE）；使用风险由你自行承担，并请遵守 Somtoday 的使用条款。“Somtoday”和“Topicus”是各自所有者的商标，此处仅用于说明本软件所适配的服务。

功能

工具	可获取的内容
whoami	你的学校标签、已关联子女及其数字 ID，以及你可以查看的门户版块。
lessons	一天的课程表，以及当天是否为学校假期。每节课都有 type（ROOSTERTOETS/EXAMEN = 测验）和表示已取消的 uitgevallen；作业和测验主题来自同一日期的 homework。
homework	每天要做和要学习的内容：指定日期范围内的所有学习计划项目（默认今天起 6 天，最多 42 天），按天分组，包含描述、学习目标、预计用时、测验类型、附件（链接）、外部链接、提交时间段/状态和完成勾选标记。
grades	最近的成绩（最多 30 条）和各科平均分。
assignments	所有提交作业，包含提交时间段、状态（即将到期、待完成、等待批阅、已批准）、逾期标记、描述、附件和链接。status=open 仅保留仍待完成的作业。
assignment_detail	一项作业的详情，内容与家长门户中显示的一致：说明、文件、链接、提交时间段和状态。已提交的文件和教师反馈仅在学生自己的会话中可见。
study_material	各科目的学习材料：按日期列出学习计划中的课程材料、按文件夹列出的年度附件（文件链接）、外部链接以及方法和出版商链接。不提供参数时列出科目；vak 用于选择一个科目；all=true 获取所有科目。
schedule	指定日期范围内的课程表（默认今天起 6 天，最多 42 天）：时间、课时、科目、教室、教师、类型（测验、考试、家长会……）、课程备注、变更和取消、附件、假期。
grades_latest	按时间从新到旧列出成绩，包含科目、栏目、描述、成绩、权重、测验类型、学期、日期、备注和补考；limit（默认 50，最多 1000）；dossier=examen 用于查看 SE 成绩。
grades_overview	一个学年的完整成绩概览：所有科目、各学期的每项成绩、报告成绩、权重和备注。schooljaar 用于选择较早的学年。
subject_grades	一门科目的全部信息：所有成绩栏目及其权重和备注、栏目定义（包括尚未评分的栏目）、综合测验组成部分，以及进度档案和考试档案。不提供 vak 时列出所有科目。
exam_grades	学校考试档案（PTA/SE）：各科目的 SE 平均分、每项 SE 成绩、尚未进行的测验以及各测验类型的平均分。
absence	学年或评分周期内的缺勤和登记（缺席、迟到、被请离、作业/学习材料未准备妥当），包含计数和记录，以及当前有效的措施。
messages	只读消息：最新对话（主题、发件人、日期、未读状态、预览；可用 zoek/ongelezen 筛选），或通过 conversatieId 查看完整对话。绝不会将任何内容标记为已读。
news	学校新闻条目（按时间从新到旧，以文本形式显示）和未读数量。
announcements	门户中显示的 Somtoday 全平台公告。
children	已关联子女的资料、班级和学校信息（导师、年级、课程），当前分班情况及可查看的门户版块。
school_info	学校联系方式和学校信息页面；paginaId 用于打开一个页面。
teachers	你可以发送消息的教职员工，以及他们所教的子女科目。
signing_requests	数字签署请求（只读；不会签署任何内容）。每个项目都包含 document: {tool: "signing_document", id, available}。
signing_document	一个签署请求的（已签署）PDF，与门户的下载按钮提供的内容一致：传入 document.id；返回提取的文本，最大 10 MB。使用你的登录令牌获取，因此不能作为 download_attachment 的 fileUrl。
parent_evening	家长会详情（时段、教师）；会从你的消息中查找邀请（只读；不会预约任何时段）。
consents	门户中设置的同意事项，例如照片使用许可（只读）。
download_attachment	通过 fileUrl 读取附件：仅限 Somtoday 托管的 HTTPS 文件（可通过 SOMTODAY_MCP_ATTACHMENT_HOSTS 扩展），最大 10 MB，不发送令牌；从 PDF/文本/HTML/CSV/JSON 中提取文本。
auth_status	是否已保存会话、会话存储位置，以及上次令牌续期的结果。绝不会返回令牌。

• lessons 接受可选的 date（YYYY-MM-DD，Europe/Amsterdam 时区），默认为明天。范围工具接受 date，或 from/to。
• 如果你的账号关联了多个孩子，请传入 leerlingId（whoami 返回的数字 ID）。
• assignments 使用 status=open 时，会隐藏已逾期且不要求在线提交的项目（inleveringenVerwacht: 0，例如已交纸质作业），并在 verborgenZonderInlevering 中报告数量；传入 includeNoHandIn=true 即可查看这些项目。
• assignments 会将近似重复项合并为一个项目（科目、主题、提交时间段和状态相同，例如同一项作业发布给两个班级），并将其他 ID 放入 duplicaatToekenningIds；传入 dedupe=false 即可分别列出。
• 如果你的账号未启用某个部分，工具会说明这一点，且不会调用该部分的 API。

不包含：任何会更改数据的操作，例如发送消息、报告缺勤、预约家长晚会时段、签署请求或上传提交内容。

只读与隐私

• 工具只发送 GET 请求。不会写入、提交任何内容，也不会将内容标记为已读。
• 服务仅与 Somtoday 的登录服务器和 API 服务器通信。
• 不进行遥测或分析。
• 你只会在浏览器窗口中的 Somtoday 登录页面输入密码。工具、CLI 参数、环境变量或提示词都不会要求你提供密码。
• 工具绝不会返回令牌。

课表、作业和成绩都是关于孩子的个人数据。请将输出保存在自己的设备上，只使用你有权使用的账号，不要分享或重新发布。根据 GDPR，你有责任妥善处理导出的数据。

安装

需要 Node.js 22 或更高版本（download_attachment 和 signing_document 使用的 PDF 文本提取功能无法在 Node 20 上运行）。

已在 npm 上发布为 somtoday-mcp，并通过此仓库的发布工作流提供来源证明。

npx -y somtoday-mcp            # start the MCP server (used by your MCP client)
npx -y somtoday-mcp login      # sign in, once, in a terminal

登录时会打开一个普通浏览器窗口。如果已安装 Google Chrome（否则使用 Microsoft Edge），则会使用该浏览器，并创建一个之后会删除的全新临时配置文件；这样能更可靠地通过 Somtoday 的 Cloudflare“Verify you are human”验证。只有在没有 Chrome/Edge 时，才会回退到 Playwright 自带的 Chromium；这种情况下请先安装一次：

npx playwright install chromium

启动窗口时不会显示“受自动化软件控制”的标记；浏览器的其他设置均不会更改。

从代码检出目录运行：

git clone https://github.com/barzoj/somtoday-mcp.git
cd somtoday-mcp
npm install
npm run build
npx playwright install chromium   # only needed without Chrome/Edge
node dist/cli.js login

MCP 客户端配置

Cursor

~/.cursor/mcp.json：

{
  "mcpServers": {
    "somtoday": {
      "command": "npx",
      "args": ["-y", "somtoday-mcp"]
    }
  }
}

Claude Desktop

claude_desktop_config.json：

{
  "mcpServers": {
    "somtoday": {
      "command": "npx",
      "args": ["-y", "somtoday-mcp"]
    }
  }
}

从本地代码检出目录运行

{
  "mcpServers": {
    "somtoday": {
      "command": "node",
      "args": ["/absolute/path/to/somtoday-mcp/dist/cli.js"]
    }
  }
}

登录

请在终端中运行登录命令，不要在 MCP 客户端内运行：

npx -y somtoday-mcp login

1. 浏览器窗口（已安装的 Chrome 或 Edge，否则是 Playwright Chromium）会打开 Somtoday 的常规登录页面。在那里搜索你的学校，方式与官方应用相同。
2. 像平常一样登录，包括完成任何两步验证。你有 10 分钟时间（Cloudflare 验证和学校搜索也计入其中）。
3. 窗口关闭后，会话将保存在你的计算机上，MCP 服务即可使用该会话。

如果你知道学校的租户 UUID，可以使用 npx -y somtoday-mcp login --school-uuid <uuid> 跳过学校搜索。

如果在登录前调用工具，或已保存的会话失效，工具会返回：

run npx somtoday-mcp login in a terminal

此时请重新运行登录命令。如果无法访问 Somtoday，工具会说明这一点，而不会要求你登录。

命令

npx -y somtoday-mcp status           # where the session is stored, last renewal result (no tokens)
npx -y somtoday-mcp status --check   # also renews the token and calls the API once
npx -y somtoday-mcp logout           # delete the stored session from this computer

你的 MCP 客户端也可以通过 auth_status 工具获取相同的诊断信息。

多个 MCP 客户端（例如，两个 Cursor 窗口）可以共用一个会话：令牌续期会通过配置目录中的锁文件串行执行，并且每次续期前都会重新读取已存储的会话。

技术细节

• 使用 OAuth 2.0 授权码流程和 PKCE（S256），采用 Somtoday 原生应用的公开（无密钥）客户端 ID 和重定向 URI。没有客户端密钥，也不会使用 Somtoday Connect 合作伙伴 API。
• 登录页面会重定向到自定义的 somtoday:// URL；Playwright 会在浏览器窗口内从该请求中读取授权码。不会启动本地 Web 服务器。
• 短期访问令牌仅保存在内存中。
• 学校是在 Somtoday 自己的登录页面上选择的。学校的租户信息来自令牌响应（somtoday_tenant），而 whoami 和 status 显示的名称则来自 orgname 声明（如果没有该声明，则使用你账户中的学校信息）。

会话存储位置

平台	位置
macOS	登录钥匙串，服务 somtoday-mcp。每次写入后都会读回并检查；如果检查失败，或设置了 SOMTODAY_MCP_DISABLE_KEYCHAIN=1，则使用下方的文件
Linux / Windows	$XDG_CONFIG_HOME/somtoday-mcp/ 中的 session.json，权限为 0600（默认路径为 ~/.config/somtoday-mcp/）

要退出登录，请运行 npx -y somtoday-mcp logout。

环境变量

变量	作用
XDG_CONFIG_HOME	文件备用存储的基础目录（默认值为 ~/.config）。
SOMTODAY_MCP_CONFIG_DIR	使用此目录替代 $XDG_CONFIG_HOME/somtoday-mcp。
SOMTODAY_MCP_DISABLE_KEYCHAIN	设置为 1 可跳过 macOS 钥匙串，始终使用文件。

日志写入 stderr（stdout 专供 MCP 协议使用），并会对类似令牌的值进行脱敏。

开发

npm install
npm run lint
npm run format:check
npm run typecheck
npm run build
npm test

测试绝不会访问网络：fetch 和钥匙串均已模拟，并且会故意阻止向 Somtoday 主机发送请求。有关测试数据和隐私的规则，请参阅 CONTRIBUTING.md；有关漏洞报告，请参阅 SECURITY.md。

ouder-portal.openapi.yaml 描述了本项目所依赖的家长门户 API 部分内容，这些内容是根据门户观察得出的；它不是官方规范。

使用真实账户进行手动检查

不属于 CI。只记录 HTTP 状态码；切勿粘贴令牌、验证码、姓名或 API 响应。

1. 运行 node dist/cli.js login 并完成登录。
2. 从你的 MCP 客户端调用 whoami、lessons、homework 和 grades。
3. 重启 MCP 服务并再次调用一个工具，以检查是否已加载保存的会话。

许可证

MIT。与 Somtoday 或 Topicus 无关联。