question-bank-mcp: Instructions file for Claude Code

CLAUDE.md — Question Bank MCP Server

Tech Stack

• Language: Python 3.12
• Framework: FastMCP (mcp>=1.0.0)
• Database: SQLite (auto-created at data/question_bank.db)
• Transport: stdio
• Testing: pytest + pytest-cov (88 tests, 93% coverage)
• Dependencies: mcp>=1.0.0, python-dateutil>=2.8.0, pytest>=9.0.0, pytest-cov>=7.0.0

How to Run

# From project root (with venv activated)
python run_server.py

# Or as a module
python -m src.question_bank

How to Connect

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "question-bank": {
      "command": "/path/to/question-bank-mcp/venv/bin/python",
      "args": ["/path/to/question-bank-mcp/run_server.py"]
    }
  }
}

Claude Code

claude mcp add question-bank /path/to/question-bank-mcp/venv/bin/python /path/to/question-bank-mcp/run_server.py

Architecture

run_server.py                  # Entry point — imports mcp from server.py, runs stdio
src/question_bank/
├── __init__.py
├── __main__.py                # python -m entry point
├── server.py                  # 12 MCP tools + 2 MCP resources (~800 lines)
└── database.py                # SQLite ORM layer (~500 lines)
tests/
├── conftest.py                # DB isolation fixture (tmp_path per test)
├── test_database.py           # 40 tests — CRUD, search, cascades, security
└── test_server.py             # 48 tests — validation, tools, formatting
data/
└── question_bank.db           # SQLite database (auto-created, gitignored)

• server.py defines all tools and resources using the @mcp.tool() and @mcp.resource() decorators
• database.py handles all SQL — table creation, CRUD, search queries
• The database auto-initializes on first import (creates tables + indexes)

Tools (12)

Tool	Key Parameters
create_question_bank	name, subject, description?, grade_level?
list_question_banks	(none)
get_bank_statistics	bank_id
create_topic	bank_id, name, description?, parent_topic_id?
list_topics	bank_id
create_question	bank_id, question_type, stem, correct_answer, options?, explanation?, difficulty?, bloom_level?, estimated_time_seconds?, points?, topic_ids?, tags?
get_question	question_id, show_answer?
update_question	question_id, plus any question field
delete_question	question_id
search_questions	bank_id?, topic_id?, question_type?, bloom_level?, difficulty_min?, difficulty_max?, status?, tags?, search_text?, limit?
activate_questions	question_ids (list)
suggest_questions	bank_id, topic, count?, difficulty?, bloom_levels?