learnhouse-mcp-server 1.0.0 → 1.0.2

package/dist/index.js

@@ -0,0 +1,489 @@
+#!/usr/bin/env node
+/**
+ * LearnHouse MCP Server
+ *
+ * Model Context Protocol server for LearnHouse LMS.
+ * Provides tools for managing courses, chapters, activities, and users.
+ */
+import { FastMCP } from "fastmcp";
+import { z } from "zod";
+import { LearnHouseClient } from "./client.js";
+import fs from "node:fs";
+import path from "node:path";
+// ============================================================
+// Configuration
+// ============================================================
+const config = {
+    baseUrl: process.env.LEARNHOUSE_URL || "http://localhost:3000",
+    email: process.env.LEARNHOUSE_EMAIL || "",
+    password: process.env.LEARNHOUSE_PASSWORD || "",
+    orgId: parseInt(process.env.LEARNHOUSE_ORG_ID || "1", 10),
+};
+// Singleton client instance
+let client = null;
+async function getClient() {
+    if (!client) {
+        client = new LearnHouseClient({
+            baseUrl: config.baseUrl,
+            orgId: config.orgId,
+        });
+        if (config.email && config.password) {
+            await client.login(config.email, config.password);
+        }
+    }
+    return client;
+}
+// ============================================================
+// MCP Server
+// ============================================================
+const server = new FastMCP({
+    name: "LearnHouse MCP Server",
+    version: "1.0.0",
+    instructions: `
+LearnHouse MCP Server provides tools to manage an LMS (Learning Management System).
+
+Available capabilities:
+- **Course Management**: List, create, update, delete courses
+- **Chapter Management**: Organize chapters within courses
+- **Activity Management**: Create and manage learning activities (documents, videos, PDFs)
+- **Content Creation**: Set TipTap document content for activities
+- **Progress Tracking**: Track user progress through courses
+- **Search**: Search across courses and content
+
+Organization ID: ${config.orgId}
+API URL: ${config.baseUrl}
+  `.trim(),
+});
+server.addTool({
+    name: "ping",
+    description: "Ping the MCP server to verify it is running and identify version.",
+    parameters: z.object({}),
+    execute: async () => {
+        return "LearnHouse MCP Server is UP (Version 1.0.2 - Fixed PUT)";
+    },
+});
+// ============================================================
+// Course Tools
+// ============================================================
+server.addTool({
+    name: "list_courses",
+    description: "List all courses in the organization",
+    parameters: z.object({
+        page: z.number().optional().default(1).describe("Page number"),
+        limit: z.number().optional().default(50).describe("Number of courses per page"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const courses = await api.listCourses(args.page, args.limit);
+        return JSON.stringify(courses, null, 2);
+    },
+});
+server.addTool({
+    name: "get_course",
+    description: "Get detailed information about a specific course",
+    parameters: z.object({
+        course_uuid: z.string().describe("The UUID of the course"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const course = await api.getCourse(args.course_uuid);
+        return JSON.stringify(course, null, 2);
+    },
+});
+server.addTool({
+    name: "create_course",
+    description: "Create a new course",
+    parameters: z.object({
+        name: z.string().describe("Course name"),
+        description: z.string().describe("Course description"),
+        public: z.boolean().optional().default(true).describe("Whether the course is public"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const course = await api.createCourse({
+            name: args.name,
+            description: args.description,
+            public: args.public,
+            learnings: [],
+        });
+        return JSON.stringify(course, null, 2);
+    },
+});
+server.addTool({
+    name: "update_course",
+    description: "Update an existing course",
+    parameters: z.object({
+        course_uuid: z.string().describe("The UUID of the course to update"),
+        name: z.string().optional().describe("New course name"),
+        description: z.string().optional().describe("New course description"),
+        published: z.boolean().optional().describe("Publish/unpublish the course"),
+        thumbnail_image: z.string().optional().describe("URL of the thumbnail image"),
+        thumbnail_type: z.enum(["IMAGE", "VIDEO"]).optional().describe("Type of thumbnail"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const update = {};
+        if (args.name)
+            update.name = args.name;
+        if (args.description)
+            update.description = args.description;
+        if (args.published !== undefined)
+            update.published = args.published;
+        if (args.thumbnail_image)
+            update.thumbnail_image = args.thumbnail_image;
+        if (args.thumbnail_type)
+            update.thumbnail_type = args.thumbnail_type;
+        const course = await api.updateCourse(args.course_uuid, update);
+        return JSON.stringify(course, null, 2);
+    },
+});
+server.addTool({
+    name: "delete_course",
+    description: "Delete a course (use with caution!)",
+    parameters: z.object({
+        course_uuid: z.string().describe("The UUID of the course to delete"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        await api.deleteCourse(args.course_uuid);
+        return `Course ${args.course_uuid} deleted successfully`;
+    },
+});
+server.addTool({
+    name: "upload_course_thumbnail",
+    description: "Upload a thumbnail image for a course from a local file path",
+    parameters: z.object({
+        course_uuid: z.string().describe("The UUID of the course"),
+        file_path: z.string().describe("Local absolute path to the image file"),
+        type: z.enum(["IMAGE", "VIDEO"]).optional().default("IMAGE").describe("Thumbnail type"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        if (!fs.existsSync(args.file_path)) {
+            throw new Error(`File not found: ${args.file_path}`);
+        }
+        const buffer = fs.readFileSync(args.file_path);
+        const fileName = path.basename(args.file_path);
+        const course = await api.uploadCourseThumbnail(args.course_uuid, buffer, fileName, args.type);
+        return JSON.stringify(course, null, 2);
+    },
+});
+// ============================================================
+// Chapter Tools
+// ============================================================
+server.addTool({
+    name: "list_chapters",
+    description: "List all chapters in a course",
+    parameters: z.object({
+        course_id: z.number().describe("The numeric ID of the course"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const chapters = await api.listChapters(args.course_id);
+        return JSON.stringify(chapters, null, 2);
+    },
+});
+server.addTool({
+    name: "get_chapter",
+    description: "Get details of a specific chapter",
+    parameters: z.object({
+        chapter_id: z.number().describe("The ID of the chapter"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const chapter = await api.getChapter(args.chapter_id);
+        return JSON.stringify(chapter, null, 2);
+    },
+});
+server.addTool({
+    name: "create_chapter",
+    description: "Create a new chapter in a course",
+    parameters: z.object({
+        course_id: z.number().describe("The numeric ID of the course"),
+        org_id: z.number().optional().default(config.orgId).describe("Organization ID"),
+        name: z.string().describe("Chapter name"),
+        description: z.string().optional().default("").describe("Chapter description"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const chapter = await api.createChapter({
+            name: args.name,
+            description: args.description || "",
+            course_id: args.course_id,
+            org_id: args.org_id,
+        });
+        return JSON.stringify(chapter, null, 2);
+    },
+});
+server.addTool({
+    name: "update_chapter",
+    description: "Update an existing chapter",
+    parameters: z.object({
+        chapter_id: z.number().describe("The ID of the chapter to update"),
+        name: z.string().optional().describe("New chapter name"),
+        description: z.string().optional().describe("New chapter description"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const update = {};
+        if (args.name)
+            update.name = args.name;
+        if (args.description !== undefined)
+            update.description = args.description;
+        const chapter = await api.updateChapter(args.chapter_id, update);
+        return JSON.stringify(chapter, null, 2);
+    },
+});
+// ============================================================
+// Activity Tools
+// ============================================================
+server.addTool({
+    name: "list_activities",
+    description: "List all activities in a chapter",
+    parameters: z.object({
+        chapter_id: z.number().describe("The ID of the chapter"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const activities = await api.listActivities(args.chapter_id);
+        return JSON.stringify(activities, null, 2);
+    },
+});
+server.addTool({
+    name: "get_activity",
+    description: "Get details of a specific activity",
+    parameters: z.object({
+        activity_uuid: z.string().describe("The UUID of the activity"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const activity = await api.getActivity(args.activity_uuid);
+        return JSON.stringify(activity, null, 2);
+    },
+});
+server.addTool({
+    name: "create_activity",
+    description: "Create a new activity in a chapter",
+    parameters: z.object({
+        chapter_id: z.number().describe("The ID of the chapter"),
+        name: z.string().describe("Activity name"),
+        activity_type: z.enum(["TYPE_DYNAMIC", "TYPE_VIDEO", "TYPE_PDF"]).optional().default("TYPE_DYNAMIC").describe("Type of activity"),
+        activity_sub_type: z.enum(["SUBTYPE_DYNAMIC_PAGE", "SUBTYPE_VIDEO_YOUTUBE", "SUBTYPE_VIDEO_HOSTED", "SUBTYPE_PDF"]).optional().default("SUBTYPE_DYNAMIC_PAGE").describe("Subtype of activity"),
+        published: z.boolean().optional().default(false).describe("Whether the activity is published"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const activity = await api.createActivity({
+            name: args.name,
+            chapter_id: args.chapter_id,
+            activity_type: args.activity_type,
+            activity_sub_type: args.activity_sub_type,
+            published: args.published,
+        });
+        return JSON.stringify(activity, null, 2);
+    },
+});
+server.addTool({
+    name: "update_activity",
+    description: "Update an existing activity",
+    parameters: z.object({
+        activity_uuid: z.string().describe("The UUID of the activity to update"),
+        name: z.string().optional().describe("New activity name"),
+        published: z.boolean().optional().describe("Publish/unpublish the activity"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const update = {};
+        if (args.name)
+            update.name = args.name;
+        if (args.published !== undefined)
+            update.published = args.published;
+        const activity = await api.updateActivity(args.activity_uuid, update);
+        return JSON.stringify(activity, null, 2);
+    },
+});
+server.addTool({
+    name: "publish_activity",
+    description: "Publish an activity to make it visible",
+    parameters: z.object({
+        activity_uuid: z.string().describe("The UUID of the activity to publish"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const activity = await api.updateActivity(args.activity_uuid, { published: true });
+        return JSON.stringify(activity, null, 2);
+    },
+});
+// ============================================================
+// Content Tools
+// ============================================================
+server.addTool({
+    name: "set_document_content",
+    description: "Set the TipTap document content for a document activity. Content must be valid TipTap JSON.",
+    parameters: z.object({
+        activity_uuid: z.string().describe("The UUID of the activity"),
+        content: z.string().describe("TipTap JSON content as a string"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        let content;
+        try {
+            content = JSON.parse(args.content);
+        }
+        catch {
+            throw new Error("Invalid JSON content. Please provide valid TipTap JSON.");
+        }
+        await api.updateActivity(args.activity_uuid, { content });
+        return `Document content updated for activity ${args.activity_uuid}`;
+    },
+});
+server.addTool({
+    name: "set_video_content",
+    description: "Set video URL for a video activity",
+    parameters: z.object({
+        activity_uuid: z.string().describe("The UUID of the activity"),
+        video_url: z.string().describe("YouTube or hosted video URL"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const activity = await api.updateActivity(args.activity_uuid, {
+            content: { video_url: args.video_url },
+        });
+        return `Video URL set for activity ${args.activity_uuid}: ${args.video_url}`;
+    },
+});
+// ============================================================
+// User & Organization Tools
+// ============================================================
+server.addTool({
+    name: "get_current_user",
+    description: "Get information about the currently authenticated user",
+    parameters: z.object({}),
+    execute: async () => {
+        const api = await getClient();
+        const user = await api.getCurrentUser();
+        return JSON.stringify(user, null, 2);
+    },
+});
+server.addTool({
+    name: "get_organization",
+    description: "Get organization details",
+    parameters: z.object({
+        org_id: z.number().optional().default(config.orgId).describe("Organization ID"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const org = await api.getOrganization(args.org_id);
+        return JSON.stringify(org, null, 2);
+    },
+});
+// ============================================================
+// Collection Tools
+// ============================================================
+server.addTool({
+    name: "list_collections",
+    description: "List all collections in the organization",
+    parameters: z.object({
+        page: z.number().optional().default(1).describe("Page number"),
+        limit: z.number().optional().default(50).describe("Number of collections per page"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const collections = await api.listCollections(args.page, args.limit);
+        return JSON.stringify(collections, null, 2);
+    },
+});
+server.addTool({
+    name: "get_collection",
+    description: "Get detailed information about a specific collection",
+    parameters: z.object({
+        collection_uuid: z.string().describe("The UUID of the collection"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const collection = await api.getCollection(args.collection_uuid);
+        return JSON.stringify(collection, null, 2);
+    },
+});
+server.addTool({
+    name: "create_collection",
+    description: "Create a new collection",
+    parameters: z.object({
+        name: z.string().describe("Collection name"),
+        description: z.string().optional().describe("Collection description"),
+        public: z.boolean().optional().default(true).describe("Whether the collection is public"),
+        courses: z.array(z.number()).optional().describe("List of course IDs to include"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const collection = await api.createCollection({
+            name: args.name,
+            description: args.description,
+            public: args.public,
+            courses: args.courses,
+        });
+        return JSON.stringify(collection, null, 2);
+    },
+});
+server.addTool({
+    name: "delete_collection",
+    description: "Delete a collection",
+    parameters: z.object({
+        collection_uuid: z.string().describe("The UUID of the collection to delete"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        await api.deleteCollection(args.collection_uuid);
+        return `Collection ${args.collection_uuid} deleted successfully`;
+    },
+});
+// ============================================================
+// Progress Tools
+// ============================================================
+server.addTool({
+    name: "get_course_progress",
+    description: "Get user's progress for a specific course",
+    parameters: z.object({
+        course_uuid: z.string().describe("The UUID of the course"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const progress = await api.getCourseProgress(args.course_uuid);
+        return JSON.stringify(progress, null, 2);
+    },
+});
+server.addTool({
+    name: "mark_activity_complete",
+    description: "Mark an activity as completed for the current user",
+    parameters: z.object({
+        activity_uuid: z.string().describe("The UUID of the activity to mark complete"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        await api.markActivityComplete(args.activity_uuid);
+        return `Activity ${args.activity_uuid} marked as complete`;
+    },
+});
+// ============================================================
+// Search Tools
+// ============================================================
+server.addTool({
+    name: "search",
+    description: "Search for courses and content in the organization",
+    parameters: z.object({
+        org_slug: z.string().optional().default("default").describe("Organization slug"),
+        query: z.string().describe("Search query"),
+    }),
+    execute: async (args) => {
+        const api = await getClient();
+        const results = await api.search(args.org_slug, args.query);
+        return JSON.stringify(results, null, 2);
+    },
+});
+// ============================================================
+// Start Server
+// ============================================================
+server.start({
+    transportType: "stdio",
+});
+console.error("LearnHouse MCP Server started");

package/dist/test-api.d.ts

@@ -0,0 +1,6 @@
+/**
+ * LearnHouse API Client Tests
+ *
+ * Run with: npm test
+ */
+export {};

package/dist/test-api.js

@@ -0,0 +1,166 @@
+/**
+ * LearnHouse API Client Tests
+ *
+ * Run with: npm test
+ */
+import { LearnHouseClient } from "./client.js";
+const BASE_URL = process.env.LEARNHOUSE_URL || "http://localhost:3000";
+const ORG_ID = parseInt(process.env.LEARNHOUSE_ORG_ID || "1");
+const EMAIL = process.env.LEARNHOUSE_EMAIL || "admin@ai-automate.me";
+const PASSWORD = process.env.LEARNHOUSE_PASSWORD || "";
+async function runTests() {
+    console.log("🧪 LearnHouse API Client Tests\n");
+    console.log(`   Base URL: ${BASE_URL}`);
+    console.log(`   Org ID: ${ORG_ID}`);
+    console.log(`   Email: ${EMAIL}\n`);
+    const client = new LearnHouseClient({
+        baseUrl: BASE_URL,
+        orgId: ORG_ID,
+    });
+    let passed = 0;
+    let failed = 0;
+    async function test(name, fn) {
+        try {
+            await fn();
+            console.log(`  ✅ ${name}`);
+            passed++;
+        }
+        catch (error) {
+            console.log(`  ❌ ${name}`);
+            console.log(`     Error: ${error instanceof Error ? error.message : error}`);
+            failed++;
+        }
+    }
+    // ===== Authentication Tests =====
+    console.log("\n📋 Authentication Tests");
+    await test("Health check (no auth)", async () => {
+        const result = await client.healthCheck();
+        if (!result.status)
+            throw new Error("No status in response");
+    });
+    if (!PASSWORD) {
+        console.log("\n⚠️  Set LEARNHOUSE_PASSWORD to run authenticated tests\n");
+        return;
+    }
+    await test("Login with credentials", async () => {
+        const result = await client.login(EMAIL, PASSWORD);
+        if (!result.tokens.access_token)
+            throw new Error("No access token");
+        if (!result.user.email)
+            throw new Error("No user email");
+    });
+    await test("Get current user", async () => {
+        const user = await client.getCurrentUser();
+        if (!user.email)
+            throw new Error("No email in user");
+        console.log(`     User: ${user.username} (${user.email})`);
+    });
+    // ===== Organization Tests =====
+    console.log("\n📋 Organization Tests");
+    await test("List organizations", async () => {
+        const orgs = await client.listOrganizations();
+        if (!Array.isArray(orgs))
+            throw new Error("Expected array");
+        console.log(`     Found ${orgs.length} organization(s)`);
+    });
+    await test("Get organization by ID", async () => {
+        const org = await client.getOrganization(ORG_ID);
+        if (!org.name)
+            throw new Error("No org name");
+        console.log(`     Org: ${org.name} (${org.slug})`);
+    });
+    // ===== Course Tests =====
+    console.log("\n📋 Course Tests");
+    let testCourse = null;
+    await test("List courses", async () => {
+        const courses = await client.listCourses(1, 10);
+        if (!Array.isArray(courses))
+            throw new Error("Expected array");
+        console.log(`     Found ${courses.length} course(s)`);
+        if (courses.length > 0) {
+            testCourse = courses[0];
+        }
+    });
+    if (testCourse) {
+        await test("Get course by UUID", async () => {
+            const course = await client.getCourse(testCourse.course_uuid);
+            if (course.id !== testCourse.id)
+                throw new Error("Course ID mismatch");
+        });
+        await test("Get course metadata", async () => {
+            const meta = await client.getCourseMeta(testCourse.course_uuid);
+            if (!meta.chapters)
+                throw new Error("No chapters in metadata");
+            console.log(`     Course "${meta.name}" has ${meta.chapters.length} chapters`);
+        });
+    }
+    // ===== Chapter Tests =====
+    console.log("\n📋 Chapter Tests");
+    let testChapter = null;
+    if (testCourse) {
+        await test("List chapters for course", async () => {
+            const chapters = await client.listChapters(testCourse.id, 1, 10);
+            if (!Array.isArray(chapters))
+                throw new Error("Expected array");
+            console.log(`     Found ${chapters.length} chapter(s)`);
+            if (chapters.length > 0) {
+                testChapter = chapters[0];
+            }
+        });
+        if (testChapter) {
+            await test("Get chapter by ID", async () => {
+                const chapter = await client.getChapter(testChapter.id);
+                if (chapter.id !== testChapter.id)
+                    throw new Error("Chapter ID mismatch");
+                console.log(`     Chapter: ${chapter.name}`);
+            });
+        }
+    }
+    // ===== Activity Tests =====
+    console.log("\n📋 Activity Tests");
+    let testActivity = null;
+    if (testChapter) {
+        await test("List activities for chapter", async () => {
+            const activities = await client.listActivities(testChapter.id);
+            if (!Array.isArray(activities))
+                throw new Error("Expected array");
+            console.log(`     Found ${activities.length} activity(ies)`);
+            if (activities.length > 0) {
+                testActivity = activities[0];
+            }
+        });
+        if (testActivity) {
+            await test("Get activity by UUID", async () => {
+                const activity = await client.getActivity(testActivity.activity_uuid);
+                if (activity.id !== testActivity.id)
+                    throw new Error("Activity ID mismatch");
+                console.log(`     Activity: ${activity.name}`);
+            });
+        }
+    }
+    // ===== Collection Tests =====
+    console.log("\n📋 Collection Tests");
+    await test("List collections", async () => {
+        const collections = await client.listCollections(1, 10);
+        if (!Array.isArray(collections))
+            throw new Error("Expected array");
+        console.log(`     Found ${collections.length} collection(s)`);
+    });
+    // ===== Search Tests =====
+    console.log("\n📋 Search Tests");
+    await test("Search for courses", async () => {
+        const results = await client.search("MCP", "courses");
+        console.log(`     Found ${results.courses?.length || 0} course(s) matching "MCP"`);
+    });
+    // ===== Summary =====
+    console.log("\n" + "=".repeat(50));
+    console.log(`📊 Results: ${passed} passed, ${failed} failed`);
+    console.log("=".repeat(50) + "\n");
+    if (failed > 0) {
+        process.exit(1);
+    }
+}
+runTests().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});