openemis-pro

---

title: openemis-mcp-pro — OpenEMIS 学校管理系统的读写 MCP 服务 description: openemis-mcp-pro 是连接 AI 助手与 OpenEMIS 学校管理信息系统的读写 MCP 服务，提供 678 个资源、3361 个端点和 40 个操作手册。 keywords:

• OpenEMIS
• 学校管理系统
• 教育管理
• 学生出勤
• 学生风险
• MCP 服务
• 写入工具

---

openemis-mcp-pro — OpenEMIS 学校管理系统的 AI 读写桥接工具

连接支持 MCP 的 Agent（Claude、Codex、Cursor 等）与任意 OpenEMIS 学校的自然语言桥接工具，支持完整的读写访问。

OpenEMIS 是由 UNESCO 和 KORDIT 开发的免费开源学校管理信息系统。它负责各类教育机构的日常管理，包括幼儿园、小学、中学、中等职业院校、技术学院和大学，可管理学生、教职员工、出勤、评估、基础设施、膳食、奖学金、考试、培训以及教育部级报告。此 MCP 服务为任意 OpenEMIS 学校提供完整的读写访问和按用户身份验证。

翻译： Русский · Español · हिन्दी · العربية

此项目基于已发布的 OpenEMIS Core API（参考文档见 api.openemis.org/core），并使用真实凭据和真实数据，通过实际往返操作对照公共演示站点 demo.openemis.org/core 完成端到端验证。

用英语提问：

“Avory 小学目前有多少名在校学生？”

Agent 规划调用方式，此 MCP 服务提供数据，你就能得到答案：

“Avory 小学（代码 P1002）目前有 553 名在校学生。”

你无需编写任何代码，也不会看到 JSON，只需提问即可。

状态： v1.0.0 — 对非工作流资源支持完整 CRUD。所有 OpenEMIS v5 资源均可进行读取查询。写入工具（创建／更新／删除）已适用于所有不通过 CakePHP Workflow 插件处理的资源。由工作流控制的资源（出勤、员工请假）会在工具层面被拦截，并引导至相应的操作手册。

---

这是什么

openemis-mcp-pro 是连接 AI 助手与 OpenEMIS 学校管理系统的读写 MCP 服务。它通过 40 个精心整理的操作手册，提供 678 个资源（学生、出勤、风险、教职员工、考试、基础设施），其中包含 26 个读取操作手册和 14 个写入／身份验证操作手册。专业版在免费只读版本的基础上，新增直接写入工具（openemis_create、openemis_update、openemis_delete）、面向 ChatGPT Custom GPT 的 HTTP 服务模式，以及按用户身份验证。

---

存在的原因

OpenEMIS Core REST API 规模庞大——仅 v5 就有 3,361 个端点，分布在 678 个资源中（Core 5.13.0）。没有 AI Agent 能将这些内容全部纳入上下文，而原始的 Swagger 风格内省会让对话充斥与用户实际问题无关的信息。

这个 MCP 通过两种方式解决这一问题：

1. 按领域缩小发现范围。 openemis_discover(topic) 工具不会将整个 API 倾倒进 Agent 的上下文，而是将范围缩小到与用户实际问题（“考勤”“学生”“评估”）相关的约 20–30 个端点——由一套小型精选知识包 Domain-*.md 提供支持。
2. 单一、可组合的获取工具。 一个 openemis_get 工具即可覆盖所有资源的列表、单条记录和筛选搜索。Agent 提供 resource + 可选的 id + 可选的 params（_fields、_conditions、orderby、page、limit），其余内容会直接映射到 OpenEMIS 的 CakePHP 风格查询 DSL。

最终效果：Agent 只需 2–4 次工具调用，而不是 30 次，就能回答自然语言问题。

---

工具

工具	起始版本	功能
openemis_health	v0.1	对配置的实例执行 ping 并报告是否可访问。会执行一次真实的登录往返——如果通过，CRUD 就能正常工作。
openemis_list_domains	v0.1	列出精选的 OpenEMIS 领域——考勤、评估、教职员工、学生、机构、日程、考试、报告——每个领域都附有一行摘要。Agent 会用它来判断问题属于哪个领域。
openemis_discover	v0.1	输入：主题字符串。输出：从领域知识包和实例级清单中提取的最多 30 个相关端点。无论底层 API 有多庞大，都能让对话保持简洁。
openemis_list_playbooks	v0.2	列出全部 40 个精选工作流指南，包含 id、标题、领域和适用对象。Agent 会用它为用户级任务查找合适的分步指南。
openemis_get_playbook	v0.2	输入：工作流指南 id。输出：完整指南——资源、排序后的步骤、指导说明和示例查询。
openemis_get	v0.1	统一的读取工具。{ resource, id?, params? }——如果提供了 id，则获取单条记录；否则按任意组合使用 _fields、_conditions、orderby、order、page、limit 以及任意临时筛选键列出记录。
openemis_create	v0.3.0	创建一条新记录。{ resource, body }——仅限非工作流资源。由工作流控制的资源（例如 institution-staff-leave）会被拦截，并引导至相应的工作流指南。
openemis_update	v0.3.0	按 id 更新现有记录。{ resource, id, body }——仅限非工作流资源。
openemis_delete	v0.3.0	按 id 删除一条记录。{ resource, id }——仅限非工作流资源。

一个典型的自然语言问题，例如 “Avory Primary 有多少名教师、多少个空缺职位？”，会解析为 3 次 openemis_get 调用——由 Agent 链式执行，使用 _conditions 缩小范围，最后整合成一条英文答复。对于 “招收一名新学生” 这样的写入请求，会先使用 openemis_get_playbook 加载分步指南，再对每个写入步骤调用 openemis_create。

---

核心兼容性

已针对 OpenEMIS Core 5.13.0（master，2026 年 6 月）进行测试。也支持更早的 5.7–5.12 版本部署——API 接口向后兼容。

功能标志 — POCOR-9660 多 ID GET

openemis_get 接受 params.ids = "1,2,3"，用于批量查询。Core 5.10+ 已支持 POCOR-9660（CrudApiController 中支持 ?id=1,2,3 和 _conditions=<field>:IN(...)），因此处理程序默认会将批量查询合并为一次往返请求。若连接的是较旧的 Core（5.7–5.9），且不支持原生运算符，则可强制使用旧版并行分发：

OPENEMIS_CORE_IN_OPERATOR=off

对于复合主键或视图资源（这些资源不适用 ids），请改用 _conditions=<field>:IN(1,2,3)；它可以按值列表筛选任意字段，且不受此标志影响。现在，筛选资源上不存在的字段会返回 HTTP 400（Core 5.10+，POCOR-9697），因此请使用准确的字段名称。

已通过 demo.openemis.org 验证

编写此 README 前，已在公开演示实例上验证其中的每一项说明：

• 使用 { username, password, api_key } 执行 POST /api/v5/login → 缓存 JWT，长 331 个字符
• 执行 GET /api/v5/institutions?limit=200&_fields=id,name,code → 获取 24 所机构，包括 "Avory Primary School" (id=6, code P1002)
• 执行 GET /api/v5/institution-students?institution_id=6&student_status_id=1&limit=1 → 分页信息显示 last_page: 553 → 当前在读学生共 553 名
• 执行 GET /api/v5/academic-periods → 获取 7 页真实学年的数据
• 执行 GET /api/v5/absence-types → 获取 EXCUSED、UNEXCUSED、LATE 等类型

本仓库附带的示例 scripts/smoke-login.mjs 会逐步执行登录测试，方便你在将其接入 Claude Code 前，先确认它能连接到自己的实例。

---

兼容的 Agent

openemis-mcp 通过 stdio 使用 Model Context Protocol，任何兼容 MCP 的客户端均可使用：

Stdio 模式（本地计算机） — 以子进程方式连接：

Agent	连接方式
Claude Code（claude CLI）	claude mcp add — 首要测试客户端，9 个工具均可用
Cursor	添加到 .cursor/mcp.json — 可使用所有工具
Cline / Continue（VS Code）	在 MCP 设置中添加服务
Codex	通过 gemmy-and-qwenny 桥接
任何 MCP 客户端	设置环境变量后，指向 node dist/server.js

HTTP 服务模式（OPENEMIS_TRANSPORT=http，在 Oracle/VPS 上安装一次即可）— 通过 URL 连接：

客户端	连接方式
Claude Code（远程）	claude mcp add --transport http --url http://your-server:3000/mcp --header "Authorization: Bearer <token>"
Cursor / Cline	在设置中添加远程 MCP URL
ChatGPT（Custom GPT）	从 http://your-server:3000/openapi.json 导入架构 → Actions → Bearer token
任何 HTTP 客户端	/api/* 上的 REST API — 参见教师指南

---

安装

需要 Node 22+（用于内置的 fetch 和 AbortController）以及 Python 3.10+（用于 mcp-openemis-gen/ 中的清单构建器和工作手册生成脚本）。MCP 服务本身仅依赖 Node；只有从源代码重新构建清单时才需要 Python。

从 GitHub 安装

git clone https://github.com/tixuz/openemis-mcp.git
cd openemis-mcp

npm install
npm run build

cp .env.example .env
$EDITOR .env

配置

.env.example 记录了所有变量。至少需要 OpenEMIS 管理员提供的三项凭据：

OPENEMIS_BASE_URL=https://demo.openemis.org/core   # or your own instance
OPENEMIS_USERNAME=admin
OPENEMIS_PASSWORD=your_password
OPENEMIS_API_KEY=your_api_key

# Optional
OPENEMIS_TIMEOUT_MS=30000
OPENEMIS_VAULT_PATH=/absolute/path/to/domain-notes
OPENEMIS_MANIFEST_PATH=/absolute/path/to/manifest.jsonl

服务会在首次经过身份验证的工具调用时按需登录，向 /api/v5/login 发送 POST 请求，从 data.token 中解析 JWT 并将其缓存在内存中。如果收到 401，服务会重新登录并重试一次。

OPENEMIS_VAULT_PATH 指向包含精选 Domain-*.md 笔记的文件夹，这些笔记由 openemis_discover 使用。如果该路径不存在，发现功能会正常降级，仅根据清单进行关键词匹配。

OPENEMIS_MANIFEST_PATH 指向配套构建器（位于 ../mcp-openemis-gen/）生成的 JSONL 文件。如果该文件不存在，发现工具会友好地提示“清单尚未构建”，而不会崩溃。

冒烟测试连通性

set -a && source .env && set +a
node scripts/smoke-login.mjs

预期结果：

[Test] Loading config...
[OK] Config loaded: baseUrl=https://demo.openemis.org/core
[Test] Creating client...
[OK] Client created
[Test] Attempting login...
[OpenEMIS] Login successful; cached JWT (331 chars)
[OK] Login successful

在 Claude Code 中注册

claude mcp add openemis \
  --env OPENEMIS_BASE_URL="https://your-openemis/core" \
  --env OPENEMIS_USERNAME="…" \
  --env OPENEMIS_PASSWORD="…" \
  --env OPENEMIS_API_KEY="…" \
  --env OPENEMIS_VAULT_PATH="/absolute/path/to/vault" \
  -- node "$(pwd)/dist/server.js"

# Verify
claude mcp list | grep openemis
# Expected: openemis: node /…/dist/server.js - ✓ Connected

此项目中启动的任何新 Claude Code 会话都会自动看到全部 9 个工具。

---

服务模式（Oracle Always Free / 任意 VPS）

设置 OPENEMIS_TRANSPORT=http，即可将其作为持久 HTTP 服务运行，而不是本地子进程。只需在服务器上安装一次；每个兼容 MCP 的客户端（Claude Code、Cursor、Cline、Windsurf）都可通过 URL 连接。

在服务器上：

git clone https://github.com/tixuz/openemis-mcp-pro.git
cd openemis-mcp-pro
npm install && npm run build
cp .env.example .env
$EDITOR .env          # set credentials + OPENEMIS_TRANSPORT=http + OPENEMIS_AUTH_TOKEN
node dist/server.js

服务模式的 .env：

OPENEMIS_BASE_URL=https://your-openemis/core
OPENEMIS_USERNAME=admin
OPENEMIS_PASSWORD=your_password
OPENEMIS_API_KEY=your_api_key

OPENEMIS_TRANSPORT=http
OPENEMIS_PORT=3000

# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
OPENEMIS_AUTH_TOKEN=your-secret-token-here

从 Claude Code 连接（远程）：

claude mcp add openemis-remote \
  --transport http \
  --url "http://your-server:3000/mcp" \
  --header "Authorization: Bearer your-secret-token-here"

健康探测（监控 / 正常运行时间检查）：

curl http://your-server:3000/health
# {"ok":true,"transport":"http","baseUrl":"https://your-openemis/core"}

⚠️ 对外公开端口之前，务必设置 OPENEMIS_AUTH_TOKEN。 否则，任何能够访问你 IP 地址的人都可以访问此端点。

---

架构

┌────────────────────────┐
│  Agent (Claude / …)    │     "How many current students at Avory?"
└───────────┬────────────┘
            │ MCP stdio (JSON-RPC)
┌───────────▼────────────┐
│  openemis-mcp          │  ← nine typed tools, ZodRawShape schemas
│  • openemis_health     │
│  • openemis_list_dom…  │  ← reads Domain-*.md from vault
│  • openemis_discover   │  ← topic → ≤30 scoped endpoints
│  • openemis_list_play… │  ← list all 40 workflow playbooks
│  • openemis_get_playbk │  ← load a playbook by id
│  • openemis_get / _create / _update / _delete   │
└───────────┬────────────┘
            │ HTTPS + Bearer JWT (cached, auto-refresh on 401)
┌───────────▼────────────┐
│  OpenEMIS Core API     │  api.openemis.org/core  (reference)
│  /api/v5/{resource}    │  demo.openemis.org/core (tested)
└────────────────────────┘

从第一行代码开始，我们就遵循以下设计原则：

1. 限定领域范围，绝不倾泻全部信息。 清单可以扩展到数千个端点，但 Agent 的上下文容量不会随之增长。openemis_discover(topic) 是筛选入口——每次对话只会看到所需的那部分内容。
2. v0.3.0 中提供写入工具。 所有非工作流资源均可使用 openemis_create / openemis_update / openemis_delete。由工作流控制的资源（attendance、staff-attendance）会在工具层被拦截，并引导至相应的操作指南。
3. 调用之间无状态。 只有 JWT 会缓存在内存中。不持久化到磁盘、不进行分析，也不会向外发送任何数据。
4. 轻量封装真实 API。 此桥接不会创造新概念——resource 名称采用 kebab-case 的 v5 路径，查询参数使用原生 _conditions / _fields DSL。你在 curl 中编写的内容可以一对一转换。

---

文档

• 资源参考 — 全部 678 项资源，包含 HTTP 方法可用性和写入状态（Core 5.13.0）
• 操作指南 — 40 份精选工作流指南（26 份读取 · 14 份写入 / 身份验证）
• ChatGPT 教师指南 — 如何让教师通过 ChatGPT Custom GPT 标记出勤
• 操作指南编写流程 — 添加操作指南的 4 步流程
• 术语表 — OpenEMIS 和教育管理关键术语的定义
• 常见问题 — 关于 OpenEMIS 和此 MCP 服务的常见问题

操作指南

#	操作手册	领域	受众	翻译
1	统计空缺职位	员工	管理员、人力资源	RU · ES · HI · AR
2	登记学生出勤	出勤	教师、管理员	RU · ES · HI · AR
3	登记员工出勤	员工	管理员、人力资源、教师	RU · ES · HI · AR
4	查看学生课表	日程	家长、学生	RU · ES · HI · AR
5	学生仪表板	学生	家长、学生	RU · ES · HI · AR
6	生成学生成绩单 PDF	报告	教师、管理员	RU · ES · HI · AR
7	为新学生办理入学	学生	管理员、注册员	RU · ES · HI · AR
8	记录行为事件	学生	教师、管理员	RU · ES · HI · AR
9	提交考试成绩	评估	教师	RU · ES · HI · AR
10	机构摘要	机构	管理员、家长	RU · ES · HI · AR
11	生成机构统计 PDF	报告	管理员	RU · ES · HI · AR
12	查看最新出勤情况	出勤	教师、管理员、家长	RU · ES · HI · AR
13	查看学生档案	学生	教师、管理员	RU · ES · HI · AR
14	查看学生成绩	评估	教师、管理员、家长	RU · ES · HI · AR
15	查看班级报告	报告	教师、管理员	RU · ES · HI · AR
16	查看课表	日程	教师、管理员、学生	RU · ES · HI · AR
17	查看完整机构档案	机构	管理员、家长、公众	RU · ES · HI · AR
18	查看完整班级档案	学生	教师、管理员	RU · ES · HI · AR
19	查看员工完整档案	员工	管理员、人力资源	RU · ES · HI · AR
20	完善学生档案	学生	教师、管理员、辅导员	RU · ES · HI · AR
21	查看机构基础设施	基础设施	管理员、设施管理人员	RU · ES · HI · AR
22	查看机构膳食	膳食	管理员、营养师、家长	RU · ES · HI · AR
23	查看学生风险档案	学生	管理员、辅导员、教师	RU · ES · HI · AR
24	查看机构风险摘要	机构	管理员、教育部	RU · ES · HI · AR
25	添加设备或资产 ✏️	基础设施	管理员、会计、设施管理人员	RU · ES · HI · AR
26	记录基础设施维修 ✏️	基础设施	管理员、会计、设施管理人员	RU · ES · HI · AR
27	添加新的膳食计划 ✏️	膳食	管理员、会计、营养师	RU · ES · HI · AR
28	确认我的身份（按用户进行身份验证）🔐	身份验证	教师、管理员、员工	RU · ES · HI · AR
29	diagnose-alert-delivery (POCOR-9509)	警报	管理员、教育部	文档即将发布
30	view-school-accreditation (POCOR-9610)	机构	管理员、教育部、校长	文档即将发布
31	view-school-registration (POCOR-9610)	机构	管理员、教育部、校长	文档即将发布
32	view-institution-budget (Core 5.10.0)	机构	管理员、财务人员	文档即将发布
33	query-student-absence-history (Core 5.10.0)	出勤	教师、管理员、家长、辅导员	文档即将发布
34	query-user-activity-audit-log (POCOR-9697)	安全	管理员、安全人员、教育部	文档即将发布
35	view-class-roster (Core 5.10.0)	机构	教师、管理员、班主任	文档即将发布
36	set-school-accreditation ✏️ (POCOR-9610)	机构	管理员、教育部	文档即将发布
37	set-school-registration ✏️ (POCOR-9610)	机构	管理员、教育部	文档即将发布
38	mark-student-meal-participation ✏️	膳食	教师、管理员、营养师	文档即将发布
39	view-admission-and-enrolment-queue-state 🔄	工作流	管理员、注册员、家长、校长	文档即将发布
40	explain-workflow-system 🔄	工作流	管理员、校长、开发者、顾问	文档即将发布

**较新的操作手册（29–40）**以完整英文内容的形式包含在 data/playbooks.json 中，并通过 openemis_get_playbook 加载。每份操作手册的 Markdown 文档及其 RU/ES/HI/AR 翻译将在后续版本中发布。

---

路线图

v0.4.0 — 浏览器身份验证（计划中）

目前，凭据需要由 OpenEMIS 管理员手动签发 api_key。v0.4.0 将新增可选的 openemis_browser_auth 工具，免去所有手动凭据配置：

1. 该工具会启动本地 Playwright 浏览器——无需预先提供目标 URL。
2. 用户导航到自己的 OpenEMIS 实例并正常登录。
3. Playwright 会监视所有网络流量。当它检测到 POST */api/v5/login 或 POST */api/v4/login 的响应时（两者都会返回相同的 JWT）：
   • 基础 URL 会自动从请求 URL 中提取（例如，https://dev-demo.openemis.org/core/api/v5/login → 基础 URL https://dev-demo.openemis.org/core）——无需预先配置 OPENEMIS_BASE_URL。
   • JWT 会从响应正文中提取。
4. 两者都会缓存在内存中，并用于后续所有 CRUD 调用。

这样就不再需要 OPENEMIS_BASE_URL、OPENEMIS_USERNAME、OPENEMIS_PASSWORD 和 OPENEMIS_API_KEY——用户只需打开浏览器并登录即可。它适用于任何 OpenEMIS 实例、任何域名和子域名，包括开发、预发布和生产环境，无需进行任何重新配置。

仍完全支持基于 .env 的凭据——现有配置不受影响。浏览器身份验证通过新工具选择启用。

v0.5.0 — 风险仪表板 ✅

view-student-risks 和 view-institution-risks——已发布。包括风险评分、按标准细分、福利案例、警报规则和发送日志。

v0.6.0 — 工作流路由 （机构专业版 + 国家专业版）

当前的写入工具（openemis_create、openemis_update、openemis_delete）一次只执行一项操作。工作流路由更进一步：MCP 会自动编排完整的多步骤操作手册，在各步骤间传递状态，并在每个阶段执行提交前验证。

新工具： openemis_run_workflow { playbook_id, params, dry_run? }——接受操作手册 ID 和结构化输入参数，按顺序执行所有步骤，并返回结构化运行日志。在试运行模式下，会报告将发生的变更，但不会写入任何内容。

工作流路由仅对高于个人专业版的套餐开放，因为机构或国家级规模的批量 AI 写入需要监督。教师标记 30 名学生需要快速处理；地区办公室在 20 所学校中为 500 名学生办理入学，则需要审计和审批。

功能	个人专业版	机构专业版	国家专业版
直接写入（单条记录）	✅	✅	✅
机构审计跟踪	—	✅	✅
工作流路由执行	—	✅	✅
机构管理员审批关卡	—	✅	✅
单个机构内的批量操作	—	✅	✅
跨多个机构的批量操作	—	—	✅
部委审批关卡	—	—	✅
跨机构监督仪表板	—	—	✅
部分失败时回滚	—	—	✅

---

方案

	免费版	个人专业版	机构专业版	国家专业版
适用范围	任何用户	一人	一所学校	部委 / 国家级
许可证	MIT	BSL 1.1	BSL 1.1	BSL 1.1
读取工具（全部 678 项资源，Core 5.13.0）	✅	✅	✅	✅
40 个精选操作手册（26 个读取 · 14 个写入/认证 · 28 个带翻译）	✅	✅	✅	✅
stdio 模式（Claude Code、Cursor、Cline）	✅	✅	✅	✅
HTTP 服务模式（Oracle / VPS 安装）	—	✅	✅	✅
OpenAPI 适配器（ChatGPT Custom GPT、任何 REST 客户端）	—	✅	✅	✅
直接写入 — 单条记录	—	✅	✅	✅
机构审计跟踪	—	—	✅	✅
工作流路由执行	—	—	✅	✅
机构管理员审批关卡	—	—	✅	✅
单个机构内批量操作	—	—	✅	✅
跨多个机构的批量操作	—	—	—	✅
部委审批关卡	—	—	—	✅
跨机构监督	—	—	—	✅
部分失败时回滚	—	—	—	✅

→ 价格与访问权限： [email protected]

---

许可证

MIT — © 2026 Khindol Madraimov

---

致谢

在人工指导下，由一支协同工作的 AI Agent 团队构建——完整团队名单请见 ACKNOWLEDGEMENTS.md：顾问 Arastu、元帅 Sunny、武士 Haiku、Xéphyrin Xirdal、Nemo 船长、Coddy (GPT-5)、Miniqwenco (Qwen 2.5 Coder 7B)、Miniqwen (Qwen 3.5 9B) 和 Gemmy (Gemma 4e4b)——他们分别负责架构、代码、分析和多语言翻译等工作。

---

与 OpenEMIS 或其维护者无关。这是一个第三方桥接工具，可调用公开的 Core API。凭据和数据均保留在你的机器上。