Chalkieboard iCloud

Chalkieboard iCloud MCP 服务 · Chalkieboard iCloud MCP

English. 面向 Chalkieboard 的本地 MCP 服务。Chalkieboard 是一款供小学教师使用的 iPad 白板应用。 该应用会将每个学科映射为 iCloud Drive 中的一个文件夹，并附带机器可读的 structure.json。此服务通过该文件夹提供八种工具，供 Claude（或任何 MCP 客户端）使用：列出学科、课程和文件；添加资料（根据文件名自动放入课程）；读取文本文件；追加应用可导入的课程计划；创建学科文件夹。它绝不会删除内容，也不会触碰应用自己的数据库——应用只会从文件夹追加内容，因此错误的文件不会损坏课程数据。无需网络，无遥测（PRIVACY.md）。 零依赖，需要 Node 18+。无需安装应用，即可使用示例文件夹试用。支持 macOS 和 Windows（iCloud for Windows）。

让 Mac 上的 AI（Claude Desktop · Claude Code 等）读取 iPad 应用的 iCloud 课程文件夹、放置资料，并追加单元和课时计划。 零依赖——只需 Node 18+。

功能

工具	功能
list_subjects	学科（活页夹）列表——文件夹名称、学年、学期、单元、课时数、文件数、班级列表、文件夹规则
list_lessons	一个学科（或全部学科）的单元、课时及其关联资料，还有等待补充的缺失文件
get_lesson	查看一个课时——包括资料文件是否位于文件夹中
list_files	学科文件夹中的文件（包括子文件夹）——类型、文件名中的排课信息、班级标记、是否已关联应用
add_material	将 pdf·pptx·html 文件放入学科文件夹。提供 unit·first（·last）·grade 时，会添加 学年_学期_单元_课时 前缀并自动放入对应课时；提供 class 时，会添加 (班级) 后缀
read_file	读取学科文件夹中的文本文件
plan_lessons	向排课表（lessons.chalkie.json）中追加单元、课时及资料关联——应用会在下次扫描时导入
create_subject	创建新的学科文件夹 学科 (学年-学期) 和空排课表——应用会在下次扫描时创建活页夹

资源：chalkieboard://structure.json · chalkieboard://README.md · chalkieboard://<学科文件夹>/lessons.chalkie.json。

没有删除工具。 只能在应用中删除。此服务不会触碰应用存储库（library.json）—— 数据只会从文件夹单向追加到应用，因此即使误放了一个文件，也不会损坏应用数据。

安装

Claude Desktop — 一键安装（推荐）

./tools/mcp/make_bundle.sh && open -a Claude tools/mcp/dist/chalkieboard.mcpb

.mcpb 捆绑包会由 Claude Desktop 复制到自身内部，并使用自己的 Node启动——无需在 Mac 上安装 Node，也不会绑定到存储库路径。 修改服务后，重新构建捆绑包并重新打开即可（在安装窗口中更新）。

Claude Code

claude mcp add --scope user chalkieboard -- node "/path/to/chalkieboard-icloud-mcp/chalkieboard-mcp.mjs"

Claude Desktop — 使用配置文件（而非捆绑包）

~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "chalkieboard": {
      "command": "node",
      "args": ["/path/to/chalkieboard-icloud-mcp/chalkieboard-mcp.mjs"]
    }
  }
}

文件夹位于 ~/Library/Mobile Documents/iCloud~only1mui~ChalkieBoard/Documents。 如需查看其他位置（例如模拟器的 -cloudroot 文件夹），请设置环境变量 CHALKIEBOARD_DIR。

前提条件

• iPad 应用必须在订阅有效且已登录 iCloud的状态下运行，文件夹和 structure.json 才会生成。
• 此 Mac 必须登录同一个 iCloud 账户。尚未下载的文件（.icloud）只会显示在列表中。

不安装应用也能试用

sample/ 中提供了一个示例文件夹，其结构与应用生成的文件夹完全一致（2 个学科、排课表、1 份练习）。可以在扩展设置的“课程文件夹”中选择它，或通过 CHALKIEBOARD_DIR 指定路径。 供审查者和其他开发者在没有 iPad 应用的情况下运行这些工具。

检查

node tools/mcp/selftest.mjs

在临时文件夹中创建与应用生成结构完全一致的文件，并断言所有工具、拒绝路径越界、拒绝覆盖以及排课表追加的幂等性。不会触碰实际的 iCloud 文件夹。

发布到商店

位置	发布方	准备事项
Claude Desktop“浏览扩展”	Anthropic 审核（提交 Google 表单）	目录_提交_初稿.md — 图标和联系方式已准备好；还缺公开存储库、示例文件夹和隐私政策页面
公开 MCP 注册表	✅ 已发布 — io.github.207studio/chalkieboard-icloud-mcp	在公开存储库 https://github.com/chalkieboard/chalkieboard-icloud-mcp 推送标签 v<版本>，release.yml 将通过捆绑、发布和发布（OIDC）完成发布

应用图标的 512px 文件（icon.png）会通过捆绑包 manifest 中的 icon·icons 加入。

公开存储库是此文件夹的副本——export_public.sh 会将其导出到 ~/chalkieboard-icloud-mcp（包括 public/ 中的 GitHub Actions）， 在该目录推送标签 v<版本> 后，release.yml 会依次执行自检 → 捆绑 → 附加发布文件 → 发布到注册表。唯一的源始终在这里（tools/mcp）。