TutorClaw MCP

An MCP server built for OpenClaw that turns the learner's OpenClaw instance into a programming tutor. Learners progress through chapters using the PRIMM-Lite pedagogy — Predict → Run → Investigate → Modify → Make — while TutorClaw tracks state, serves content, gates tiers, and handles Stripe upgrades.

TutorClaw follows the platform-inversion model: OpenClaw provides the compute, messaging, and agent orchestration on the learner's side; TutorClaw provides only tools, content, and teaching logic — no database, no cloud, just JSON and markdown on disk.

---

Features

• 9 MCP tools covering learner state, content delivery, pedagogy, code execution, and billing
• PRIMM-Lite methodology — stage-appropriate prompts and assessment built into the tools
• Local-first storage — learners and progress in JSON, chapters in markdown, exercises in JSON
• Tier gating — free tier caps (chapters 1–5, 50 exchanges/day, 10 code submissions/day); paid tier unlimited
• Stripe integration — get_upgrade_url creates a checkout session; /webhook endpoint verifies checkout.session.completed and flips the learner to paid
• Sandboxed code execution — blocks os, subprocess, shutil, open(); 5-second timeout per submission
• Streamable-HTTP transport — stateless, FastMCP, port 8000

---

The 9 Tools

Tool	Purpose
register_learner	Create a new learner and return their ID + API key
get_learner_state	Read chapter, stage, confidence, tier, exchanges remaining
update_progress	Advance chapter/stage and apply a confidence delta
get_chapter_content	Fetch chapter markdown, optionally narrowed to a section
get_exercises	Return practice problems, optionally filtered by weak areas
generate_guidance	Produce a stage-appropriate code excerpt and teaching system prompt
assess_response	Score a learner's answer against expected concepts
submit_code	Execute Python code in a sandbox with import and builtin restrictions
get_upgrade_url	Create a Stripe checkout session for a free-tier learner

---

Project Layout

tutorclaw-mcp/
├── src/tutorclaw/
│   ├── server.py          # FastMCP server, tool registration, /webhook route
│   ├── store.py           # JSON persistence, tier checks, quota tracking
│   ├── webhook.py         # Stripe checkout.session.completed handler
│   └── tools/
│       ├── learners.py    # register_learner, get_learner_state, update_progress
│       ├── content.py     # get_chapter_content, get_exercises
│       ├── guidance.py    # generate_guidance
│       ├── assessment.py  # assess_response
│       ├── execution.py   # submit_code (sandboxed)
│       └── billing.py     # get_upgrade_url
├── content/
│   ├── chapters/          # 01-variables.md … 05-files.md (free), 06+ (paid)
│   └── exercises/         # 01-exercises.json … 05-exercises.json
├── data/                  # Runtime state (gitignored): learners.json, learner_state.json
├── tests/                 # Per-tool unit tests + integration + payment-flow suites
├── AGENTS.md              # Agent instructions: session-start + tutoring flow
├── CLAUDE.md              # Build rules (uv, flat Annotated params, streamable-http)
└── pyproject.toml

---

Requirements

• Python 3.14+
• uv for dependency management
• A Stripe account (test mode is fine) for the upgrade flow

---

Setup

# Clone
git clone https://github.com/mohsinsheikhani/tutorclaw-mcp.git
cd tutorclaw-mcp

# Install dependencies
uv sync

# Configure Stripe (required only for get_upgrade_url and /webhook)
cp .env.example .env
# Edit .env and fill in:
#   STRIPE_SECRET_KEY=sk_test_...
#   STRIPE_PRICE_ID_PAID=price_...
#   STRIPE_WEBHOOK_SECRET=whsec_...

---

Running the Server

uv run tutorclaw

The server starts on http://0.0.0.0:8000 with streamable-HTTP stateless transport. The MCP endpoint is /mcp and the Stripe webhook is /webhook.

Connect with MCP Inspector

npx @modelcontextprotocol/inspector

Point it at http://localhost:8000/mcp and explore the 9 tools.

Stripe webhook (local testing)

stripe listen --forward-to localhost:8000/webhook
# Copy the printed whsec_... into .env as STRIPE_WEBHOOK_SECRET
stripe trigger checkout.session.completed

---

Tier Gating

Limit	Free	Paid
Chapters accessible	1–5	All
Exchanges per day	50	Unlimited
Code submissions per day	10	Unlimited

Daily counters reset automatically at the first request after the reset date rolls over. Tools raise a ValueError with an upgrade hint when any gate trips.

---

Storage Model

• data/learners.json — {learner_id: {name, email, tier, api_key, created_at}}
• data/learner_state.json — {learner_id: {chapter, stage, confidence, exchanges_remaining, exchanges_reset_date, code_submissions_today, weak_areas}}

Writes are atomic (temp-file + os.replace). Both files are gitignored.

---

Testing

uv run pytest

The suite covers every tool with both unit and integration tests, plus a full payment-flow test (checkout session creation → webhook verification → tier upgrade). All tests use isolated tmp_path fixtures, so the production data/ directory is never touched.

---

Agent Usage

Drop AGENTS.md into the agent's context — it defines the session-start protocol, the tutoring flow, and the tool-selection rules:

1. On first message: get_learner_state → register_learner if missing.
2. For a lesson: get_chapter_content → generate_guidance → present → assess_response → update_progress.
3. For practice: get_exercises.
4. For code: submit_code (never assess_response).
5. On tier block: get_upgrade_url.

---

License

MIT