Metadata-Version: 2.5
Name: essencestudy-teacher-mcp
Version: 0.2.0
Summary: MCP server for running an EssenceStudy course from the terminal: assignments, documents, rubrics, enrolment, grading and usage
Project-URL: Homepage, https://study.essencescholar.com
Project-URL: Repository, https://github.com/EssenceScholar/EssenceScholar
Author-email: EssenceScholar <admin@essencescholar.com>
License: MIT
License-File: LICENSE
Keywords: agent,education,essencestudy,grading,llm,mcp,rubric,teaching
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Education
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]<2.0,>=1.3
Description-Content-Type: text/markdown

# EssenceStudy Teacher MCP

Run an EssenceStudy course from your terminal — create assignments, attach
documents, write rubrics, enrol students, read and grade submissions, publish
grades, and watch token spend — through any MCP client (Claude Code, Claude
Desktop, or your own agent).

## Install

```bash
uv pip install -e .          # from this directory
```

## Configure

No credentials in config files:

```json
{
  "mcpServers": {
    "essencestudy-teacher": {
      "command": "essencestudy-teacher-mcp"
    }
  }
}
```

The first time you use it, run **`authorize_terminal`**. It returns a link and a
short code straight away:

> **Open this link:** https://study.essencescholar.com/?device=XXXX-XXXX
> **Code:** `XXXX-XXXX`

Open the link in the browser where you are already signed in to EssenceStudy,
check the code matches, and press Approve. Then call **`finish_authorization`**
to collect the key — it is written to `~/.essencestudy/credentials` (mode 600)
and reused from then on.

Two steps rather than one on purpose: a single blocking call cannot show you the
code, because an MCP server's stdout is the protocol channel to the client, not
your screen.

Revoke it whenever you like — from your profile in the web app, or with
`revoke_terminal_access`. A revoked key stops working immediately.

**Optional environment**

- `ESSENCESTUDY_API_URL` — defaults to production. Point at
  `http://127.0.0.1:8004` for nightly; keys are stored per backend URL, so both
  can be authorised at once. Note nightly shares the production database, so
  writes there are real.
- `ESSENCESTUDY_API_KEY` — supply a key directly and skip the browser step.
  For CI, where nobody can click Approve.

## What you can say

- *"List my courses, then show me the assignments in Entrepreneurial Finance."*
- *"Create a draft assignment in course 6 called 'Variance analysis', restrict
  the canvas to retriever and agent, and attach ~/cases/board-pack.pdf."*
- *"Write a four-criterion rubric for assignment 34 weighted 30/30/25/15."*
- *"Enrol these twelve students and tell me which ones were newly created."*
- *"Who hasn't started assignment 34? Who is graded but not published?"*
- *"Publish all graded submissions for assignment 34."*
- *"What did assignment 34 cost, and which student used the most tokens?"*

## Two things worth knowing

**Draft vs published.** `create_assignment` makes a draft. `publish_assignment`
is the noisy step: it makes the assignment visible, warms its documents, and
emails every enrolled student. Keep them separate deliberately.

**Saved vs published grades.** `grade_submission` saves a grade; the student
sees nothing until `publish_grades` runs. That gap is the most common reason a
student reports their work was never marked — `list_submissions` shows
`"graded, NOT published"` precisely so you can spot it.
