Ace Achievers MCP Server
This MCP server provides tools to search and retrieve information from the Ace Achievers course catalog and question bank, enabling MCP-compatible AI clients to answer queries about courses, practice questions, and pricing.
Search Courses – Filter the 26-course catalog by subject (
maths,science,computer-science), year level (5–12), and course type (e.g.foundation,advanced,mock,bundle,acceleration).Get Course Details – Retrieve full details for a specific course by ID, including structure, target band, and free-tier info.
Search Questions – Search the practice question bank by topic (e.g.
geometry,algebra,number-theory) and/or difficulty (easy,medium,hard); returns question stems only, never solutions.Get Question with Tiered Hints – Fetch a specific question with controlled hint reveal: level 0 (question only), level 1 (nudge), level 2 (approach), level 3 (full solution), enforcing pedagogical guardrails server-side.
Get Question Bank Statistics – Overview of the question corpus with counts by subject, difficulty, and topic.
Get Pricing Info – Returns a redirect to the live pricing source rather than stored prices, ensuring up-to-date information.
The server can use a bundled sample question set or be configured to load larger private question banks via environment variables, and integrates with MCP-capable clients like Claude Desktop.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Ace Achievers MCP Server Find a hard geometry question and give me a nudge hint"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ace Achievers MCP Server
An MCP (Model Context Protocol) server exposing the Ace Achievers course catalog and question-bank tools to any MCP client — Claude Desktop, Claude Code, or your own agent.
What this is
MCP is the open standard that lets an LLM agent call typed tools over a common wire protocol (JSON-RPC over stdio or HTTP) — write the server once, and any MCP-capable client can use it. This server packages the product-data tools I built for an Australian K-12 competition-learning platform, so an agent can answer "which course fits a Year 7 student new to competition maths?" against live catalog data instead of guessing.
Related MCP server: Brain Grain Quiz Coach
Tools
Tool | What it does |
| Filter the 26-course catalog (maths / science / computer-science, Years 5–12) |
| One course in full — structure, target band, free-tier info |
| Search the question bank — returns stems only, never spoilers |
| Tiered reveal: 0 = question, 1 = nudge, 2 = approach, 3 = full solution |
| Corpus overview — data source and counts by subject / difficulty / topic |
| The redirect-volatile pricing contract (see design notes) |
Quick start
git clone https://github.com/Star4future/aceachievers-mcp-server
cd aceachievers-mcp-server
pip install -e ".[dev]"
pytest # 16 tests
aceachievers-mcp # runs the stdio serverClaude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"aceachievers": {
"command": "aceachievers-mcp"
}
}
}Then ask Claude: "Find a hard geometry question and give me a nudge, not the answer."
TypeScript client
The server is Python; the product that would consume it is TypeScript. So the
repo also ships a typed, zod-validated TS/Node client
(clients/ts/) built on the official
@modelcontextprotocol/sdk — the same six tools behind typed methods, every
result validated at runtime (not cast):
cd clients/ts
npm install
npm run test:unit # 5 hermetic tests — green with NO Python installed
npm test # + 4 integration tests against the real server
npm run demo # call every tool through the typed client
npm run report # catalogue contract check (a real consumer, CI-gated)See clients/ts/README.md for the design notes.
Design notes
Redirect-volatile pricing. Prices and enrolment windows change on the live site, so this
server refuses to store them: get_pricing_info returns the live source instead of numbers.
Stable facts (course structure, topics, question content) are served from the bundled snapshot.
This is the same volatile/stable knowledge split that let the platform's production chat
assistant absorb a 3× catalog expansion with zero pricing-logic rewrites — the bot can't go
stale on facts it never stored.
Tiered hint reveal. get_question mirrors the production RAG tutor's pedagogy: a student
who asks for a nudge must not receive the answer, so hints unlock level by level and the
listing view never includes solutions. The guardrail lives server-side — the client can't
accidentally spoil.
Sample data in the repo, real bank via env. The bundled question set is original material
written for this demo in the production bank's format; licensed past-paper content is not
redistributed here. The production deployment points these same tools at the private store
(2,500+ taxonomically classified problems, extracted from PDFs via a Vision-API pipeline) —
implemented via environment variables, with records from both production schemas (AMC maths
and science-olympiad) normalised onto one shape (private_bank.py):
# option 1 — explicit files, ";"-separated
QBANK_PATHS="D:\private\amc_junior.json;D:\private\jso_master.json"
# option 2 — a directory of *.json bank files
QBANK_DIR="D:\private\qbank"No env vars → the bundled sample serves; unknown ids and missing hints degrade gracefully.
Layout
src/aceachievers_mcp/
├── server.py # FastMCP server: 6 tools, pure logic separated for testing
├── private_bank.py # env-configured private bank loading + schema normalisation
└── data/
├── courses.json # 26-course catalog snapshot (no prices — by design)
└── sample_questions.json # 10 original questions with 3-tier hints
scripts/demo_client.py # stdio client that exercises all six tools end-to-end
tests/test_tools.py # 16 unit tests
clients/ts/ # typed, zod-validated TypeScript/Node client (9 tests + CI)License
MIT — see LICENSE.
Available Tools
5 toolsget_courseA
Get one course by id (e.g. "amc-foundation").
Includes structure, target band and free-tier info. Pricing is deliberately redirected to the live source rather than stored.
Inputs: course_id (required). Returns: object
get_pricing_infoA
How to answer pricing questions: returns the live pricing source.
Prices are deliberately not stored in this dataset (redirect-volatile design) — always send users to the live page for money amounts.
Inputs: no named parameters. Returns: object
get_questionA
Fetch one question with tiered hint reveal.
Args: question_id: e.g. "SAMPLE-NT-001". hint_level: 0 = question only, 1 = + nudge, 2 = + approach, 3 = + full solution and answer.
Inputs: question_id (required), hint_level. Returns: object
search_coursesA
Search the course catalog.
Args: subject: "maths", "science" or "computer-science". year_level: student year level (5-12); matches courses covering it. course_type: substring filter — "foundation", "advanced", "mock", "bundle" or "acceleration".
Returns matching courses (no prices — see get_pricing_info).
Inputs: subject, year_level, course_type. Returns: result
search_questionsA
Search practice questions (sample set bundled with this repo).
Args: topic: substring filter — "number-theory", "geometry", "counting", "algebra", "rates". difficulty: "easy", "medium" or "hard".
Returns question stems only; fetch hints/solutions via get_question.
Inputs: topic, difficulty. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct resource: courses, pricing, and questions. Get vs search are clearly separated, and no two tools overlap in purpose.
All tools follow a consistent verb_noun pattern using 'get' or 'search', with clear and predictable names.
With 5 tools, the set is well-scoped for the domain of retrieving course and question information, neither too sparse nor overloaded.
The tool set covers retrieval and search for courses and questions plus pricing info. No obvious gaps for the stated purpose of an informational assistant.
Maintenance
Related MCP Connectors
Search university course materials, your flashcards, quizzes, streak and quota. All tools read-only.
Read-only access to Epivo's live course catalogue for AI agents.
Aspire Learning MCP — browse courses, chapters, lessons, and import LaTeX quizzes
Read and author HiveLearn courses, events, quizzes, certificates, resources, leaderboards, tracks.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides intelligent access to a university course catalog with full-text search, prerequisite tracking, instructor lookups, and course comparison prompts.-
- AlicenseNot gradedqualityCmaintenanceEnables Alexa+ or any MCP client to conduct bilingual Tamil/English exam coaching for TNPSC, UPSC, and CTET, with adaptive quizzes, verified explanations, streaks, and topic browsing.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible AI assistants to search an exam-prep catalog, retrieve 204 free practice questions with answers and explanations across 15 IT and nursing certifications, check pricing, and get official exam facts.MIT
- AlicenseAqualityBmaintenanceConnects AI assistants to a medical question bank so students can search exam questions, generate and grade mock exams with detailed explanations, and track their weakest topics. Answer keys are withheld until grading, keeping practice honest.6MIT