Content
# populi-mcp
MCP (Model Context Protocol) server for the [Populi LMS](https://www.populiweb.com/) API. Exposes tools for people, course offerings, enrollments, academic terms, assignments (including tests), lessons, course meetings, and grades.
For how these pieces fit together conceptually, see **[populi.md](./populi.md)** (Populi domain model / ontology).
## Jupyter Book (optional)
A minimal **[Jupyter Book](https://jupyterbook.org/)** lives under **`book/`** (Markdown + `_config.yml`). **Dev Containers:** reopen the repo in the container (`.devcontainer/`); on create it installs Python deps and runs **`jupyter-book build book`**.
Serve the built site (port **8000** is forwarded in the devcontainer):
```bash
npm run book:serve
# or: python -m http.server 8000 --directory book/_build/html
```
Then open the forwarded port in the browser. Rebuild after edits: **`jupyter-book build book`** or **`npm run book:build`**.
## Setup
1. **Environment variables**:
- `POPULI_BASE_URL` — Your Populi instance URL (e.g. `https://yourschool.populiweb.com`) — required for Populi tools
- `POPULI_API_KEY` — API key from Populi (Account & Settings → API → Keys) — required for Populi tools
- `GITHUB_TOKEN` — GitHub token with `admin:org` scope — required for Classroom tools
2. **Install and build**:
```bash
npm install
npm run build
```
## Usage
### Run locally
```bash
POPULI_BASE_URL=https://yourschool.populiweb.com POPULI_API_KEY=sk_xxx npm start
```
### Cursor MCP
Add to `.cursor/mcp.json` (project or user):
```json
{
"mcpServers": {
"populi": {
"command": "node",
"args": ["/path/to/populi-mcp/dist/index.js"],
"env": {
"POPULI_BASE_URL": "https://yourschool.populiweb.com",
"POPULI_API_KEY": "sk_your_api_key"
}
}
}
}
```
Or use `npx`:
```json
{
"mcpServers": {
"populi": {
"command": "npx",
"args": ["-y", "populi-mcp"],
"env": {
"POPULI_BASE_URL": "https://yourschool.populiweb.com",
"POPULI_API_KEY": "sk_your_api_key"
}
}
}
}
```
## Tools
### Populi
| Tool | Description |
|------|-------------|
| `populi_list_academic_terms` | List academic terms |
| `populi_get_person` | Get a person by ID |
| `populi_list_people` | List/search people |
| `populi_get_course_offering` | Get a course offering by ID |
| `populi_list_course_offerings` | List course offerings for an academic term |
| `populi_list_catalog_courses` | List catalog courses (definitions) |
| `populi_get_catalog_course` | Get one catalog course by ID |
| `populi_create_course_offering` | Create an offering in a term (`fields` per [Populi API](https://populi.co/api/)) |
| `populi_list_enrollments` | List enrollments (roster) for a course in a term |
#### Assignments, lessons, meetings, grades
| Tool | Description |
|------|-------------|
| `populi_list_assignment_groups` | List assignment groups (grade categories) |
| `populi_create_assignment_group` | Create an assignment group (`fields` per [API](https://populi.co/api/)) |
| `populi_list_assignments` | List assignments (tests, essays, uploads, etc.) |
| `populi_get_assignment` | Get one assignment; optional `expand` |
| `populi_create_assignment` | Create assignment (`fields`: e.g. `name`, `type`) |
| `populi_update_assignment` | Update assignment (`fields` PUT body) |
| `populi_list_assignment_submissions` | List submissions for an assignment |
| `populi_get_assignment_submission` | Get a student’s submission |
| `populi_list_assignment_test_instances` | List test attempts for a test assignment |
| `populi_get_assignment_test_instance` | Get one student’s test attempt |
| `populi_get_assignment_grade` | Get assignment grade for a student |
| `populi_update_assignment_grade` | Set assignment grade for a student |
| `populi_get_assignment_rubric_scores` | Get rubric scores for a student on an assignment |
| `populi_list_lessons` | List lessons (content modules) |
| `populi_get_lesson` | Get a lesson; optional `expand` |
| `populi_list_lesson_pages` | List pages in a lesson |
| `populi_get_lesson_page` | Get one lesson page |
| `populi_list_course_meetings` | List class sessions / meetings |
| `populi_get_course_meeting` | Get one meeting |
| `populi_list_course_offering_students` | Roster with enrollment IDs |
| `populi_get_course_offering_student` | One enrollment (student in course) |
| `populi_update_enrollment_final_grade` | Set final course grade |
| `populi_get_course_offering_calendar` | Course calendar |
### GitHub Classroom linking
| Tool | Description |
|------|-------------|
| `populi_export_roster_for_classroom` | Export Populi roster as CSV/JSON for GitHub Classroom manual roster import |
| `classroom_list_classrooms` | List GitHub Classroom classrooms |
| `classroom_list_assignments` | List assignments for a classroom |
| `classroom_get_assignment` | Get assignment details (invite link, etc.) |
| `classroom_list_accepted_assignments` | List accepted assignments (student repos) |
| `classroom_get_grades` | Get grades with roster_identifier ↔ github_username mapping |
| `populi_github_invite_roster_to_org` | Invite everyone on the Populi roster to a **GitHub org** by **email** (after resolving each person’s email). Optional `dry_run`. |
| `populi_github_match_classroom_roster` | Report: Populi roster vs **GitHub Classroom** grade rows (matched / missing on each side by roster identifier). |
**GitHub tools** need `GITHUB_TOKEN` with **`admin:org`** (org invites + Classroom). **`populi_github_invite_roster_to_org`** with **`dry_run: true`** only calls Populi (no token). Use **`populi_export_roster_for_classroom`** + the same identifier field as GitHub Classroom’s roster, then **`populi_github_match_classroom_roster`** to verify linkage before grading sync.
## Populi API
- [API Reference](https://populi.co/api/)
- Rate limits: 50 req/min (3AM–7PM PST), 100 req/min otherwise
