Skip to main content
Glama

Edvibe School MCP

状态:实验性 / 非官方。 本仓库是 Ruslan Sungurov 的私人试点项目。它尚不是 Edvibe 的官方产品。未经 Ruslan 和 Edvibe 明确批准,请勿部署、发布或连接真实学校。审批门禁 A–F 请参见 PLAN.md。

一个无状态的 Model Context Protocol 服务器,基于官方 Edvibe School API 构建。v1 的目标受众是使用 Pro 套餐且 API 模块可用的 Edvibe/ProgressMe 学校。MCP 无法在没有该模块的套餐上启用 API;更广泛的可用性由 Edvibe 的产品决策决定。

当前已有的内容

  • 不可变的上游 OpenAPI 快照(openapi/snapshots/swagger-2026-08-22.json),SHA-256 为 68342121d2fd…。

  • 权威操作清单(manifest/operations.json),包含全部 78 个操作、稳定的英文 operationId、风险类别和 MCP 工具注解。

  • 面向 MCP 的规范化 OpenAPI 副本(openapi/normalized/edvibe-school-api.normalized.json),由快照 + 清单生成。

  • CI 验证器(scripts/validate.js),强制执行 78 操作契约、35 + 24 + 17 + 2 风险分类、快照/清单/规范化文件的一致性、注解矩阵、不可变性以及密钥扫描。

目前尚不存在的内容:Postman 集合、MCP 服务器代码、部署、公开上架。这些是 PLAN.md 中的后续阶段。

Related MCP server: SchoolBridge

契约一览

类别

数量

含义

readOnlyHint

destructiveHint

read

35

只读

true

false

write

24

普通状态变更

false

false

high-risk

17

破坏性 / 难以逆转

false

true

sensitive

2

返回登录令牌

false

false + 显式警告

总计

78

风险由操作的实际语义决定,而非 HTTP 方法。值得注意的是,GET /api/Marathon/AddMarathonNewStudents 会改变状态,因此被归类为 write;另有 8 个只读操作使用 POST。

仓库布局

openapi/
  snapshots/            # immutable upstream OpenAPI (never edit)
  normalized/           # generated MCP-oriented copy (never edit by hand)
manifest/
  operations.json       # generated authoritative inventory (never edit by hand)
scripts/
  risk-classification.js  # human-authored risk map (single input)
  operation-meta.js       # human-authored English descriptions + warnings
  generate-manifest.js    # snapshot + risk map -> manifest/operations.json
  normalize.js            # snapshot + manifest -> normalized spec
  validate.js             # CI checks
.github/workflows/
  contract.yml           # regenerates + validates + fails if artifacts stale
README.md  CONTEXT.md  PLAN.md  AGENTS.md  package.json

本地工作流

要求:Node.js 20+。

npm run build:contract   # generate manifest + normalized spec
npm run validate         # run all CI checks

切勿编辑 openapi/snapshots/、openapi/normalized/ 或 manifest/ 下的文件。请修改 scripts/risk-classification.js 或 scripts/operation-meta.js,然后重新运行 npm run build:contract。

安全态势(v1)

  • 无状态服务器:没有全局可变的密钥/域名;凭据上下文限定在请求/会话范围内。

  • API 密钥永远不会出现在工具结果、日志、测试夹具、示例或缓存中。

  • 所有返回给客户端的错误都会剥离 errorStackTrace。

  • 返回 HTTP 200 但 BaseResponse.isSuccess=false 的响应会被视为 MCP 错误。

  • 在任何上游调用之前,学校域名会对照由 Edvibe 管控的白名单进行验证;对于私人试点项目,仅允许显式指定的测试学校主机名。

  • 仅支持 HTTPS,端口 443,上游路径固定为 /school-api,无重定向,无 IP 字面量,无私有/保留目标,具备 DNS 重绑定防护。

  • 内部速率限制:每个密钥 10 rps(低于上游的 15 rps),每个密钥最多 4 个并发请求。

  • 不会对 write、high-risk、sensitive 操作自动重试。

  • LoginPupil 和 LoginTeacher 仍保留在 78 工具契约中,但在获得记录在案的产品/安全批准(Gate F)之前,在公共端点上处于禁用状态。

审批门禁

公开 Postman 集合、真实写入、仓库移交、部署、发布以及面向公众启用登录工具,均需获得 Ruslan 的明确批准。参见 PLAN.md → “审批门禁”。

支持的客户端(v1)

  • 本地 Cursor(auto-run 已关闭)。

  • 本地 Codex(default_tools_approval_mode = "writes";high-risk/sensitive 工具按工具单独设置 approval_mode = "prompt")。

Cursor Cloud、Cursor auto-run 和 ChatGPT 在 v1 中不受支持。

来源

本仓库源自 ProgressMe Obsidian vault 中的 Edvibe MCP 交接包(Instruments/Edvibe MCP/)。CONTEXT.md、PLAN.md 和 AGENTS.md 分别是项目上下文、计划和 agent 指令。

Available Tools

78 tools
AccessGroupsAddMembersC

Add members to an access group.

Inputs: accessGroupId (required), bodyTeacherIds, bodyGroupClassIds, bodyIndividualClassIds.

AccessGroupsCreateA

Create a new access group.

Inputs: name (required).

AccessGroupsDeleteA
Destructive

Delete an access group.

WARNING: Destructive: removes the access group. Requires client-side approval.

Inputs: accessGroupId (required).

AccessGroupsGetDetailsA
Read-only

Get details of a single access group by id.

Inputs: accessGroupId (required).

AccessGroupsGetGroupClassesA
Read-only

List group classes linked to an access group (paginated).

Inputs: accessGroupId (required), Skip, Take.

AccessGroupsGetIndividualClassesA
Read-only

List individual classes linked to an access group (paginated).

Inputs: accessGroupId (required), Skip, Take.

AccessGroupsGetListB
Read-only

List access groups with optional filters by teacher, group class, or individual class.

Inputs: teacherId, groupClassId, individualClassId.

AccessGroupsGetTeachersA
Read-only

List teachers assigned to an access group (paginated).

Inputs: accessGroupId (required), Skip, Take.

AccessGroupsRemoveMembersA
Destructive

Remove members from an access group.

WARNING: Destructive: unlinks members from the group. Requires client-side approval.

Inputs: accessGroupId (required), bodyTeacherIds, bodyGroupClassIds, bodyIndividualClassIds.

BooksGetBookA
Read-only

Get a single book by id.

Inputs: bodyBookId.

BooksGetBooksPlatformA
Read-only

List books available on the platform.

Inputs: no named parameters.

BooksGetBooksSchoolA
Read-only

List books available to the current school.

Inputs: no named parameters.

BooksPinLessonToClassC

Pin a lesson from a book to a class.

Inputs: bodyClassId, bodyLessonId.

ClassesGetStatisticsD
Read-only

Get class statistics.

Inputs: bodyClassId, bodyPupilId.

GroupClassesChangeTeacherC

Change the teacher assigned to a group class.

Inputs: classId (required), teacherId (required).

GroupClassesCreateC

Create a new group class.

Inputs: bodyName (required), bodyTeacherId (required), bodyAccessGroups, bodyLessonTariffDurationId.

GroupClassesDeleteA
Destructive

Delete a group class.

WARNING: Destructive: removes the group class. Requires client-side approval.

Inputs: classId.

GroupClassesGetDetailA
Read-only

Get details of a single group class by id.

Inputs: classId.

GroupClassesGetListB
Read-only

List group classes with optional filters and pagination.

Inputs: Search, PupilId, pageSkip, pageTake, +2 more.

GroupClassesUpdateC

Update an existing group class.

Inputs: classId (required), bodyName, bodyTeacherId, bodyLessonTariffDurationId.

GroupClassPupilsAddA

Add pupils to a group class. Adding a pupil to a group class activates the pupil and consumes the school's tariff limit of activated students. The limit depends on the school's tariff plan. Exceeding it returns HTTP 400 "The number of activated students has been exceeded".

Inputs: classId (required), bodyPupilIds.

GroupClassPupilsDeleteA
Destructive

Remove a pupil from a group class.

WARNING: Destructive: unlinks the pupil from the group class. Requires client-side approval.

Inputs: classId (required), pupilId (required).

GroupClassPupilsGetListA
Read-only

List pupils in a group class (paginated).

Inputs: ClassId (required), pageSkip, pageTake.

IndividualClassesChangeTeacherA

Change the teacher assigned to an individual class.

Inputs: classId (required), teacherId (required), classLearningLanguage.

IndividualClassesCreateC

Create a new individual class.

Inputs: bodyName (required), bodyPupilId (required), bodyTeacherId (required), bodyClassLanguageId.

IndividualClassesDeleteA
Destructive

Delete an individual class.

WARNING: Destructive: removes the individual class. Requires client-side approval.

Inputs: classId.

IndividualClassesGetDetailA
Read-only

Get details of a single individual class by id.

Inputs: classId.

IndividualClassesGetListA
Read-only

List individual classes with optional filters and pagination.

Inputs: Search, PupilId, pageSkip, pageTake, +2 more.

IndividualClassesUpdateB

Update an existing individual class.

Inputs: classId (required), bodyName, bodyLessonTariffDurationId.

LessonPackagesGetListB
Read-only

List lesson packages for a pupil and/or class.

Inputs: classId (required), pupilId (required), updatedAfter.

LessonPackagesSetPackageC

Set a lesson package for a pupil and class.

Inputs: classId (required), pupilId (required), bodyComment (required), bodyLessonPackageId (required), +4 more.

LessonPackagesUpdatePackagePeriodC

Update the period of a lesson package.

Inputs: classId (required), pupilId (required), bodyLessonPackageDurationId (required), bodyToDate, +1 more.

LessonPackagesWriteOffLessonsA
Destructive

Write off lessons from a package.

WARNING: Destructive: decrements lesson balance. Requires client-side approval.

Inputs: bodyCount (required), bodyClassId (required), bodyComment (required), bodyPupilId (required), +1 more.

LessonTariffsAddTariffDurationB

Add a duration option to a lesson tariff.

Inputs: bodyDuration (required), lessonTariffId (required), bodyPrice, bodyLessonsCount, +1 more.

LessonTariffsCreateB

Create a new lesson tariff.

Inputs: bodyName (required), bodyDurations, bodyDescription.

LessonTariffsDeleteA
Destructive

Delete a lesson tariff.

WARNING: Destructive: removes the tariff. Requires client-side approval.

Inputs: lessonTariffId (required).

LessonTariffsDeleteLessonPackageA
Destructive

Delete a lesson package attached to a tariff.

WARNING: Destructive: removes the lesson package. Requires client-side approval.

Inputs: LessonTariffId (required), LessonTariffPackageId (required), LessonTariffDurationId (required).

LessonTariffsDeleteTariffDurationA
Destructive

Delete a tariff duration.

WARNING: Destructive: removes the tariff duration. Requires client-side approval.

Inputs: LessonTariffId (required), LessonTariffDurationId (required).

LessonTariffsGetListA
Read-only

List lesson tariffs (paginated, with soft-deleted filter).

Inputs: Search, pageSkip, pageTake, IsDeleted.

LessonTariffsGetTariffDurationListB
Read-only

List lesson tariff durations (paginated).

Inputs: pageSkip, pageTake, LessonTariffIds.

LessonTariffsGetTariffForDurationIdA
Read-only

Get a lesson tariff by its duration id.

Inputs: schoolLessonTariffDurationId (required).

MarathonAddMarathonNewStudentsA

Add new students to a marathon by email. Note: this is a GET that mutates state.

WARNING: Mutates state: invites new students to a marathon. Requires client-side approval.

Inputs: Emails, MarathonId, ModeratorsIds, MailMessageLanguageId.

MarathonChangeActivationMarathonPupilA
Destructive

Activate or deactivate a pupil in a marathon.

WARNING: Destructive: changes pupil activation state in a marathon. Requires client-side approval.

Inputs: bodyPupilId, bodyIsActivate, bodyMarathonId.

MarathonCreateModeratorC

Create a marathon moderator.

Inputs: bodyTeacherId, bodyMarathonId.

MarathonDeleteModeratorA
Destructive

Delete a marathon moderator.

WARNING: Destructive: removes the moderator. Requires client-side approval.

Inputs: bodyMarathonId, bodyIsSelectAll, bodyModeratorId, bodySelectedPupilsIds.

MarathonGetMarathonListA
Read-only

List marathons (paginated, with search and folder filter).

Inputs: FolderId, pageSkip, pageTake, SearchTerm.

MarathonGetMarathonStudentsA
Read-only

List students in a marathon with search and filter.

Inputs: Filter, MarathonId, SearchTerm.

MarathonGetModeratorsA
Read-only

List marathon moderators (paginated).

Inputs: pageSkip, pageTake, TeacherId, MarathonId.

MarathonSetModeratorsForPupilB

Assign moderators to a marathon pupil.

Inputs: bodyMarathonPupilId, bodySelectedModeratorsIds.

MarathonSetPupilsForModeratorB

Assign pupils to a marathon moderator.

Inputs: bodyMarathonId, bodyModeratorId, bodySelectedPupilsIds.

MarathonUnsetModeratorsForPupilA
Destructive

Unassign moderators from a marathon pupil.

WARNING: Destructive: unlinks moderators from the pupil. Requires client-side approval.

Inputs: bodyMarathonPupilId, bodySelectedModeratorsIds.

MarathonUnsetPupilsForModeratorB
Destructive

Unassign pupils from a marathon moderator.

WARNING: Destructive: unlinks pupils from the moderator. Requires client-side approval.

Inputs: bodyMarathonId, bodyIsSelectAll, bodyModeratorId, bodySelectedPupilsIds.

PupilsCreateC

Create a new pupil.

Inputs: bodyName (required), bodyEmail (required), bodyNote, bodyPhone, +12 more.

PupilsDeleteA
Destructive

Delete a pupil. The pupil must be unlinked from all classes first: remove from group classes via GroupClassPupilsDelete and delete individual classes via IndividualClassesDelete. Upstream returns HTTP 400 "Pupil have classes" if any class link remains.

WARNING: Destructive: removes the pupil. Requires client-side approval.

Inputs: pupilId.

PupilsGetCursorListB
Read-only

List pupils using cursor-based pagination.

Inputs: Search, ActiveOnly, OnlyUpdated, cursorLimit, +6 more.

PupilsGetDetailA
Read-only

Get details of a single pupil by id.

Inputs: pupilId.

PupilsGetListA
Read-only

List pupils with search, filters and pagination.

Inputs: Search, pageSkip, pageTake, ActiveOnly, +4 more.

PupilsUpdateB

Update an existing pupil.

Inputs: pupilId (required), bodyName, bodyNote, bodyEmail, +12 more.

PupilTagCreateB

Create a new pupil tag.

Inputs: TagName (required).

PupilTagDeleteA
Destructive

Delete a pupil tag.

WARNING: Destructive: removes the tag. Requires client-side approval.

Inputs: TagId (required).

PupilTagGetListA
Read-only

List all pupil tags.

Inputs: no named parameters.

ScheduleCreateLessonA

Create a new lesson in the schedule. The groupId field accepts the id of any class (group or individual). Creating a lesson may activate the pupil as a side effect (response includes isActivatedPupil).

Inputs: bodyDate (required), bodyGroupId (required), bodyDurationMinutes (required), bodyPupilId, +3 more.

ScheduleDeleteLessonA
Destructive

Delete a lesson from the schedule.

WARNING: Destructive: removes the lesson. Requires client-side approval.

Inputs: lessonId, bodyComment, bodyDeleteRepeatLessons.

ScheduleGetPackageForGroupLessonB
Read-only

Get the lesson package applicable to a group lesson.

Inputs: lessonId (required), pupilId.

ScheduleGetPackageForIndividualLessonA
Read-only

Get the lesson package applicable to an individual lesson.

Inputs: lessonId (required).

ScheduleGetPupilScheduleA
Read-only

Get a pupil's schedule for a date range.

Inputs: dateEnd (required), pupilId (required), dateStart (required), bodyGroupId, +2 more.

ScheduleGetSchoolScheduleB
Read-only

Get the school schedule for a date range.

Inputs: bodyPage, bodyDateEnd, bodyGroupId, bodyPupilId, +3 more.

ScheduleGetSchoolWeekWorkTimeA
Read-only

Get the school's weekly work time.

Inputs: no named parameters.

ScheduleGetTeacherScheduleA
Read-only

Get a teacher's schedule for a date range in a given timezone.

Inputs: dateEnd (required), dateStart (required), teacherId (required), timezone.

ScheduleGetTeacherWeekWorkTimeB
Read-only

Get a teacher's weekly work time.

Inputs: teacherId (required), fromMonday (required).

TeachersCreateB

Create a new teacher.

Inputs: bodyName (required), bodyEmail (required), bodyPhone, bodySkype, +7 more.

TeachersDeleteA
Destructive

Delete a teacher.

WARNING: Destructive: removes the teacher. Requires client-side approval.

Inputs: teacherId.

TeachersGetDetailA
Read-only

Get details of a single teacher by id.

Inputs: teacherId.

TeachersGetListB
Read-only

List teachers with search and pagination.

Inputs: Search, pageSkip, pageTake.

TeachersUpdateC

Update an existing teacher.

Inputs: bodyName, bodyEmail, bodyPhone, bodySkype, +9 more.

UserAuthCheckAuthTokenC
Read-only

Check whether an auth token is valid.

Inputs: bodySessionToken.

UserAuthLoginPupilA

Authenticate a pupil and return a login token.

WARNING: Sensitive: returns a login token. Public enablement requires recorded product/security approval. The token must never be logged, cached, or returned outside the direct successful tool result.

Inputs: bodyPupilId.

UserAuthLoginTeacherA

Authenticate a teacher and return a login token.

WARNING: Sensitive: returns a login token. Public enablement requires recorded product/security approval. The token must never be logged, cached, or returned outside the direct successful tool result.

Inputs: bodyTeacherId.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 78 tools

    Disambiguation4/5

    Most tools are clearly separated by resource prefix and action, and the descriptions clarify their purpose. A few list-related tools such as PupilsGetList vs PupilsGetCursorList and LessonTariffsGetTariffForDurationId vs LessonTariffsGetTariffDurationList could cause misselection, but overall boundaries are reasonably clear.

    Naming Consistency4/5

    The tools generally follow a Resource + Verb + OptionalObject pattern, making them readable and predictable. Deviations such as MarathonAddMarathonNewStudents, MarathonChangeActivationMarathonPupil, and mixed Create/Add/Set/Unset verbs are minor inconsistencies within an otherwise coherent scheme.

    Tool Count1/5

    78 tools is an extreme count for a single MCP server. While the domain is broad, the surface area is far too large for effective agent discovery and selection, and many tools could be grouped or exposed as sub-resources rather than flat tool entries.

    Completeness3/5

    The server covers many core school-management workflows: pupils, teachers, group/individual classes, tariffs, packages, schedules, and auth. However, there are notable gaps such as no marathon create/update/delete, no schedule lesson update/reschedule, and no access group update, which leave some workflows incomplete.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      This MCP server provides comprehensive read and write access to Google Classroom, enabling management of courses, rosters, assignments, and grades. It supports full lifecycle operations for educational environments including student submissions, teacher invitations, and coursework organization.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI agents to safely query and act on school data (attendance, fees, student records) with strict role-based access control and a two-step write approval flow.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLM agents and automation tools to interact with Moodle through a permission-checked MCP endpoint, covering courses, activities, question banks, enrolments, and administrative operations via 240 external functions.
      4
      GPL 3.0
    • F
      license
      C
      quality
      C
      maintenance
      Enables interaction with the Edookit school management system API, exposing attendance, lessons, people, grades, payments, courses, timetable, and individual goals as MCP tools.
      46
      -