@tinyweb_dev/oe-exam-sdk 0.1.1 → 0.1.3

package/dist/mcp/tools/exams.js

@@ -1,439 +1 @@
-import { mkdir, writeFile } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
-import { z } from 'zod';
-import { mcpRequest } from '../http-client.js';
-import { buildToolResult, unwrapData, wrapHandler } from './_helpers.js';
-const questionSchema = z.record(z.string(), z.unknown()).describe('Full API question payload or short form: { question, options, answer, points?, partId?, partNo? }.');
-const partSchema = z.record(z.string(), z.unknown()).describe('Part payload: { name?, partId?, questions: [...] }.');
-const templateSchema = z.record(z.string(), z.unknown()).describe('Template payload accepted by PATCH /manage/exams/:id/template.');
-const examLevelSchema = z.enum(['PRE_A1', 'A1', 'A2', 'B1', 'B2', 'C1', 'C2']);
-export function registerExamTools(server) {
-    server.registerTool('exam_templates_search', {
-        title: 'Search exam templates',
-        description: 'Search available OE Exam templates. Use this before exam_create_with_questions to choose examTemplateId.',
-        inputSchema: {
-            search: z.string().optional().describe('Template name keyword.'),
-            page: z.number().int().positive().default(1).describe('1-based page number.'),
-            limit: z.number().int().positive().max(50).default(9).describe('Page size sent as API size.'),
-        },
-    }, wrapHandler('exam_templates_search', async (input) => {
-        const query = new URLSearchParams({ page: String(input.page ?? 1), size: String(input.limit ?? 9) });
-        if (input.search)
-            query.set('filter', `name:like:${input.search}`);
-        const result = await mcpRequest({ method: 'GET', url: `/api/v1/exam-templates?${query}` });
-        return buildToolResult({ templates: unwrapList(result) });
-    }));
-    server.registerTool('exam_template_get', {
-        title: 'Get exam template',
-        description: 'Get one OE Exam template by id. The returned templatePayload can be passed as template to exam_create_with_questions.',
-        inputSchema: {
-            id: z.string().min(1).describe('Template id from exam_templates_search.'),
-        },
-    }, wrapHandler('exam_template_get', async (input) => {
-        const template = unwrapData(await mcpRequest({ method: 'GET', url: `/api/v1/exam-templates/${encodeURIComponent(String(input.id))}` }));
-        return buildToolResult({ template, templatePayload: toTemplatePayload(template) });
-    }));
-    server.registerTool('exam_question_template_get', {
-        title: 'Get question payload template',
-        description: 'Return easy-to-fill question JSON templates for exam_create_with_questions. Use this before creating questions if you need the expected shape.',
-        inputSchema: {
-            templateId: z.string().min(1).optional().describe('Template id. If provided, generate question payloads from template.parts.'),
-            type: z.string().default('CHOOSE_THE_CORRECT_ANSWER').describe('Fallback question type when templateId is omitted.'),
-            count: z.number().int().positive().max(100).default(1).describe('Fallback count when templateId is omitted.'),
-            partId: z.union([z.string(), z.number()]).default(1),
-            partNo: z.number().int().positive().default(1),
-            skill: z.string().default('READING'),
-        },
-    }, wrapHandler('exam_question_template_get', async (input) => {
-        const template = typeof input.templateId === 'string'
-            ? unwrapData(await mcpRequest({ method: 'GET', url: `/api/v1/exam-templates/${encodeURIComponent(input.templateId)}` }))
-            : undefined;
-        return buildToolResult({
-            usage: 'Pass questions directly into exam_create_with_questions.questions. Fill content/correctAnswer for each generated API-format payload.',
-            templateId: template?.id,
-            questions: template ? questionsFromTemplate(template) : fallbackQuestions(input),
-        });
-    }));
-    server.registerTool('exam_json_template_generate', {
-        title: 'Get exam JSON template',
-        description: 'Generate a user-friendly examJson skeleton from templateTitle or templateId. Edit this JSON, then pass it to exam_create_from_json.',
-        inputSchema: {
-            templateTitle: z.string().optional().describe('Template title to search, e.g. Achievers 2026 Round 1.'),
-            templateId: z.string().optional().describe('Exact template id. Preferred when known.'),
-            name: z.string().optional().describe('Exam name to put in the JSON.'),
-            examLevel: examLevelSchema.optional().describe('Optional exam level for the generated JSON.'),
-            difficulty: z.enum(['EASY', 'MEDIUM', 'HARD']).optional().describe('Optional difficulty for the generated JSON.'),
-            durationMinutes: z.number().int().positive().optional().describe('Optional duration for the generated JSON.'),
-        },
-    }, wrapHandler('exam_json_template_generate', async (input) => {
-        const template = await resolveTemplate({ templateId: input.templateId, templateTitle: input.templateTitle });
-        const examJson = examJsonTemplate(template, input);
-        const examJsonString = JSON.stringify(examJson, null, 2);
-        const filePath = resolve(`${slugFromTitle(String(input.name ?? template.title ?? template.name ?? 'exam'))}.json`);
-        await mkdir(dirname(filePath), { recursive: true });
-        await writeFile(filePath, `${examJsonString}\n`, 'utf8');
-        return buildToolResult({
-            usage: 'Edit filePath, then call exam_create_from_json with the edited JSON string.',
-            templateId: template.id,
-            templateTitle: template.title ?? template.name,
-            filePath,
-            examJson,
-            examJsonString,
-        });
-    }));
-    server.registerTool('exam_create_from_json', {
-        title: 'Create exam from JSON',
-        description: 'Create an exam from a user-friendly JSON payload grouped by parts. Searches template by title, patches template, maps questions to template.parts, then creates questions.',
-        inputSchema: {
-            examJson: z.string().optional().describe('JSON string with { name, templateTitle/templateId, parts: [{ questions: [...] }] }. Use this for copy/paste.'),
-            exam: z.record(z.string(), z.unknown()).optional().describe('Same payload as object if the client supports object arguments.'),
-        },
-    }, wrapHandler('exam_create_from_json', async (input) => {
-        const examInput = parseExamJsonInput(input.examJson, input.exam);
-        const template = await resolveTemplate(examInput);
-        const questions = questionsFromExamJson(examInput, template);
-        const payload = examPayloadFromJson(examInput, template.id, questions);
-        const exam = unwrapData(await mcpRequest({ method: 'POST', url: '/api/v1/manage/exams', body: payload.exam }));
-        await mcpRequest({ method: 'PATCH', url: `/api/v1/manage/exams/${encodeURIComponent(exam.id)}/template`, body: { template: toTemplatePayload(template) } });
-        const savedQuestions = questions.length === 0 ? null : await mcpRequest({ method: 'POST', url: '/api/v1/manage/questions/batch', body: { examId: exam.id, questions } });
-        return buildToolResult({ exam, templateId: template.id, questions: savedQuestions, generatedQuestionCount: questions.length });
-    }));
-    server.registerTool('exam_create_with_questions', {
-        title: 'Create exam with questions',
-        description: 'Create an exam, optionally patch template, then bulk create questions via /api/v1/manage/questions/batch. If you do not know examTemplateId/template, call exam_templates_search then exam_template_get first.',
-        inputSchema: {
-            name: z.string().min(1),
-            code: z.string().min(1).optional(),
-            examLevel: examLevelSchema.optional().describe('Valid exam level only: PRE_A1, A1, A2, B1, B2, C1, C2. Do not use template title/id here.'),
-            difficulty: z.enum(['EASY', 'MEDIUM', 'HARD']).optional(),
-            totalScore: z.number().nonnegative().optional(),
-            durationMinutes: z.number().int().positive().optional(),
-            description: z.string().optional(),
-            isComplete: z.boolean().optional(),
-            isActive: z.boolean().optional(),
-            examTemplateId: z.string().min(1).optional(),
-            template: templateSchema.optional(),
-            questions: z.array(questionSchema).default([]),
-        },
-    }, wrapHandler('exam_create_with_questions', async (input) => {
-        const { template, questions, ...examPayload } = input;
-        const exam = unwrapData(await mcpRequest({ method: 'POST', url: '/api/v1/manage/exams', body: clean(examPayload) }));
-        const templatePayload = isNonEmptyRecord(template) ? template : await getTemplatePayload(examPayload.examTemplateId);
-        if (isNonEmptyRecord(templatePayload)) {
-            await mcpRequest({ method: 'PATCH', url: `/api/v1/manage/exams/${encodeURIComponent(exam.id)}/template`, body: { template: templatePayload } });
-        }
-        const normalizedQuestions = questions.map(normalizeQuestion);
-        const savedQuestions = normalizedQuestions.length === 0 ? null : await mcpRequest({ method: 'POST', url: '/api/v1/manage/questions/batch', body: { examId: exam.id, questions: normalizedQuestions } });
-        return buildToolResult({ exam, questions: savedQuestions });
-    }));
-}
-function clean(input) {
-    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
-}
-function isNonEmptyRecord(value) {
-    return Boolean(value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length > 0);
-}
-function parseExamJsonInput(examJson, exam) {
-    if (isNonEmptyRecord(exam))
-        return exam;
-    if (typeof examJson !== 'string' || !examJson.trim())
-        throw new Error('examJson or exam is required');
-    const parsed = JSON.parse(examJson);
-    if (!isNonEmptyRecord(parsed))
-        throw new Error('examJson must be a JSON object');
-    return parsed;
-}
-async function resolveTemplate(input) {
-    const templateId = stringOrUndefined(input.templateId);
-    if (templateId)
-        return unwrapData(await mcpRequest({ method: 'GET', url: `/api/v1/exam-templates/${encodeURIComponent(templateId)}` }));
-    const templateTitle = stringOrUndefined(input.templateTitle);
-    if (!templateTitle)
-        throw new Error('templateTitle or templateId is required');
-    const query = new URLSearchParams({ page: '1', size: '10', filter: `name:like:${templateTitle}` });
-    const templates = unwrapList(await mcpRequest({ method: 'GET', url: `/api/v1/exam-templates?${query}` }));
-    const exact = templates.find((template) => (template.title ?? template.name) === templateTitle);
-    const template = exact ?? templates[0];
-    if (!template?.id)
-        throw new Error(`No exam template found for title: ${templateTitle}`);
-    return unwrapData(await mcpRequest({ method: 'GET', url: `/api/v1/exam-templates/${encodeURIComponent(template.id)}` }));
-}
-function examPayloadFromJson(input, templateId, questions) {
-    return {
-        exam: clean({
-            name: stringValue(input.name, 'New OE Exam'),
-            code: stringOrUndefined(input.code) ?? codeFromName(stringValue(input.name, 'New OE Exam')),
-            totalScore: numberValue(input.totalScore, questions.length || 100),
-            description: stringOrUndefined(input.description) ?? stringOrUndefined(input.templateTitle) ?? '',
-            isComplete: booleanValue(input.isComplete, false),
-            isActive: booleanValue(input.isActive, false),
-            examTemplateId: templateId,
-            examLevel: validExamLevel(input.examLevel),
-            difficulty: validDifficulty(input.difficulty),
-            durationMinutes: numberOrUndefined(input.durationMinutes),
-        }),
-    };
-}
-function examJsonTemplate(template, options) {
-    const parts = Array.isArray(template.parts) ? template.parts.filter(isNonEmptyRecord) : [];
-    return {
-        name: stringValue(options.name, `${template.title ?? template.name ?? 'OE Exam'} Draft`),
-        templateId: template.id,
-        templateTitle: template.title ?? template.name,
-        totalScore: numberValue(template.totalScore ?? template.total_questions, totalQuestionCount(parts)),
-        examLevel: validExamLevel(options.examLevel) ?? validExamLevel(template.examLevel ?? template.exam_level ?? template.level) ?? 'A1',
-        difficulty: validDifficulty(options.difficulty) ?? 'MEDIUM',
-        durationMinutes: numberValue(options.durationMinutes, 45),
-        isComplete: false,
-        isActive: false,
-        parts: parts.map((part, index) => examJsonPartTemplate(part, index)),
-    };
-}
-function examJsonPartTemplate(part, index) {
-    const startIndex = numberValue(part.startIndex, 0);
-    const count = numberValue(part.questionCount, numberValue(part.endIndex, startIndex) - startIndex + 1);
-    return {
-        id: part.id ?? index + 1,
-        name: part.name ?? `Part ${index + 1}`,
-        questionType: stringValue(part.questionType, 'CHOOSE_THE_CORRECT_ANSWER'),
-        skill: stringValue(part.skill, 'READING'),
-        questions: Array.from({ length: Math.max(count, 0) }, (_, offset) => simpleQuestionTemplate(part, startIndex + offset + 1)),
-    };
-}
-function simpleQuestionTemplate(part, questionNumber) {
-    const questionType = stringValue(part.questionType, 'CHOOSE_THE_CORRECT_ANSWER');
-    const options = (Array.isArray(part.defaultValue) && part.defaultValue.length > 0
-        ? part.defaultValue
-        : Array.from({ length: numberValue(part.optionCount, 4) }, (_, index) => String.fromCharCode(65 + index))).map(String);
-    if (questionType.includes('FILL') || questionType.includes('WRITE'))
-        return { question: `Question ${questionNumber}`, answer: '' };
-    if (questionType.includes('SPEAK'))
-        return { prompt: `Question ${questionNumber}`, expectedAnswer: '' };
-    return { question: `Question ${questionNumber}`, options, answer: options[0] ?? 'A' };
-}
-function totalQuestionCount(parts) {
-    return parts.reduce((total, part) => total + numberValue(part.questionCount, 0), 0);
-}
-function questionsFromExamJson(input, template) {
-    const templateParts = Array.isArray(template.parts) ? template.parts.filter(isNonEmptyRecord) : [];
-    const parts = Array.isArray(input.parts) ? input.parts.filter(isNonEmptyRecord) : [{ questions: input.questions }];
-    return parts.flatMap((part, partIndex) => {
-        const templatePart = findTemplatePart(part, templateParts, partIndex);
-        const questions = Array.isArray(part.questions) ? part.questions.filter(isNonEmptyRecord) : [];
-        return questions.map((question, questionIndex) => questionFromPart(question, templatePart, partIndex, questionIndex));
-    });
-}
-function findTemplatePart(part, templateParts, index) {
-    const partId = stringOrUndefined(part.partId ?? part.id);
-    const name = stringOrUndefined(part.name);
-    return templateParts.find((item) => String(item.id) === partId)
-        ?? templateParts.find((item) => typeof item.name === 'string' && item.name === name)
-        ?? templateParts[index]
-        ?? { id: index + 1, questionType: 'CHOOSE_THE_CORRECT_ANSWER', skill: 'READING', optionCount: 4 };
-}
-function questionFromPart(question, part, partIndex, questionIndex) {
-    const startIndex = numberValue(part.startIndex, 0);
-    const base = questionPayload({
-        questionType: stringValue(question.questionType ?? question.type ?? part.questionType, 'CHOOSE_THE_CORRECT_ANSWER'),
-        questionNumber: numberValue(question.questionNumber, startIndex + questionIndex + 1),
-        partId: String(question.partId ?? part.id ?? partIndex + 1),
-        partNo: numberValue(question.partNo, partIndex + 1),
-        sectionId: numberOrUndefined(question.sectionId ?? part.sectionId),
-        skill: stringValue(question.questionSkillType ?? question.skill ?? part.skill, 'READING'),
-        optionCount: numberValue(part.optionCount, 4),
-        defaultValue: Array.isArray(part.defaultValue) ? part.defaultValue : undefined,
-    });
-    return normalizeQuestion(applySimpleQuestionFields({ ...base, ...question }), questionIndex);
-}
-function applySimpleQuestionFields(question) {
-    const content = isNonEmptyRecord(question.content) ? { ...question.content } : {};
-    if (typeof question.question === 'string')
-        content.question = question.question;
-    if (typeof question.text === 'string')
-        content.question = question.text;
-    if (Array.isArray(question.options)) {
-        content.optionType = content.optionType ?? 'text';
-        content.options = question.options;
-    }
-    return clean({
-        ...question,
-        content: isNonEmptyRecord(content) ? content : question.content,
-        correctAnswer: question.answer === undefined && question.expectedAnswer === undefined
-            ? question.correctAnswer
-            : simpleCorrectAnswer(question.questionType, question.answer ?? question.expectedAnswer, content.options),
-    });
-}
-function simpleCorrectAnswer(questionType, answer, options) {
-    if (answer === undefined)
-        return undefined;
-    const type = String(questionType ?? '');
-    if (type.includes('FILL') || type.includes('WRITE'))
-        return { answers: [String(answer)] };
-    if (type.includes('SPEAK'))
-        return { expectedAnswer: String(answer) };
-    return { answer: answerIndexFromOptions(answer, options) };
-}
-function answerIndexFromOptions(answer, options) {
-    if (typeof answer === 'string' && Array.isArray(options)) {
-        const index = options.map(String).findIndex((option) => option === answer);
-        if (index >= 0)
-            return index;
-    }
-    return answerIndex(answer);
-}
-function codeFromName(name) {
-    return name.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_|_$/g, '').slice(0, 40) || 'OE_EXAM';
-}
-function slugFromTitle(title) {
-    return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 80) || 'exam';
-}
-function stringOrUndefined(value) {
-    return typeof value === 'string' && value ? value : undefined;
-}
-function booleanValue(value, fallback) {
-    return typeof value === 'boolean' ? value : fallback;
-}
-function validExamLevel(value) {
-    return typeof value === 'string' && examLevelSchema.safeParse(value).success ? value : undefined;
-}
-function validDifficulty(value) {
-    return typeof value === 'string' && ['EASY', 'MEDIUM', 'HARD'].includes(value) ? value : undefined;
-}
-function normalizeQuestion(question, index) {
-    if (question.questionType)
-        return clean({
-            ...question,
-            partId: question.partId === undefined ? undefined : String(question.partId),
-            partNo: question.partNo ?? 1,
-            questionNumber: question.questionNumber ?? index + 1,
-            points: question.points ?? 1,
-            addToQuestionBank: question.addToQuestionBank ?? false,
-            isExample: question.isExample ?? false,
-        });
-    const options = Array.isArray(question.options) ? question.options : ['A', 'B', 'C', 'D'];
-    return clean({
-        questionType: question.type ?? 'CHOOSE_THE_CORRECT_ANSWER',
-        content: question.content ?? {
-            question: String(question.question ?? question.text ?? `Question ${index + 1}`),
-            optionType: 'text',
-            options,
-        },
-        correctAnswer: question.correctAnswer ?? { answer: answerIndex(question.answer ?? question.correctAnswerIndex ?? 0) },
-        points: question.points ?? 1,
-        explanation: question.explanation ?? '',
-        questionNumber: question.questionNumber ?? index + 1,
-        partId: String(question.partId ?? 1),
-        partNo: question.partNo ?? 1,
-        sectionId: question.sectionId,
-        questionSkillType: question.questionSkillType ?? question.skill ?? 'READING',
-        addToQuestionBank: question.addToQuestionBank ?? false,
-        isExample: question.isExample ?? false,
-    });
-}
-function answerIndex(value) {
-    if (typeof value === 'number')
-        return value;
-    if (typeof value === 'string' && /^[A-E]$/i.test(value))
-        return value.toUpperCase().charCodeAt(0) - 65;
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? parsed : 0;
-}
-function fallbackQuestions(input) {
-    return Array.from({ length: Number(input.count ?? 1) }, (_, index) => questionPayload({
-        questionType: String(input.type ?? 'CHOOSE_THE_CORRECT_ANSWER'),
-        questionNumber: index + 1,
-        partId: String(input.partId ?? 1),
-        partNo: Number(input.partNo ?? 1),
-        skill: String(input.skill ?? 'READING'),
-    }));
-}
-function questionsFromTemplate(template) {
-    const parts = Array.isArray(template.parts) ? template.parts.filter(isNonEmptyRecord) : [];
-    return parts.flatMap((part, partIndex) => {
-        const startIndex = numberValue(part.startIndex, 0);
-        const count = numberValue(part.questionCount, numberValue(part.endIndex, startIndex) - startIndex + 1);
-        return Array.from({ length: Math.max(count, 0) }, (_, offset) => questionPayload({
-            questionType: stringValue(part.questionType, 'CHOOSE_THE_CORRECT_ANSWER'),
-            questionNumber: startIndex + offset + 1,
-            partId: String(part.id ?? partIndex + 1),
-            partNo: partIndex + 1,
-            sectionId: numberOrUndefined(part.sectionId),
-            skill: stringValue(part.skill, 'READING'),
-            optionCount: numberValue(part.optionCount, 4),
-            defaultValue: Array.isArray(part.defaultValue) ? part.defaultValue : undefined,
-        }));
-    });
-}
-function questionPayload(input) {
-    return clean({
-        questionType: input.questionType,
-        content: contentTemplate(input.questionType, input.questionNumber, input.optionCount, input.defaultValue),
-        correctAnswer: correctAnswerTemplate(input.questionType),
-        points: 1,
-        explanation: '',
-        questionNumber: input.questionNumber,
-        partId: input.partId,
-        partNo: input.partNo,
-        sectionId: input.sectionId,
-        questionSkillType: input.skill,
-        addToQuestionBank: false,
-        isExample: false,
-    });
-}
-function contentTemplate(questionType, questionNumber, optionCount = 4, defaultValue) {
-    const options = (defaultValue?.length ? defaultValue : Array.from({ length: optionCount }, (_, index) => String.fromCharCode(65 + index))).map(String);
-    if (questionType.includes('FILL') || questionType.includes('WRITE'))
-        return { question: `Question ${questionNumber}`, text: '' };
-    if (questionType.includes('SPEAK'))
-        return { prompt: `Question ${questionNumber}` };
-    if (questionType.includes('LISTEN'))
-        return { question: `Question ${questionNumber}`, audioUrl: '', optionType: 'text', options };
-    return { question: `Question ${questionNumber}`, optionType: 'text', options };
-}
-function correctAnswerTemplate(questionType) {
-    if (questionType.includes('FILL') || questionType.includes('WRITE'))
-        return { answers: [''] };
-    if (questionType.includes('SPEAK'))
-        return { expectedAnswer: '' };
-    return { answer: 0 };
-}
-function stringValue(value, fallback) {
-    return typeof value === 'string' && value ? value : fallback;
-}
-function numberValue(value, fallback) {
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? parsed : fallback;
-}
-function numberOrUndefined(value) {
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? parsed : undefined;
-}
-function unwrapList(value) {
-    const data = unwrapData(value);
-    if (Array.isArray(data))
-        return data;
-    if (data && typeof data === 'object' && 'data' in data && Array.isArray(data.data))
-        return data.data;
-    return [];
-}
-async function getTemplatePayload(id) {
-    if (typeof id !== 'string' || !id)
-        return undefined;
-    const template = unwrapData(await mcpRequest({ method: 'GET', url: `/api/v1/exam-templates/${encodeURIComponent(id)}` }));
-    return toTemplatePayload(template);
-}
-function toTemplatePayload(template) {
-    const parts = Array.isArray(template.parts) ? template.parts : [];
-    return clean({
-        id: template.id,
-        title: template.title ?? template.name,
-        subTitle: template.subTitle ?? template.sub_title ?? '',
-        theme: template.theme,
-        totalQuestions: template.totalQuestions ?? template.total_questions,
-        totalParts: template.totalParts ?? template.total_parts ?? parts.length,
-        description: template.description ?? '',
-        examLevel: template.examLevel ?? template.exam_level ?? template.level ?? '',
-        type: template.type ?? null,
-        parts,
-    });
-}
+import{mkdir as e,writeFile as t}from"node:fs/promises";import{dirname as n,resolve as i}from"node:path";import{z as a}from"zod";import{mcpRequest as o}from"../http-client.js";import{buildToolResult as r,unwrapData as s,wrapHandler as l}from"./_helpers.js";const p=a.record(a.string(),a.unknown()).describe("Full API question payload or short form: { question, options, answer, points?, partId?, partNo? }."),u=(a.record(a.string(),a.unknown()).describe("Part payload: { name?, partId?, questions: [...] }."),a.record(a.string(),a.unknown()).describe("Template payload accepted by PATCH /manage/exams/:id/template.")),m=a.enum(["PRE_A1","A1","A2","B1","B2","C1","C2"]);export function registerExamTools(g){g.registerTool("exam_templates_search",{title:"Search exam templates",description:"Search available OE Exam templates. Use this before exam_create_with_questions to choose examTemplateId.",inputSchema:{search:a.string().optional().describe("Template name keyword."),page:a.number().int().positive().default(1).describe("1-based page number."),limit:a.number().int().positive().max(50).default(9).describe("Page size sent as API size.")}},l("exam_templates_search",async e=>{const t=new URLSearchParams({page:String(e.page??1),size:String(e.limit??9)});e.search&&t.set("filter",`name:like:${e.search}`);const n=await o({method:"GET",url:`/api/v1/exam-templates?${t}`});return r({templates:k(n)})})),g.registerTool("exam_template_get",{title:"Get exam template",description:"Get one OE Exam template by id. The returned templatePayload can be passed as template to exam_create_with_questions.",inputSchema:{id:a.string().min(1).describe("Template id from exam_templates_search.")}},l("exam_template_get",async e=>{const t=s(await o({method:"GET",url:`/api/v1/exam-templates/${encodeURIComponent(String(e.id))}`}));return r({template:t,templatePayload:P(t)})})),g.registerTool("exam_question_template_get",{title:"Get question payload template",description:"Return easy-to-fill question JSON templates for exam_create_with_questions. Use this before creating questions if you need the expected shape.",inputSchema:{templateId:a.string().min(1).optional().describe("Template id. If provided, generate question payloads from template.parts."),type:a.string().default("CHOOSE_THE_CORRECT_ANSWER").describe("Fallback question type when templateId is omitted."),count:a.number().int().positive().max(100).default(1).describe("Fallback count when templateId is omitted."),partId:a.union([a.string(),a.number()]).default(1),partNo:a.number().int().positive().default(1),skill:a.string().default("READING")}},l("exam_question_template_get",async e=>{const t="string"==typeof e.templateId?s(await o({method:"GET",url:`/api/v1/exam-templates/${encodeURIComponent(e.templateId)}`})):void 0;return r({usage:"Pass questions directly into exam_create_with_questions.questions. Fill content/correctAnswer for each generated API-format payload.",templateId:t?.id,questions:t?b(t):S(e)})})),g.registerTool("exam_json_template_generate",{title:"Get exam JSON template",description:"Generate a user-friendly examJson skeleton from templateTitle or templateId. Edit this JSON, then pass it to exam_create_from_json.",inputSchema:{templateTitle:a.string().optional().describe("Template title to search, e.g. Achievers 2026 Round 1."),templateId:a.string().optional().describe("Exact template id. Preferred when known."),name:a.string().optional().describe("Exam name to put in the JSON."),examLevel:m.optional().describe("Optional exam level for the generated JSON."),difficulty:a.enum(["EASY","MEDIUM","HARD"]).optional().describe("Optional difficulty for the generated JSON."),durationMinutes:a.number().int().positive().optional().describe("Optional duration for the generated JSON.")}},l("exam_json_template_generate",async a=>{const o=await f({templateId:a.templateId,templateTitle:a.templateTitle}),s=function(e,t){const n=Array.isArray(e.parts)?e.parts.filter(c):[];return{name:v(t.name,`${e.title??e.name??"OE Exam"} Draft`),templateId:e.id,templateTitle:e.title??e.name,totalScore:O(e.totalScore??e.total_questions,y(n)),examLevel:_(t.examLevel)??_(e.examLevel??e.exam_level??e.level)??"A1",difficulty:E(t.difficulty)??"MEDIUM",durationMinutes:O(t.durationMinutes,45),isComplete:!1,isActive:!1,parts:n.map((e,t)=>function(e,t){const n=O(e.startIndex,0),i=O(e.questionCount,O(e.endIndex,n)-n+1);return{id:e.id??t+1,name:e.name??`Part ${t+1}`,questionType:v(e.questionType,"CHOOSE_THE_CORRECT_ANSWER"),skill:v(e.skill,"READING"),questions:Array.from({length:Math.max(i,0)},(t,i)=>function(e,t){const n=v(e.questionType,"CHOOSE_THE_CORRECT_ANSWER"),i=(Array.isArray(e.defaultValue)&&e.defaultValue.length>0?e.defaultValue:Array.from({length:O(e.optionCount,4)},(e,t)=>String.fromCharCode(65+t))).map(String);return n.includes("FILL")||n.includes("WRITE")?{question:`Question ${t}`,answer:""}:n.includes("SPEAK")?{prompt:`Question ${t}`,expectedAnswer:""}:{question:`Question ${t}`,options:i,answer:i[0]??"A"}}(e,n+i+1))}}(e,t))}}(o,a),l=JSON.stringify(s,null,2),p=i(`${u=String(a.name??o.title??o.name??"exam"),u.toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-|-$/g,"").slice(0,80)||"exam"}.json`);var u;return await e(n(p),{recursive:!0}),await t(p,`${l}\n`,"utf8"),r({usage:"Edit filePath, then call exam_create_from_json with the edited JSON string.",templateId:o.id,templateTitle:o.title??o.name,filePath:p,examJson:s,examJsonString:l})})),g.registerTool("exam_create_from_json",{title:"Create exam from JSON",description:"Create an exam from a user-friendly JSON payload grouped by parts. Searches template by title, patches template, maps questions to template.parts, then creates questions.",inputSchema:{examJson:a.string().optional().describe("JSON string with { name, templateTitle/templateId, parts: [{ questions: [...] }] }. Use this for copy/paste."),exam:a.record(a.string(),a.unknown()).optional().describe("Same payload as object if the client supports object arguments.")}},l("exam_create_from_json",async e=>{const t=function(e,t){if(c(t))return t;if("string"!=typeof e||!e.trim())throw new Error("examJson or exam is required");const n=JSON.parse(e);if(!c(n))throw new Error("examJson must be a JSON object");return n}(e.examJson,e.exam),n=await f(t),i=function(e,t){const n=Array.isArray(t.parts)?t.parts.filter(c):[],i=Array.isArray(e.parts)?e.parts.filter(c):[{questions:e.questions}];return i.flatMap((e,t)=>{const i=function(e,t,n){const i=A(e.partId??e.id),a=A(e.name);return t.find(e=>String(e.id)===i)??t.find(e=>"string"==typeof e.name&&e.name===a)??t[n]??{id:n+1,questionType:"CHOOSE_THE_CORRECT_ANSWER",skill:"READING",optionCount:4}}(e,n,t);return(Array.isArray(e.questions)?e.questions.filter(c):[]).map((e,n)=>function(e,t,n,i){const a=O(t.startIndex,0),o=w({questionType:v(e.questionType??e.type??t.questionType,"CHOOSE_THE_CORRECT_ANSWER"),questionNumber:O(e.questionNumber,a+i+1),partId:String(e.partId??t.id??n+1),partNo:O(e.partNo,n+1),sectionId:R(e.sectionId??t.sectionId),skill:v(e.questionSkillType??e.skill??t.skill,"READING"),optionCount:O(t.optionCount,4),defaultValue:Array.isArray(t.defaultValue)?t.defaultValue:void 0});return q(function(e){const t=c(e.content)?{...e.content}:{};"string"==typeof e.question&&(t.question=e.question);"string"==typeof e.text&&(t.question=e.text);Array.isArray(e.options)&&(t.optionType=t.optionType??"text",t.options=e.options);return d({...e,content:c(t)?t:e.content,correctAnswer:void 0===e.answer&&void 0===e.expectedAnswer?e.correctAnswer:x(e.questionType,e.answer??e.expectedAnswer,t.options)})}({...o,...e}),i)}(e,i,t,n))})}(t,n),a=function(e,t,n){return{exam:d({name:v(e.name,"New OE Exam"),code:A(e.code)??h(v(e.name,"New OE Exam")),totalScore:O(e.totalScore,n.length||100),description:A(e.description)??A(e.templateTitle)??"",isComplete:T(e.isComplete,!1),isActive:T(e.isActive,!1),examTemplateId:t,examLevel:_(e.examLevel),difficulty:E(e.difficulty),durationMinutes:R(e.durationMinutes)})}}(t,n.id,i),l=s(await o({method:"POST",url:"/api/v1/manage/exams",body:a.exam}));await o({method:"PATCH",url:`/api/v1/manage/exams/${encodeURIComponent(l.id)}/template`,body:{template:P(n)}});const p=0===i.length?null:await o({method:"POST",url:"/api/v1/manage/questions/batch",body:{examId:l.id,questions:i}});return r({exam:l,templateId:n.id,questions:p,generatedQuestionCount:i.length})})),g.registerTool("exam_create_with_questions",{title:"Create exam with questions",description:"Create an exam, optionally patch template, then bulk create questions via /api/v1/manage/questions/batch. If you do not know examTemplateId/template, call exam_templates_search then exam_template_get first.",inputSchema:{name:a.string().min(1),code:a.string().min(1).optional(),examLevel:m.optional().describe("Valid exam level only: PRE_A1, A1, A2, B1, B2, C1, C2. Do not use template title/id here."),difficulty:a.enum(["EASY","MEDIUM","HARD"]).optional(),totalScore:a.number().nonnegative().optional(),durationMinutes:a.number().int().positive().optional(),description:a.string().optional(),isComplete:a.boolean().optional(),isActive:a.boolean().optional(),examTemplateId:a.string().min(1).optional(),template:u.optional(),questions:a.array(p).default([])}},l("exam_create_with_questions",async e=>{const{template:t,questions:n,...i}=e,a=s(await o({method:"POST",url:"/api/v1/manage/exams",body:d(i)})),l=c(t)?t:await async function(e){if("string"!=typeof e||!e)return;const t=s(await o({method:"GET",url:`/api/v1/exam-templates/${encodeURIComponent(e)}`}));return P(t)}(i.examTemplateId);c(l)&&await o({method:"PATCH",url:`/api/v1/manage/exams/${encodeURIComponent(a.id)}/template`,body:{template:l}});const p=n.map(q),u=0===p.length?null:await o({method:"POST",url:"/api/v1/manage/questions/batch",body:{examId:a.id,questions:p}});return r({exam:a,questions:u})}))}function d(e){return Object.fromEntries(Object.entries(e).filter(([,e])=>void 0!==e))}function c(e){return Boolean(e&&"object"==typeof e&&!Array.isArray(e)&&Object.keys(e).length>0)}async function f(e){const t=A(e.templateId);if(t)return s(await o({method:"GET",url:`/api/v1/exam-templates/${encodeURIComponent(t)}`}));const n=A(e.templateTitle);if(!n)throw new Error("templateTitle or templateId is required");const i=new URLSearchParams({page:"1",size:"10",filter:`name:like:${n}`}),a=k(await o({method:"GET",url:`/api/v1/exam-templates?${i}`})),r=a.find(e=>(e.title??e.name)===n),l=r??a[0];if(!l?.id)throw new Error(`No exam template found for title: ${n}`);return s(await o({method:"GET",url:`/api/v1/exam-templates/${encodeURIComponent(l.id)}`}))}function y(e){return e.reduce((e,t)=>e+O(t.questionCount,0),0)}function x(e,t,n){if(void 0===t)return;const i=String(e??"");return i.includes("FILL")||i.includes("WRITE")?{answers:[String(t)]}:i.includes("SPEAK")?{expectedAnswer:String(t)}:{answer:g(t,n)}}function g(e,t){if("string"==typeof e&&Array.isArray(t)){const n=t.map(String).findIndex(t=>t===e);if(n>=0)return n}return I(e)}function h(e){return e.toUpperCase().replace(/[^A-Z0-9]+/g,"_").replace(/^_|_$/g,"").slice(0,40)||"OE_EXAM"}function A(e){return"string"==typeof e&&e?e:void 0}function T(e,t){return"boolean"==typeof e?e:t}function _(e){return"string"==typeof e&&m.safeParse(e).success?e:void 0}function E(e){return"string"==typeof e&&["EASY","MEDIUM","HARD"].includes(e)?e:void 0}function q(e,t){if(e.questionType)return d({...e,partId:void 0===e.partId?void 0:String(e.partId),partNo:e.partNo??1,questionNumber:e.questionNumber??t+1,points:e.points??1,addToQuestionBank:e.addToQuestionBank??!1,isExample:e.isExample??!1});const n=Array.isArray(e.options)?e.options:["A","B","C","D"];return d({questionType:e.type??"CHOOSE_THE_CORRECT_ANSWER",content:e.content??{question:String(e.question??e.text??`Question ${t+1}`),optionType:"text",options:n},correctAnswer:e.correctAnswer??{answer:I(e.answer??e.correctAnswerIndex??0)},points:e.points??1,explanation:e.explanation??"",questionNumber:e.questionNumber??t+1,partId:String(e.partId??1),partNo:e.partNo??1,sectionId:e.sectionId,questionSkillType:e.questionSkillType??e.skill??"READING",addToQuestionBank:e.addToQuestionBank??!1,isExample:e.isExample??!1})}function I(e){if("number"==typeof e)return e;if("string"==typeof e&&/^[A-E]$/i.test(e))return e.toUpperCase().charCodeAt(0)-65;const t=Number(e);return Number.isFinite(t)?t:0}function S(e){return Array.from({length:Number(e.count??1)},(t,n)=>w({questionType:String(e.type??"CHOOSE_THE_CORRECT_ANSWER"),questionNumber:n+1,partId:String(e.partId??1),partNo:Number(e.partNo??1),skill:String(e.skill??"READING")}))}function b(e){return(Array.isArray(e.parts)?e.parts.filter(c):[]).flatMap((e,t)=>{const n=O(e.startIndex,0),i=O(e.questionCount,O(e.endIndex,n)-n+1);return Array.from({length:Math.max(i,0)},(i,a)=>w({questionType:v(e.questionType,"CHOOSE_THE_CORRECT_ANSWER"),questionNumber:n+a+1,partId:String(e.id??t+1),partNo:t+1,sectionId:R(e.sectionId),skill:v(e.skill,"READING"),optionCount:O(e.optionCount,4),defaultValue:Array.isArray(e.defaultValue)?e.defaultValue:void 0}))})}function w(e){return d({questionType:e.questionType,content:C(e.questionType,e.questionNumber,e.optionCount,e.defaultValue),correctAnswer:N(e.questionType),points:1,explanation:"",questionNumber:e.questionNumber,partId:e.partId,partNo:e.partNo,sectionId:e.sectionId,questionSkillType:e.skill,addToQuestionBank:!1,isExample:!1})}function C(e,t,n=4,i){const a=(i?.length?i:Array.from({length:n},(e,t)=>String.fromCharCode(65+t))).map(String);return e.includes("FILL")||e.includes("WRITE")?{question:`Question ${t}`,text:""}:e.includes("SPEAK")?{prompt:`Question ${t}`}:e.includes("LISTEN")?{question:`Question ${t}`,audioUrl:"",optionType:"text",options:a}:{question:`Question ${t}`,optionType:"text",options:a}}function N(e){return e.includes("FILL")||e.includes("WRITE")?{answers:[""]}:e.includes("SPEAK")?{expectedAnswer:""}:{answer:0}}function v(e,t){return"string"==typeof e&&e?e:t}function O(e,t){const n=Number(e);return Number.isFinite(n)?n:t}function R(e){const t=Number(e);return Number.isFinite(t)?t:void 0}function k(e){const t=s(e);return Array.isArray(t)?t:t&&"object"==typeof t&&"data"in t&&Array.isArray(t.data)?t.data:[]}function P(e){const t=Array.isArray(e.parts)?e.parts:[];return d({id:e.id,title:e.title??e.name,subTitle:e.subTitle??e.sub_title??"",theme:e.theme,totalQuestions:e.totalQuestions??e.total_questions,totalParts:e.totalParts??e.total_parts??t.length,description:e.description??"",examLevel:e.examLevel??e.exam_level??e.level??"",type:e.type??null,parts:t})}

package/dist/mcp/tools/index.js

@@ -1,6 +1 @@
-import { registerExamTools } from './exams.js';
-import { registerResultTools } from './results.js';
-export function registerAllMcpTools(server) {
-    registerExamTools(server);
-    registerResultTools(server);
-}
+import{registerExamTools as o}from"./exams.js";import{registerResultTools as r}from"./results.js";export function registerAllMcpTools(s){o(s),r(s)}

package/dist/mcp/tools/results.js

@@ -1,19 +1 @@
-import { z } from 'zod';
-import { mcpRequest } from '../http-client.js';
-import { buildToolResult, wrapHandler } from './_helpers.js';
-export function registerResultTools(server) {
-    server.registerTool('exam_result_get', {
-        title: 'Get exam result review',
-        description: 'Fetch student exam result review by attemptId. Optional token supports public result review links.',
-        inputSchema: {
-            attemptId: z.string().min(1),
-            token: z.string().min(1).optional(),
-            includeAttempt: z.boolean().default(true),
-        },
-    }, wrapHandler('exam_result_get', async ({ attemptId, token, includeAttempt }) => {
-        const query = token ? `?token=${encodeURIComponent(String(token))}` : '';
-        const result = await mcpRequest({ method: 'GET', url: `/api/v1/student/results/${encodeURIComponent(String(attemptId))}${query}` });
-        const attempt = includeAttempt === false ? null : await mcpRequest({ method: 'GET', url: `/api/v1/student/attempts/${encodeURIComponent(String(attemptId))}${query}` });
-        return buildToolResult({ result, attempt });
-    }));
-}
+import{z as t}from"zod";import{mcpRequest as e}from"../http-client.js";import{buildToolResult as n,wrapHandler as o}from"./_helpers.js";export function registerResultTools(r){r.registerTool("exam_result_get",{title:"Get exam result review",description:"Fetch student exam result review by attemptId. Optional token supports public result review links.",inputSchema:{attemptId:t.string().min(1),token:t.string().min(1).optional(),includeAttempt:t.boolean().default(!0)}},o("exam_result_get",async({attemptId:t,token:o,includeAttempt:r})=>{const i=o?`?token=${encodeURIComponent(String(o))}`:"",s=await e({method:"GET",url:`/api/v1/student/results/${encodeURIComponent(String(t))}${i}`}),l=!1===r?null:await e({method:"GET",url:`/api/v1/student/attempts/${encodeURIComponent(String(t))}${i}`});return n({result:s,attempt:l})}))}