@massteck/aloc-mcp-server 1.0.3 → 1.0.5

package/README.md

@@ -13,6 +13,9 @@ Official Model Context Protocol (MCP) server for **ALOC** (`@massteck/aloc-mcp-s
 | `aloc_get_subject_years` | Discovery | **0 credits** | Available examination years for a specific subject & body. |
 | `aloc_check_credit_balance` | Account | **0 credits** | Check remaining API credit balance & authentication status. |
 | `aloc_search_questions` | Content | **1–3 credits** | Search curriculum-aligned examination questions with options, topics, and difficulty. |
+| `aloc_generate_assessment` | Assessment | **1 credit** | Assemble psychometrically balanced examination papers based on presets, topics, and seeds. |
+| `aloc_create_assessment_session` | Assessment | **1 credit** | Initialize a timed candidate test session (2-hour lifecycle) for cheat-resistant delivery. |
+| `aloc_get_session_questions` | Assessment | **1 credit** | Retrieve questions allocated to an active candidate assessment session. |
 | `aloc_get_question_explanation` | Learning | **10 credits** | Retrieve step-by-step solutions, misconceptions, and remedial hints. |
 | `aloc_get_curriculum_taxonomy` | Curriculum | **Free/3 credits** | Explore the topic taxonomy and syllabus hierarchy. |
 | `aloc_find_similar_questions` | Intelligence | **10 credits** | Find vector-similar exam questions. |

package/dist/client.d.ts

@@ -116,4 +116,36 @@ export declare class AlocClient {
      * Report an error, typo, or disputed answer on a question.
      */
     reportQuestionIssue(questionId: string, type: "question" | "option_a" | "option_b" | "option_c" | "option_d" | "correct_answer" | "explanation" | "other", message: string, reporterName?: string): Promise<any>;
+    /**
+     * Generate a psychometrically balanced examination assessment paper.
+     */
+    generateAssessment(params: {
+        subject: string;
+        examType: string;
+        preset?: "jamb_standard_40" | "waec_standard_50" | "micro_test_10" | "custom";
+        count?: number;
+        seed?: string;
+        shuffleOptions?: boolean;
+        difficultyDistribution?: {
+            easy?: number;
+            medium?: number;
+            hard?: number;
+        };
+        topics?: string[];
+    }): Promise<any>;
+    /**
+     * Start a timed candidate assessment sitting (2-hour lifecycle).
+     */
+    createAssessmentSession(params: {
+        subject: string;
+        examType: string;
+        preset?: "jamb_standard_40" | "waec_standard_50" | "micro_test_10" | "custom";
+        count?: number;
+        seed?: string;
+        shuffleOptions?: boolean;
+    }): Promise<any>;
+    /**
+     * Retrieve questions allocated to an active candidate assessment session.
+     */
+    getSessionQuestions(sessionId: string): Promise<any>;
 }

package/dist/client.js

@@ -171,5 +171,26 @@ class AlocClient {
         });
         return response.data;
     }
+    /**
+     * Generate a psychometrically balanced examination assessment paper.
+     */
+    async generateAssessment(params) {
+        const response = await this.http.post("/assessments/generate", params);
+        return response.data;
+    }
+    /**
+     * Start a timed candidate assessment sitting (2-hour lifecycle).
+     */
+    async createAssessmentSession(params) {
+        const response = await this.http.post("/assessments/sessions", params);
+        return response.data;
+    }
+    /**
+     * Retrieve questions allocated to an active candidate assessment session.
+     */
+    async getSessionQuestions(sessionId) {
+        const response = await this.http.get(`/assessments/sessions/${encodeURIComponent(sessionId)}/questions`);
+        return response.data;
+    }
 }
 exports.AlocClient = AlocClient;

package/dist/index.js

@@ -191,6 +191,99 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
                     required: ["questionId", "type", "message"],
                 },
             },
+            {
+                name: "aloc_generate_assessment",
+                description: "Assemble a psychometrically balanced examination paper based on syllabus presets (JAMB 40, WAEC 50, Micro 10) or custom Bloom difficulty distributions, topics, and seeds. Consumes 1 ALOC credit.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        subject: {
+                            type: "string",
+                            description: "Subject name (e.g. 'mathematics', 'physics', 'english')",
+                        },
+                        examType: {
+                            type: "string",
+                            enum: ["waec", "jamb", "neco", "post_utme", "state"],
+                            description: "Target African examination body",
+                        },
+                        preset: {
+                            type: "string",
+                            enum: ["jamb_standard_40", "waec_standard_50", "micro_test_10", "custom"],
+                            description: "Standard syllabus preset",
+                        },
+                        count: {
+                            type: "number",
+                            description: "Number of questions (max 60, default 40)",
+                        },
+                        seed: {
+                            type: "string",
+                            description: "Deterministic seed for reproducible student batches",
+                        },
+                        shuffleOptions: {
+                            type: "boolean",
+                            description: "Whether to randomize distractor option keys (anti-cheating)",
+                            default: false,
+                        },
+                        topics: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Specific topics to cover in the assessment",
+                        },
+                    },
+                    required: ["subject", "examType"],
+                },
+            },
+            {
+                name: "aloc_create_assessment_session",
+                description: "Initialize a timed candidate assessment session (2-hour lifecycle) for secure, cheat-resistant live test delivery. Consumes 1 ALOC credit.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        subject: {
+                            type: "string",
+                            description: "Subject name",
+                        },
+                        examType: {
+                            type: "string",
+                            enum: ["waec", "jamb", "neco", "post_utme", "state"],
+                            description: "Examination body",
+                        },
+                        preset: {
+                            type: "string",
+                            enum: ["jamb_standard_40", "waec_standard_50", "micro_test_10", "custom"],
+                            description: "Standard syllabus preset",
+                        },
+                        count: {
+                            type: "number",
+                            description: "Number of questions to assemble",
+                        },
+                        seed: {
+                            type: "string",
+                            description: "Deterministic student candidate seed",
+                        },
+                        shuffleOptions: {
+                            type: "boolean",
+                            description: "Whether to shuffle option distractors",
+                            default: false,
+                        },
+                    },
+                    required: ["subject", "examType"],
+                },
+            },
+            {
+                name: "aloc_get_session_questions",
+                description: "Retrieve questions allocated to an active candidate assessment session. Consumes 1 ALOC credit.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        sessionId: {
+                            type: "string",
+                            description: "UUID of the active assessment session",
+                        },
+                    },
+                    required: ["sessionId"],
+                },
+            },
         ],
     };
 });
@@ -311,6 +404,58 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case "aloc_generate_assessment": {
+                const { subject, examType, preset, count, seed, shuffleOptions, difficultyDistribution, topics, } = (args || {});
+                const result = await client.generateAssessment({
+                    subject,
+                    examType,
+                    preset,
+                    count,
+                    seed,
+                    shuffleOptions,
+                    difficultyDistribution,
+                    topics,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "aloc_create_assessment_session": {
+                const { subject, examType, preset, count, seed, shuffleOptions } = (args || {});
+                const result = await client.createAssessmentSession({
+                    subject,
+                    examType,
+                    preset,
+                    count,
+                    seed,
+                    shuffleOptions,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "aloc_get_session_questions": {
+                const { sessionId } = (args || {});
+                const result = await client.getSessionQuestions(sessionId);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
             default:
                 throw new Error(`Unknown ALOC tool: ${name}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massteck/aloc-mcp-server",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Official Model Context Protocol (MCP) Server for ALOC assessment content infrastructure",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/client.ts

@@ -200,4 +200,44 @@ export class AlocClient {
     });
     return response.data;
   }
+
+  /**
+   * Generate a psychometrically balanced examination assessment paper.
+   */
+  public async generateAssessment(params: {
+    subject: string;
+    examType: string;
+    preset?: "jamb_standard_40" | "waec_standard_50" | "micro_test_10" | "custom";
+    count?: number;
+    seed?: string;
+    shuffleOptions?: boolean;
+    difficultyDistribution?: { easy?: number; medium?: number; hard?: number };
+    topics?: string[];
+  }) {
+    const response = await this.http.post("/assessments/generate", params);
+    return response.data;
+  }
+
+  /**
+   * Start a timed candidate assessment sitting (2-hour lifecycle).
+   */
+  public async createAssessmentSession(params: {
+    subject: string;
+    examType: string;
+    preset?: "jamb_standard_40" | "waec_standard_50" | "micro_test_10" | "custom";
+    count?: number;
+    seed?: string;
+    shuffleOptions?: boolean;
+  }) {
+    const response = await this.http.post("/assessments/sessions", params);
+    return response.data;
+  }
+
+  /**
+   * Retrieve questions allocated to an active candidate assessment session.
+   */
+  public async getSessionQuestions(sessionId: string) {
+    const response = await this.http.get(`/assessments/sessions/${encodeURIComponent(sessionId)}/questions`);
+    return response.data;
+  }
 }

package/src/index.ts

@@ -208,6 +208,102 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ["questionId", "type", "message"],
         },
       },
+      {
+        name: "aloc_generate_assessment",
+        description:
+          "Assemble a psychometrically balanced examination paper based on syllabus presets (JAMB 40, WAEC 50, Micro 10) or custom Bloom difficulty distributions, topics, and seeds. Consumes 1 ALOC credit.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            subject: {
+              type: "string",
+              description: "Subject name (e.g. 'mathematics', 'physics', 'english')",
+            },
+            examType: {
+              type: "string",
+              enum: ["waec", "jamb", "neco", "post_utme", "state"],
+              description: "Target African examination body",
+            },
+            preset: {
+              type: "string",
+              enum: ["jamb_standard_40", "waec_standard_50", "micro_test_10", "custom"],
+              description: "Standard syllabus preset",
+            },
+            count: {
+              type: "number",
+              description: "Number of questions (max 60, default 40)",
+            },
+            seed: {
+              type: "string",
+              description: "Deterministic seed for reproducible student batches",
+            },
+            shuffleOptions: {
+              type: "boolean",
+              description: "Whether to randomize distractor option keys (anti-cheating)",
+              default: false,
+            },
+            topics: {
+              type: "array",
+              items: { type: "string" },
+              description: "Specific topics to cover in the assessment",
+            },
+          },
+          required: ["subject", "examType"],
+        },
+      },
+      {
+        name: "aloc_create_assessment_session",
+        description:
+          "Initialize a timed candidate assessment session (2-hour lifecycle) for secure, cheat-resistant live test delivery. Consumes 1 ALOC credit.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            subject: {
+              type: "string",
+              description: "Subject name",
+            },
+            examType: {
+              type: "string",
+              enum: ["waec", "jamb", "neco", "post_utme", "state"],
+              description: "Examination body",
+            },
+            preset: {
+              type: "string",
+              enum: ["jamb_standard_40", "waec_standard_50", "micro_test_10", "custom"],
+              description: "Standard syllabus preset",
+            },
+            count: {
+              type: "number",
+              description: "Number of questions to assemble",
+            },
+            seed: {
+              type: "string",
+              description: "Deterministic student candidate seed",
+            },
+            shuffleOptions: {
+              type: "boolean",
+              description: "Whether to shuffle option distractors",
+              default: false,
+            },
+          },
+          required: ["subject", "examType"],
+        },
+      },
+      {
+        name: "aloc_get_session_questions",
+        description:
+          "Retrieve questions allocated to an active candidate assessment session. Consumes 1 ALOC credit.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            sessionId: {
+              type: "string",
+              description: "UUID of the active assessment session",
+            },
+          },
+          required: ["sessionId"],
+        },
+      },
     ],
   };
 });
@@ -339,6 +435,70 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
+      case "aloc_generate_assessment": {
+        const {
+          subject,
+          examType,
+          preset,
+          count,
+          seed,
+          shuffleOptions,
+          difficultyDistribution,
+          topics,
+        } = (args || {}) as any;
+        const result = await client.generateAssessment({
+          subject,
+          examType,
+          preset,
+          count,
+          seed,
+          shuffleOptions,
+          difficultyDistribution,
+          topics,
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "aloc_create_assessment_session": {
+        const { subject, examType, preset, count, seed, shuffleOptions } = (args || {}) as any;
+        const result = await client.createAssessmentSession({
+          subject,
+          examType,
+          preset,
+          count,
+          seed,
+          shuffleOptions,
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "aloc_get_session_questions": {
+        const { sessionId } = (args || {}) as any;
+        const result = await client.getSessionQuestions(sessionId);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
       default:
         throw new Error(`Unknown ALOC tool: ${name}`);
     }