@mindstone-engineering/mcp-server-talentlms 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TalentLMS authentication module.
+ *
+ * API key + domain management — stored via env vars (TALENTLMS_API_KEY, TALENTLMS_DOMAIN)
+ * or configured at runtime via the configure_talentlms tool.
+ *
+ * Auth: Basic auth with base64(apiKey:) — colon after key, empty password.
+ */
+/**
+ * Normalize a user-provided domain input to a subdomain.
+ * Handles full URLs like "https://acme.talentlms.com" → "acme",
+ * bare domains like "acme.talentlms.com" → "acme", and plain subdomains.
+ */
+export declare const normalizeTalentLmsSubdomainInput: (input: string | undefined) => string | undefined;
+/**
+ * Validate that a subdomain value is safe to use in a URL.
+ */
+export declare function isValidSubdomain(value: string): boolean;
+export declare function getApiKey(): string;
+export declare function setApiKey(key: string): void;
+export declare function getDomain(): string;
+export declare function setDomain(d: string): void;
+export declare function isConfigured(): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,70 @@
+/**
+ * TalentLMS authentication module.
+ *
+ * API key + domain management — stored via env vars (TALENTLMS_API_KEY, TALENTLMS_DOMAIN)
+ * or configured at runtime via the configure_talentlms tool.
+ *
+ * Auth: Basic auth with base64(apiKey:) — colon after key, empty password.
+ */
+const MULTI_LABEL_SUBDOMAIN_REGEX = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+const extractHostnameFromUserInput = (input) => {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return '';
+    const candidate = trimmed.includes('://') ? trimmed : `https://${trimmed}`;
+    try {
+        return new URL(candidate).hostname.toLowerCase();
+    }
+    catch {
+        return trimmed
+            .toLowerCase()
+            .replace(/^[a-z]+:\/\//, '')
+            .split('/')[0]
+            .split('?')[0]
+            .split('#')[0]
+            .split(':')[0];
+    }
+};
+/**
+ * Normalize a user-provided domain input to a subdomain.
+ * Handles full URLs like "https://acme.talentlms.com" → "acme",
+ * bare domains like "acme.talentlms.com" → "acme", and plain subdomains.
+ */
+export const normalizeTalentLmsSubdomainInput = (input) => {
+    if (!input)
+        return undefined;
+    const hostname = extractHostnameFromUserInput(input);
+    if (!hostname)
+        return undefined;
+    const normalizedHostname = hostname.trim().toLowerCase().replace(/\.$/, '');
+    const withoutSuffix = normalizedHostname.endsWith('.talentlms.com')
+        ? normalizedHostname.slice(0, -'.talentlms.com'.length)
+        : normalizedHostname;
+    return withoutSuffix || undefined;
+};
+/**
+ * Validate that a subdomain value is safe to use in a URL.
+ */
+export function isValidSubdomain(value) {
+    return MULTI_LABEL_SUBDOMAIN_REGEX.test(value);
+}
+/** Runtime API key — starts from env, can be updated via configure tool. */
+let apiKey = process.env.TALENTLMS_API_KEY ?? '';
+/** Runtime domain — starts from env, can be updated via configure tool. */
+let domain = normalizeTalentLmsSubdomainInput(process.env.TALENTLMS_DOMAIN) ?? '';
+export function getApiKey() {
+    return apiKey;
+}
+export function setApiKey(key) {
+    apiKey = key;
+}
+export function getDomain() {
+    return domain;
+}
+export function setDomain(d) {
+    domain = d;
+}
+export function isConfigured() {
+    return apiKey.trim().length > 0 && domain.trim().length > 0;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+/**
+ * TalentLMS API HTTP client.
+ *
+ * Centralises Basic auth injection (base64(apiKey:) with colon preserved, empty password),
+ * error handling, rate-limit messaging, and timeout handling.
+ *
+ * Base URL: https://{domain}.talentlms.com/api/v1
+ */
+/**
+ * Make an authenticated request to the TalentLMS API.
+ */
+export declare function talentlmsFetch<T>(path: string, options?: RequestInit): Promise<T>;
+/**
+ * URL-encode form parameters, omitting undefined values.
+ */
+export declare function formEncode(params: Record<string, string | undefined>): string;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,79 @@
+/**
+ * TalentLMS API HTTP client.
+ *
+ * Centralises Basic auth injection (base64(apiKey:) with colon preserved, empty password),
+ * error handling, rate-limit messaging, and timeout handling.
+ *
+ * Base URL: https://{domain}.talentlms.com/api/v1
+ */
+import { TalentLMSError, REQUEST_TIMEOUT_MS } from './types.js';
+import { getApiKey, getDomain, isConfigured } from './auth.js';
+function getBaseUrl() {
+    return `https://${getDomain()}.talentlms.com/api/v1`;
+}
+/**
+ * Make an authenticated request to the TalentLMS API.
+ */
+export async function talentlmsFetch(path, options = {}) {
+    if (!isConfigured()) {
+        throw new TalentLMSError('TalentLMS not configured', 'AUTH_REQUIRED', 'Configure your TalentLMS API key and domain. Call configure_talentlms first.');
+    }
+    const apiKey = getApiKey();
+    const url = `${getBaseUrl()}${path}`;
+    const authHeader = 'Basic ' + Buffer.from(`${apiKey}:`).toString('base64');
+    const headers = {
+        Authorization: authHeader,
+        ...(options.headers || {}),
+    };
+    if (options.body) {
+        headers['Content-Type'] = 'application/x-www-form-urlencoded';
+    }
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new TalentLMSError('Request to TalentLMS API timed out', 'TIMEOUT', 'The request took too long. Try again or check if TalentLMS is available.');
+        }
+        throw error;
+    }
+    if (response.status === 429) {
+        throw new TalentLMSError('Rate limited by TalentLMS. Please wait before retrying.', 'RATE_LIMITED', 'Please wait before retrying. TalentLMS rate limits: 2,000-10,000 calls/hour depending on plan.');
+    }
+    if (response.status === 401 || response.status === 403) {
+        let errorText;
+        try {
+            const errorBody = await response.json();
+            errorText = errorBody?.error?.message || 'Unauthorized';
+        }
+        catch {
+            errorText = 'Unauthorized';
+        }
+        throw new TalentLMSError(`Authentication failed: ${errorText}`, 'AUTH_FAILED', 'Re-configure with configure_talentlms. Ensure Super Admin API access is enabled.');
+    }
+    if (!response.ok) {
+        let errorText;
+        try {
+            const errorBody = await response.json();
+            errorText = errorBody?.error?.message || JSON.stringify(errorBody);
+        }
+        catch {
+            errorText = await response.text().catch(() => 'Unknown error');
+        }
+        throw new TalentLMSError(`TalentLMS API error (${response.status}): ${errorText}`, `HTTP_${response.status}`, 'Check the request parameters and try again.');
+    }
+    return response.json();
+}
+/**
+ * URL-encode form parameters, omitting undefined values.
+ */
+export function formEncode(params) {
+    const entries = Object.entries(params).filter(([, v]) => v !== undefined);
+    return new URLSearchParams(entries).toString();
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * TalentLMS MCP Server
+ *
+ * Comprehensive LMS integration via TalentLMS API:
+ * - Users (list, get, create, status, courses)
+ * - Courses (list, get, create, users, enrol, unenrol, SSO)
+ * - Groups (list, get, create, add course)
+ * - Branches (list)
+ * - Reporting (site info, timeline, user progress)
+ * - Assessments (test answers, survey answers, ILT sessions)
+ *
+ * Environment variables:
+ * - TALENTLMS_API_KEY: TalentLMS API key (Super Admin required)
+ * - TALENTLMS_DOMAIN: TalentLMS subdomain (e.g., "acme" for acme.talentlms.com)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * TalentLMS MCP Server
+ *
+ * Comprehensive LMS integration via TalentLMS API:
+ * - Users (list, get, create, status, courses)
+ * - Courses (list, get, create, users, enrol, unenrol, SSO)
+ * - Groups (list, get, create, add course)
+ * - Branches (list)
+ * - Reporting (site info, timeline, user progress)
+ * - Assessments (test answers, survey answers, ILT sessions)
+ *
+ * Environment variables:
+ * - TALENTLMS_API_KEY: TalentLMS API key (Super Admin required)
+ * - TALENTLMS_DOMAIN: TalentLMS subdomain (e.g., "acme" for acme.talentlms.com)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('TalentLMS MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,17 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerUserTools, registerCourseTools, registerGroupTools, registerBranchTools, registerReportingTools, registerAssessmentTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'talentlms-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerUserTools(server);
+    registerCourseTools(server);
+    registerGroupTools(server);
+    registerBranchTools(server);
+    registerReportingTools(server);
+    registerAssessmentTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/assessments.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAssessmentTools(server: McpServer): void;
+//# sourceMappingURL=assessments.d.ts.map

package/dist/tools/assessments.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { talentlmsFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerAssessmentTools(server) {
+    server.registerTool('get_talentlms_test_answers', {
+        description: 'Get a user\'s answers for a specific test/quiz.\n\n' +
+            'Returns: questions, user answers, correct answers, score.\n\n' +
+            'WORKFLOW:\n' +
+            '1. Get course details with get_talentlms_course to find test/unit IDs\n' +
+            '2. Call this tool with the test ID and user ID',
+        inputSchema: z.object({
+            test_id: z.string().min(1).describe('Test/quiz ID (from course units)'),
+            user_id: z.string().min(1).describe('User ID'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const result = await talentlmsFetch(`/gettestanswers/test_id:${encodeURIComponent(args.test_id)},user_id:${encodeURIComponent(args.user_id)}`);
+        return JSON.stringify({ ok: true, testAnswers: result });
+    }));
+    server.registerTool('get_talentlms_survey_answers', {
+        description: 'Get a user\'s responses to a survey.\n\n' +
+            'Returns: questions, user responses.',
+        inputSchema: z.object({
+            survey_id: z.string().min(1).describe('Survey ID (from course units)'),
+            user_id: z.string().min(1).describe('User ID'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const result = await talentlmsFetch(`/getsurveyanswers/survey_id:${encodeURIComponent(args.survey_id)},user_id:${encodeURIComponent(args.user_id)}`);
+        return JSON.stringify({ ok: true, surveyAnswers: result });
+    }));
+    server.registerTool('get_talentlms_ilt_sessions', {
+        description: 'Get instructor-led training (ILT) sessions for a specific ILT unit.\n\n' +
+            'Returns: session ID, course, instructor, date, time, location, enrolled users.\n\n' +
+            'WORKFLOW:\n' +
+            '1. Get course details with get_talentlms_course to find ILT unit IDs\n' +
+            '2. Call this tool with the ILT unit ID',
+        inputSchema: z.object({
+            ilt_id: z.string().min(1).describe('ILT unit ID (from course units)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const sessions = await talentlmsFetch(`/getiltsessions/ilt_id:${encodeURIComponent(args.ilt_id)}`);
+        return JSON.stringify({ ok: true, sessions, count: sessions.length });
+    }));
+}
+//# sourceMappingURL=assessments.js.map

package/dist/tools/branches.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerBranchTools(server: McpServer): void;
+//# sourceMappingURL=branches.d.ts.map

package/dist/tools/branches.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { talentlmsFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerBranchTools(server) {
+    server.registerTool('list_talentlms_branches', {
+        description: 'List all branches in TalentLMS (multi-tenant).\n\n' +
+            'Returns: id, name, description, created_on.',
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        const branches = await talentlmsFetch('/branches');
+        return JSON.stringify({ ok: true, branches, count: branches.length });
+    }));
+}
+//# sourceMappingURL=branches.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerConfigureTools(server: McpServer): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/tools/configure.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { setApiKey, setDomain, normalizeTalentLmsSubdomainInput, isValidSubdomain } from '../auth.js';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { TalentLMSError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_talentlms', {
+        description: 'Configure TalentLMS API credentials. Call this when the user provides their API key and domain.\n\n' +
+            'WORKFLOW:\n' +
+            '1. Go to your TalentLMS admin panel → Account & Settings → Security\n' +
+            '2. Enable API access\n' +
+            '3. Copy the API key\n' +
+            '4. Your domain is the subdomain part of your URL (e.g., "acme" for acme.talentlms.com)\n\n' +
+            'Note: Requires a paid TalentLMS plan and Super Admin access.',
+        inputSchema: z.object({
+            api_key: z.string().min(1).describe('TalentLMS API key'),
+            domain: z.string().min(1).describe('TalentLMS subdomain (e.g., "acme" for acme.talentlms.com)'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const apiKey = args.api_key.trim();
+        const domain = normalizeTalentLmsSubdomainInput(args.domain);
+        if (!apiKey || !domain) {
+            return JSON.stringify({ ok: false, error: 'Both api_key and domain are required.' });
+        }
+        if (!isValidSubdomain(domain)) {
+            return JSON.stringify({
+                ok: false,
+                error: 'Invalid domain. Enter just the subdomain part (e.g., "acme" or "acme.eu"), or paste your TalentLMS URL (e.g., https://acme.talentlms.com).',
+            });
+        }
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/talentlms/configure', { apiKey, domain });
+                if (result.success) {
+                    setApiKey(apiKey);
+                    setDomain(domain);
+                    const message = result.warning
+                        ? `TalentLMS configured successfully. Note: ${result.warning}`
+                        : `TalentLMS configured successfully for ${domain}.talentlms.com! Try list_talentlms_users or list_talentlms_courses.`;
+                    return JSON.stringify({ ok: true, message });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new TalentLMSError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof TalentLMSError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new TalentLMSError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge — store in-memory
+        setApiKey(apiKey);
+        setDomain(domain);
+        return JSON.stringify({
+            ok: true,
+            message: `TalentLMS configured successfully for ${domain}.talentlms.com! Try list_talentlms_users or list_talentlms_courses.`,
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/courses.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCourseTools(server: McpServer): void;
+//# sourceMappingURL=courses.d.ts.map

package/dist/tools/courses.js

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+import { talentlmsFetch, formEncode } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerCourseTools(server) {
+    server.registerTool('list_talentlms_courses', {
+        description: 'List all courses in TalentLMS.\n\n' +
+            'Returns: id, name, code, category_id, description, status, creation_date, price, creator_id.\n\n' +
+            'RELATED TOOLS:\n' +
+            '- get_talentlms_course: Get full course details\n' +
+            '- get_talentlms_course_users: See enrolled users',
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        const courses = await talentlmsFetch('/courses');
+        const compact = courses.map(c => ({
+            id: c.id, name: c.name, code: c.code, category_id: c.category_id,
+            description: c.description, status: c.status, creation_date: c.creation_date,
+            price: c.price, creator_id: c.creator_id,
+        }));
+        return JSON.stringify({ ok: true, courses: compact, count: compact.length });
+    }));
+    server.registerTool('get_talentlms_course', {
+        description: 'Get full course details by ID.\n\n' +
+            'Returns: name, description, units (content structure), rules, prerequisites, certification, custom fields.\n\n' +
+            'RELATED TOOLS:\n' +
+            '- list_talentlms_courses: Find course IDs\n' +
+            '- get_talentlms_course_users: See who is enrolled',
+        inputSchema: z.object({
+            course_id: z.string().min(1).describe('Course ID'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const course = await talentlmsFetch(`/courses/id:${encodeURIComponent(args.course_id)}`);
+        return JSON.stringify({ ok: true, course });
+    }));
+    server.registerTool('create_talentlms_course', {
+        description: 'Create a new course in TalentLMS.\n\n' +
+            'RELATED TOOLS:\n' +
+            '- enrol_talentlms_user: Add users to the new course',
+        inputSchema: z.object({
+            name: z.string().min(1).describe('Course name'),
+            description: z.string().optional().describe('Course description'),
+            code: z.string().optional().describe('Course code (optional)'),
+            category_id: z.string().optional().describe('Category ID (optional)'),
+            creator_id: z.string().optional().describe('Creator user ID (optional)'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const body = formEncode({
+            name: args.name,
+            description: args.description,
+            code: args.code,
+            category_id: args.category_id,
+            creator_id: args.creator_id,
+        });
+        const course = await talentlmsFetch('/createcourse', {
+            method: 'POST',
+            body,
+        });
+        return JSON.stringify({ ok: true, message: 'Course created.', course });
+    }));
+    server.registerTool('get_talentlms_course_users', {
+        description: 'Get all users enrolled in a course, with their progress and completion status.\n\n' +
+            'Returns: user id, name, role, completion_status, completion_percentage, total_time.\n\n' +
+            'RELATED TOOLS:\n' +
+            '- get_talentlms_user_courses: See all courses for a user (reverse lookup)\n' +
+            '- enrol_talentlms_user: Add a user to this course',
+        inputSchema: z.object({
+            course_id: z.string().min(1).describe('Course ID'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const course = await talentlmsFetch(`/courses/id:${encodeURIComponent(args.course_id)}`);
+        const users = course.users || [];
+        return JSON.stringify({ ok: true, users, count: users.length });
+    }));
+    server.registerTool('enrol_talentlms_user', {
+        description: 'Enrol a user into a course.\n\n' +
+            'COMMON MISTAKES:\n' +
+            '- User must exist first (use create_talentlms_user if needed)\n' +
+            '- Cannot enrol the same user twice',
+        inputSchema: z.object({
+            user_id: z.string().min(1).describe('User ID'),
+            course_id: z.string().min(1).describe('Course ID'),
+            role: z.enum(['learner', 'instructor']).optional().describe('Enrolment role. Default: learner'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const body = formEncode({
+            user_id: args.user_id,
+            course_id: args.course_id,
+            role: args.role,
+        });
+        await talentlmsFetch('/addusertocourse', {
+            method: 'POST',
+            body,
+        });
+        return JSON.stringify({ ok: true, message: 'User enrolled in course.' });
+    }));
+    server.registerTool('unenrol_talentlms_user', {
+        description: 'Remove a user from a course.\n\n' +
+            'RELATED TOOLS:\n' +
+            '- get_talentlms_course_users: Check current enrolment',
+        inputSchema: z.object({
+            user_id: z.string().min(1).describe('User ID'),
+            course_id: z.string().min(1).describe('Course ID'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, withErrorHandling(async (args) => {
+        await talentlmsFetch(`/removeuserfromcourse/course_id:${encodeURIComponent(args.course_id)},user_id:${encodeURIComponent(args.user_id)}`);
+        return JSON.stringify({ ok: true, message: 'User removed from course.' });
+    }));
+    server.registerTool('get_talentlms_course_sso_link', {
+        description: 'Generate an SSO link to launch a user directly into a course.\n\n' +
+            'Returns a URL that logs the user in and redirects them to the course. Link is temporary.',
+        inputSchema: z.object({
+            user_id: z.string().min(1).describe('User ID'),
+            course_id: z.string().min(1).describe('Course ID'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const result = await talentlmsFetch(`/gotocourse/user_id:${encodeURIComponent(args.user_id)},course_id:${encodeURIComponent(args.course_id)}`);
+        return JSON.stringify({ ok: true, result });
+    }));
+}
+//# sourceMappingURL=courses.js.map

package/dist/tools/groups.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGroupTools(server: McpServer): void;
+//# sourceMappingURL=groups.d.ts.map

package/dist/tools/groups.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { talentlmsFetch, formEncode } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerGroupTools(server) {
+    server.registerTool('list_talentlms_groups', {
+        description: 'List all groups in TalentLMS.\n\n' +
+            'Returns: id, name, description, creator_id, created_on, key (enrollment key).\n\n' +
+            'RELATED TOOLS:\n' +
+            '- get_talentlms_group: Get group details including members and courses',
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        const groups = await talentlmsFetch('/groups');
+        return JSON.stringify({ ok: true, groups, count: groups.length });
+    }));
+    server.registerTool('get_talentlms_group', {
+        description: 'Get group details including members and assigned courses.\n\n' +
+            'Returns: group info, list of users in the group, list of courses assigned to the group.',
+        inputSchema: z.object({
+            group_id: z.string().min(1).describe('Group ID'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const group = await talentlmsFetch(`/groups/id:${encodeURIComponent(args.group_id)}`);
+        return JSON.stringify({ ok: true, group });
+    }));
+    server.registerTool('create_talentlms_group', {
+        description: 'Create a new group in TalentLMS.',
+        inputSchema: z.object({
+            name: z.string().min(1).describe('Group name'),
+            description: z.string().optional().describe('Group description'),
+            key: z.string().optional().describe('Enrollment key (optional)'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const body = formEncode({
+            name: args.name,
+            description: args.description,
+            key: args.key,
+        });
+        const group = await talentlmsFetch('/creategroup', {
+            method: 'POST',
+            body,
+        });
+        return JSON.stringify({ ok: true, message: 'Group created.', group });
+    }));
+    server.registerTool('add_course_to_talentlms_group', {
+        description: 'Assign a course to a group. All group members will be enrolled.',
+        inputSchema: z.object({
+            group_id: z.string().min(1).describe('Group ID'),
+            course_id: z.string().min(1).describe('Course ID'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        await talentlmsFetch(`/addcoursetogroup/group_id:${encodeURIComponent(args.group_id)},course_id:${encodeURIComponent(args.course_id)}`);
+        return JSON.stringify({ ok: true, message: 'Course added to group.' });
+    }));
+}
+//# sourceMappingURL=groups.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,8 @@
+export { registerConfigureTools } from './configure.js';
+export { registerUserTools } from './users.js';
+export { registerCourseTools } from './courses.js';
+export { registerGroupTools } from './groups.js';
+export { registerBranchTools } from './branches.js';
+export { registerReportingTools } from './reporting.js';
+export { registerAssessmentTools } from './assessments.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,8 @@
+export { registerConfigureTools } from './configure.js';
+export { registerUserTools } from './users.js';
+export { registerCourseTools } from './courses.js';
+export { registerGroupTools } from './groups.js';
+export { registerBranchTools } from './branches.js';
+export { registerReportingTools } from './reporting.js';
+export { registerAssessmentTools } from './assessments.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/reporting.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerReportingTools(server: McpServer): void;
+//# sourceMappingURL=reporting.d.ts.map

package/dist/tools/reporting.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { talentlmsFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerReportingTools(server) {
+    server.registerTool('get_talentlms_site_info', {
+        description: 'Get TalentLMS site-level statistics and configuration.\n\n' +
+            'Returns: total users, total courses, signup method, site name, timezone, domain, and more.',
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        const info = await talentlmsFetch('/siteinfo');
+        return JSON.stringify({ ok: true, siteInfo: info });
+    }));
+    server.registerTool('get_talentlms_timeline', {
+        description: 'Get activity timeline for users or courses.\n\n' +
+            'Returns recent activity events: enrolments, completions, logins, course accesses.',
+        inputSchema: z.object({
+            type: z.enum(['users', 'courses']).describe('Timeline type'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const timeline = await talentlmsFetch(`/gettimeline/type:${args.type}`);
+        return JSON.stringify({ ok: true, timeline, count: timeline.length });
+    }));
+    server.registerTool('get_talentlms_user_progress', {
+        description: 'Get detailed progress for a user in a specific course.\n\n' +
+            'Returns: unit-by-unit progress, completion status, score, time spent per unit.\n\n' +
+            'WORKFLOW:\n' +
+            '1. Find user ID with list_talentlms_users\n' +
+            '2. Find course ID with list_talentlms_courses or get_talentlms_user_courses\n' +
+            '3. Call this tool for detailed breakdown',
+        inputSchema: z.object({
+            user_id: z.string().min(1).describe('User ID'),
+            course_id: z.string().min(1).describe('Course ID'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const result = await talentlmsFetch(`/getuserstatusincourse/course_id:${encodeURIComponent(args.course_id)},user_id:${encodeURIComponent(args.user_id)}`);
+        return JSON.stringify({ ok: true, progress: result });
+    }));
+}
+//# sourceMappingURL=reporting.js.map

package/dist/tools/users.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerUserTools(server: McpServer): void;
+//# sourceMappingURL=users.d.ts.map

package/dist/tools/users.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { talentlmsFetch, formEncode } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerUserTools(server) {
+    server.registerTool('list_talentlms_users', {
+        description: 'List all users in TalentLMS.\n\n' +
+            'Returns: id, login, first_name, last_name, email, role, status, last_updated.\n\n' +
+            'RELATED TOOLS:\n' +
+            '- get_talentlms_user: Get full profile by ID\n' +
+            '- get_talentlms_user_courses: See courses a user is enrolled in',
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        const users = await talentlmsFetch('/users');
+        const compact = users.map(u => ({
+            id: u.id, login: u.login, first_name: u.first_name, last_name: u.last_name,
+            email: u.email, role: u.role, status: u.status, last_updated: u.last_updated,
+        }));
+        return JSON.stringify({ ok: true, users: compact, count: compact.length });
+    }));
+    server.registerTool('get_talentlms_user', {
+        description: 'Get a user\'s full profile by ID or email.\n\n' +
+            'Returns: full profile including role, status, custom fields, last login, created date.\n\n' +
+            'RELATED TOOLS:\n' +
+            '- list_talentlms_users: Find user IDs\n' +
+            '- get_talentlms_user_courses: See their enrolled courses',
+        inputSchema: z.object({
+            user_id: z.string().optional().describe('User ID'),
+            email: z.string().optional().describe('User email (alternative to user_id)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const userId = args.user_id;
+        const email = args.email;
+        if (!userId && !email) {
+            return JSON.stringify({ ok: false, error: 'Provide either user_id or email.', resolution: 'Use list_talentlms_users to find user IDs.' });
+        }
+        const path = userId
+            ? `/users/id:${encodeURIComponent(userId)}`
+            : `/users/email:${encodeURIComponent(email)}`;
+        const user = await talentlmsFetch(path);
+        return JSON.stringify({ ok: true, user });
+    }));
+    server.registerTool('create_talentlms_user', {
+        description: 'Create a new user in TalentLMS.\n\n' +
+            'COMMON MISTAKES:\n' +
+            '- login must be unique across TalentLMS instance\n' +
+            '- email must be unique unless allow_duplicate_emails is enabled',
+        inputSchema: z.object({
+            first_name: z.string().min(1).describe('First name'),
+            last_name: z.string().min(1).describe('Last name'),
+            email: z.string().min(1).describe('Email address'),
+            login: z.string().min(1).describe('Login username'),
+            password: z.string().optional().describe('Password (auto-generated if omitted)'),
+            user_type: z.string().optional().describe('User type: Learner, Trainer, Admin, SuperAdmin. Default: Learner'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const body = formEncode({
+            first_name: args.first_name,
+            last_name: args.last_name,
+            email: args.email,
+            login: args.login,
+            password: args.password,
+            user_type: args.user_type,
+        });
+        const user = await talentlmsFetch('/usersignup', {
+            method: 'POST',
+            body,
+        });
+        return JSON.stringify({ ok: true, message: 'User created.', user });
+    }));
+    server.registerTool('set_talentlms_user_status', {
+        description: 'Activate or deactivate a user in TalentLMS.\n\n' +
+            'RELATED TOOLS:\n' +
+            '- list_talentlms_users: Find user IDs',
+        inputSchema: z.object({
+            user_id: z.string().min(1).describe('User ID'),
+            status: z.enum(['active', 'inactive']).describe('New status'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const path = `/usersetstatus/user_id:${encodeURIComponent(args.user_id)},status:${args.status}`;
+        const result = await talentlmsFetch(path);
+        return JSON.stringify({ ok: true, message: `User status set to ${args.status}.`, result });
+    }));
+    server.registerTool('get_talentlms_user_courses', {
+        description: 'Get all courses a user is enrolled in, with progress and completion status.\n\n' +
+            'Returns: course id, name, role, completion status, progress percentage, total_time, last_accessed.\n\n' +
+            'RELATED TOOLS:\n' +
+            '- get_talentlms_course_users: See all users in a course (reverse lookup)',
+        inputSchema: z.object({
+            user_id: z.string().min(1).describe('User ID'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const user = await talentlmsFetch(`/users/id:${encodeURIComponent(args.user_id)}`);
+        const courses = user.courses || [];
+        return JSON.stringify({ ok: true, courses, count: courses.length });
+    }));
+}
+//# sourceMappingURL=users.js.map

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+export declare const REQUEST_TIMEOUT_MS: number;
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class TalentLMSError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,12 @@
+export const REQUEST_TIMEOUT_MS = parseInt(process.env.TALENTLMS_REQUEST_TIMEOUT || '30000', 10);
+export class TalentLMSError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'TalentLMSError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On TalentLMSError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { TalentLMSError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On TalentLMSError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof TalentLMSError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mindstone-engineering/mcp-server-talentlms",
+  "version": "0.1.0",
+  "description": "TalentLMS MCP server for Model Context Protocol hosts — users, courses, groups, branches, reporting, assessments",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-talentlms": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/talentlms"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/talentlms",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}