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

Related MCP server: openclaw-mcp

The 9 Tools

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

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