@graspful/mcp 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,273 @@
+# @graspful/mcp
+
+[![npm version](https://img.shields.io/npm/v/@graspful/mcp)](https://www.npmjs.com/package/@graspful/mcp)
+[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
+[![License](https://img.shields.io/npm/l/@graspful/mcp)](https://github.com/willwearing/graspful/blob/main/LICENSE)
+
+MCP server for creating adaptive learning courses. AI agents scaffold, validate, review, and publish courses as YAML knowledge graphs.
+
+Part of [Graspful](https://graspful.ai) -- the agent-first adaptive learning platform. Courses are authored as two YAML files (graph structure + content), validated offline, then imported via API.
+
+## Quick Start
+
+### 1. Configure your editor
+
+```bash
+npx @graspful/cli init
+```
+
+Detects your editor (Claude Code, Cursor, Windsurf) and writes the MCP config automatically.
+
+Or add manually to your editor's MCP config (see [Editor Configuration](#editor-configuration) below):
+
+```json
+{
+  "mcpServers": {
+    "graspful": {
+      "command": "npx",
+      "args": ["@graspful/mcp"]
+    }
+  }
+}
+```
+
+### 2. Create an account
+
+Call the `graspful_register` tool with your email and password. This creates an account, org, and API key — all in one step, no browser needed.
+
+```
+graspful_register(email: "you@example.com", password: "your-password")
+```
+
+Or via CLI: `npx @graspful/cli register --email you@example.com --password your-password`
+
+### 3. Build a course
+
+```
+graspful_scaffold_course(topic: "Your Topic", estimatedHours: 10)
+→ edit the YAML
+graspful_validate(yaml: "...")
+graspful_review_course(yaml: "...")
+graspful_import_course(yaml: "...", org: "your-org", publish: true)
+```
+
+Scaffold, fill, validate, and review work offline — no account needed. You only need to register before importing or publishing.
+
+## Available Tools
+
+10 tools. Focused and minimal -- agents degrade above 40 tools.
+
+| Tool | Description | Auth Required |
+|------|-------------|:---:|
+| `graspful_scaffold_course` | Generate a course YAML skeleton with sections, concepts, and prerequisite edges | No |
+| `graspful_fill_concept` | Add knowledge points and problem stubs to a specific concept | No |
+| `graspful_validate` | Validate any Graspful YAML against its Zod schema. Auto-detects file type | No |
+| `graspful_review_course` | Run all 10 mechanical quality checks. Returns a score with failure details | No |
+| `graspful_describe_course` | Compute course statistics without importing (concept/KP/problem counts, graph depth) | No |
+| `graspful_create_brand` | Generate brand YAML scaffold for a white-label learning site | No |
+| `graspful_import_course` | Import course YAML into an organization. Creates as draft by default | Yes |
+| `graspful_publish_course` | Publish a draft course. Runs review gate first -- all 10 checks must pass | Yes |
+| `graspful_import_brand` | Import brand YAML to create white-label site config | Yes |
+| `graspful_list_courses` | List all courses in an organization | Yes |
+
+## Tool Reference
+
+### `graspful_scaffold_course`
+
+Generate a course YAML skeleton with sections, concepts, and prerequisite edges. Returns a minimal valid YAML structure with TODO placeholders. This is step 1 of the Graspful two-YAML workflow.
+
+| Parameter | Type | Required | Description |
+|-----------|------|:---:|-------------|
+| `topic` | string | Yes | Course topic (e.g., "Linear Algebra") |
+| `estimatedHours` | number | No | Total course hours (default: 10) |
+| `sourceDocument` | string | No | Reference to source material |
+
+### `graspful_fill_concept`
+
+Add knowledge points (KPs) and problem stubs to a specific concept in a course YAML. Returns the full updated YAML. Fails if the concept already has KPs (prevents accidental overwrites).
+
+| Parameter | Type | Required | Description |
+|-----------|------|:---:|-------------|
+| `yaml` | string | Yes | Full course YAML string |
+| `conceptId` | string | Yes | ID of the concept to fill |
+| `kps` | number | No | Number of KP stubs (default: 2) |
+| `problemsPerKp` | number | No | Problems per KP (default: 3) |
+
+### `graspful_validate`
+
+Validate any Graspful YAML (course, brand, or academy manifest) against its Zod schema. Auto-detects file type. For courses, also checks DAG validity and prerequisite integrity. Runs offline -- no API needed. Use frequently during authoring.
+
+| Parameter | Type | Required | Description |
+|-----------|------|:---:|-------------|
+| `yaml` | string | Yes | YAML string to validate |
+
+**Returns:** `{ valid, fileType, errors, stats }`
+
+### `graspful_review_course`
+
+Run all 10 mechanical quality checks. Returns a score (e.g., "8/10") with details on each failure. A score of 10/10 is required for publishing.
+
+**The 10 checks:**
+
+1. Schema validation (valid Zod schema)
+2. Unique problem IDs
+3. Valid prerequisites (all refs point to real concepts)
+4. No DAG cycles
+5. Minimum KPs per concept
+6. Minimum problems per KP
+7. Difficulty distribution (2+ levels per concept)
+8. Explanation coverage (worked examples)
+9. Question deduplication (no near-duplicates at same difficulty)
+10. Concept tag coverage
+
+| Parameter | Type | Required | Description |
+|-----------|------|:---:|-------------|
+| `yaml` | string | Yes | Full course YAML string |
+
+**Returns:** `{ passed, score, failures, warnings, stats }`
+
+### `graspful_import_course`
+
+Import course YAML into a Graspful organization. Creates as draft by default. If `publish=true`, the server runs the review gate first.
+
+| Parameter | Type | Required | Description |
+|-----------|------|:---:|-------------|
+| `yaml` | string | Yes | Full course YAML string |
+| `org` | string | Yes | Organization slug |
+| `publish` | boolean | No | Publish immediately (default: false) |
+
+**Returns:** `{ courseId, url, published, reviewFailures? }`
+
+### `graspful_publish_course`
+
+Publish a draft course. Server runs the review gate first -- all 10 checks must pass.
+
+| Parameter | Type | Required | Description |
+|-----------|------|:---:|-------------|
+| `courseId` | string | Yes | Course ID (UUID) |
+| `org` | string | Yes | Organization slug |
+
+**Returns:** `{ courseId, published }`
+
+### `graspful_describe_course`
+
+Compute statistics for a course YAML without importing it. Use to track authoring progress.
+
+| Parameter | Type | Required | Description |
+|-----------|------|:---:|-------------|
+| `yaml` | string | Yes | Full course YAML string |
+
+**Returns:** `{ courseName, courseId, version, estimatedHours, concepts, authoredConcepts, stubConcepts, knowledgePoints, problems, graphDepth, conceptsWithoutKps, kpsWithoutProblems, sections }`
+
+### `graspful_create_brand`
+
+Generate brand YAML scaffold for a white-label learning site. Niche presets set appropriate colors, taglines, and copy.
+
+| Parameter | Type | Required | Description |
+|-----------|------|:---:|-------------|
+| `niche` | string | Yes | `education`, `healthcare`, `finance`, `tech`, or `legal` |
+| `name` | string | No | Brand name |
+| `domain` | string | No | Custom domain |
+| `orgSlug` | string | No | Organization slug |
+
+### `graspful_import_brand`
+
+Import brand YAML into Graspful. Creates the white-label site configuration.
+
+| Parameter | Type | Required | Description |
+|-----------|------|:---:|-------------|
+| `yaml` | string | Yes | Full brand YAML string |
+| `orgSlug` | string | Yes | Organization slug |
+
+**Returns:** `{ slug, domain, verificationStatus }`
+
+### `graspful_list_courses`
+
+List all courses in a Graspful organization.
+
+| Parameter | Type | Required | Description |
+|-----------|------|:---:|-------------|
+| `org` | string | Yes | Organization slug |
+
+## Typical Agent Workflow
+
+```
+1. Scaffold       graspful_scaffold_course(topic: "Kubernetes Networking", estimatedHours: 8)
+                  Edit the returned YAML -- add concepts, set prerequisites
+
+2. Validate       graspful_validate(yaml) -- catch schema errors early
+
+3. Fill           graspful_fill_concept(yaml, conceptId: "k8s-services")
+                  Repeat for each concept. Replace TODO placeholders with real content.
+                  Validate after each fill.
+
+4. Review         graspful_review_course(yaml) -- run quality gate
+                  Fix failures, re-review until 10/10
+
+5. Import         graspful_import_course(yaml, org: "acme") -- creates draft
+
+6. Brand          graspful_create_brand(niche: "tech", name: "Acme Learn")
+                  graspful_import_brand(yaml, orgSlug: "acme")
+
+7. Publish        graspful_publish_course(courseId: "...", org: "acme")
+```
+
+Offline tools (scaffold, fill, validate, review, describe, create_brand) need no API key. Only import, publish, import_brand, and list_courses require `GRASPFUL_API_KEY`.
+
+## Editor Configuration
+
+### Claude Code / Claude Desktop
+
+Add to `~/.claude/claude_desktop_config.json` or your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "graspful": {
+      "command": "npx",
+      "args": ["@graspful/mcp"],
+      "env": {
+        "GRASPFUL_API_KEY": "gsk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "graspful": {
+      "command": "npx",
+      "args": ["@graspful/mcp"],
+      "env": {
+        "GRASPFUL_API_KEY": "gsk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Windsurf / Codex / Other MCP-compatible agents
+
+Same pattern -- point `command` at `npx` and `args` at `@graspful/mcp`. The server communicates over stdio using the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|:---:|-------------|
+| `GRASPFUL_API_KEY` | For import/publish/list | API key for authenticated operations |
+| `GRASPFUL_API_URL` | No | API base URL (default: `https://api.graspful.ai`) |
+
+## Links
+
+- [Graspful](https://graspful.ai) -- Platform
+- [Content Authoring Guide](../../content/README.md) -- YAML schema reference and authoring rules
+- [Course Review Gate](../../docs/course-review-gate.md) -- Full specification of all 10 quality checks
+- [CLI Agent Strategy](../../docs/cli-agent-strategy.md) -- Design philosophy and architecture
+- [@graspful/cli](https://www.npmjs.com/package/@graspful/cli) -- CLI companion package
+- [Model Context Protocol](https://modelcontextprotocol.io) -- MCP specification

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
 export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -39,10 +39,22 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const yaml = __importStar(require("js-yaml"));
 const crypto = __importStar(require("crypto"));
-const schemas_1 = require("./schemas");
+const shared_1 = require("@graspful/shared");
+// ─── Auth guard ─────────────────────────────────────────────────────────────
+const AUTH_REQUIRED_ERROR = 'Not authenticated. To authenticate, either:\n' +
+    '1. Call the graspful_register tool with an email and password to create an account and get an API key, OR\n' +
+    '2. Set the GRASPFUL_API_KEY environment variable (e.g., GRASPFUL_API_KEY=gsk_...).\n\n' +
+    'You can scaffold, validate, and review courses without authentication. ' +
+    'Authentication is only required for importing, publishing, and listing courses.';
+function requireApiAuth() {
+    const apiKey = process.env.GRASPFUL_API_KEY;
+    if (!apiKey) {
+        throw new Error(AUTH_REQUIRED_ERROR);
+    }
+}
 // ─── API Client (mirrors packages/cli/src/lib/api-client.ts) ──────────────
 function getApiCredentials() {
-    const baseUrl = (process.env.GRASPFUL_API_URL || 'https://api.graspful.com').replace(/\/$/, '');
+    const baseUrl = (process.env.GRASPFUL_API_URL || 'https://api.graspful.ai').replace(/\/$/, '');
     const apiKey = process.env.GRASPFUL_API_KEY;
     if (apiKey) {
         return { baseUrl, authHeader: `Bearer ${apiKey}` };
@@ -226,9 +238,9 @@ function validateYaml(yamlStr) {
         return { valid: false, errors: ['Could not detect file type. Expected top-level key: course, brand, or academy'], stats: {} };
     }
     const schemaMap = {
-        course: schemas_1.CourseYamlSchema,
-        brand: schemas_1.BrandYamlSchema,
-        academy: schemas_1.AcademyManifestSchema,
+        course: shared_1.CourseYamlSchema,
+        brand: shared_1.BrandYamlSchema,
+        academy: shared_1.AcademyManifestSchema,
     };
     const result = schemaMap[fileType].safeParse(raw);
     if (!result.success) {
@@ -261,7 +273,7 @@ function validateYaml(yamlStr) {
 }
 // ─── Review helpers (mirrors packages/cli/src/commands/review.ts) ───────────
 function checkYamlParses(raw) {
-    const result = schemas_1.CourseYamlSchema.safeParse(raw);
+    const result = shared_1.CourseYamlSchema.safeParse(raw);
     if (result.success) {
         return { check: 'yaml_parses', passed: true };
     }
@@ -552,7 +564,7 @@ function runReview(yamlStr) {
             stats: { concepts: 0, kps: 0, problems: 0, authoredConcepts: 0, stubConcepts: 0 },
         };
     }
-    const data = schemas_1.CourseYamlSchema.parse(raw);
+    const data = shared_1.CourseYamlSchema.parse(raw);
     const authoredConcepts = data.concepts.filter((c) => c.knowledgePoints.length > 0);
     const stubConcepts = data.concepts.filter((c) => c.knowledgePoints.length === 0);
     const kps = data.concepts.reduce((sum, c) => sum + c.knowledgePoints.length, 0);
@@ -615,7 +627,7 @@ function computeGraphDepth(concepts) {
 }
 function describeCourse(yamlStr) {
     const raw = yaml.load(yamlStr);
-    const result = schemas_1.CourseYamlSchema.safeParse(raw);
+    const result = shared_1.CourseYamlSchema.safeParse(raw);
     if (!result.success) {
         throw new Error(`Invalid course YAML: ${result.error.issues[0]?.message ?? 'unknown error'}`);
     }
@@ -672,7 +684,7 @@ function describeCourse(yamlStr) {
 // ─── Fill concept helper (mirrors packages/cli/src/commands/fill-concept.ts) ─
 function fillConcept(yamlStr, conceptId, options) {
     const raw = yaml.load(yamlStr);
-    const parsed = schemas_1.CourseYamlSchema.safeParse(raw);
+    const parsed = shared_1.CourseYamlSchema.safeParse(raw);
     if (!parsed.success) {
         throw new Error(`Invalid course YAML: ${parsed.error.issues[0]?.message ?? 'unknown error'}`);
     }
@@ -816,7 +828,7 @@ A score of 10/10 is required for publishing. Run this before graspful_import_cou
         name: 'graspful_import_course',
         description: `Import a course YAML into a Graspful organization. Creates the course as a draft by default.
 
-Requires GRASPFUL_API_KEY environment variable to be set.
+IMPORTANT: Requires authentication. If not authenticated, call graspful_register first to create an account and get an API key, or set the GRASPFUL_API_KEY environment variable. Without auth, this tool will fail.
 
 If publish=true, the server runs the review gate first — the course must pass all 10 quality checks to be published. If review fails, the course is imported as a draft and failures are returned.
 
@@ -835,7 +847,7 @@ Returns { courseId, url, published, reviewFailures? }.`,
         name: 'graspful_publish_course',
         description: `Publish a draft course (sets isPublished = true). The server runs the review gate — course must pass all 10 quality checks.
 
-Requires GRASPFUL_API_KEY environment variable to be set.
+IMPORTANT: Requires authentication. If not authenticated, call graspful_register first to create an account and get an API key, or set the GRASPFUL_API_KEY environment variable. Without auth, this tool will fail.
 
 Returns { courseId, published }.`,
         inputSchema: {
@@ -895,7 +907,7 @@ Edit the YAML to customize, then import with graspful_import_brand.`,
         name: 'graspful_import_brand',
         description: `Import a brand YAML into Graspful. Creates the white-label site configuration.
 
-Requires GRASPFUL_API_KEY environment variable to be set.
+IMPORTANT: Requires authentication. If not authenticated, call graspful_register first to create an account and get an API key, or set the GRASPFUL_API_KEY environment variable. Without auth, this tool will fail.
 
 Returns { slug, domain, verificationStatus }.`,
         inputSchema: {
@@ -910,7 +922,7 @@ Returns { slug, domain, verificationStatus }.`,
         name: 'graspful_list_courses',
         description: `List all courses in a Graspful organization.
 
-Requires GRASPFUL_API_KEY environment variable to be set.
+IMPORTANT: Requires authentication. If not authenticated, call graspful_register first to create an account and get an API key, or set the GRASPFUL_API_KEY environment variable. Without auth, this tool will fail.
 
 Returns an array of courses with their IDs, names, published status, and stats.`,
         inputSchema: {
@@ -921,6 +933,24 @@ Returns an array of courses with their IDs, names, published status, and stats.`
             required: ['org'],
         },
     },
+    {
+        name: 'graspful_register',
+        description: `Create a new Graspful account and organization. Returns an API key that authenticates all subsequent tool calls.
+
+Call this BEFORE using graspful_import_course, graspful_publish_course, graspful_import_brand, or graspful_list_courses. Those tools require authentication and will fail without it.
+
+You do NOT need to register to use graspful_scaffold_course, graspful_fill_concept, graspful_validate, graspful_review_course, graspful_describe_course, or graspful_create_brand — those work offline.
+
+Returns { userId, orgSlug, apiKey }. The API key is automatically used for subsequent authenticated tool calls in this session.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                email: { type: 'string', description: 'Email address for the new account' },
+                password: { type: 'string', description: 'Password (min 8 characters)' },
+            },
+            required: ['email', 'password'],
+        },
+    },
 ];
 function textResult(text) {
     return { content: [{ type: 'text', text }] };
@@ -956,6 +986,7 @@ async function handleToolCall(name, args) {
         }
         case 'graspful_import_course': {
             try {
+                requireApiAuth();
                 const result = await apiPost(`/api/v1/orgs/${args.org}/courses/import`, { yaml: args.yaml, publish: args.publish ?? false });
                 return textResult(JSON.stringify(result, null, 2));
             }
@@ -965,6 +996,7 @@ async function handleToolCall(name, args) {
         }
         case 'graspful_publish_course': {
             try {
+                requireApiAuth();
                 const result = await apiPost(`/api/v1/orgs/${args.org}/courses/${args.courseId}/publish`, {});
                 return textResult(JSON.stringify(result, null, 2));
             }
@@ -991,6 +1023,7 @@ async function handleToolCall(name, args) {
         }
         case 'graspful_import_brand': {
             try {
+                requireApiAuth();
                 let raw;
                 try {
                     raw = yaml.load(args.yaml);
@@ -1007,6 +1040,7 @@ async function handleToolCall(name, args) {
         }
         case 'graspful_list_courses': {
             try {
+                requireApiAuth();
                 const result = await apiGet(`/api/v1/orgs/${args.org}/courses`);
                 return textResult(JSON.stringify(result, null, 2));
             }
@@ -1014,6 +1048,44 @@ async function handleToolCall(name, args) {
                 return errorResult(`List failed: ${e instanceof Error ? e.message : String(e)}`);
             }
         }
+        case 'graspful_register': {
+            try {
+                const email = args.email;
+                const password = args.password;
+                const { baseUrl } = getApiCredentials();
+                const res = await fetch(`${baseUrl}/api/v1/auth/register`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ email, password }),
+                });
+                if (!res.ok) {
+                    const text = await res.text();
+                    let message = `Registration failed (${res.status})`;
+                    try {
+                        const parsed = JSON.parse(text);
+                        if (parsed.message)
+                            message = parsed.message;
+                    }
+                    catch {
+                        if (text)
+                            message = text;
+                    }
+                    return errorResult(message);
+                }
+                const data = await res.json();
+                // Set the API key in the environment so subsequent tool calls are authenticated
+                process.env.GRASPFUL_API_KEY = data.apiKey;
+                return textResult(JSON.stringify({
+                    userId: data.userId,
+                    orgSlug: data.orgSlug,
+                    apiKey: data.apiKey,
+                    message: `Account created. Organization slug: ${data.orgSlug}. API key is now active for this session — you can call graspful_import_course, graspful_publish_course, and other authenticated tools.`,
+                }, null, 2));
+            }
+            catch (e) {
+                return errorResult(`Registration failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
         default:
             return errorResult(`Unknown tool: ${name}`);
     }