@massteck/aloc-mcp-server 1.0.5 → 1.0.7

package/README.md

@@ -23,15 +23,33 @@ Official Model Context Protocol (MCP) server for **ALOC** (`@massteck/aloc-mcp-s
 
 ---
 
-## Quickstart
+## Standard MCP Prompts
 
-### 1. Installation
+In addition to tools, the server registers standard pedagogical prompt templates:
+
+| Prompt | Target Domain | Description |
+| :--- | :---: | :--- |
+| `aloc_socratic_tutor` | Socratic Pedagogy | Guides LLMs to retrieve questions and provide progressive hints without spoiling answers. |
+| `aloc_exam_revision_planner` | Curriculum Planning | Analyzes syllabus topic hierarchies and Bloom difficulty to compile structured study timetables. |
+| `aloc_bloom_evaluator` | Psychometrics | Evaluates cognitive complexity and diagnoses underlying student misconceptions. |
+
+---
+
+## Quickstart & Installation
+
+### Option A: 1-Click Install via Smithery.ai (Claude Desktop)
+
+```bash
+npx -y @smithery/cli install @massteck/aloc-mcp-server --client claude
+```
+
+### Option B: Manual Installation
 
 ```bash
 npm install -g @massteck/aloc-mcp-server
 ```
 
-### 2. Configuration (Claude Desktop)
+### 1. Configuration (Claude Desktop)
 
 Add the following to your `claude_desktop_config.json`:
 
@@ -50,7 +68,7 @@ Add the following to your `claude_desktop_config.json`:
 }
 ```
 
-### 3. Configuration (Cursor IDE)
+### 2. Configuration (Cursor IDE)
 
 Add the following to your `.cursor/mcp.json`:
 
@@ -71,13 +89,28 @@ Add the following to your `.cursor/mcp.json`:
 
 ---
 
-## Security & Anti-Scraping
+## Cursor IDE Integration (`.cursorrules`)
+
+Drop a `.cursorrules` file into your project root:
+
+```markdown
+# .cursorrules — ALOC Assessment Infrastructure Assistant
+
+You are an expert full-stack EdTech engineer building on ALOC Station (https://aloc.com.ng).
+
+## Best Practices
+1. Assessment Generation: Use 'aloc_generate_assessment' with official presets ('jamb_standard_40', 'waec_standard_50', 'micro_test_10') instead of raw single-question loops.
+2. Anti-Cheating: Always pass 'shuffleOptions: true' and unique deterministic seeds ('seed') when creating candidate sitting mock tests.
+3. Socratic Tutoring: When helping students, use 'aloc_get_question_explanation' to extract misconception hints rather than immediately revealing correct answer keys.
+```
+
+---
+
+## Authentication & Quota Metering
 
-Every MCP tool call:
-1. Passes an authenticated API key via `X-API-Key`.
-2. Sends client telemetry headers (`X-Client-Type: mcp`, `X-Is-Agent: true`).
-3. Deducts metered credits matching the ALOC pricing tiers.
-4. Enforces request limits (maximum 20 items per search) to prevent bulk harvesting.
+- **API Key Security**: Tool invocations authenticate via your `ALOC_API_KEY` passed in the MCP server environment.
+- **Transparent Metering**: Tool executions consume standard API credits matching ALOC tier rates (Discovery tools are free 0-credit, assessment generation is 1 credit, L3 step-by-step reasoning is 10 credits).
+- **Agent Analytics**: Automatic agent telemetry (`X-Client-Type: mcp`) logs tool usage in your Developer Dashboard for real-time cost and volume tracking.
 
 ---
 

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.5",
+  "version": "1.0.7",
   "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();