tutor-ledger

Pay-As-You-Learn tutor ledger

The plugin starts @three-ws/tutor-mcp over stdio (npx -y @three-ws/tutor-mcp, bin tutor-mcp). It needs no key or signer. The questions themselves are billed elsewhere. This server only reads and seals the ledger.

Environment (both optional)

• THREE_WS_BASE: API origin, default https://three.ws.
• THREE_WS_TIMEOUT_MS: per-request timeout in milliseconds.

Tools

Tool	Argument	Endpoint
load_session	sessionId (string, 1-100 characters)	GET /api/tutor/session?sessionId=...
close_session	sessionId (string, 1-100 characters)	POST /api/tutor/session with { sessionId, action: "end" }

What comes back

load_session returns status (open or closed), questionCount, lineItems (one per answered question: question text, level, output tokens, cost in atomic units, a $x.xxxxxx string and a timestamp), totalAtomics and totalUsd. A session that is already closed also returns its invoice. An unknown sessionId returns an empty open session.

close_session seals the ledger. It sets status to closed, stamps a SHA-256 attestation over the line items and total, and returns closedAt, lineItems, totalAtomics, totalUsd and attestation. After closing, no more questions can be billed to that session. Closing is free and moves no funds, because the learner was already charged per question.

Worked example

Request: "How much has session calc-101 cost, and give me the invoice."

1. Call load_session with { "sessionId": "calc-101" } and report questionCount and totalUsd.
2. Closing is irreversible, so confirm with the user that they want the session sealed.
3. Call close_session with { "sessionId": "calc-101" } and return the attestation with the itemized lineItems.

Notes

• Do not invent a sessionId. Use the one the user gives you, since the id is how the ledger is addressed.
• Closing cannot be undone. Always load first and confirm before closing.