Metadata-Version: 2.5
Name: essencestudy-teacher-mcp
Version: 0.5.0
Summary: MCP server for running an EssenceStudy course from the terminal: Draft with AI, assignments, documents, real data, 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.30
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

Published on PyPI — nothing to clone. With `uv` installed, `uvx` runs it directly:

```bash
# Claude Code:
claude mcp add essencestudy-teacher -- uvx essencestudy-teacher-mcp
```

## Configure

Claude Desktop / any MCP client (no credentials in config files):

```json
{
  "mcpServers": {
    "essencestudy-teacher": {
      "command": "uvx",
      "args": ["essencestudy-teacher-mcp"]
    }
  }
}
```

You need a **teacher account** on EssenceStudy — students cannot approve a
terminal key.

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."*
- *"Create an institutional-address join link for assignment 82 in course 30."*
- *"List course 30's invite links and revoke link 7."*
- *"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?"*
- *"Prepare a student walkthrough for assignment 88. Show its Canvas and allowed
  tools, and include my notes about checking inputs."*
- *"Draft a 3-hour practice case on oat-milk demand in the Netherlands for course 30,
  with real Eurostat and Google Trends data and a Python Lab."* (then answer its questions)
- *"How is my Draft with AI build doing? Wait for it."*
- *"Show me the new thumbs-down feedback on Draft with AI."* (admins)

## Draft with AI (version 0.5.0)

The same conversation as the web app's **Draft with AI**, from your terminal:
`draft_with_ai` starts it in a course with what you want in plain words, and the AI
asks instead of assuming. `ai_draft_reply` answers its questions (an option's label
or value, or words) and asks for changes; `ai_draft_status` shows the phase, the
open questions and a running build's progress, and can wait (a build takes 10–40
minutes, its checks most of it). `ai_draft_settings` sets the autonomy and the setup
(Python Lab, exam, level, hours), and `ai_draft_conversations` lists them.

- **Autonomy.** `check` (default) stops for you after the brief, the documents and the
  canvas, and after the platform checks, before any repair changes what you approved.
  `big` asks only big choices; `auto` builds, then shows.
- **Real data.** `data_sources` lists US Census (ACS, County Business Patterns),
  Eurostat, Google Trends (unofficial), World Bank, FRED and SEC EDGAR, and your own
  MCP data connections. The AI proposes fetches and fetches nothing until you agree.
  `connect_data_source` adds a keyless MCP service; a service that needs a key is added
  in the web app, so the key is typed into the browser once and never passes through
  an AI conversation.
- **Keeping the result.** `keep_ai_draft` keeps a finished draft in its course,
  UNPUBLISHED, with its documents, rubric and starting canvas (a Python Lab keeps its
  notebook and hidden checks). `publish_assignment` stays the separate, noisy step.
- **Feedback.** `rate_ai_message` is the web app's thumbs up/down. Admins read the
  inbox with `ai_feedback` (and the conversation behind a rating with
  `ai_feedback_conversation`) and file each entry with `triage_ai_feedback`.

## Course walkthrough companion (local version 0.4.2)

The package now includes the **course-walkthrough** skill and two read-only tools:

- `walkthrough_guide(section="skill")` reads the guide without account access.
  Other sections are `teacher_mcp`, `canvas`, `recording`, `audio`, `professor_brief` and
  `storyboard`. Resource-capable clients can also read
  `essencestudy://skills/course-walkthrough`.
- `prepare_walkthrough(assignment_id=88)` uses your existing teacher authorization
  to read the brief, **official starter** Canvas, visible rubric, allowed tools,
  dates and Python-help policy. It never substitutes your saved staff canvas for
  a missing starter. It omits solutions, student work and document inventories
  whose student visibility cannot be determined from the current staff API.

The agent combines this evidence with your extra notes, separating student-facing
messages from private professor notes. Its browser/audio tools create the video,
captions and illustrated guide, or just a recording script when requested.
The MCP does not record or synthesize media. A policy snapshot does not verify
live student quotas or the rendered UI; those are checked before filming.
Preparation does not run work, submit, enroll, publish or send messages.

`walkthrough_guide(section="audio")` includes documented Fish Audio, OpenAI and
ElevenLabs request examples, voice/pronunciation choices, segmented narration,
duration/caption checks and reusable audio metadata. It supplies guidance only;
it does not send text to a speech provider or require speech credentials to read.

The guide travels with the Python wheel, so clients can read it even without a
host skill folder. To explicitly export it for a host that supports local skills:

```bash
# Run from this source folder while 0.4.2 is unpublished:
uvx --from . essencestudy-teacher-skill --destination ~/.codex/skills/course-walkthrough
# Or use --destination ~/.claude/skills/course-walkthrough for Claude Code.
```

The exporter leaves existing different files and symlinks unchanged. An identical
existing export is a no-op. If you already maintain one shared Claude/Codex skill,
retain that arrangement instead of creating another copy.

This version is local source only, not yet on PyPI. The plain install command
above still installs the published release. Locally configured clients must be
restarted to load the updated tool list. The same package works with production
or nightly according to `ESSENCESTUDY_API_URL`; credentials are unchanged.

The skill under `teacher_walkthrough/skill/` is the package's release snapshot.
When updating it from a shared authoring copy, preserve its relative references
and validate both the skill and wheel contents. Do not bundle account data,
credentials, real student examples or private professor notes into this package.

## 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.

**Invite links (local version 0.4.0).** `create_invite_link`, `list_invite_links`
and `revoke_invite_link` use the course's invite permissions. The default restricts
joining to institutional addresses. A link enrolls students in the whole course,
even when it opens one assignment. Creation sends no emails and publishes nothing.
Revoking stops new joins; existing members keep access. `list_students` includes
enrollment source and invite ID. The URL comes from the backend's environment,
so the local nightly server returns nightly links. This source version has not
been published to PyPI; restart locally configured clients after updating it.
