ALOC Model Context Protocol (MCP) Server

Official Model Context Protocol (MCP) server for ALOC (@massteck/aloc-mcp-server) — providing African educational examination content, curriculum structures, AI-enriched explanations, and autonomous discovery tools to AI agents and LLM clients (Claude Desktop, Cursor, LangChain, AI Tutors).

Features & Tools

| Tool | Category | Credits | Description | | :--- | :---: | :---: | :--- | | aloc_get_platform_overview | Discovery | 0 credits | Discover supported African exam bodies (WAEC, JAMB, NECO), subjects, year coverage, and API layer rules. | | aloc_get_sitemap | Discovery | 0 credits | Direct URLs to developer portal, documentation, and error guides. | | 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. | | aloc_report_question_issue | Quality | 0 credits | Report a typo or disputed answer to ALOC moderation. |

Standard MCP Prompts

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)

npx -y @smithery/cli install @massteck/aloc-mcp-server --client claude

Option B: Manual Installation

npm install -g @massteck/aloc-mcp-server

1. Configuration (Claude Desktop)

Add the following to your claude_desktop_config.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"
      }
    }
  }
}

2. Configuration (Cursor IDE)

Add the following to your .cursor/mcp.json:

{
  "mcpServers": {
    "aloc": {
      "command": "npx",
      "args": ["-y", "@massteck/aloc-mcp-server"],
      "env": {
        "ALOC_API_KEY": "your_aloc_api_key_here",
        "ALOC_AGENT_FRAMEWORK": "cursor"
      }
    }
  }
}

Cursor IDE Integration (.cursorrules)

Drop a .cursorrules file into your project root:

# .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

• 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.

Documentation & Support

For comprehensive integration guides, interactive API playground, and developer credentials, visit the official ALOC Developer Portal:

• 📖 Documentation: https://aloc.com.ng/docs
• 🎮 API Playground: https://aloc.com.ng/playground
• 📧 Support: [email protected]