Graspful

Build courses with lessons, practice questions, and scheduled review.

Graspful stores academies, courses, and brand configuration in YAML files. You or an external agent, such as Claude or Codex, author the content through CLI commands or MCP tools. The CLI creates draft scaffolds. The author supplies the source material, writes the lessons and questions, and reviews the facts before publication.

Learners work through explanations, examples, and questions. Their answers update progress estimates. Prerequisites guide lesson order, and the system schedules later review.

How it works

1. Plan the academy. Define its audience, source material, course scope, and prerequisites.
2. Create draft files. Use the CLI or MCP tools to scaffold the academy and its courses. Scaffold and fill commands generate placeholders for the author to complete.
3. Write and review. Replace all placeholders with sourced explanations, worked examples, and practice questions. Check the answer explanations against the sources.
4. Validate. Run graspful validate and graspful review. Automated checks report structural problems. The author still checks accuracy and teaching quality.
5. Import a draft. Import the reviewed files, inspect the result, then publish when ready. Importing without --publish saves a draft.
6. Configure the brand. Import a brand YAML file for the landing page, theme, and copy. Custom domains require domain and hosting setup.

Read the course authoring runbook before building a course.

Quickstart

bun add -g @graspful/cli

# Create a local draft scaffold.
bunx @graspful/cli create academy --topic "Your topic" -o academy.yaml
mkdir -p courses
bunx @graspful/cli create course --topic "Foundations" -o courses/foundations.yaml

These files need authoring and review before import. Follow the runbook to complete the content and match the academy manifest to its course files.

Register before using import or publish commands:

bunx @graspful/cli register --email [email protected]

Registration opens browser authentication, creates a private organization workspace, and saves an API key locally. MCP reads those saved credentials for authenticated tools. GRASPFUL_API_KEY overrides the saved key. A course or brand import creates the public website. See auth and access.

CLI commands

Command	Auth required	Purpose
graspful register	No	Register through browser authentication and save an API key
graspful login	No	Authenticate an existing account
graspful create academy	No	Create an academy plan and manifest scaffold
graspful create course	No	Create a course YAML scaffold
graspful create brand	No	Create brand YAML with theme presets
graspful fill concept	No	Add placeholder knowledge points and questions
graspful validate	No	Validate the YAML schema and prerequisite graph
graspful review	No	Run mechanical quality checks
graspful describe	No	Show course statistics
graspful import	Yes	Import YAML, saving a draft unless publication is requested and succeeds
graspful publish	Yes	Request publication of a reviewed draft

Check the command result to confirm whether publication succeeded.

MCP server

graspful init authenticates through the browser and configures detected clients. For local authoring before registration, configure the MCP server directly. This example uses the Claude Desktop and Cursor format; see the linked MCP guide for other clients:

{
  "mcpServers": {
    "graspful": {
      "command": "bunx",
      "args": ["@graspful/mcp"],
      "env": { "GRASPFUL_API_KEY": "gsk_..." }
    }
  }
}

The external agent writes the course content and uses Graspful tools to scaffold, validate, review, import, and publish it. The MCP server performs structured course operations. See the MCP documentation for setup and the tool reference.

Billing status

Stripe and Stripe Connect integration code exists. Paid subscriptions and creator payouts are not ready for customers. Live credentials, price configuration, creator onboarding, webhook setup, and payment verification are required before accepting payments.

The repository contains proposed pricing and revenue-share settings. Treat those as configuration under development, rather than an offer to customers.

Tech stack

• Backend: NestJS, Prisma, PostgreSQL
• Frontend: Next.js App Router, React, Tailwind CSS, shadcn/ui
• CLI: @graspful/cli
• MCP server: @graspful/mcp
• Authentication: Supabase Auth and API keys
• Billing integration: Stripe and Stripe Connect, pending setup
• Workspace: Turborepo and bun

Repository layout

graspful/
├── apps/web/          # Public site, academy pages, and learner app (port 3001)
├── apps/site/         # Separate creator dashboard app (port 3002)
├── backend/          # NestJS API
├── packages/
│   ├── creator-ui/   # Components and API contracts shared by both apps
│   ├── client/       # CLI and MCP HTTP client
│   ├── shared/       # Schemas, types, quality checks
│   ├── cli/          # CLI
│   └── mcp/          # MCP server
├── content/
│   ├── courses/      # Course YAML files
│   ├── brands/       # Brand YAML files
│   └── academies/    # Academy manifests
└── docs/             # Documentation

Development

bun install
bun run dev
bun run build
bun run lint
bun run typecheck
bun run test
bun run test:scripts

Copy the relevant environment examples into each workspace before starting services. apps/site provides a dedicated creator deployment and login surface; apps/web serves the platform and branded learner sites. Shared creator code lives in packages/creator-ui.

Run browser tests in both apps with bun run test:e2e. Follow local E2E setup to use an isolated database and auth service. CLAUDE.md lists the test requirements.

Maintenance scripts live in backend/scripts. Run the demo seed from backend with bun run seed:demo electrical or bun run seed:demo javascript. The reference book is available as The Math Academy Way PDF; local downloads are ignored.

Documentation

• Course authoring runbook
• Course review gate
• Course content format
• Brand configuration
• Platform FAQ

License

See LICENSE.md for the license terms.