@massteck/aloc-mcp-server 1.0.1

package/README.md

@@ -0,0 +1,59 @@
+# ALOC Model Context Protocol (MCP) Server
+
+Official Model Context Protocol (MCP) server for **ALOC** — providing African educational examination content, curriculum structures, and AI-enriched explanations to AI agents and LLM clients (Claude Desktop, Cursor, LangChain, AI Tutors).
+
+---
+
+## Features & Tools
+
+| Tool | Layer | Credits | Description |
+| :--- | :---: | :---: | :--- |
+| `aloc_search_questions` | L1 / L2 | 1–3 credits | Search curriculum-aligned examination questions (WAEC, JAMB, NECO) with options, topics, and difficulty. |
+| `aloc_get_question_explanation` | L3 | 10 credits | Retrieve step-by-step solutions, misconceptions, and explanations. |
+| `aloc_get_curriculum_taxonomy` | L2 | Free/3 credits | Explore the topic taxonomy and syllabus hierarchy. |
+| `aloc_find_similar_questions` | L4 | 10 credits | Find vector-similar exam questions. |
+
+---
+
+## Quickstart
+
+### 1. Installation
+
+```bash
+npm install -g @massteck/aloc-mcp-server
+```
+
+### 2. Configuration (Claude Desktop)
+
+Add the following to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "aloc": {
+      "command": "npx",
+      "args": ["-y", "@massteck/aloc-mcp-server"],
+      "env": {
+        "ALOC_API_KEY": "your_aloc_api_key_here",
+        "ALOC_BASE_URL": "https://dev.aloc.com.ng/api/v1"
+      }
+    }
+  }
+}
+```
+
+### 3. Configuration (Cursor / Agent Frameworks)
+
+Set the environment variables:
+* `ALOC_API_KEY`: Your ALOC Developer API Key (`aloc_...`)
+* `ALOC_AGENT_FRAMEWORK`: Optional identifier (e.g. `cursor`, `custom-ai-tutor`)
+
+---
+
+## Security & Anti-Scraping
+
+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 dumping.

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+export interface AlocClientConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    agentFramework?: string;
+}
+export declare class AlocClient {
+    private http;
+    private apiKey;
+    constructor(config?: AlocClientConfig);
+    getQuestions(params: {
+        subject: string;
+        examType?: string;
+        year?: number | string;
+        topic?: string;
+        difficulty?: string;
+        limit?: number;
+    }): Promise<any>;
+    getQuestionExplanation(questionId: string, depth?: string): Promise<any>;
+    getCurriculumTaxonomy(params?: {
+        subject?: string;
+        examType?: string;
+    }): Promise<any>;
+    getSimilarQuestions(questionId: string, limit?: number): Promise<any>;
+    getSubjects(): Promise<any>;
+}

package/dist/client.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlocClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+class AlocClient {
+    http;
+    apiKey;
+    constructor(config = {}) {
+        this.apiKey = config.apiKey || process.env.ALOC_API_KEY || "";
+        const baseUrl = config.baseUrl || process.env.ALOC_BASE_URL || "https://dev.aloc.com.ng/api/v1";
+        if (!this.apiKey) {
+            console.error("[WARN] ALOC_API_KEY is not set. Authenticated MCP requests will fail until an API key is provided.");
+        }
+        this.http = axios_1.default.create({
+            baseURL: baseUrl,
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                "X-API-Key": this.apiKey,
+                "X-Client-Type": "mcp",
+                "X-Is-Agent": "true",
+                "X-Agent-Framework": config.agentFramework || process.env.ALOC_AGENT_FRAMEWORK || "mcp-sdk",
+                "User-Agent": "ALOC-MCP-Server/1.0.0 (Node.js)",
+            },
+            timeout: 15000,
+        });
+    }
+    async getQuestions(params) {
+        const response = await this.http.get("/questions", { params });
+        return response.data;
+    }
+    async getQuestionExplanation(questionId, depth) {
+        const response = await this.http.post(`/questions/${questionId}/explain`, {
+            depth: depth || "step_by_step",
+        });
+        return response.data;
+    }
+    async getCurriculumTaxonomy(params) {
+        const response = await this.http.get("/curriculum", { params });
+        return response.data;
+    }
+    async getSimilarQuestions(questionId, limit) {
+        const response = await this.http.get(`/questions/${questionId}/similar`, {
+            params: { limit: limit || 3 },
+        });
+        return response.data;
+    }
+    async getSubjects() {
+        const response = await this.http.get("/subjects");
+        return response.data;
+    }
+}
+exports.AlocClient = AlocClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const client_js_1 = require("./client.js");
+const client = new client_js_1.AlocClient();
+const server = new index_js_1.Server({
+    name: "aloc-mcp-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Register available tools
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "aloc_search_questions",
+                description: "Search and retrieve curriculum-aligned examination questions (WAEC, JAMB, NECO) with options, metadata, and difficulty levels. Consumes 1-3 ALOC credits.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        subject: {
+                            type: "string",
+                            description: "Subject name (e.g. 'mathematics', 'english', 'biology', 'physics', 'chemistry', 'economics')",
+                        },
+                        examType: {
+                            type: "string",
+                            enum: ["waec", "jamb", "neco", "post-utme"],
+                            description: "Target African examination body",
+                        },
+                        year: {
+                            type: "number",
+                            description: "Examination year (e.g. 2022)",
+                        },
+                        topic: {
+                            type: "string",
+                            description: "Topic filter (e.g. 'algebra', 'calculus', 'photosynthesis')",
+                        },
+                        difficulty: {
+                            type: "string",
+                            enum: ["easy", "medium", "hard"],
+                            description: "Calibrated difficulty rating",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Number of questions to return (max 20, default 5)",
+                            default: 5,
+                        },
+                    },
+                    required: ["subject"],
+                },
+            },
+            {
+                name: "aloc_get_question_explanation",
+                description: "Retrieve step-by-step breakdown, remedial hints, and AI-generated conceptual explanations for a specific question. Consumes 10 ALOC credits.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        questionId: {
+                            type: "string",
+                            description: "UUID of the question",
+                        },
+                        depth: {
+                            type: "string",
+                            enum: ["step_by_step", "concise", "remedial"],
+                            description: "Explanation granularity",
+                            default: "step_by_step",
+                        },
+                    },
+                    required: ["questionId"],
+                },
+            },
+            {
+                name: "aloc_get_curriculum_taxonomy",
+                description: "Retrieve official African examination curriculum structure, subject breakdown, and topic hierarchy.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        subject: {
+                            type: "string",
+                            description: "Subject name",
+                        },
+                        examType: {
+                            type: "string",
+                            enum: ["waec", "jamb", "neco"],
+                            description: "Examination body",
+                        },
+                    },
+                },
+            },
+            {
+                name: "aloc_find_similar_questions",
+                description: "Find conceptually similar or variant examination questions using semantic vector similarity. Consumes 10 ALOC credits.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        questionId: {
+                            type: "string",
+                            description: "UUID of the source question",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Number of similar questions to return (max 10, default 3)",
+                            default: 3,
+                        },
+                    },
+                    required: ["questionId"],
+                },
+            },
+        ],
+    };
+});
+// Handle tool execution
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "aloc_search_questions": {
+                const { subject, examType, year, topic, difficulty, limit } = (args || {});
+                const result = await client.getQuestions({
+                    subject,
+                    examType,
+                    year,
+                    topic,
+                    difficulty,
+                    limit: Math.min(limit || 5, 20),
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "aloc_get_question_explanation": {
+                const { questionId, depth } = (args || {});
+                const result = await client.getQuestionExplanation(questionId, depth);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "aloc_get_curriculum_taxonomy": {
+                const { subject, examType } = (args || {});
+                const result = await client.getCurriculumTaxonomy({ subject, examType });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "aloc_find_similar_questions": {
+                const { questionId, limit } = (args || {});
+                const result = await client.getSimilarQuestions(questionId, limit);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown ALOC tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const errorMessage = error.response?.data?.message || error.response?.data?.error || error.message || "Unknown error";
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `[ALOC Error] ${errorMessage}`,
+                },
+            ],
+        };
+    }
+});
+// Start transport
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("ALOC MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error starting ALOC MCP Server:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@massteck/aloc-mcp-server",
+  "version": "1.0.1",
+  "description": "Official Model Context Protocol (MCP) Server for ALOC assessment content infrastructure",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "aloc-mcp-server": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "aloc",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "edtech",
+    "curriculum",
+    "assessment"
+  ],
+  "author": "ALOC Infrastructure Team",
+  "license": "Proprietary",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "axios": "^1.7.9",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.5",
+    "typescript": "^5.7.3"
+  }
+}

package/src/client.ts

@@ -0,0 +1,73 @@
+import axios, { AxiosInstance } from "axios";
+
+export interface AlocClientConfig {
+  apiKey?: string;
+  baseUrl?: string;
+  agentFramework?: string;
+}
+
+export class AlocClient {
+  private http: AxiosInstance;
+  private apiKey: string;
+
+  constructor(config: AlocClientConfig = {}) {
+    this.apiKey = config.apiKey || process.env.ALOC_API_KEY || "";
+    const baseUrl = config.baseUrl || process.env.ALOC_BASE_URL || "https://dev.aloc.com.ng/api/v1";
+
+    if (!this.apiKey) {
+      console.error(
+        "[WARN] ALOC_API_KEY is not set. Authenticated MCP requests will fail until an API key is provided."
+      );
+    }
+
+    this.http = axios.create({
+      baseURL: baseUrl,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "X-API-Key": this.apiKey,
+        "X-Client-Type": "mcp",
+        "X-Is-Agent": "true",
+        "X-Agent-Framework": config.agentFramework || process.env.ALOC_AGENT_FRAMEWORK || "mcp-sdk",
+        "User-Agent": "ALOC-MCP-Server/1.0.0 (Node.js)",
+      },
+      timeout: 15000,
+    });
+  }
+
+  public async getQuestions(params: {
+    subject: string;
+    examType?: string;
+    year?: number | string;
+    topic?: string;
+    difficulty?: string;
+    limit?: number;
+  }) {
+    const response = await this.http.get("/questions", { params });
+    return response.data;
+  }
+
+  public async getQuestionExplanation(questionId: string, depth?: string) {
+    const response = await this.http.post(`/questions/${questionId}/explain`, {
+      depth: depth || "step_by_step",
+    });
+    return response.data;
+  }
+
+  public async getCurriculumTaxonomy(params?: { subject?: string; examType?: string }) {
+    const response = await this.http.get("/curriculum", { params });
+    return response.data;
+  }
+
+  public async getSimilarQuestions(questionId: string, limit?: number) {
+    const response = await this.http.get(`/questions/${questionId}/similar`, {
+      params: { limit: limit || 3 },
+    });
+    return response.data;
+  }
+
+  public async getSubjects() {
+    const response = await this.http.get("/subjects");
+    return response.data;
+  }
+}

package/src/index.ts

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { AlocClient } from "./client.js";
+
+const client = new AlocClient();
+
+const server = new Server(
+  {
+    name: "aloc-mcp-server",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Register available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "aloc_search_questions",
+        description:
+          "Search and retrieve curriculum-aligned examination questions (WAEC, JAMB, NECO) with options, metadata, and difficulty levels. Consumes 1-3 ALOC credits.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            subject: {
+              type: "string",
+              description: "Subject name (e.g. 'mathematics', 'english', 'biology', 'physics', 'chemistry', 'economics')",
+            },
+            examType: {
+              type: "string",
+              enum: ["waec", "jamb", "neco", "post-utme"],
+              description: "Target African examination body",
+            },
+            year: {
+              type: "number",
+              description: "Examination year (e.g. 2022)",
+            },
+            topic: {
+              type: "string",
+              description: "Topic filter (e.g. 'algebra', 'calculus', 'photosynthesis')",
+            },
+            difficulty: {
+              type: "string",
+              enum: ["easy", "medium", "hard"],
+              description: "Calibrated difficulty rating",
+            },
+            limit: {
+              type: "number",
+              description: "Number of questions to return (max 20, default 5)",
+              default: 5,
+            },
+          },
+          required: ["subject"],
+        },
+      },
+      {
+        name: "aloc_get_question_explanation",
+        description:
+          "Retrieve step-by-step breakdown, remedial hints, and AI-generated conceptual explanations for a specific question. Consumes 10 ALOC credits.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            questionId: {
+              type: "string",
+              description: "UUID of the question",
+            },
+            depth: {
+              type: "string",
+              enum: ["step_by_step", "concise", "remedial"],
+              description: "Explanation granularity",
+              default: "step_by_step",
+            },
+          },
+          required: ["questionId"],
+        },
+      },
+      {
+        name: "aloc_get_curriculum_taxonomy",
+        description:
+          "Retrieve official African examination curriculum structure, subject breakdown, and topic hierarchy.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            subject: {
+              type: "string",
+              description: "Subject name",
+            },
+            examType: {
+              type: "string",
+              enum: ["waec", "jamb", "neco"],
+              description: "Examination body",
+            },
+          },
+        },
+      },
+      {
+        name: "aloc_find_similar_questions",
+        description:
+          "Find conceptually similar or variant examination questions using semantic vector similarity. Consumes 10 ALOC credits.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            questionId: {
+              type: "string",
+              description: "UUID of the source question",
+            },
+            limit: {
+              type: "number",
+              description: "Number of similar questions to return (max 10, default 3)",
+              default: 3,
+            },
+          },
+          required: ["questionId"],
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "aloc_search_questions": {
+        const { subject, examType, year, topic, difficulty, limit } = (args || {}) as any;
+        const result = await client.getQuestions({
+          subject,
+          examType,
+          year,
+          topic,
+          difficulty,
+          limit: Math.min(limit || 5, 20),
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "aloc_get_question_explanation": {
+        const { questionId, depth } = (args || {}) as any;
+        const result = await client.getQuestionExplanation(questionId, depth);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "aloc_get_curriculum_taxonomy": {
+        const { subject, examType } = (args || {}) as any;
+        const result = await client.getCurriculumTaxonomy({ subject, examType });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "aloc_find_similar_questions": {
+        const { questionId, limit } = (args || {}) as any;
+        const result = await client.getSimilarQuestions(questionId, limit);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown ALOC tool: ${name}`);
+    }
+  } catch (error: any) {
+    const errorMessage =
+      error.response?.data?.message || error.response?.data?.error || error.message || "Unknown error";
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `[ALOC Error] ${errorMessage}`,
+        },
+      ],
+    };
+  }
+});
+
+// Start transport
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("ALOC MCP Server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error starting ALOC MCP Server:", error);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}