{
  "markdown": "---\ntitle: openemis-mcp-pro — Read + Write MCP Server for OpenEMIS School Management\ndescription: openemis-mcp-pro is the read and write MCP server that bridges AI assistants to the OpenEMIS school management information system — 678 resources, 3361 endpoints, 40 playbooks.\nkeywords:\n  - OpenEMIS\n  - school management system\n  - education management\n  - student attendance\n  - student risks\n  - MCP server\n  - write tools\n---\n\n<p align=\"center\">\n  <img src=\"assets/logo.png\" alt=\"openemis-mcp-pro logo — read and write AI bridge for OpenEMIS school management\" width=\"320\">\n</p>\n\n# openemis-mcp-pro — Read + Write AI Bridge for OpenEMIS School Management\n\n**A natural-language bridge between MCP-aware agents (Claude, Codex, Cursor, etc.) and any OpenEMIS school — with full read + write access.**\n\n[**OpenEMIS**](https://www.openemis.org) is a free, open-source **school management information system** developed by UNESCO and KORDIT. It runs the day-to-day administration of every kind of educational institution — kindergartens, primary schools, secondary schools, secondary vocational institutions, technical colleges, and universities — managing students, staff, attendance, assessment, infrastructure, meals, scholarships, examinations, training, and ministry-level reporting. This MCP-pro server adds full read + write access plus per-user authentication on top of any OpenEMIS school.\n\n**Translations:** [Русский](docs/translations/README.ru.md) · [Español](docs/translations/README.es.md) · [हिन्दी](docs/translations/README.hi.md) · [العربية](docs/translations/README.ar.md)\n\nBuilt on top of the published **OpenEMIS Core API** (reference docs at [api.openemis.org/core](https://api.openemis.org/core)) and **verified end-to-end against the public demo at [demo.openemis.org/core](https://demo.openemis.org/core)** with real credentials, real data, real round-trips.\n\nAsk in English:\n\n> *\"How many current students are at Avory Primary?\"*\n\nThe agent plans the calls, this MCP delivers the data, and you get the answer:\n\n> *\"Avory Primary School (code P1002) has 553 currently enrolled students.\"*\n\nYou never write a line of code. You never see JSON. You just ask.\n\n> **Status:** v1.0.0 — **full CRUD** for non-workflow resources. Read queries work against every OpenEMIS v5 resource. Write tools (create/update/delete) are live for all resources that do not flow through the CakePHP Workflow plugin. Workflow-controlled resources (attendance, staff leave) are blocked at the tool level and redirect to the appropriate playbook.\n\n---\n\n## What this is\n\nopenemis-mcp-pro is the read + write MCP server that connects AI assistants to the OpenEMIS school management system. It exposes 678 resources (students, attendance, risks, staff, exams, infrastructure) across 40 curated playbooks — 26 read and 14 write/auth. The pro distribution adds direct write tools (`openemis_create`, `openemis_update`, `openemis_delete`), HTTP server mode for ChatGPT Custom GPT, and per-user authentication on top of the free read-only distribution.\n\n---\n\n## Why this exists\n\nThe OpenEMIS Core REST API is large — the v5 surface alone exposes **3,361 endpoints across 678 resources** (Core 5.13.0). No AI agent can hold that in context, and raw Swagger-style introspection floods a conversation with noise that has nothing to do with the user's actual question.\n\nThis MCP solves that in two ways:\n\n1. **Domain-scoped discovery.** Instead of dumping the whole API into the agent's context, the `openemis_discover(topic)` tool narrows to the ~20–30 endpoints relevant to what the user is actually asking about (\"attendance\", \"students\", \"assessment\") — powered by a small curated knowledge pack of `Domain-*.md` notes.\n2. **A single, composable getter.** One `openemis_get` tool covers list + singleton + filtered search across every resource. The agent supplies `resource` + optional `id` + optional `params` (`_fields`, `_conditions`, `orderby`, `page`, `limit`) and the rest of the OpenEMIS CakePHP-style query DSL maps straight through.\n\nThe net effect: agents answer natural-language questions in 2–4 tool calls, not 30.\n\n---\n\n## Tools\n\n| Tool | Since | What it does |\n|---|---|---|\n| `openemis_health` | v0.1 | Pings the configured instance and reports reachability. Performs a real login round-trip — if this passes, CRUD will work. |\n| `openemis_list_domains` | v0.1 | Lists the curated OpenEMIS domains — Attendance, Assessment, Staff, Student, Institution, Schedule, Examination, Report — each with a one-line summary. The agent uses this to figure out *where* a question lives. |\n| `openemis_discover` | v0.1 | Input: a topic string. Output: up to 30 endpoints relevant to that topic, drawn from the domain knowledge pack and the per-instance manifest. Keeps conversations small regardless of how large the underlying API is. |\n| `openemis_list_playbooks` | v0.2 | Lists all 40 curated workflow playbooks with id, title, domain, and audience. The agent uses this to find the right step-by-step guide for a user-level task. |\n| `openemis_get_playbook` | v0.2 | Input: a playbook id. Output: the full playbook — resources, ordered steps, guidance notes, and example queries. |\n| `openemis_get` | v0.1 | Unified read tool. `{ resource, id?, params? }` — if `id` is present, fetches the singleton; otherwise lists with any combination of `_fields`, `_conditions`, `orderby`, `order`, `page`, `limit`, plus any ad-hoc filter key. |\n| `openemis_create` | v0.3.0 | Create a new record. `{ resource, body }` — non-workflow resources only. Workflow-controlled resources (e.g. institution-staff-leave) are blocked and will redirect to the appropriate playbook. |\n| `openemis_update` | v0.3.0 | Update an existing record by id. `{ resource, id, body }` — non-workflow resources only. |\n| `openemis_delete` | v0.3.0 | Delete a record by id. `{ resource, id }` — non-workflow resources only. |\n\nA representative natural-language question like *\"how many teachers at Avory Primary, how many vacant positions?\"* resolves to three `openemis_get` calls — chained by the agent, narrowed by `_conditions`, delivered back as a single English answer. A write request like *\"enrol a new student\"* uses `openemis_get_playbook` to load the step-by-step guide, then `openemis_create` for each write step.\n\n---\n\n## Core compatibility\n\nTested against **OpenEMIS Core 5.13.0** (master, June 2026). Earlier 5.7 – 5.12 deployments are also supported — the API surface is backwards-compatible.\n\n### Capability flag — POCOR-9660 multi-id GET\n\n`openemis_get` accepts `params.ids = \"1,2,3\"` for batch lookups. Core 5.10+ carries POCOR-9660 (`?id=1,2,3` and `_conditions=<field>:IN(...)` support in `CrudApiController`), so the handler collapses the batch into a single round-trip **by default**. Pointing at an older Core (5.7 – 5.9) without the native operator? Force the legacy parallel fan-out:\n\n```bash\nOPENEMIS_CORE_IN_OPERATOR=off\n```\n\nFor composite-PK or view resources — where `ids` does not apply — use `_conditions=<field>:IN(1,2,3)` instead; it filters any field by a value list and works regardless of this flag. Filtering on a field that does not exist on a resource now returns HTTP 400 (Core 5.10+, POCOR-9697), so use exact field names.\n\n## Verified against demo.openemis.org\n\nEvery claim in this README was proven against the public demo instance before being written:\n\n- `POST /api/v5/login` with `{ username, password, api_key }` → JWT cached, 331 chars\n- `GET /api/v5/institutions?limit=200&_fields=id,name,code` → 24 institutions incl. `\"Avory Primary School\" (id=6, code P1002)`\n- `GET /api/v5/institution-students?institution_id=6&student_status_id=1&limit=1` → pagination reports `last_page: 553` → **553 currently enrolled students**\n- `GET /api/v5/academic-periods` → 7 pages of real academic-year data\n- `GET /api/v5/absence-types` → `EXCUSED`, `UNEXCUSED`, `LATE`, etc.\n\nThe sample `scripts/smoke-login.mjs` shipped with this repo performs the login test step-by-step so you can confirm reachability against your own instance before wiring it into Claude Code.\n\n---\n\n## Compatible agents\n\nopenemis-mcp speaks the **Model Context Protocol** over stdio — any MCP-compatible client works:\n\n**Stdio mode (local machine)** — connects as a subprocess:\n\n| Agent | How to connect |\n|---|---|\n| **Claude Code** (`claude` CLI) | `claude mcp add` — primary tested client, all 9 tools available |\n| **Cursor** | Add to `.cursor/mcp.json` — full tool access |\n| **Cline / Continue** (VS Code) | Add server in MCP settings |\n| **Codex** | Via [gemmy-and-qwenny](https://github.com/tixuz/gemmy-and-qwenny) bridge |\n| **Any MCP client** | Point at `node dist/server.js` with env vars set |\n\n**HTTP server mode** (`OPENEMIS_TRANSPORT=http`, install once on Oracle/VPS) — connects by URL:\n\n| Client | How to connect |\n|---|---|\n| **Claude Code** (remote) | `claude mcp add --transport http --url http://your-server:3000/mcp --header \"Authorization: Bearer <token>\"` |\n| **Cursor / Cline** | Add remote MCP URL in settings |\n| **ChatGPT** (Custom GPT) | Import schema from `http://your-server:3000/openapi.json` → Actions → Bearer token |\n| **Any HTTP client** | REST API at `/api/*` — see [Teacher Guide](docs/CHATGPT-TEACHER-GUIDE.md) |\n\n---\n\n## Install\n\nRequires **Node 22+** (for built-in `fetch` and `AbortController`) and **Python 3.10+** (for the manifest builder and playbook generator scripts in `mcp-openemis-gen/`). The MCP server itself is Node-only; Python is only needed if you rebuild the manifest from source.\n\n### From GitHub\n\n```bash\ngit clone https://github.com/tixuz/openemis-mcp.git\ncd openemis-mcp\n\nnpm install\nnpm run build\n\ncp .env.example .env\n$EDITOR .env\n```\n\n### Configure\n\n`.env.example` documents every variable. At minimum you need the three credentials your OpenEMIS admin issues:\n\n```env\nOPENEMIS_BASE_URL=https://demo.openemis.org/core   # or your own instance\nOPENEMIS_USERNAME=admin\nOPENEMIS_PASSWORD=your_password\nOPENEMIS_API_KEY=your_api_key\n\n# Optional\nOPENEMIS_TIMEOUT_MS=30000\nOPENEMIS_VAULT_PATH=/absolute/path/to/domain-notes\nOPENEMIS_MANIFEST_PATH=/absolute/path/to/manifest.jsonl\n```\n\nThe server logs in lazily on the first authenticated tool call, POSTing to `/api/v5/login`, parsing the JWT out of `data.token`, and caching it in memory. On a 401 it re-logs in and retries once.\n\n`OPENEMIS_VAULT_PATH` points at the folder containing the curated `Domain-*.md` notes used by `openemis_discover`. If missing, discovery degrades gracefully to keyword matching against the manifest alone.\n\n`OPENEMIS_MANIFEST_PATH` points at the JSONL output of the companion builder in `../mcp-openemis-gen/`. If absent, the discovery tools return a friendly \"manifest not built yet\" hint — they don't crash.\n\n### Smoke-test reachability\n\n```bash\nset -a && source .env && set +a\nnode scripts/smoke-login.mjs\n```\n\nExpected:\n\n```\n[Test] Loading config...\n[OK] Config loaded: baseUrl=https://demo.openemis.org/core\n[Test] Creating client...\n[OK] Client created\n[Test] Attempting login...\n[OpenEMIS] Login successful; cached JWT (331 chars)\n[OK] Login successful\n```\n\n### Register with Claude Code\n\n```bash\nclaude mcp add openemis \\\n  --env OPENEMIS_BASE_URL=\"https://your-openemis/core\" \\\n  --env OPENEMIS_USERNAME=\"…\" \\\n  --env OPENEMIS_PASSWORD=\"…\" \\\n  --env OPENEMIS_API_KEY=\"…\" \\\n  --env OPENEMIS_VAULT_PATH=\"/absolute/path/to/vault\" \\\n  -- node \"$(pwd)/dist/server.js\"\n\n# Verify\nclaude mcp list | grep openemis\n# Expected: openemis: node /…/dist/server.js - ✓ Connected\n```\n\nAny new Claude Code session in this project will see all nine tools automatically.\n\n---\n\n### Server mode (Oracle Always Free / any VPS)\n\nSet `OPENEMIS_TRANSPORT=http` to run as a persistent HTTP server instead of a local subprocess. Install once on your server; every MCP-compatible client (Claude Code, Cursor, Cline, Windsurf) connects by URL.\n\n**On your server:**\n\n```bash\ngit clone https://github.com/tixuz/openemis-mcp-pro.git\ncd openemis-mcp-pro\nnpm install && npm run build\ncp .env.example .env\n$EDITOR .env          # set credentials + OPENEMIS_TRANSPORT=http + OPENEMIS_AUTH_TOKEN\nnode dist/server.js\n```\n\n**.env for server mode:**\n\n```env\nOPENEMIS_BASE_URL=https://your-openemis/core\nOPENEMIS_USERNAME=admin\nOPENEMIS_PASSWORD=your_password\nOPENEMIS_API_KEY=your_api_key\n\nOPENEMIS_TRANSPORT=http\nOPENEMIS_PORT=3000\n\n# Generate: node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"\nOPENEMIS_AUTH_TOKEN=your-secret-token-here\n```\n\n**Connect from Claude Code (remote):**\n\n```bash\nclaude mcp add openemis-remote \\\n  --transport http \\\n  --url \"http://your-server:3000/mcp\" \\\n  --header \"Authorization: Bearer your-secret-token-here\"\n```\n\n**Health probe** (monitoring / uptime checks):\n\n```bash\ncurl http://your-server:3000/health\n# {\"ok\":true,\"transport\":\"http\",\"baseUrl\":\"https://your-openemis/core\"}\n```\n\n> ⚠️ **Always set `OPENEMIS_AUTH_TOKEN`** before exposing the port publicly. Without it the endpoint is open to anyone who can reach your IP.\n\n---\n\n## Architecture\n\n```\n┌────────────────────────┐\n│  Agent (Claude / …)    │     \"How many current students at Avory?\"\n└───────────┬────────────┘\n            │ MCP stdio (JSON-RPC)\n┌───────────▼────────────┐\n│  openemis-mcp          │  ← nine typed tools, ZodRawShape schemas\n│  • openemis_health     │\n│  • openemis_list_dom…  │  ← reads Domain-*.md from vault\n│  • openemis_discover   │  ← topic → ≤30 scoped endpoints\n│  • openemis_list_play… │  ← list all 40 workflow playbooks\n│  • openemis_get_playbk │  ← load a playbook by id\n│  • openemis_get / _create / _update / _delete   │\n└───────────┬────────────┘\n            │ HTTPS + Bearer JWT (cached, auto-refresh on 401)\n┌───────────▼────────────┐\n│  OpenEMIS Core API     │  api.openemis.org/core  (reference)\n│  /api/v5/{resource}    │  demo.openemis.org/core (tested)\n└────────────────────────┘\n```\n\nDesign principles, from the first line of code:\n\n1. **Domain-scoped, never firehose.** The manifest can grow to thousands of endpoints; the agent's context is not going to. `openemis_discover(topic)` is the funnel — every conversation only ever sees the slice it needs.\n2. **Write tools in v0.3.0.** `openemis_create` / `openemis_update` / `openemis_delete` are live for all non-workflow resources. Workflow-controlled resources (attendance, staff-attendance) are blocked at the tool level and redirect to the appropriate playbook.\n3. **Stateless between calls.** Only the JWT is cached in memory. No disk persistence, no analytics, nothing phones home.\n4. **Thin over the real API.** This bridge doesn't invent new concepts — `resource` names are kebab-case v5 paths, query params are the native `_conditions` / `_fields` DSL. What you'd write in curl translates 1:1.\n\n---\n\n## Documentation\n\n- [Resource Reference](docs/resources.md) — all 678 resources with HTTP method availability and write status (Core 5.13.0)\n- [Playbooks](docs/playbooks/) — 40 curated workflow guides (26 read · 14 write/auth)\n- [ChatGPT Teacher Guide](docs/CHATGPT-TEACHER-GUIDE.md) — how to let teachers mark attendance via ChatGPT Custom GPT\n- [Playbook Authoring Routine](docs/PLAYBOOK-ROUTINE.md) — 4-step process for adding new playbooks\n- [Glossary](docs/GLOSSARY.md) — definitions of key OpenEMIS and education management terms\n- [FAQ](docs/FAQ.md) — frequently asked questions about OpenEMIS and this MCP server\n\n### Playbooks\n\n| # | Playbook | Domain | Audience | Translations |\n|---|---|---|---|---|\n| 1 | [Count Vacant Positions](docs/playbooks/count-vacant-positions.md) | Staff | admin, hr | [RU](docs/playbooks/count-vacant-positions.ru.md) · [ES](docs/playbooks/count-vacant-positions.es.md) · [HI](docs/playbooks/count-vacant-positions.hi.md) · [AR](docs/playbooks/count-vacant-positions.ar.md) |\n| 2 | [Mark Student Attendance](docs/playbooks/mark-student-attendance.md) | Attendance | teacher, admin | [RU](docs/playbooks/mark-student-attendance.ru.md) · [ES](docs/playbooks/mark-student-attendance.es.md) · [HI](docs/playbooks/mark-student-attendance.hi.md) · [AR](docs/playbooks/mark-student-attendance.ar.md) |\n| 3 | [Mark Staff Attendance](docs/playbooks/mark-staff-attendance.md) | Staff | admin, hr, teacher | [RU](docs/playbooks/mark-staff-attendance.ru.md) · [ES](docs/playbooks/mark-staff-attendance.es.md) · [HI](docs/playbooks/mark-staff-attendance.hi.md) · [AR](docs/playbooks/mark-staff-attendance.ar.md) |\n| 4 | [View Student Timetable](docs/playbooks/view-student-timetable.md) | Schedule | parent, student | [RU](docs/playbooks/view-student-timetable.ru.md) · [ES](docs/playbooks/view-student-timetable.es.md) · [HI](docs/playbooks/view-student-timetable.hi.md) · [AR](docs/playbooks/view-student-timetable.ar.md) |\n| 5 | [Student Dashboard](docs/playbooks/student-dashboard.md) | Student | parent, student | [RU](docs/playbooks/student-dashboard.ru.md) · [ES](docs/playbooks/student-dashboard.es.md) · [HI](docs/playbooks/student-dashboard.hi.md) · [AR](docs/playbooks/student-dashboard.ar.md) |\n| 6 | [Generate Student Report Card PDF](docs/playbooks/generate-student-report-card-pdf.md) | Report | teacher, admin | [RU](docs/playbooks/generate-student-report-card-pdf.ru.md) · [ES](docs/playbooks/generate-student-report-card-pdf.es.md) · [HI](docs/playbooks/generate-student-report-card-pdf.hi.md) · [AR](docs/playbooks/generate-student-report-card-pdf.ar.md) |\n| 7 | [Enrol a New Student](docs/playbooks/enroll-new-student.md) | Student | admin, registrar | [RU](docs/playbooks/enroll-new-student.ru.md) · [ES](docs/playbooks/enroll-new-student.es.md) · [HI](docs/playbooks/enroll-new-student.hi.md) · [AR](docs/playbooks/enroll-new-student.ar.md) |\n| 8 | [Record a Behaviour Incident](docs/playbooks/record-behavior-incident.md) | Student | teacher, admin | [RU](docs/playbooks/record-behavior-incident.ru.md) · [ES](docs/playbooks/record-behavior-incident.es.md) · [HI](docs/playbooks/record-behavior-incident.hi.md) · [AR](docs/playbooks/record-behavior-incident.ar.md) |\n| 9 | [Submit Exam Marks](docs/playbooks/submit-exam-marks.md) | Assessment | teacher | [RU](docs/playbooks/submit-exam-marks.ru.md) · [ES](docs/playbooks/submit-exam-marks.es.md) · [HI](docs/playbooks/submit-exam-marks.hi.md) · [AR](docs/playbooks/submit-exam-marks.ar.md) |\n| 10 | [Institution Summary](docs/playbooks/institution-summary.md) | Institution | admin, parent | [RU](docs/playbooks/institution-summary.ru.md) · [ES](docs/playbooks/institution-summary.es.md) · [HI](docs/playbooks/institution-summary.hi.md) · [AR](docs/playbooks/institution-summary.ar.md) |\n| 11 | [Generate Institution Statistics PDF](docs/playbooks/generate-institution-statistics-pdf.md) | Report | admin | [RU](docs/playbooks/generate-institution-statistics-pdf.ru.md) · [ES](docs/playbooks/generate-institution-statistics-pdf.es.md) · [HI](docs/playbooks/generate-institution-statistics-pdf.hi.md) · [AR](docs/playbooks/generate-institution-statistics-pdf.ar.md) |\n| 12 | [View Latest Attendance](docs/playbooks/view-latest-attendance.md) | Attendance | teacher, admin, parent | [RU](docs/playbooks/view-latest-attendance.ru.md) · [ES](docs/playbooks/view-latest-attendance.es.md) · [HI](docs/playbooks/view-latest-attendance.hi.md) · [AR](docs/playbooks/view-latest-attendance.ar.md) |\n| 13 | [View Student Profile](docs/playbooks/view-student-profile.md) | Student | teacher, admin | [RU](docs/playbooks/view-student-profile.ru.md) · [ES](docs/playbooks/view-student-profile.es.md) · [HI](docs/playbooks/view-student-profile.hi.md) · [AR](docs/playbooks/view-student-profile.ar.md) |\n| 14 | [View Student Marks](docs/playbooks/view-student-marks.md) | Assessment | teacher, admin, parent | [RU](docs/playbooks/view-student-marks.ru.md) · [ES](docs/playbooks/view-student-marks.es.md) · [HI](docs/playbooks/view-student-marks.hi.md) · [AR](docs/playbooks/view-student-marks.ar.md) |\n| 15 | [View Class Report](docs/playbooks/view-class-report.md) | Report | teacher, admin | [RU](docs/playbooks/view-class-report.ru.md) · [ES](docs/playbooks/view-class-report.es.md) · [HI](docs/playbooks/view-class-report.hi.md) · [AR](docs/playbooks/view-class-report.ar.md) |\n| 16 | [View Timetable](docs/playbooks/view-timetable.md) | Schedule | teacher, admin, student | [RU](docs/playbooks/view-timetable.ru.md) · [ES](docs/playbooks/view-timetable.es.md) · [HI](docs/playbooks/view-timetable.hi.md) · [AR](docs/playbooks/view-timetable.ar.md) |\n| 17 | [View Full Institution Profile](docs/playbooks/view-institution-profile.md) | Institution | admin, parent, public | [RU](docs/playbooks/view-institution-profile.ru.md) · [ES](docs/playbooks/view-institution-profile.es.md) · [HI](docs/playbooks/view-institution-profile.hi.md) · [AR](docs/playbooks/view-institution-profile.ar.md) |\n| 18 | [View Full Class Profile](docs/playbooks/view-class-profile.md) | Student | teacher, admin | [RU](docs/playbooks/view-class-profile.ru.md) · [ES](docs/playbooks/view-class-profile.es.md) · [HI](docs/playbooks/view-class-profile.hi.md) · [AR](docs/playbooks/view-class-profile.ar.md) |\n| 19 | [View a Staff Member's Full Profile](docs/playbooks/view-staff-profile.md) | Staff | admin, hr | [RU](docs/playbooks/view-staff-profile.ru.md) · [ES](docs/playbooks/view-staff-profile.es.md) · [HI](docs/playbooks/view-staff-profile.hi.md) · [AR](docs/playbooks/view-staff-profile.ar.md) |\n| 20 | [Enhance Student Profile](docs/playbooks/enhance-student-profile.md) | Student | teacher, admin, counsellor | [RU](docs/playbooks/enhance-student-profile.ru.md) · [ES](docs/playbooks/enhance-student-profile.es.md) · [HI](docs/playbooks/enhance-student-profile.hi.md) · [AR](docs/playbooks/enhance-student-profile.ar.md) |\n| 21 | [View Institution Infrastructure](docs/playbooks/view-institution-infrastructure.md) | Institution | admin, facilities | [RU](docs/playbooks/view-institution-infrastructure.ru.md) · [ES](docs/playbooks/view-institution-infrastructure.es.md) · [HI](docs/playbooks/view-institution-infrastructure.hi.md) · [AR](docs/playbooks/view-institution-infrastructure.ar.md) |\n| 22 | [View Institution Meals](docs/playbooks/view-institution-meals.md) | Institution | admin, nutritionist, parent | [RU](docs/playbooks/view-institution-meals.ru.md) · [ES](docs/playbooks/view-institution-meals.es.md) · [HI](docs/playbooks/view-institution-meals.hi.md) · [AR](docs/playbooks/view-institution-meals.ar.md) |\n| 23 | [View Student Risk Profile](docs/playbooks/view-student-risks.md) | Student | admin, counsellor, teacher | [RU](docs/playbooks/view-student-risks.ru.md) · [ES](docs/playbooks/view-student-risks.es.md) · [HI](docs/playbooks/view-student-risks.hi.md) · [AR](docs/playbooks/view-student-risks.ar.md) |\n| 24 | [View Institution Risk Summary](docs/playbooks/view-institution-risks.md) | Institution | admin, ministry | [RU](docs/playbooks/view-institution-risks.ru.md) · [ES](docs/playbooks/view-institution-risks.es.md) · [HI](docs/playbooks/view-institution-risks.hi.md) · [AR](docs/playbooks/view-institution-risks.ar.md) |\n| 25 | [Add Equipment or Assets ✏️](docs/playbooks/add-institution-asset.md) | Infrastructure | admin, accountant, facilities | [RU](docs/playbooks/add-institution-asset.ru.md) · [ES](docs/playbooks/add-institution-asset.es.md) · [HI](docs/playbooks/add-institution-asset.hi.md) · [AR](docs/playbooks/add-institution-asset.ar.md) |\n| 26 | [Record an Infrastructure Repair ✏️](docs/playbooks/record-infrastructure-repair.md) | Infrastructure | admin, accountant, facilities | [RU](docs/playbooks/record-infrastructure-repair.ru.md) · [ES](docs/playbooks/record-infrastructure-repair.es.md) · [HI](docs/playbooks/record-infrastructure-repair.hi.md) · [AR](docs/playbooks/record-infrastructure-repair.ar.md) |\n| 27 | [Add a New Meal Programme ✏️](docs/playbooks/add-meal-programme.md) | Meals | admin, accountant, nutritionist | [RU](docs/playbooks/add-meal-programme.ru.md) · [ES](docs/playbooks/add-meal-programme.es.md) · [HI](docs/playbooks/add-meal-programme.hi.md) · [AR](docs/playbooks/add-meal-programme.ar.md) |\n| 28 | [Resolve My Identity (per-user auth) 🔐](docs/playbooks/resolve-my-identity.md) | Auth | teacher, admin, staff | [RU](docs/playbooks/resolve-my-identity.ru.md) · [ES](docs/playbooks/resolve-my-identity.es.md) · [HI](docs/playbooks/resolve-my-identity.hi.md) · [AR](docs/playbooks/resolve-my-identity.ar.md) |\n| 29 | `diagnose-alert-delivery` (POCOR-9509) | Alerts | admin, ministry | _docs follow_ |\n| 30 | `view-school-accreditation` (POCOR-9610) | Institution | admin, ministry, principal | _docs follow_ |\n| 31 | `view-school-registration` (POCOR-9610) | Institution | admin, ministry, principal | _docs follow_ |\n| 32 | `view-institution-budget` (Core 5.10.0) | Institution | admin, finance | _docs follow_ |\n| 33 | `query-student-absence-history` (Core 5.10.0) | Attendance | teacher, admin, parent, counsellor | _docs follow_ |\n| 34 | `query-user-activity-audit-log` (POCOR-9697) | Security | admin, security, ministry | _docs follow_ |\n| 35 | `view-class-roster` (Core 5.10.0) | Institution | teacher, admin, homeroom | _docs follow_ |\n| 36 | `set-school-accreditation` ✏️ (POCOR-9610) | Institution | admin, ministry | _docs follow_ |\n| 37 | `set-school-registration` ✏️ (POCOR-9610) | Institution | admin, ministry | _docs follow_ |\n| 38 | `mark-student-meal-participation` ✏️ | Meals | teacher, admin, nutritionist | _docs follow_ |\n| 39 | `view-admission-and-enrolment-queue-state` 🔄 | Workflow | admin, registrar, parent, principal | _docs follow_ |\n| 40 | `explain-workflow-system` 🔄 | Workflow | admin, principal, developer, consultant | _docs follow_ |\n\n> **Newer playbooks (29–40)** ship as full English content in `data/playbooks.json` and are loaded via `openemis_get_playbook`. Per-playbook markdown docs and RU/ES/HI/AR translations land in a follow-up release.\n---\n\n## Roadmap\n\n### v0.4.0 — Browser Auth (planned)\n\nToday, credentials require a manually-issued `api_key` from the OpenEMIS admin. v0.4.0 will add an optional `openemis_browser_auth` tool that eliminates all manual credential configuration:\n\n1. The tool launches a local Playwright browser — **no target URL required upfront**.\n2. The user navigates to their OpenEMIS instance and logs in normally.\n3. Playwright watches all network traffic. When it sees a response to **`POST */api/v5/login`** or **`POST */api/v4/login`** (both return identical JWTs):\n   - The **base URL** is extracted from the request URL automatically (e.g. `https://dev-demo.openemis.org/core/api/v5/login` → base `https://dev-demo.openemis.org/core`) — no need to pre-configure `OPENEMIS_BASE_URL`.\n   - The **JWT** is extracted from the response body.\n4. Both are cached in memory and used for all subsequent CRUD calls.\n\nThis removes `OPENEMIS_BASE_URL`, `OPENEMIS_USERNAME`, `OPENEMIS_PASSWORD`, and `OPENEMIS_API_KEY` as requirements — the user just opens a browser and logs in. Works with any OpenEMIS instance, any domain, any subdomain, including dev, staging, and production environments without any reconfiguration.\n\n**`.env`-based credentials remain fully supported** — existing setups are unchanged. Browser auth is opt-in via the new tool.\n\n### v0.5.0 — Risk Dashboards ✅\n\n`view-student-risks` and `view-institution-risks` — shipped. Risk scores, per-criterion breakdown, welfare cases, alert rules, and delivery logs.\n\n### v0.6.0 — Workflow Routes *(Institution Pro + Country Pro)*\n\nCurrent write tools (`openemis_create`, `openemis_update`, `openemis_delete`) execute one operation at a time. Workflow routes take this further: the MCP **orchestrates a complete multi-step playbook automatically**, carrying state from step to step and enforcing pre-commit validation at each stage.\n\n**New tool:** `openemis_run_workflow { playbook_id, params, dry_run? }` — accepts a playbook ID and structured input parameters, executes all steps in sequence, returns a structured run log. In dry-run mode, reports what would change without writing anything.\n\nWorkflow routes are gated above Individual Pro because bulk AI writes at institution or national scale need oversight. A teacher marking 30 students needs speed; a district office enrolling 500 students across 20 schools needs audit and approval.\n\n| Feature | Individual Pro | Institution Pro | Country Pro |\n|---|---|---|---|\n| Direct write (single record) | ✅ | ✅ | ✅ |\n| Institution audit trail | — | ✅ | ✅ |\n| Workflow route execution | — | ✅ | ✅ |\n| Institution-admin approval gate | — | ✅ | ✅ |\n| Batch ops within one institution | — | ✅ | ✅ |\n| Multi-institution batch ops | — | — | ✅ |\n| Ministry approval gates | — | — | ✅ |\n| Cross-institution oversight dashboard | — | — | ✅ |\n| Roll-back on partial failure | — | — | ✅ |\n\n---\n\n## Plans\n\n| | **Free** | **Individual Pro** | **Institution Pro** | **Country Pro** |\n|---|---|---|---|---|\n| **Scope** | Any user | One person | One school | Ministry / national |\n| **Licence** | MIT | BSL 1.1 | BSL 1.1 | BSL 1.1 |\n| Read tools (all 678 resources, Core 5.13.0) | ✅ | ✅ | ✅ | ✅ |\n| 40 curated playbooks (26 read · 14 write/auth · 28 with translations) | ✅ | ✅ | ✅ | ✅ |\n| stdio mode (Claude Code, Cursor, Cline) | ✅ | ✅ | ✅ | ✅ |\n| **HTTP server mode** (Oracle / VPS install) | — | ✅ | ✅ | ✅ |\n| **OpenAPI adapter** (ChatGPT Custom GPT, any REST client) | — | ✅ | ✅ | ✅ |\n| Direct write — single record | — | ✅ | ✅ | ✅ |\n| Institution audit trail | — | — | ✅ | ✅ |\n| Workflow route execution | — | — | ✅ | ✅ |\n| Institution-admin approval gate | — | — | ✅ | ✅ |\n| Batch ops within one institution | — | — | ✅ | ✅ |\n| Multi-institution batch ops | — | — | — | ✅ |\n| Ministry approval gates | — | — | — | ✅ |\n| Cross-institution oversight | — | — | — | ✅ |\n| Roll-back on partial failure | — | — | — | ✅ |\n\n→ **Pricing and access:** khindol.madraimov@gmail.com\n\n---\n\n## License\n\n[MIT](LICENSE.md) — © 2026 Khindol Madraimov\n\n---\n\n## Acknowledgements\n\nBuilt by a coordinated team of AI agents under human direction — see [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md) for the full team: Adviser Arastu, Marshal Sunny, Samurai Haiku, Xéphyrin Xirdal, Captain Nemo, Coddy (GPT-5), Miniqwenco (Qwen 2.5 Coder 7B), Miniqwen (Qwen 3.5 9B), and Gemmy (Gemma 4e4b) — each with distinct roles across architecture, code, analysis, and multilingual translation.\n\n---\n\n*Not affiliated with OpenEMIS or its maintainers. This is a third-party bridge that speaks the public Core API. Credentials and data stay on your machine.*\n",
  "bytes": 30320,
  "sha": "249fadbdba422110e0c240bd5b91bb2b6db2b212b788d560631001d3ba6fc2b3",
  "repo_slug": "tixuz/openemis-mcp-pro",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tixuz_openemis_pro_ed02e8e9/readme"
}