@learnwithagents/mcp-server

Local Model Context Protocol (stdio) server for Learn with Agents / DevTutor. It connects the student’s editor (Cursor, VS Code, etc.) to your Convex deployment over HTTPS (curriculum, progress, verification, hints).

Students do not need this monorepo: they install the published npm package and authenticate using the Cloudflare-hosted web app (agent tokens + CLI login).

Production architecture

| Piece | Role | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | This npm package | MCP tools + tool descriptions (orchestration and teaching fidelity). Versioned with semver. | | Convex (*.convex.site) | Tutor HTTP API: POST /mcp/next-lesson, verify, hints, mark-complete, list-courses. Stores lesson bodies after curriculum sync. | | Cloudflare (web app) | Login, billing, agent tokens, CLI login redirect (/cli-login), and student setup UI (MCP install + **AGENTS.md** instructions). | | Student course folder | Small folder they open with File → Open Folder. Must contain root **AGENTS.md** (same content as your shipped template: COURSE_SLUG, IDE:, MCP usage). |

Student editor → npm MCP (stdio) → HTTPS → Convex tutor routes
                    ↑
Student web browser → Cloudflare app (token, login, setup docs)

What updates when

| Change | Ship via | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | Lesson copy, hints, verification rules, teaching_diagnostics in frontmatter, new lessons in DB | Curriculum sync to Convex (no npm release) unless the HTTP lesson shape or MCP tool copy changes. | | Tool descriptions, client behavior, new MCP tools, breaking args | New npm version of @learnwithagents/mcp-server. |

Semver policy (published package)

• Patch — Wording fixes in tool descriptions, bug fixes, non-breaking behavior.
• Minor — New optional tool parameters, new tools, backward-compatible additions.
• Major — Renamed tools, removed tools, or breaking changes to arguments or response shape.

Curriculum-only changes do not require an npm bump if the MCP contract is unchanged.

Editor tool descriptors (Cursor, etc.)

After publishing a new version, students should update the package their MCP config runs (e.g. npx -y @learnwithagents/mcp-server@latest or a pinned version). The editor may cache MCP tool schemas until the server process restarts or the config changes.

Build (monorepo)

pnpm --filter @learnwithagents/mcp-server build

Configure Cursor / VS Code

Use your Convex site URL (ends in .convex.site) as --site-url, and an agent token from the web app Tokens page.

pnpm --filter @learnwithagents/mcp-server run mcp -- --token=dt_... --site-url=https://YOUR_DEPLOYMENT.convex.site

(Workspace packages do not expose their bin to pnpm exec in the same package; use the mcp script or node ./dist/index.js after build.)

Course setup (init)

Interactive scaffold for a bundled course (creates the project folder, writes AGENTS.md from the packaged template, runs browser login if needed, optionally merges MCP config for Cursor, VS Code, or Antigravity):

npx -y @learnwithagents/mcp-server@latest init code-kenya-pre-course

• init --help — flags for non-interactive use (-y, --course=, --ide=cursor|vscode|antigravity, --dir=, --skip-mcp-config, --force, --web-origin=).
• New self-heal flags:
  • Strict pre-launch behavior now auto-repairs by default: init runs health checks and re-runs login automatically on missing/rejected config.
  • --repair forces one additional login retry before failing.
  • --force-reset clears local auth config and forces a fresh login before setup.
• Bundled courses ship under dist/scaffolds/<course-slug>/ in the published package; new slugs require a new npm release until a server-delivered manifest exists.
• Browser URL for login / init: when LEARNWITHAGENTS_WEB_ORIGIN is unset, the CLI uses the shipped default production origin (https://learnwithagents.com). For local development, set LEARNWITHAGENTS_WEB_ORIGIN=http://localhost:3000 (or pass --web-origin= where supported).

Login helper

pnpm --filter @learnwithagents/mcp-server run mcp -- login

Then open the printed /cli-login?port=... URL in the browser (Cloudflare app) and approve the token handoff. Credentials are stored in ~/.learnwithagents/config.json as token, siteUrl (Convex HTTP site for /mcp/...), and webOrigin (the web app origin for /billing, e.g. https://learnwithagents.com). To run the stdio server from env vars only, set LEARNWITHAGENTS_TOKEN, LEARNWITHAGENTS_SITE_URL, and LEARNWITHAGENTS_WEB_ORIGIN.

Doctor (health check + repair)

Validate your local MCP credentials and backend connectivity:

npx -y @learnwithagents/mcp-server@latest doctor --course=code-kenya-pre-course

If diagnostics fail, re-run with automatic repair:

npx -y @learnwithagents/mcp-server@latest doctor --repair --course=code-kenya-pre-course

MCP enabled + auth checklist

After init or manual install, verify all of the following before starting lessons:

• MCP server key exists as learnwithagents in editor config:
  • Cursor: <project>/.cursor/mcp.json under mcpServers
  • VS Code: <project>/.vscode/mcp.json under servers
  • Antigravity: ~/.gemini/antigravity/mcp_config.json under mcpServers
• In editor MCP settings, learnwithagents is enabled/connected.
• If disabled, enable it and restart MCP server/editor.
• Run list_courses first as a quick health check before start_or_resume_course.
• If chat shows invalid_token or UNAUTHENTICATED, run:

npx -y @learnwithagents/mcp-server@latest login

Then restart MCP server/editor and retry.

Logout helper

pnpm --filter @learnwithagents/mcp-server run mcp -- logout

Removes the local saved credentials file (~/.learnwithagents/config.json on macOS/Linux, %USERPROFILE%\\.learnwithagents\\config.json on Windows). This is local sign-out only; revoke server tokens separately from the web app.

Tools

• fetch_next_lesson — Next incomplete lesson. Optional course_slug (e.g. code-kenya-pre-course); if omitted, uses the last course in this stdio session or the server default. Default response (as assembled markdown): progress header (course/module position), optional learner line until addressing is recorded, Tutor policy (course + per-user merge), optional teachingDiagnostics nudge when lesson.teachingDiagnostics === true, # title, and full lesson body. JSON from Convex includes progress, learner, tutorPolicy, lesson (with teachingDiagnostics: boolean). Use detail: "debug" or LEARNWITHAGENTS_MCP_DEBUG=1 for lesson id and raw verification/hints JSON.
• list_courses — Published courses with title and course_slug.
• start_or_resume_course — Same as fetch_next_lesson with a required course_slug.
• mark_lesson_complete — Mark progress after the student passes verification; lesson_id optional when this session already fetched a lesson.
• request_hint — Progressive hints when the student is stuck; lesson_id optional the same way.
• set_tutor_address — Record name + value or neutral how to address the learner (welcome lesson); persists on users in Convex.
• verify_tutor_address_recorded — Confirms set_tutor_address ran for this token (welcome lesson check).
• verify_step — shell (default), file_contains, or file_regex inside the workspace (pass **workspace_root** as the folder that contains the learner’s AGENTS.md). Do not call it before the student is ready; read/glob before the first message is only when lesson.teachingDiagnostics from the last fetch is true (for messaging, not a substitute for this tool).

Resource

• tutor://curriculum/current — Same as fetch_next_lesson without a course (default course). Add ?course=code-kenya-pre-course for an explicit slug.

HTTP API (Convex HTTP actions)

The MCP server POSTs to your deployment with the user’s bearer token:

• POST /mcp/next-lesson — Optional body { "courseSlug": "…" }. Returns { progress, learner, tutorPolicy, lesson } (each lesson includes teachingDiagnostics: boolean) or { done: true, … }. Unknown slug → 404 { error: "unknown_course" }.
• POST /mcp/set-tutor-address — Body { "mode": "name", "value": "…" } or { "mode": "neutral" }.
• POST /mcp/verify-tutor-address — Body optional. Returns { ok: true } if a preference is stored.
• POST /mcp/list-courses — { courses: [{ _id, slug, title, order }] }.
• Additional routes for verify, hint, mark-complete (see packages/backend/convex/http.ts).

Future: server-delivered orchestration notes

Optional later: return a short instruction string from the API with each lesson so minor orchestration tweaks can ship without an npm release. Deferred until needed; tool descriptions remain the primary contract for v1.