@graspful/mcp 0.2.3 → 0.2.5

package/dist/index.js

@@ -34,15 +34,25 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOLS = void 0;
+exports.mcpDistinctId = mcpDistinctId;
+exports.handleToolCall = handleToolCall;
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 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 posthog_node_1 = require("posthog-node");
+const node_crypto_1 = require("node:crypto");
 const shared_1 = require("@graspful/shared");
 // ─── PostHog analytics ──────────────────────────────────────────────────────
-const posthogKey = process.env.POSTHOG_API_KEY || process.env.NEXT_PUBLIC_POSTHOG_KEY;
+const DEFAULT_POSTHOG_KEY = 'phc_ahQLCJsOBzeuro1yDeurs1a3xx07pIreJWeXG9T4d4';
+const telemetryDisabled = process.env.GRASPFUL_TELEMETRY_DISABLED === '1' ||
+    process.env.NODE_ENV === 'test';
+const posthogKey = telemetryDisabled
+    ? null
+    : process.env.POSTHOG_API_KEY ||
+        process.env.NEXT_PUBLIC_POSTHOG_KEY ||
+        DEFAULT_POSTHOG_KEY;
 const posthogClient = posthogKey
     ? new posthog_node_1.PostHog(posthogKey, {
         host: process.env.POSTHOG_HOST || process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com',
@@ -50,8 +60,18 @@ const posthogClient = posthogKey
         flushInterval: 0,
     })
     : null;
+const anonymousMcpDistinctId = `anonymous-mcp:${(0, node_crypto_1.randomUUID)()}`;
 function mcpDistinctId() {
-    return process.env.GRASPFUL_USER_ID || process.env.GRASPFUL_API_KEY || 'anonymous-mcp';
+    if (process.env.GRASPFUL_USER_ID) {
+        return process.env.GRASPFUL_USER_ID;
+    }
+    if (process.env.GRASPFUL_API_KEY) {
+        const digest = (0, node_crypto_1.createHash)('sha256')
+            .update(process.env.GRASPFUL_API_KEY)
+            .digest('hex');
+        return `credential:${digest}`;
+    }
+    return anonymousMcpDistinctId;
 }
 function mcpCapture(event, properties = {}) {
     posthogClient?.capture({
@@ -72,7 +92,7 @@ function requireApiAuth() {
         throw new Error(AUTH_REQUIRED_ERROR);
     }
 }
-// ─── API Client (mirrors packages/cli/src/lib/api-client.ts) ──────────────
+// ─── API Client ─────────────────────────────────────────────────────────────
 function getApiCredentials() {
     const baseUrl = (process.env.GRASPFUL_API_URL || 'https://api.graspful.ai').replace(/\/$/, '');
     const apiKey = process.env.GRASPFUL_API_KEY;
@@ -81,15 +101,15 @@ function getApiCredentials() {
     }
     return { baseUrl };
 }
-async function apiPost(path, body) {
+async function apiFetch(method, path, body) {
     const { baseUrl, authHeader } = getApiCredentials();
     const headers = { 'Content-Type': 'application/json' };
     if (authHeader)
         headers['Authorization'] = authHeader;
     const res = await fetch(`${baseUrl}${path}`, {
-        method: 'POST',
+        method,
         headers,
-        body: JSON.stringify(body),
+        body: body !== undefined ? JSON.stringify(body) : undefined,
     });
     if (!res.ok) {
         const text = await res.text();
@@ -97,658 +117,34 @@ async function apiPost(path, body) {
     }
     return res.json();
 }
-async function apiGet(path) {
-    const { baseUrl, authHeader } = getApiCredentials();
-    const headers = { 'Content-Type': 'application/json' };
-    if (authHeader)
-        headers['Authorization'] = authHeader;
-    const res = await fetch(`${baseUrl}${path}`, {
-        method: 'GET',
-        headers,
-    });
-    if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`API error ${res.status}: ${text}`);
-    }
-    return res.json();
+// ─── YAML helpers ───────────────────────────────────────────────────────────
+const YAML_DUMP_OPTS = { lineWidth: 120, noRefs: true };
+function parseYaml(yamlStr) {
+    return yaml.load(yamlStr);
 }
-// ─── Scaffold helpers (mirrors packages/cli/src/commands/create-course.ts) ──
-function scaffoldCourse(topic, options) {
-    const slug = topic.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
-    return yaml.dump({
-        course: {
-            id: slug,
-            name: topic,
-            description: `Adaptive course on ${topic}`,
-            estimatedHours: options.hours || 10,
-            version: '2026.1',
-            sourceDocument: options.source || 'TODO: Add source document',
-        },
-        sections: [
-            { id: 'foundations', name: 'Foundations', description: 'Core concepts' },
-            { id: 'application', name: 'Application', description: 'Applied concepts' },
-        ],
-        concepts: [
-            {
-                id: `${slug}-intro`,
-                name: `Introduction to ${topic}`,
-                section: 'foundations',
-                difficulty: 2,
-                estimatedMinutes: 15,
-                tags: ['foundational'],
-                prerequisites: [],
-                knowledgePoints: [],
-            },
-        ],
-    }, { lineWidth: 120, noRefs: true });
+function dumpYaml(obj) {
+    return yaml.dump(obj, YAML_DUMP_OPTS);
 }
-function scaffoldBrand(niche, options) {
-    const NICHE_PRESETS = {
-        education: { preset: 'blue', tagline: 'Learn smarter, not harder', headline: 'Master any subject with adaptive learning' },
-        healthcare: { preset: 'emerald', tagline: 'Training that saves lives', headline: 'Adaptive healthcare education for professionals' },
-        finance: { preset: 'slate', tagline: 'Build financial expertise', headline: 'Master finance with adaptive learning' },
-        tech: { preset: 'indigo', tagline: 'Level up your skills', headline: 'Adaptive tech training that meets you where you are' },
-        legal: { preset: 'amber', tagline: 'Know the law, pass the exam', headline: 'Adaptive legal education for exam success' },
-        default: { preset: 'blue', tagline: 'Learn adaptively', headline: 'Personalized learning that works' },
-    };
-    const config = NICHE_PRESETS[niche] || NICHE_PRESETS['default'];
-    const slug = (options.name || niche).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
-    const name = options.name || `${niche.charAt(0).toUpperCase() + niche.slice(1)} Academy`;
-    const domain = options.domain || `${slug}.graspful.ai`;
-    return yaml.dump({
-        brand: {
-            id: slug,
-            name,
-            domain,
-            tagline: config.tagline,
-            orgSlug: options.orgSlug || 'TODO: your-org-slug',
-        },
-        theme: {
-            preset: config.preset,
-            radius: '0.5rem',
-        },
-        landing: {
-            hero: {
-                headline: config.headline,
-                subheadline: `${name} uses adaptive learning to help you master concepts faster.`,
-                ctaText: 'Start Learning',
-            },
-            features: {
-                heading: 'Why choose us?',
-                items: [
-                    { title: 'Adaptive Learning', description: 'Content adapts to your knowledge level', icon: 'brain' },
-                    { title: 'Spaced Repetition', description: 'Review at optimal intervals for lasting memory', icon: 'clock' },
-                    { title: 'Progress Tracking', description: 'See exactly where you stand', icon: 'chart' },
-                ],
-            },
-            howItWorks: {
-                heading: 'How it works',
-                items: [
-                    { title: 'Take a diagnostic', description: 'We assess what you already know' },
-                    { title: 'Learn adaptively', description: 'Focus on gaps, skip what you know' },
-                    { title: 'Master the material', description: 'Prove mastery through progressive challenges' },
-                ],
+const TOOLS = [
+    {
+        name: 'graspful_create_academy',
+        description: `Generate an academy plan and manifest scaffold for an academy-first workflow. Every academy is a connected curriculum made of one or more real courses.
+
+Use this before authoring course YAML when the topic should be decomposed into learner-facing parts. If you do not pass courseNames, the scaffold creates the four default planning layers: foundations, core structures, operational flows, and applied judgment. The result includes authoring gates for source material, learner promise, landing-page proof, graph checks, and review before publishing.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                topic: { type: 'string', description: 'Academy topic name (e.g., "PostHog TAM", "Linear Algebra")' },
+                courseNames: {
+                    type: 'array',
+                    description: 'Optional ordered course names to include in the manifest',
+                    items: { type: 'string' },
+                },
+                version: { type: 'string', description: 'Academy version string (default: 2026.1)' },
             },
-            faq: [],
-        },
-        seo: {
-            title: `${name} — Adaptive Learning`,
-            description: config.tagline,
-            keywords: [niche, 'learning', 'adaptive', 'education'],
+            required: ['topic'],
         },
-    }, { lineWidth: 120, noRefs: true });
-}
-function detectFileType(data) {
-    if (typeof data !== 'object' || data === null)
-        return null;
-    const obj = data;
-    if ('course' in obj)
-        return 'course';
-    if ('brand' in obj)
-        return 'brand';
-    if ('academy' in obj)
-        return 'academy';
-    return null;
-}
-function detectCycles(concepts) {
-    const graph = new Map();
-    for (const c of concepts) {
-        graph.set(c.id, c.prerequisites);
-    }
-    const visited = new Set();
-    const inStack = new Set();
-    const cycles = [];
-    function dfs(node, path) {
-        if (inStack.has(node)) {
-            const cycleStart = path.indexOf(node);
-            const cycle = path.slice(cycleStart).concat(node);
-            cycles.push(`Cycle: ${cycle.join(' -> ')}`);
-            return true;
-        }
-        if (visited.has(node))
-            return false;
-        visited.add(node);
-        inStack.add(node);
-        path.push(node);
-        for (const dep of graph.get(node) ?? []) {
-            dfs(dep, path);
-        }
-        path.pop();
-        inStack.delete(node);
-        return false;
-    }
-    for (const id of graph.keys()) {
-        if (!visited.has(id)) {
-            dfs(id, []);
-        }
-    }
-    return cycles;
-}
-function validateYaml(yamlStr) {
-    let raw;
-    try {
-        raw = yaml.load(yamlStr);
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        return { valid: false, errors: [`YAML parse error: ${msg}`], stats: {} };
-    }
-    const fileType = detectFileType(raw);
-    if (!fileType) {
-        return { valid: false, errors: ['Could not detect file type. Expected top-level key: course, brand, or academy'], stats: {} };
-    }
-    const schemaMap = {
-        course: shared_1.CourseYamlSchema,
-        brand: shared_1.BrandYamlSchema,
-        academy: shared_1.AcademyManifestSchema,
-    };
-    const result = schemaMap[fileType].safeParse(raw);
-    if (!result.success) {
-        const errors = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
-        return { valid: false, fileType, errors, stats: {} };
-    }
-    // For courses, also check DAG
-    const dagErrors = [];
-    let stats = { fileType };
-    if (fileType === 'course') {
-        const data = result.data;
-        const conceptIds = new Set(data.concepts.map((c) => c.id));
-        for (const concept of data.concepts) {
-            for (const prereq of concept.prerequisites) {
-                if (!conceptIds.has(prereq)) {
-                    dagErrors.push(`Concept "${concept.id}" has unknown prerequisite "${prereq}"`);
-                }
-            }
-        }
-        const cycles = detectCycles(data.concepts.map((c) => ({ id: c.id, prerequisites: c.prerequisites })));
-        dagErrors.push(...cycles);
-        const kpCount = data.concepts.reduce((sum, c) => sum + c.knowledgePoints.length, 0);
-        const problemCount = data.concepts.reduce((sum, c) => sum + c.knowledgePoints.reduce((s, kp) => s + kp.problems.length, 0), 0);
-        stats = { fileType, concepts: data.concepts.length, knowledgePoints: kpCount, problems: problemCount };
-    }
-    if (dagErrors.length > 0) {
-        return { valid: false, fileType, errors: dagErrors, stats };
-    }
-    return { valid: true, fileType, errors: [], stats };
-}
-// ─── Review helpers (mirrors packages/cli/src/commands/review.ts) ───────────
-function checkYamlParses(raw) {
-    const result = shared_1.CourseYamlSchema.safeParse(raw);
-    if (result.success) {
-        return { check: 'yaml_parses', passed: true };
-    }
-    const errors = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
-    return {
-        check: 'yaml_parses',
-        passed: false,
-        details: `${errors.length} schema error(s): ${errors.slice(0, 5).join('; ')}${errors.length > 5 ? ` (+${errors.length - 5} more)` : ''}`,
-    };
-}
-function checkUniqueProblemIds(data) {
-    const duplicates = [];
-    const seen = new Set();
-    for (const concept of data.concepts) {
-        for (const kp of concept.knowledgePoints) {
-            for (const problem of kp.problems) {
-                if (seen.has(problem.id)) {
-                    duplicates.push(problem.id);
-                }
-                seen.add(problem.id);
-            }
-        }
-    }
-    if (duplicates.length === 0) {
-        return { check: 'unique_problem_ids', passed: true };
-    }
-    return {
-        check: 'unique_problem_ids',
-        passed: false,
-        details: `Duplicate problem IDs: ${duplicates.join(', ')}`,
-    };
-}
-function checkPrerequisitesValid(data) {
-    const conceptIds = new Set(data.concepts.map((c) => c.id));
-    const invalid = [];
-    for (const concept of data.concepts) {
-        for (const prereq of concept.prerequisites) {
-            if (!conceptIds.has(prereq)) {
-                invalid.push(`${concept.id} -> ${prereq}`);
-            }
-        }
-    }
-    if (invalid.length === 0) {
-        return { check: 'prerequisites_valid', passed: true };
-    }
-    return {
-        check: 'prerequisites_valid',
-        passed: false,
-        details: `Unknown prerequisites: ${invalid.join(', ')}`,
-    };
-}
-function normalizeText(text) {
-    return text.toLowerCase().replace(/[^a-z0-9\s]/g, '').replace(/\s+/g, ' ').trim();
-}
-function checkQuestionDeduplication(data) {
-    const seen = new Map();
-    const collisions = [];
-    for (const concept of data.concepts) {
-        for (const kp of concept.knowledgePoints) {
-            for (const problem of kp.problems) {
-                const normalized = normalizeText(problem.question);
-                const hash = crypto.createHash('md5').update(normalized).digest('hex').substring(0, 12);
-                const key = `${hash}-d${problem.difficulty ?? 'none'}`;
-                const existing = seen.get(key);
-                if (existing) {
-                    collisions.push(`"${problem.id}" collides with "${existing.problemId}" (same question text at same difficulty)`);
-                }
-                else {
-                    seen.set(key, { problemId: problem.id });
-                }
-            }
-        }
-    }
-    if (collisions.length === 0) {
-        return { check: 'question_deduplication', passed: true };
-    }
-    return {
-        check: 'question_deduplication',
-        passed: false,
-        details: collisions.slice(0, 5).join('; ') + (collisions.length > 5 ? ` (+${collisions.length - 5} more)` : ''),
-    };
-}
-function checkDifficultyStaircase(data) {
-    const failures = [];
-    for (const concept of data.concepts) {
-        if (concept.knowledgePoints.length === 0)
-            continue;
-        const difficulties = new Set();
-        for (const kp of concept.knowledgePoints) {
-            for (const problem of kp.problems) {
-                if (problem.difficulty != null) {
-                    difficulties.add(problem.difficulty);
-                }
-            }
-        }
-        if (difficulties.size > 0 && difficulties.size < 2) {
-            failures.push(`"${concept.id}" has problems at only ${difficulties.size} difficulty level(s) — need 2+`);
-        }
-    }
-    if (failures.length === 0) {
-        return { check: 'difficulty_staircase', passed: true };
-    }
-    return {
-        check: 'difficulty_staircase',
-        passed: false,
-        details: failures.slice(0, 5).join('; ') + (failures.length > 5 ? ` (+${failures.length - 5} more)` : ''),
-    };
-}
-function extractStems(text) {
-    return text.toLowerCase().replace(/[^a-z0-9\s]/g, '').split(/\s+/).filter((w) => w.length > 4);
-}
-function checkCrossConceptCoverage(data) {
-    const stemConceptCount = new Map();
-    for (const concept of data.concepts) {
-        for (const kp of concept.knowledgePoints) {
-            for (const problem of kp.problems) {
-                const stems = extractStems(problem.question);
-                for (const stem of stems) {
-                    if (!stemConceptCount.has(stem)) {
-                        stemConceptCount.set(stem, new Set());
-                    }
-                    stemConceptCount.get(stem).add(concept.id);
-                }
-            }
-        }
-    }
-    const overused = [];
-    for (const [stem, concepts] of stemConceptCount) {
-        if (concepts.size > 3) {
-            overused.push(`"${stem}" appears across ${concepts.size} concepts`);
-        }
-    }
-    const commonWords = new Set([
-        'which', 'would', 'should', 'could', 'about', 'their', 'there', 'these', 'those',
-        'being', 'between', 'through', 'during', 'before', 'after', 'above', 'below',
-        'following', 'statement', 'answer', 'question', 'correct', 'incorrect',
-        'agent', 'property', 'owner', 'buyer', 'seller',
-    ]);
-    const meaningfulOverused = overused.filter((entry) => {
-        const stem = entry.match(/"([^"]+)"/)?.[1] ?? '';
-        return !commonWords.has(stem);
-    });
-    if (meaningfulOverused.length === 0) {
-        return { check: 'cross_concept_coverage', passed: true };
-    }
-    return {
-        check: 'cross_concept_coverage',
-        passed: meaningfulOverused.length <= 5,
-        details: meaningfulOverused.slice(0, 5).join('; ') + (meaningfulOverused.length > 5 ? ` (+${meaningfulOverused.length - 5} more)` : ''),
-    };
-}
-function checkProblemVariantDepth(data) {
-    const failures = [];
-    for (const concept of data.concepts) {
-        if (concept.knowledgePoints.length === 0)
-            continue;
-        for (const kp of concept.knowledgePoints) {
-            if (kp.problems.length < 3) {
-                failures.push(`"${concept.id}/${kp.id}" has ${kp.problems.length} problem(s) — need 3+`);
-            }
-        }
-    }
-    if (failures.length === 0) {
-        return { check: 'problem_variant_depth', passed: true };
-    }
-    return {
-        check: 'problem_variant_depth',
-        passed: false,
-        details: failures.slice(0, 5).join('; ') + (failures.length > 5 ? ` (+${failures.length - 5} more)` : ''),
-    };
-}
-function checkInstructionFormatting(data) {
-    const warnings = [];
-    for (const concept of data.concepts) {
-        for (const kp of concept.knowledgePoints) {
-            if (!kp.instruction)
-                continue;
-            if (kp.instruction.match(/^[\w\-./]+\.(md|txt|html)$/))
-                continue;
-            const wordCount = kp.instruction.split(/\s+/).filter(Boolean).length;
-            const hasContentBlocks = kp.instructionContent && kp.instructionContent.length > 0;
-            if (wordCount > 100 && !hasContentBlocks) {
-                warnings.push(`"${concept.id}/${kp.id}" instruction is ${wordCount} words with no content blocks`);
-            }
-        }
-    }
-    if (warnings.length === 0) {
-        return { check: 'instruction_formatting', passed: true };
-    }
-    return {
-        check: 'instruction_formatting',
-        passed: false,
-        details: warnings.slice(0, 5).join('; ') + (warnings.length > 5 ? ` (+${warnings.length - 5} more)` : ''),
-    };
-}
-function checkWorkedExampleCoverage(data) {
-    const authoredConcepts = data.concepts.filter((c) => c.knowledgePoints.length > 0);
-    if (authoredConcepts.length === 0) {
-        return { check: 'worked_example_coverage', passed: true };
-    }
-    const withExamples = authoredConcepts.filter((c) => c.knowledgePoints.some((kp) => kp.workedExample && kp.workedExample.trim().length > 0));
-    const coverage = withExamples.length / authoredConcepts.length;
-    if (coverage >= 0.5) {
-        return { check: 'worked_example_coverage', passed: true };
-    }
-    return {
-        check: 'worked_example_coverage',
-        passed: false,
-        details: `${withExamples.length}/${authoredConcepts.length} authored concepts have worked examples (${Math.round(coverage * 100)}%) — need 50%+`,
-    };
-}
-function checkImportDryRun(data) {
-    const conceptIds = new Set(data.concepts.map((c) => c.id));
-    const errors = [];
-    for (const concept of data.concepts) {
-        for (const prereq of concept.prerequisites) {
-            if (!conceptIds.has(prereq)) {
-                errors.push(`Unknown prerequisite: ${concept.id} -> ${prereq}`);
-            }
-        }
-    }
-    const graph = new Map();
-    for (const c of data.concepts) {
-        graph.set(c.id, [...c.prerequisites]);
-    }
-    const visited = new Set();
-    const inStack = new Set();
-    function hasCycle(node, path) {
-        if (inStack.has(node)) {
-            const cycleStart = path.indexOf(node);
-            const cycle = path.slice(cycleStart).concat(node);
-            errors.push(`Cycle detected: ${cycle.join(' -> ')}`);
-            return true;
-        }
-        if (visited.has(node))
-            return false;
-        visited.add(node);
-        inStack.add(node);
-        path.push(node);
-        let foundCycle = false;
-        for (const dep of graph.get(node) ?? []) {
-            if (hasCycle(dep, path)) {
-                foundCycle = true;
-            }
-        }
-        path.pop();
-        inStack.delete(node);
-        return foundCycle;
-    }
-    for (const id of graph.keys()) {
-        if (!visited.has(id)) {
-            hasCycle(id, []);
-        }
-    }
-    if (errors.length === 0) {
-        return { check: 'import_dry_run', passed: true };
-    }
-    return {
-        check: 'import_dry_run',
-        passed: false,
-        details: errors.join('; '),
-    };
-}
-function runReview(yamlStr) {
-    let raw;
-    try {
-        raw = yaml.load(yamlStr);
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        return {
-            passed: false,
-            score: '0/10',
-            failures: [{ check: 'yaml_parses', passed: false, details: `YAML parse error: ${msg}` }],
-            warnings: [],
-            stats: { concepts: 0, kps: 0, problems: 0, authoredConcepts: 0, stubConcepts: 0 },
-        };
-    }
-    const checks = [];
-    const parseCheck = checkYamlParses(raw);
-    checks.push(parseCheck);
-    if (!parseCheck.passed) {
-        return {
-            passed: false,
-            score: '0/10',
-            failures: checks.filter((c) => !c.passed),
-            warnings: [],
-            stats: { concepts: 0, kps: 0, problems: 0, authoredConcepts: 0, stubConcepts: 0 },
-        };
-    }
-    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);
-    const problems = data.concepts.reduce((sum, c) => sum + c.knowledgePoints.reduce((s, kp) => s + kp.problems.length, 0), 0);
-    const stats = {
-        concepts: data.concepts.length,
-        kps,
-        problems,
-        authoredConcepts: authoredConcepts.length,
-        stubConcepts: stubConcepts.length,
-    };
-    checks.push(checkUniqueProblemIds(data));
-    checks.push(checkPrerequisitesValid(data));
-    checks.push(checkQuestionDeduplication(data));
-    checks.push(checkDifficultyStaircase(data));
-    checks.push(checkCrossConceptCoverage(data));
-    checks.push(checkProblemVariantDepth(data));
-    checks.push(checkInstructionFormatting(data));
-    checks.push(checkWorkedExampleCoverage(data));
-    checks.push(checkImportDryRun(data));
-    const passedCount = checks.filter((c) => c.passed).length;
-    const failures = checks.filter((c) => !c.passed);
-    return {
-        passed: failures.length === 0,
-        score: `${passedCount}/10`,
-        failures,
-        warnings: [],
-        stats,
-    };
-}
-// ─── Describe helper (mirrors packages/cli/src/commands/describe.ts) ────────
-function computeGraphDepth(concepts) {
-    const graph = new Map();
-    for (const c of concepts) {
-        graph.set(c.id, c.prerequisites);
-    }
-    const memo = new Map();
-    function depth(id, visited) {
-        if (memo.has(id))
-            return memo.get(id);
-        if (visited.has(id))
-            return 0;
-        visited.add(id);
-        const prereqs = graph.get(id) ?? [];
-        let maxPrereqDepth = 0;
-        for (const prereq of prereqs) {
-            if (graph.has(prereq)) {
-                maxPrereqDepth = Math.max(maxPrereqDepth, depth(prereq, visited));
-            }
-        }
-        const d = maxPrereqDepth + 1;
-        memo.set(id, d);
-        return d;
-    }
-    let maxDepth = 0;
-    for (const c of concepts) {
-        maxDepth = Math.max(maxDepth, depth(c.id, new Set()));
-    }
-    return maxDepth;
-}
-function describeCourse(yamlStr) {
-    const raw = yaml.load(yamlStr);
-    const result = shared_1.CourseYamlSchema.safeParse(raw);
-    if (!result.success) {
-        throw new Error(`Invalid course YAML: ${result.error.issues[0]?.message ?? 'unknown error'}`);
-    }
-    const data = result.data;
-    const concepts = data.concepts;
-    const sections = data.sections;
-    const authoredConcepts = concepts.filter((c) => c.knowledgePoints.length > 0);
-    const stubConcepts = concepts.filter((c) => c.knowledgePoints.length === 0);
-    const kpCount = concepts.reduce((sum, c) => sum + c.knowledgePoints.length, 0);
-    const problemCount = concepts.reduce((sum, c) => sum + c.knowledgePoints.reduce((s, kp) => s + kp.problems.length, 0), 0);
-    const graphDepth = computeGraphDepth(concepts);
-    const conceptsWithoutKps = stubConcepts.map((c) => c.id);
-    const kpsWithoutProblems = [];
-    for (const c of concepts) {
-        for (const kp of c.knowledgePoints) {
-            if (kp.problems.length === 0) {
-                kpsWithoutProblems.push(`${c.id}/${kp.id}`);
-            }
-        }
-    }
-    const sectionBreakdown = [];
-    if (sections.length > 0) {
-        for (const section of sections) {
-            const sectionConcepts = concepts.filter((c) => c.section === section.id);
-            const sKps = sectionConcepts.reduce((sum, c) => sum + c.knowledgePoints.length, 0);
-            const sProblems = sectionConcepts.reduce((sum, c) => sum + c.knowledgePoints.reduce((s, kp) => s + kp.problems.length, 0), 0);
-            sectionBreakdown.push({ section: section.id, concepts: sectionConcepts.length, kps: sKps, problems: sProblems });
-        }
-        const unsectioned = concepts.filter((c) => !c.section);
-        if (unsectioned.length > 0) {
-            const uKps = unsectioned.reduce((sum, c) => sum + c.knowledgePoints.length, 0);
-            const uProblems = unsectioned.reduce((sum, c) => sum + c.knowledgePoints.reduce((s, kp) => s + kp.problems.length, 0), 0);
-            sectionBreakdown.push({ section: '(unsectioned)', concepts: unsectioned.length, kps: uKps, problems: uProblems });
-        }
-    }
-    return {
-        courseName: data.course.name,
-        courseId: data.course.id,
-        version: data.course.version,
-        estimatedHours: data.course.estimatedHours,
-        concepts: concepts.length,
-        authoredConcepts: authoredConcepts.length,
-        stubConcepts: stubConcepts.length,
-        knowledgePoints: kpCount,
-        problems: problemCount,
-        graphDepth,
-        conceptsWithoutKps: conceptsWithoutKps.length,
-        conceptsWithoutKpsList: conceptsWithoutKps,
-        kpsWithoutProblems: kpsWithoutProblems.length,
-        kpsWithoutProblemsList: kpsWithoutProblems,
-        sections: sectionBreakdown,
-    };
-}
-// ─── Fill concept helper (mirrors packages/cli/src/commands/fill-concept.ts) ─
-function fillConcept(yamlStr, conceptId, options) {
-    const raw = yaml.load(yamlStr);
-    const parsed = shared_1.CourseYamlSchema.safeParse(raw);
-    if (!parsed.success) {
-        throw new Error(`Invalid course YAML: ${parsed.error.issues[0]?.message ?? 'unknown error'}`);
-    }
-    const data = parsed.data;
-    const concept = data.concepts.find((c) => c.id === conceptId);
-    if (!concept) {
-        throw new Error(`Concept "${conceptId}" not found. Available: ${data.concepts.map((c) => c.id).join(', ')}`);
-    }
-    if (concept.knowledgePoints.length > 0) {
-        throw new Error(`Concept "${conceptId}" already has ${concept.knowledgePoints.length} KP(s). Remove them first to regenerate.`);
-    }
-    const kpCount = options.kps ?? 2;
-    const problemsPerKp = options.problemsPerKp ?? 3;
-    const newKps = [];
-    for (let i = 1; i <= kpCount; i++) {
-        const problems = [];
-        for (let j = 1; j <= problemsPerKp; j++) {
-            problems.push({
-                id: `${conceptId}-kp${i}-p${j}`,
-                type: 'multiple_choice',
-                question: `TODO: Write question ${j} for ${conceptId} KP${i}`,
-                options: ['Option A', 'Option B', 'Option C', 'Option D'],
-                correct: 0,
-                explanation: 'TODO: Explain the correct answer',
-                difficulty: Math.min(j + 1, 5),
-            });
-        }
-        newKps.push({
-            id: `${conceptId}-kp${i}`,
-            instruction: `TODO: Write instruction for ${concept.name} — knowledge point ${i}`,
-            workedExample: `TODO: Write a worked example for ${concept.name} — knowledge point ${i}`,
-            problems,
-        });
-    }
-    // Rebuild the raw object to preserve structure
-    const rawObj = raw;
-    const concepts = rawObj['concepts'];
-    const targetConcept = concepts.find((c) => c['id'] === conceptId);
-    if (targetConcept) {
-        targetConcept['knowledgePoints'] = newKps;
-    }
-    return yaml.dump(rawObj, { lineWidth: 120, noRefs: true });
-}
-const TOOLS = [
+    },
     {
         name: 'graspful_scaffold_course',
         description: `Generate a course YAML skeleton with sections, concepts, and prerequisite edges. Returns a minimal valid YAML structure with TODO placeholders.
@@ -793,7 +189,7 @@ Fails if the concept already has KPs (to prevent accidental overwrites).`,
             properties: {
                 yaml: { type: 'string', description: 'The full course YAML string' },
                 conceptId: { type: 'string', description: 'ID of the concept to fill (must exist in the YAML and have 0 KPs)' },
-                kps: { type: 'number', description: 'Number of KP stubs to add (default: 2)' },
+                kps: { type: 'number', description: 'Number of KP stubs to add as a starting point (default: 3, not a cap)' },
                 problemsPerKp: { type: 'number', description: 'Number of problem stubs per KP (default: 3)' },
             },
             required: ['yaml', 'conceptId'],
@@ -829,7 +225,7 @@ The 10 checks are:
 3. prerequisites_valid — All prerequisite refs point to real concepts
 4. question_deduplication — No near-duplicate questions at the same difficulty
 5. difficulty_staircase — Each concept has problems at 2+ difficulty levels
-6. cross_concept_coverage — No single term dominates too many concepts
+6. problem_teaching_alignment — Problems only assess material introduced in the current lesson path
 7. problem_variant_depth — Each KP has 3+ problems
 8. instruction_formatting — Long instructions have content blocks
 9. worked_example_coverage — 50%+ of authored concepts have worked examples
@@ -844,6 +240,29 @@ A score of 10/10 is required for publishing. Run this before graspful_import_cou
             required: ['yaml'],
         },
     },
+    {
+        name: 'graspful_import_academy',
+        description: `Import an academy manifest and its referenced course YAMLs into a Graspful organization.
+
+IMPORTANT: Requires authentication. If not authenticated, run \`graspful register\` in a terminal first or set the \`GRASPFUL_API_KEY\` environment variable. Without auth, this tool will fail.
+
+If publish=true, Graspful imports the academy first and then attempts to publish each imported course. Returns the academy result plus publishedCourseIds and publishFailures.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                manifestYaml: { type: 'string', description: 'The full academy manifest YAML string' },
+                courseYamls: {
+                    type: 'object',
+                    description: 'Object mapping manifest file paths to the full course YAML strings',
+                },
+                org: { type: 'string', description: 'Organization slug (e.g., "acme-learning")' },
+                publish: { type: 'boolean', description: 'If true, publish every imported course after academy import. Default: false' },
+                replace: { type: 'boolean', description: 'Replace existing academy/course content on re-import. Default: false' },
+                archiveMissing: { type: 'boolean', description: 'Archive removed content on re-import. Default: false' },
+            },
+            required: ['manifestYaml', 'courseYamls', 'org'],
+        },
+    },
     {
         name: 'graspful_import_course',
         description: `Import a course YAML into a Graspful organization. Creates the course as a draft by default.
@@ -917,6 +336,7 @@ Edit the YAML to customize, then import with \`graspful_import_brand\`.`,
             properties: {
                 niche: { type: 'string', description: 'Brand niche: education, healthcare, finance, tech, or legal' },
                 name: { type: 'string', description: 'Brand name (default: "{Niche} Academy")' },
+                topic: { type: 'string', description: 'Academy topic for more specific landing-page copy' },
                 domain: { type: 'string', description: 'Custom domain (default: "{slug}.graspful.ai")' },
                 orgSlug: { type: 'string', description: 'Organization slug to associate with' },
             },
@@ -954,6 +374,7 @@ Returns an array of courses with their IDs, names, published status, and stats.`
         },
     },
 ];
+exports.TOOLS = TOOLS;
 function textResult(text) {
     return { content: [{ type: 'text', text }] };
 }
@@ -962,39 +383,113 @@ function errorResult(text) {
 }
 async function handleToolCall(name, args) {
     switch (name) {
+        case 'graspful_create_academy': {
+            const topic = args.topic;
+            const obj = (0, shared_1.scaffoldAcademyObject)(topic, {
+                courseNames: args.courseNames,
+                version: args.version,
+            });
+            mcpCapture('academy scaffolded', { topic, course_count: obj.courses.length });
+            return textResult(dumpYaml(obj));
+        }
         case 'graspful_scaffold_course': {
             const topic = args.topic;
-            const estimatedHours = args.estimatedHours;
-            const sourceDocument = args.sourceDocument;
-            const yamlContent = scaffoldCourse(topic, { hours: estimatedHours, source: sourceDocument });
-            mcpCapture('course scaffolded', { topic, estimated_hours: estimatedHours });
-            return textResult(yamlContent);
+            const obj = (0, shared_1.scaffoldCourseObject)(topic, {
+                hours: args.estimatedHours,
+                source: args.sourceDocument,
+            });
+            mcpCapture('course scaffolded', { topic, estimated_hours: args.estimatedHours });
+            return textResult(dumpYaml(obj));
         }
         case 'graspful_fill_concept': {
             try {
                 const conceptId = args.conceptId;
-                const updatedYaml = fillConcept(args.yaml, conceptId, { kps: args.kps, problemsPerKp: args.problemsPerKp });
+                const raw = parseYaml(args.yaml);
+                const updated = (0, shared_1.fillConceptInRaw)(raw, conceptId, {
+                    kps: args.kps,
+                    problemsPerKp: args.problemsPerKp,
+                });
                 mcpCapture('concept filled', { concept_id: conceptId });
-                return textResult(updatedYaml);
+                return textResult(dumpYaml(updated));
             }
             catch (e) {
                 return errorResult(e instanceof Error ? e.message : String(e));
             }
         }
         case 'graspful_validate': {
-            const result = validateYaml(args.yaml);
+            let raw;
+            try {
+                raw = parseYaml(args.yaml);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return textResult(JSON.stringify({ valid: false, errors: [`YAML parse error: ${msg}`], stats: {} }, null, 2));
+            }
+            const result = (0, shared_1.validateParsedYaml)(raw);
             mcpCapture('course validated', { valid: result.valid, error_count: result.errors.length, file_type: result.fileType });
             return textResult(JSON.stringify(result, null, 2));
         }
         case 'graspful_review_course': {
-            const result = runReview(args.yaml);
+            let raw;
+            try {
+                raw = parseYaml(args.yaml);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return textResult(JSON.stringify({
+                    passed: false,
+                    score: '0/10',
+                    failures: [{ check: 'yaml_parses', passed: false, details: `YAML parse error: ${msg}` }],
+                    warnings: [],
+                    stats: { concepts: 0, kps: 0, problems: 0, authoredConcepts: 0, stubConcepts: 0 },
+                }, null, 2));
+            }
+            const result = (0, shared_1.runQualityGate)(raw);
             mcpCapture('course reviewed', { score: result.score, passed: result.passed });
             return textResult(JSON.stringify(result, null, 2));
         }
+        case 'graspful_import_academy': {
+            try {
+                requireApiAuth();
+                const result = await apiFetch('POST', `/api/v1/orgs/${args.org}/academies/import`, {
+                    manifestYaml: args.manifestYaml,
+                    courseYamls: args.courseYamls,
+                    replace: args.replace ?? false,
+                    archiveMissing: args.archiveMissing ?? false,
+                });
+                const publishedCourseIds = [];
+                const publishFailures = [];
+                if (args.publish) {
+                    for (const courseResult of result.courseResults) {
+                        try {
+                            await apiFetch('POST', `/api/v1/orgs/${args.org}/courses/${courseResult.courseId}/publish`, {});
+                            publishedCourseIds.push(courseResult.courseId);
+                        }
+                        catch (error) {
+                            publishFailures.push(`${courseResult.courseId}: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
+                mcpCapture('academy imported', {
+                    academy_id: result.academyId,
+                    org: args.org,
+                    course_count: result.courseCount,
+                    published_count: publishedCourseIds.length,
+                });
+                return textResult(JSON.stringify({
+                    ...result,
+                    publishedCourseIds,
+                    publishFailures,
+                }, null, 2));
+            }
+            catch (e) {
+                return errorResult(`Academy import failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
         case 'graspful_import_course': {
             try {
                 requireApiAuth();
-                const result = await apiPost(`/api/v1/orgs/${args.org}/courses/import`, { yaml: args.yaml, publish: args.publish ?? false });
+                const result = await apiFetch('POST', `/api/v1/orgs/${args.org}/courses/import`, { yaml: args.yaml, publish: args.publish ?? false });
                 mcpCapture('course imported', { course_id: result.courseId, org: args.org, published: result.published });
                 return textResult(JSON.stringify(result, null, 2));
             }
@@ -1005,7 +500,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`, {});
+                const result = await apiFetch('POST', `/api/v1/orgs/${args.org}/courses/${args.courseId}/publish`, {});
                 mcpCapture('course published', { course_id: result.courseId, org: args.org, published: result.published });
                 return textResult(JSON.stringify(result, null, 2));
             }
@@ -1015,7 +510,9 @@ async function handleToolCall(name, args) {
         }
         case 'graspful_describe_course': {
             try {
-                const stats = describeCourse(args.yaml);
+                const raw = parseYaml(args.yaml);
+                const parsed = shared_1.CourseYamlSchema.parse(raw);
+                const stats = (0, shared_1.describeCourse)(parsed);
                 mcpCapture('course described', stats);
                 return textResult(JSON.stringify(stats, null, 2));
             }
@@ -1025,25 +522,25 @@ async function handleToolCall(name, args) {
         }
         case 'graspful_create_brand': {
             const niche = args.niche;
-            const yamlContent = scaffoldBrand(niche, {
+            const obj = (0, shared_1.scaffoldBrandObject)(niche, {
                 name: args.name,
+                topic: args.topic,
                 domain: args.domain,
                 orgSlug: args.orgSlug,
             });
             mcpCapture('brand scaffolded', { niche });
-            return textResult(yamlContent);
+            return textResult(dumpYaml(obj));
         }
         case 'graspful_import_brand': {
             try {
                 requireApiAuth();
                 let raw;
                 try {
-                    raw = yaml.load(args.yaml);
+                    raw = parseYaml(args.yaml);
                 }
                 catch (e) {
                     throw new Error(`YAML parse error: ${e instanceof Error ? e.message : String(e)}`);
                 }
-                // Unwrap YAML structure to flat DTO (brand YAML has nested brand: key)
                 const parsed = raw;
                 const brandSection = (parsed.brand || {});
                 const dto = {
@@ -1058,7 +555,7 @@ async function handleToolCall(name, args) {
                     seo: parsed.seo || {},
                     pricing: parsed.pricing || {},
                 };
-                const result = await apiPost('/api/v1/brands', dto);
+                const result = await apiFetch('POST', '/api/v1/brands', dto);
                 mcpCapture('brand imported', { slug: result.slug, domain: result.domain });
                 return textResult(JSON.stringify(result, null, 2));
             }
@@ -1069,7 +566,7 @@ async function handleToolCall(name, args) {
         case 'graspful_list_courses': {
             try {
                 requireApiAuth();
-                const result = await apiGet(`/api/v1/orgs/${args.org}/courses`);
+                const result = await apiFetch('GET', `/api/v1/orgs/${args.org}/courses`);
                 mcpCapture('courses listed', { org: args.org, count: result.length });
                 return textResult(JSON.stringify(result, null, 2));
             }
@@ -1081,36 +578,37 @@ async function handleToolCall(name, args) {
             return errorResult(`Unknown tool: ${name}`);
     }
 }
-// ─── MCP Server ─────────────────────────────────────────────────────────────
-const server = new index_js_1.Server({
-    name: 'graspful',
-    version: '0.1.0',
-}, {
-    capabilities: {
-        tools: {},
-    },
-});
-server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
-    return { tools: TOOLS };
-});
-server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    return handleToolCall(name, args ?? {});
-});
-// ─── Start server ───────────────────────────────────────────────────────────
-async function main() {
-    const transport = new stdio_js_1.StdioServerTransport();
-    await server.connect(transport);
-}
-main().catch((error) => {
-    console.error('Fatal error:', error);
-    process.exit(1);
-});
-async function shutdown() {
-    if (posthogClient)
-        await posthogClient.shutdown();
-    process.exit(0);
+// ─── MCP Server (only when run directly) ────────────────────────────────────
+if (require.main === module) {
+    const server = new index_js_1.Server({
+        name: 'graspful',
+        version: '0.2.4',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+        return { tools: TOOLS };
+    });
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        return handleToolCall(name, args ?? {});
+    });
+    async function main() {
+        const transport = new stdio_js_1.StdioServerTransport();
+        await server.connect(transport);
+    }
+    main().catch((error) => {
+        console.error('Fatal error:', error);
+        process.exit(1);
+    });
+    async function shutdown() {
+        if (posthogClient)
+            await posthogClient.shutdown();
+        process.exit(0);
+    }
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
 }
-process.on('SIGTERM', shutdown);
-process.on('SIGINT', shutdown);
 //# sourceMappingURL=index.js.map