Edvibe School MCP
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
契约一览
类别 | 数量 | 含义 |
|
|
read | 35 | 只读 |
|
|
write | 24 | 普通状态变更 |
|
|
high-risk | 17 | 破坏性 / 难以逆转 |
|
|
sensitive | 2 | 返回登录令牌 |
|
|
总计 | 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 toolsAccessGroupsAddMembersC
Add members to an access group.
Inputs: accessGroupId (required), bodyTeacherIds, bodyGroupClassIds, bodyIndividualClassIds.
AccessGroupsCreateA
Create a new access group.
Inputs: name (required).
AccessGroupsDeleteADestructive
Delete an access group.
WARNING: Destructive: removes the access group. Requires client-side approval.
Inputs: accessGroupId (required).
AccessGroupsGetDetailsARead-only
Get details of a single access group by id.
Inputs: accessGroupId (required).
AccessGroupsGetGroupClassesARead-only
List group classes linked to an access group (paginated).
Inputs: accessGroupId (required), Skip, Take.
AccessGroupsGetIndividualClassesARead-only
List individual classes linked to an access group (paginated).
Inputs: accessGroupId (required), Skip, Take.
AccessGroupsGetListBRead-only
List access groups with optional filters by teacher, group class, or individual class.
Inputs: teacherId, groupClassId, individualClassId.
AccessGroupsGetTeachersARead-only
List teachers assigned to an access group (paginated).
Inputs: accessGroupId (required), Skip, Take.
AccessGroupsRemoveMembersADestructive
Remove members from an access group.
WARNING: Destructive: unlinks members from the group. Requires client-side approval.
Inputs: accessGroupId (required), bodyTeacherIds, bodyGroupClassIds, bodyIndividualClassIds.
BooksGetBookARead-only
Get a single book by id.
Inputs: bodyBookId.
BooksGetBooksPlatformARead-only
List books available on the platform.
Inputs: no named parameters.
BooksGetBooksSchoolARead-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.
ClassesGetStatisticsDRead-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.
GroupClassesDeleteADestructive
Delete a group class.
WARNING: Destructive: removes the group class. Requires client-side approval.
Inputs: classId.
GroupClassesGetDetailARead-only
Get details of a single group class by id.
Inputs: classId.
GroupClassesGetListBRead-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.
GroupClassPupilsDeleteADestructive
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).
GroupClassPupilsGetListARead-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.
IndividualClassesDeleteADestructive
Delete an individual class.
WARNING: Destructive: removes the individual class. Requires client-side approval.
Inputs: classId.
IndividualClassesGetDetailARead-only
Get details of a single individual class by id.
Inputs: classId.
IndividualClassesGetListARead-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.
LessonPackagesGetListBRead-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.
LessonPackagesWriteOffLessonsADestructive
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.
LessonTariffsDeleteADestructive
Delete a lesson tariff.
WARNING: Destructive: removes the tariff. Requires client-side approval.
Inputs: lessonTariffId (required).
LessonTariffsDeleteLessonPackageADestructive
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).
LessonTariffsDeleteTariffDurationADestructive
Delete a tariff duration.
WARNING: Destructive: removes the tariff duration. Requires client-side approval.
Inputs: LessonTariffId (required), LessonTariffDurationId (required).
LessonTariffsGetListARead-only
List lesson tariffs (paginated, with soft-deleted filter).
Inputs: Search, pageSkip, pageTake, IsDeleted.
LessonTariffsGetTariffDurationListBRead-only
List lesson tariff durations (paginated).
Inputs: pageSkip, pageTake, LessonTariffIds.
LessonTariffsGetTariffForDurationIdARead-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.
MarathonChangeActivationMarathonPupilADestructive
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.
MarathonDeleteModeratorADestructive
Delete a marathon moderator.
WARNING: Destructive: removes the moderator. Requires client-side approval.
Inputs: bodyMarathonId, bodyIsSelectAll, bodyModeratorId, bodySelectedPupilsIds.
MarathonGetMarathonListARead-only
List marathons (paginated, with search and folder filter).
Inputs: FolderId, pageSkip, pageTake, SearchTerm.
MarathonGetMarathonStudentsARead-only
List students in a marathon with search and filter.
Inputs: Filter, MarathonId, SearchTerm.
MarathonGetModeratorsARead-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.
MarathonUnsetModeratorsForPupilADestructive
Unassign moderators from a marathon pupil.
WARNING: Destructive: unlinks moderators from the pupil. Requires client-side approval.
Inputs: bodyMarathonPupilId, bodySelectedModeratorsIds.
MarathonUnsetPupilsForModeratorBDestructive
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.
PupilsDeleteADestructive
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.
PupilsGetCursorListBRead-only
List pupils using cursor-based pagination.
Inputs: Search, ActiveOnly, OnlyUpdated, cursorLimit, +6 more.
PupilsGetDetailARead-only
Get details of a single pupil by id.
Inputs: pupilId.
PupilsGetListARead-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).
PupilTagDeleteADestructive
Delete a pupil tag.
WARNING: Destructive: removes the tag. Requires client-side approval.
Inputs: TagId (required).
PupilTagGetListARead-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.
ScheduleDeleteLessonADestructive
Delete a lesson from the schedule.
WARNING: Destructive: removes the lesson. Requires client-side approval.
Inputs: lessonId, bodyComment, bodyDeleteRepeatLessons.
ScheduleGetPackageForGroupLessonBRead-only
Get the lesson package applicable to a group lesson.
Inputs: lessonId (required), pupilId.
ScheduleGetPackageForIndividualLessonARead-only
Get the lesson package applicable to an individual lesson.
Inputs: lessonId (required).
ScheduleGetPupilScheduleARead-only
Get a pupil's schedule for a date range.
Inputs: dateEnd (required), pupilId (required), dateStart (required), bodyGroupId, +2 more.
ScheduleGetSchoolScheduleBRead-only
Get the school schedule for a date range.
Inputs: bodyPage, bodyDateEnd, bodyGroupId, bodyPupilId, +3 more.
ScheduleGetSchoolWeekWorkTimeARead-only
Get the school's weekly work time.
Inputs: no named parameters.
ScheduleGetTeacherScheduleARead-only
Get a teacher's schedule for a date range in a given timezone.
Inputs: dateEnd (required), dateStart (required), teacherId (required), timezone.
ScheduleGetTeacherWeekWorkTimeBRead-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.
TeachersDeleteADestructive
Delete a teacher.
WARNING: Destructive: removes the teacher. Requires client-side approval.
Inputs: teacherId.
TeachersGetDetailARead-only
Get details of a single teacher by id.
Inputs: teacherId.
TeachersGetListBRead-only
List teachers with search and pagination.
Inputs: Search, pageSkip, pageTake.
TeachersUpdateC
Update an existing teacher.
Inputs: bodyName, bodyEmail, bodyPhone, bodySkype, +9 more.
UserAuthCheckAuthTokenCRead-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
Scored across 78 tools
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.
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.
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.
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
Related MCP Connectors
Hosted MCP for Google Workspace, Atlassian and Notion: one OAuth, per-user accounts, write access.
One MCP endpoint for your company's tools, with per-person sign-in, policy and audit.
Scopable MSP API: clients, quotes, assessments, compliance, QBRs. OAuth 2.1, read-only or read-write
Managed MCP gateway with OAuth, per-agent permissions, shared accounts and activity logs.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceThis 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.-
- FlicenseNot gradedqualityDmaintenanceAn 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.-
- AlicenseNot gradedqualityBmaintenanceEnables 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.4GPL 3.0
- FlicenseCqualityCmaintenanceEnables interaction with the Edookit school management system API, exposing attendance, lessons, people, grades, payments, courses, timetable, and individual goals as MCP tools.46-