Metadata-Version: 2.5
Name: essenceteacher-mcp
Version: 0.1.0
Summary: MCP server exposing EssenceTeacher courses, assignments, grading and student support as agent tools
Project-URL: Homepage, https://study.essencescholar.com
Project-URL: Repository, https://github.com/EssenceScholar/EssenceTeacher-MCP
Author-email: EssenceScholar <admin@essencescholar.com>
License: MIT
License-File: LICENSE
Keywords: agent,education,grading,llm,mcp,teaching
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]<2.0,>=1.3
Description-Content-Type: text/markdown

# EssenceTeacher MCP

An MCP server that puts a teacher's own courses, assignments, submissions and
student-support queue in front of an AI assistant — so "where is my class stuck?"
is answered from the real data instead of from a description of it.

Companion to [`essencescholar-mcp`](https://pypi.org/project/essencescholar-mcp/),
which does the same for the research platform.

## Install

Nothing to install — run it with `uvx`:

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

That's the whole config. There is deliberately **no API key in it**: the first
time a tool needs one, ask your assistant to sign in.

## Signing in

Say *"sign in to EssenceTeacher"*. The `sign_in` tool prints a short code and a
URL; open it in a browser where you are already signed in, approve the code, and
the key is collected once and stored at `~/.config/essenceteacher/api_key`
(owner-read only). Later sessions just work.

No key is ever pasted into a chat. Only teaching staff can approve — a student
account is refused by the server.

If you would rather manage the credential yourself, set `ESSENCETEACHER_API_KEY`
and `sign_in` is never needed. `ESSENCETEACHER_API_URL` points at a different
deployment; it defaults to `https://study.essencescholar.com`.

## Tools

**Getting in** — `sign_in`, `whoami`

**Courses** — `list_courses`, `course_details`, `list_materials`, `gradebook`

**Assignments** — `list_assignments`, `get_assignment`, `assignment_usage`,
`list_submissions`

**Student support** — `flagged_questions`, `announcements`

**Long jobs** — `list_jobs`, `get_job`

Start at `list_courses`; its ids feed everything else.

## It reads; it does not act

Every tool here is read-only. There is nothing that publishes grades, edits a
rubric, posts an announcement or reruns a student's submission — and that is a
design decision, not an omission.

Those acts change what a student sees and what a teacher is accountable for. They
belong in the app, where the teacher sees the consequence before agreeing to it.
An assistant that can publish grades by misreading a sentence is worse than one
that cannot publish them at all. When the right next step is one of those, the
server's instructions tell the assistant to say so and name the screen.

`sign_in` is the single exception, and it writes only a credential, with the
teacher's own browser consent.

## Student data

Rosters, submissions and gradebooks identify real students. Under GDPR the
university is the controller, not this tool.

`course_details`, `gradebook` and `list_submissions` say so in their own
descriptions, so the assistant knows before it calls them. The server's
instructions ask it to answer from aggregates where aggregates will do — a grade
distribution rarely needs names attached, and a chat transcript keeps whatever is
put into it. Asking for a named list is a teacher's call to make; the point is
that names are not reached for by default.

## Questions it is good at

- *"Which assignment are students struggling with most?"* — `flagged_questions`
  across courses, grouped by category.
- *"Has everyone submitted assignment 34?"* — `list_submissions`, counted.
- *"What does this assignment actually require?"* — `get_assignment` for the
  rubric, in the words the students were given.
- *"Is this assignment expensive to run for 80 students?"* — `assignment_usage`.
- *"The chatbot keeps saying it does not know about X"* — `list_materials`, to
  check whether X is in the material set at all.

## Licence

MIT.
