ALOC Model Context Protocol (MCP) Server
Official# ALOC Model Context Protocol (MCP) Server
[](https://www.npmjs.com/package/@massteck/aloc-mcp-server)
[](./LICENSE)
[](https://smithery.ai/servers/massteck/aloc)
Official Model Context Protocol (MCP) server for **[ALOC Station](https://aloc.com.ng)** (`@massteck/aloc-mcp-server`) — providing verified, deduplicated African educational examination content (**WAEC**, **JAMB UTME**, **NECO**, **Post-UTME**), structured curriculum trees, Bloom difficulty ratings, step-by-step derivations, and cheat-resistant exam session assembly to AI agents and IDEs (**Claude Desktop**, **Cursor**, **Windsurf**, **VS Code Copilot**, **LangChain**, and custom AI tutors).
---
## Features & Tools (12 Tools)
| Tool | Category | Credits | Description |
| :--- | :---: | :---: | :--- |
| `aloc_get_platform_overview` | Discovery | **0 credits** | Discover supported African exam bodies (WAEC, JAMB, NECO, Post-UTME), 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 (`historical` approved items by default). |
| `aloc_generate_assessment` | Assessment | **5 credits** | Assemble psychometrically balanced examination papers based on presets, topics, and deterministic seeds. |
| `aloc_create_assessment_session` | Assessment | **5 credits** | Initialize a timed candidate test session (2-hour lifecycle) for cheat-resistant delivery. |
| `aloc_get_session_questions` | Assessment | **0 credits** | Retrieve questions allocated to an active candidate assessment session (free reconnect). |
| `aloc_get_question_explanation` | Learning | **10 credits** | Retrieve step-by-step solutions, misconception traps, 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 `pgvector` semantically similar exam questions. |
| `aloc_report_question_issue` | Quality | **0 credits** | Report a typo or disputed answer key to ALOC's 24h Maker-Checker moderation queue. |
---
## 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
Obtain a free API key (**1,000 monthly credits included**) at **[aloc.com.ng/register](https://aloc.com.ng/register)**.
### Option A: Zero-Install Hosted Streamable HTTP Gateway (Recommended)
Connect directly to ALOC's hosted MCP endpoint (`https://aloc.com.ng/mcp/v1`) in Claude Desktop, Cursor, or any Streamable HTTP MCP client without installing Node packages locally:
```json
{
"mcpServers": {
"aloc": {
"url": "https://aloc.com.ng/mcp/v1",
"headers": {
"X-API-Key": "aloc_live_your_api_key_here"
}
}
}
}
```
### Option B: 1-Click Install via Smithery.ai (Claude Desktop)
```bash
npx -y @smithery/cli install massteck/aloc --client claude
```
### Option C: Local Node.js Stdio (`npx` / `npm`)
#### 1. Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"aloc": {
"command": "npx",
"args": ["-y", "@massteck/aloc-mcp-server"],
"env": {
"ALOC_API_KEY": "aloc_live_your_api_key_here"
}
}
}
}
```
#### 2. Cursor IDE (`.cursor/mcp.json`)
```json
{
"mcpServers": {
"aloc": {
"command": "npx",
"args": ["-y", "@massteck/aloc-mcp-server"],
"env": {
"ALOC_API_KEY": "aloc_live_your_api_key_here",
"ALOC_AGENT_FRAMEWORK": "cursor"
}
}
}
}
```
---
## Cursor IDE Integration (`.cursorrules`)
Drop a `.cursorrules` file into your project root when building EdTech applications on ALOC:
```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, Quality Telemetry & Licensing
- **API Key Security**: Authenticate via `ALOC_API_KEY` (stdio) or `X-API-Key` header (Streamable HTTP).
- **Transparent Metering**: Discovery tools and active session reconnects consume **0 credits**; question search consumes **1–3 credits**; paper/session assembly consumes **5 credits**; L3/L4 explanations and similarity consume **10 credits**.
- **Live Data Quality Audit**: Inspect live question counts, deduplication guarantees, and syllabus alignment telemetry anytime at **[aloc.com.ng/data-quality](https://aloc.com.ng/data-quality)**.
- **License**: Client wrapper code is released under the **[MIT License](./LICENSE)**. Examination datasets and API responses are governed by the **[ALOC Terms of Service](https://aloc.com.ng/terms)**.
---
## Documentation & Links
- 📖 **MCP Documentation**: [https://aloc.com.ng/docs/mcp](https://aloc.com.ng/docs/mcp)
- 🐍 **Python & TypeScript SDKs**: [https://aloc.com.ng/docs/sdks](https://aloc.com.ng/docs/sdks)
- 📊 **20-Year Syllabus Benchmarks**: [https://aloc.com.ng/benchmarks](https://aloc.com.ng/benchmarks)
- 🎮 **Interactive API Playground**: [https://aloc.com.ng/playground](https://aloc.com.ng/playground)
- 📧 **API Support**: [api@aloc.com.ng](mailto:api@aloc.com.ng)
TDQS
Scored across 13 tools
Core actions are clearly distinct: searching questions, explaining a question, finding similar questions, generating a paper, and managing a session are easy to tell apart. The only fuzzy zone is the discovery/metadata cluster (platform_overview, coverage_matrix, subject_years, curriculum_taxonomy, sitemap), where coverage_matrix vs subject_years and overview vs sitemap could be confused at a glance, though descriptions do disambiguate them.
Every tool uses the same aloc_ prefix followed by a verb_noun snake_case name (get_, create_, search_, find_, generate_, report_, check_). Verb choice matches the operation type consistently, so an agent can predict names.
13 tools sits squarely in the well-scoped range for an exam content API, with each tool mapping to a distinct capability layer (discovery, retrieval, generation, session, billing, feedback). Nothing looks padded or missing purely on count grounds.
The question-retrieval, explanation, similarity, generation, and discovery surfaces are well covered, but the assessment session lifecycle is a dead end: you can create a session and fetch its questions, yet there is no submit/complete/expire session or retrieve results/grading tool. A direct get-question-by-id fetch is also only implicitly reachable via search.