@massteck/aloc-mcp-server 1.0.4 → 1.0.6

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/index.js

@@ -12,6 +12,7 @@ const server = new index_js_1.Server({
 }, {
     capabilities: {
         tools: {},
+        prompts: {},
     },
 });
 // Register available tools
@@ -473,6 +474,149 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         };
     }
 });
+// Register available prompts
+server.setRequestHandler(types_js_1.ListPromptsRequestSchema, async () => {
+    return {
+        prompts: [
+            {
+                name: "aloc_socratic_tutor",
+                description: "Enacts an adaptive Socratic tutor for African curriculum exams (JAMB, WAEC, NECO). Queries questions via ALOC tools and provides progressive hints without spoiling answers.",
+                arguments: [
+                    {
+                        name: "subject",
+                        description: "Curriculum subject (e.g. 'mathematics', 'physics', 'english')",
+                        required: true,
+                    },
+                    {
+                        name: "examType",
+                        description: "Target examination body ('jamb', 'waec', 'neco')",
+                        required: false,
+                    },
+                    {
+                        name: "topic",
+                        description: "Specific curriculum topic or concept",
+                        required: false,
+                    },
+                ],
+            },
+            {
+                name: "aloc_exam_revision_planner",
+                description: "Analyzes curriculum topic weightings and difficulty scores to compile a structured, multi-week study and mock testing timetable.",
+                arguments: [
+                    {
+                        name: "subject",
+                        description: "Target subject (e.g. 'chemistry', 'biology')",
+                        required: true,
+                    },
+                    {
+                        name: "examType",
+                        description: "Examination body (e.g. 'jamb', 'waec')",
+                        required: true,
+                    },
+                    {
+                        name: "weeksAvailable",
+                        description: "Number of weeks until the examination sitting",
+                        required: false,
+                    },
+                ],
+            },
+            {
+                name: "aloc_bloom_evaluator",
+                description: "Evaluates candidate responses, diagnoses cognitive levels (Bloom's Taxonomy), and maps common distractors to underlying misconceptions.",
+                arguments: [
+                    {
+                        name: "questionId",
+                        description: "UUID of the question being analyzed",
+                        required: true,
+                    },
+                ],
+            },
+        ],
+    };
+});
+// Handle prompt execution
+server.setRequestHandler(types_js_1.GetPromptRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    switch (name) {
+        case "aloc_socratic_tutor": {
+            const subject = args?.subject || "mathematics";
+            const examType = args?.examType || "jamb";
+            const topic = args?.topic ? ` focusing on '${args.topic}'` : "";
+            return {
+                description: `Socratic tutoring session for ${examType.toUpperCase()} ${subject}${topic}`,
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: `You are an expert, encouraging Socratic tutor specializing in West African examinations (${examType.toUpperCase()} syllabus for ${subject}${topic}).
+
+Instructions:
+1. Use the 'aloc_search_questions' tool to retrieve a verified past examination question for ${subject} (${examType}).
+2. Present the question and its multiple-choice options (A, B, C, D) clearly to the student without revealing the answer key.
+3. Invite the student to attempt the question.
+4. When the student replies:
+   - If correct: Praise their mathematical/conceptual reasoning and explain WHY it is correct using 'aloc_get_question_explanation'.
+   - If incorrect: Do NOT give away the answer key. Use 'aloc_get_question_explanation' to extract the simplified explanation and common distractor pitfalls. Give a progressive Socratic hint that guides the student to discover their own error.
+5. Offer follow-up questions from similar topics using 'aloc_find_similar_questions'.`,
+                        },
+                    },
+                ],
+            };
+        }
+        case "aloc_exam_revision_planner": {
+            const subject = args?.subject || "mathematics";
+            const examType = args?.examType || "jamb";
+            const weeks = args?.weeksAvailable || "4";
+            return {
+                description: `Study revision planner for ${examType.toUpperCase()} ${subject}`,
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: `You are an academic curriculum strategist. Create a comprehensive ${weeks}-week revision plan for a candidate preparing for the ${examType.toUpperCase()} ${subject} examination.
+
+Instructions:
+1. First, call 'aloc_get_curriculum_taxonomy' for subject '${subject}' and exam '${examType}' to retrieve the full official topic breakdown.
+2. Call 'aloc_get_subject_years' to understand the historical depth.
+3. Break the revision schedule into weekly modules:
+   - Week-by-week topic milestones
+   - High-yield topics (most frequently tested)
+   - Diagnostic mock test recommendations using 'aloc_generate_assessment' presets (e.g. 'jamb_standard_40' or 'waec_standard_50')
+   - Recommended daily practice question volume.`,
+                        },
+                    },
+                ],
+            };
+        }
+        case "aloc_bloom_evaluator": {
+            const questionId = args?.questionId || "";
+            return {
+                description: `Bloom's Taxonomy evaluation for question ${questionId}`,
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: `You are an assessment psychometrician. Analyze question ID '${questionId}' from the ALOC database.
+
+Instructions:
+1. Call 'aloc_get_question_explanation' for questionId '${questionId}' with depth 'step_by_step'.
+2. Provide a psychometric breakdown:
+   - Cognitive domain (Bloom's Taxonomy: Remember, Understand, Apply, Analyze, Evaluate, Create)
+   - Calibrated difficulty rating and computational complexity
+   - Distractor analysis: Explain what conceptual misunderstanding leads a candidate to choose each wrong option.
+   - Recommended remedial teaching strategy for educators.`,
+                        },
+                    },
+                ],
+            };
+        }
+        default:
+            throw new Error(`Unknown ALOC prompt: ${name}`);
+    }
+});
 // Start transport
 async function main() {
     const transport = new stdio_js_1.StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massteck/aloc-mcp-server",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Official Model Context Protocol (MCP) Server for ALOC assessment content infrastructure",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,10 +19,15 @@
     "aloc",
     "mcp",
     "model-context-protocol",
+    "smithery",
     "ai-agent",
     "edtech",
     "curriculum",
-    "assessment"
+    "assessment",
+    "jamb",
+    "waec",
+    "neco",
+    "cbt"
   ],
   "author": "ALOC Infrastructure Team",
   "license": "Proprietary",

package/smithery.yaml

@@ -0,0 +1,23 @@
+# Smithery.ai Model Context Protocol configuration
+# https://smithery.ai/docs/config
+
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    required:
+      - apiKey
+    properties:
+      apiKey:
+        type: string
+        description: "Your ALOC live or sandbox API key (obtain from https://aloc.com.ng/dashboard/api-keys)"
+      baseUrl:
+        type: string
+        default: "https://dev.aloc.com.ng/api/v1"
+        description: "ALOC Station API base URL"
+  commandFunction:
+    package: "@massteck/aloc-mcp-server"
+    args: []
+    env:
+      ALOC_API_KEY: "{{apiKey}}"
+      ALOC_BASE_URL: "{{baseUrl}}"

package/src/index.ts

@@ -4,6 +4,8 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { AlocClient } from "./client.js";
@@ -18,6 +20,7 @@ const server = new Server(
   {
     capabilities: {
       tools: {},
+      prompts: {},
     },
   }
 );
@@ -517,6 +520,161 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
+// Register available prompts
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return {
+    prompts: [
+      {
+        name: "aloc_socratic_tutor",
+        description:
+          "Enacts an adaptive Socratic tutor for African curriculum exams (JAMB, WAEC, NECO). Queries questions via ALOC tools and provides progressive hints without spoiling answers.",
+        arguments: [
+          {
+            name: "subject",
+            description: "Curriculum subject (e.g. 'mathematics', 'physics', 'english')",
+            required: true,
+          },
+          {
+            name: "examType",
+            description: "Target examination body ('jamb', 'waec', 'neco')",
+            required: false,
+          },
+          {
+            name: "topic",
+            description: "Specific curriculum topic or concept",
+            required: false,
+          },
+        ],
+      },
+      {
+        name: "aloc_exam_revision_planner",
+        description:
+          "Analyzes curriculum topic weightings and difficulty scores to compile a structured, multi-week study and mock testing timetable.",
+        arguments: [
+          {
+            name: "subject",
+            description: "Target subject (e.g. 'chemistry', 'biology')",
+            required: true,
+          },
+          {
+            name: "examType",
+            description: "Examination body (e.g. 'jamb', 'waec')",
+            required: true,
+          },
+          {
+            name: "weeksAvailable",
+            description: "Number of weeks until the examination sitting",
+            required: false,
+          },
+        ],
+      },
+      {
+        name: "aloc_bloom_evaluator",
+        description:
+          "Evaluates candidate responses, diagnoses cognitive levels (Bloom's Taxonomy), and maps common distractors to underlying misconceptions.",
+        arguments: [
+          {
+            name: "questionId",
+            description: "UUID of the question being analyzed",
+            required: true,
+          },
+        ],
+      },
+    ],
+  };
+});
+
+// Handle prompt execution
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    case "aloc_socratic_tutor": {
+      const subject = args?.subject || "mathematics";
+      const examType = args?.examType || "jamb";
+      const topic = args?.topic ? ` focusing on '${args.topic}'` : "";
+
+      return {
+        description: `Socratic tutoring session for ${examType.toUpperCase()} ${subject}${topic}`,
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `You are an expert, encouraging Socratic tutor specializing in West African examinations (${examType.toUpperCase()} syllabus for ${subject}${topic}).
+
+Instructions:
+1. Use the 'aloc_search_questions' tool to retrieve a verified past examination question for ${subject} (${examType}).
+2. Present the question and its multiple-choice options (A, B, C, D) clearly to the student without revealing the answer key.
+3. Invite the student to attempt the question.
+4. When the student replies:
+   - If correct: Praise their mathematical/conceptual reasoning and explain WHY it is correct using 'aloc_get_question_explanation'.
+   - If incorrect: Do NOT give away the answer key. Use 'aloc_get_question_explanation' to extract the simplified explanation and common distractor pitfalls. Give a progressive Socratic hint that guides the student to discover their own error.
+5. Offer follow-up questions from similar topics using 'aloc_find_similar_questions'.`,
+            },
+          },
+        ],
+      };
+    }
+
+    case "aloc_exam_revision_planner": {
+      const subject = args?.subject || "mathematics";
+      const examType = args?.examType || "jamb";
+      const weeks = args?.weeksAvailable || "4";
+
+      return {
+        description: `Study revision planner for ${examType.toUpperCase()} ${subject}`,
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `You are an academic curriculum strategist. Create a comprehensive ${weeks}-week revision plan for a candidate preparing for the ${examType.toUpperCase()} ${subject} examination.
+
+Instructions:
+1. First, call 'aloc_get_curriculum_taxonomy' for subject '${subject}' and exam '${examType}' to retrieve the full official topic breakdown.
+2. Call 'aloc_get_subject_years' to understand the historical depth.
+3. Break the revision schedule into weekly modules:
+   - Week-by-week topic milestones
+   - High-yield topics (most frequently tested)
+   - Diagnostic mock test recommendations using 'aloc_generate_assessment' presets (e.g. 'jamb_standard_40' or 'waec_standard_50')
+   - Recommended daily practice question volume.`,
+            },
+          },
+        ],
+      };
+    }
+
+    case "aloc_bloom_evaluator": {
+      const questionId = args?.questionId || "";
+
+      return {
+        description: `Bloom's Taxonomy evaluation for question ${questionId}`,
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `You are an assessment psychometrician. Analyze question ID '${questionId}' from the ALOC database.
+
+Instructions:
+1. Call 'aloc_get_question_explanation' for questionId '${questionId}' with depth 'step_by_step'.
+2. Provide a psychometric breakdown:
+   - Cognitive domain (Bloom's Taxonomy: Remember, Understand, Apply, Analyze, Evaluate, Create)
+   - Calibrated difficulty rating and computational complexity
+   - Distractor analysis: Explain what conceptual misunderstanding leads a candidate to choose each wrong option.
+   - Recommended remedial teaching strategy for educators.`,
+            },
+          },
+        ],
+      };
+    }
+
+    default:
+      throw new Error(`Unknown ALOC prompt: ${name}`);
+  }
+});
+
 // Start transport
 async function main() {
   const transport = new StdioServerTransport();