@gonzih/story-teacher 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maksim Soltan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# story-teacher
+
+An MCP server that wraps AI conversations with children aged 5–12 in interactive, educational stories. Learning objectives (math, science, history, vocabulary, coding, ecology) are embedded in choose-your-own-adventure narratives powered by Claude.
+
+## Features
+
+- **6 complete story worlds** with 30+ story segments
+- **Adaptive difficulty** that never punishes wrong answers — always redirects through narrative
+- **Claude-powered** dynamic story continuations with streaming
+- **SQLite session tracking** with parent progress reports
+- **Curriculum-mapped** with Common Core and NGSS standards
+- **MCP-compatible** — works with Claude Desktop and any MCP client
+
+## Story Worlds
+
+| Story | Subject | Ages |
+|-------|---------|------|
+| The Number Kingdom | Math | 5–12 |
+| The Science Ship | Science | 7–11 |
+| The Time Traveler | History | 8–12 |
+| The Word Wizard | Literacy | 6–10 |
+| The Coding Quest | Coding | 9–12 |
+| The Eco Explorer | Ecology | 7–11 |
+
+## MCP Tools
+
+### `start_story`
+Begin a new story session.
+```json
+{
+  "profileId": "child-name",
+  "ageGroup": "8-10",
+  "storyType": "number-kingdom"
+}
+```
+
+### `answer`
+Submit an answer to the current question.
+```json
+{
+  "sessionId": "...",
+  "answer": "56"
+}
+```
+
+### `get_story_types`
+List all available story types.
+
+### `get_session_summary`
+Get what was learned in a session — great for parents.
+
+### `get_progress`
+View overall learning progress, streaks, and points for a profile.
+
+## Installation
+
+```bash
+npm install -g @gonzih/story-teacher
+```
+
+Requires `ANTHROPIC_API_KEY` environment variable.
+
+## Claude Desktop Config
+
+```json
+{
+  "mcpServers": {
+    "story-teacher": {
+      "command": "story-teacher",
+      "env": {
+        "ANTHROPIC_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## License
+
+MIT — Gonzih

package/SKILL.md

@@ -0,0 +1,40 @@
+# story-teacher Skill
+
+## What it does
+
+Runs educational storytelling sessions for children aged 5–12 via MCP. Each session is a choose-your-own-adventure story where learning questions are embedded naturally in the narrative. Correct answers advance the story dramatically; wrong answers get a gentle narrative redirect (never "wrong").
+
+## How to use
+
+1. Call `get_story_types` to show the user which adventures are available
+2. Call `start_story` with the child's profile ID, age group, and chosen story
+3. Present the `storyIntro` and `firstQuestion.text` to the child
+4. When the child responds, call `answer` with the session ID and their answer
+5. Present `storyContinuation` and `nextQuestion.text`
+6. Repeat until the child is done, then call `get_session_summary`
+
+## Age groups
+
+- `5-7` — Very young; simple vocabulary, counting, basic addition/subtraction
+- `8-10` — Elementary; multiplication, fractions, basic science, history
+- `11-12` — Pre-teen; algebra, complex science, deeper history, coding logic
+
+## Example session
+
+```
+Parent: Start a math story for my 7-year-old named Sam
+→ start_story({ profileId: "sam", ageGroup: "5-7", storyType: "number-kingdom" })
+
+Child: [reads intro and question]
+Child: "8"
+→ answer({ sessionId: "...", answer: "8" })
+→ Returns: correct=true, story celebration, next question
+```
+
+## Points system
+
+- Easy correct: 10 points
+- Medium correct: 15 points
+- Hard correct: 25 points
+- Streak bonus (3+ correct): 1.2×
+- Milestone messages every 5 correct answers

package/dist/adaptive.d.ts

@@ -0,0 +1,13 @@
+import { StorySegment } from './stories/types.js';
+export interface DifficultyState {
+    consecutiveWrong: number;
+    consecutiveCorrect: number;
+    totalCorrect: number;
+    totalAnswered: number;
+    usedSegmentIds: string[];
+}
+export declare function selectNextSegment(state: DifficultyState, storyType: string, ageGroup: string): StorySegment | null;
+export declare function shouldAddExtraHint(state: DifficultyState): boolean;
+export declare function calculatePoints(correct: boolean, difficulty: string, consecutiveCorrect: number): number;
+export declare function getMilestoneMessage(questionsAnswered: number): string | null;
+export declare function getEncouragementAfterWrong(consecutiveWrong: number): string;

package/dist/adaptive.js

@@ -0,0 +1,88 @@
+import { getSegmentsForAgeGroup } from './stories/index.js';
+export function selectNextSegment(state, storyType, ageGroup) {
+    const allSegments = getSegmentsForAgeGroup(storyType, ageGroup);
+    if (allSegments.length === 0)
+        return null;
+    // Filter out already used segments
+    const available = allSegments.filter(s => !state.usedSegmentIds.includes(s.id));
+    if (available.length === 0) {
+        // Recycle segments when exhausted (allow reuse)
+        const recycled = allSegments.filter(s => state.usedSegmentIds.slice(-Math.floor(allSegments.length / 2)).indexOf(s.id) === -1);
+        if (recycled.length === 0)
+            return allSegments[Math.floor(Math.random() * allSegments.length)];
+        return pickByDifficulty(recycled, state);
+    }
+    return pickByDifficulty(available, state);
+}
+function pickByDifficulty(segments, state) {
+    let preferredDifficulty;
+    if (state.consecutiveWrong >= 3) {
+        // Struggling — go easier
+        preferredDifficulty = 'easy';
+    }
+    else if (state.consecutiveCorrect >= 5) {
+        // On a roll — challenge them
+        preferredDifficulty = 'hard';
+    }
+    else if (state.totalAnswered > 0 && state.totalCorrect / state.totalAnswered > 0.8) {
+        // Doing well — medium/hard
+        preferredDifficulty = 'medium';
+    }
+    else {
+        preferredDifficulty = 'medium';
+    }
+    // Try to get preferred difficulty
+    const preferred = segments.filter(s => s.difficulty === preferredDifficulty);
+    if (preferred.length > 0) {
+        return preferred[Math.floor(Math.random() * preferred.length)];
+    }
+    // Fall back to any difficulty, biased toward preferred
+    const easier = ['easy', 'medium', 'hard'];
+    if (state.consecutiveWrong >= 3) {
+        for (const diff of easier) {
+            const found = segments.filter(s => s.difficulty === diff);
+            if (found.length > 0)
+                return found[Math.floor(Math.random() * found.length)];
+        }
+    }
+    // Return random from available
+    return segments[Math.floor(Math.random() * segments.length)];
+}
+export function shouldAddExtraHint(state) {
+    return state.consecutiveWrong >= 3;
+}
+export function calculatePoints(correct, difficulty, consecutiveCorrect) {
+    if (!correct)
+        return 0;
+    let base = 10;
+    if (difficulty === 'medium')
+        base = 15;
+    if (difficulty === 'hard')
+        base = 25;
+    // Streak bonus
+    if (consecutiveCorrect >= 5)
+        base = Math.floor(base * 1.5);
+    else if (consecutiveCorrect >= 3)
+        base = Math.floor(base * 1.2);
+    return base;
+}
+export function getMilestoneMessage(questionsAnswered) {
+    const milestones = {
+        5: "AMAZING! You've answered 5 questions! The whole kingdom is celebrating your brilliance! Keep going — great adventures lie ahead!",
+        10: "TEN QUESTIONS! You are a true champion! The story-world is glowing with your achievements! You're unstoppable!",
+        15: "FIFTEEN! You've become a legend in this world! Ancient records are being updated to include YOUR name! What a journey!",
+        20: "TWENTY QUESTIONS — you've mastered the realm! The greatest adventurers who ever lived couldn't have done better!",
+    };
+    return milestones[questionsAnswered] ?? null;
+}
+export function getEncouragementAfterWrong(consecutiveWrong) {
+    const messages = [
+        "Almost! Let's think about this together...",
+        "Great try! Every explorer gets stuck sometimes — that's how we learn!",
+        "You're so close! Let me give you a helpful clue...",
+        "Don't worry at all — even the wisest wizards need hints sometimes!",
+        "The path forward becomes clearer with each step — here's another clue!",
+    ];
+    const idx = Math.min(consecutiveWrong - 1, messages.length - 1);
+    return messages[idx];
+}

package/dist/claude.d.ts

@@ -0,0 +1,16 @@
+export interface StoryContext {
+    storyType: string;
+    storyName: string;
+    ageGroup: string;
+    currentSegmentIntro: string;
+    question: string;
+    userAnswer: string;
+    isCorrect: boolean;
+    correctContinuation: string;
+    incorrectContinuation: string;
+    consecutiveWrong: number;
+    questionsAnswered: number;
+    characterName?: string;
+}
+export declare function generateStoryContinuation(context: StoryContext): Promise<string>;
+export declare function generateStoryIntro(storyType: string, storyName: string, ageGroup: string, segmentIntro: string, firstQuestion: string): Promise<string>;

package/dist/claude.js

@@ -0,0 +1,88 @@
+import Anthropic from '@anthropic-ai/sdk';
+const client = new Anthropic();
+export async function generateStoryContinuation(context) {
+    const ageDescriptor = context.ageGroup === '5-7' ? 'ages 5-7 (very young, simple vocabulary)' :
+        context.ageGroup === '8-10' ? 'ages 8-10 (elementary school, curious and energetic)' :
+            'ages 11-12 (pre-teen, sophisticated, loves challenges)';
+    const systemPrompt = `You are a magical storyteller for children aged ${context.ageGroup}. You are narrating "${context.storyName}".
+Your voice is warm, exciting, and encouraging. You NEVER break story immersion.
+When a child answers correctly: celebrate with the story, make them feel heroic and brilliant!
+When a child answers incorrectly: gently redirect through the narrative — the story pauses briefly, a character helps, but you NEVER say "wrong" or "incorrect". Keep it narrative: "Hmm, the door doesn't open yet..." or "The spell fizzles a little..."
+Keep responses SHORT (2-4 sentences). Age-appropriate vocabulary for ${ageDescriptor}. No scary or dark themes. Pure adventure, wonder, and encouragement.
+Always end on an exciting note that makes the child want to keep going.`;
+    const userMessage = context.isCorrect
+        ? `The child is in the story: "${context.storyType}".
+The current scene: ${context.currentSegmentIntro}
+The question was: "${context.question}"
+The child answered: "${context.userAnswer}" — which is CORRECT!
+The template continuation is: "${context.correctContinuation}"
+Generate an exciting, celebratory 2-4 sentence story continuation in this world. Make the child feel like a hero! Be creative and add vivid sensory details.`
+        : `The child is in the story: "${context.storyType}".
+The current scene: ${context.currentSegmentIntro}
+The question was: "${context.question}"
+The child answered: "${context.userAnswer}" — which needs another try.
+${context.consecutiveWrong >= 3 ? 'This child has tried several times — be extra gentle and hint very directly through the story.' : ''}
+The template continuation is: "${context.incorrectContinuation}"
+Generate a kind, narrative 2-4 sentence story continuation that gently redirects without breaking immersion. Never say "wrong". A story character can offer a clue.`;
+    try {
+        let fullText = '';
+        const stream = await client.messages.create({
+            model: 'claude-opus-4-6',
+            max_tokens: 16000,
+            thinking: {
+                type: 'enabled',
+                budget_tokens: 8000,
+            },
+            system: systemPrompt,
+            messages: [{ role: 'user', content: userMessage }],
+            stream: true,
+        });
+        for await (const event of stream) {
+            if (event.type === 'content_block_delta') {
+                if (event.delta.type === 'text_delta') {
+                    fullText += event.delta.text;
+                }
+            }
+        }
+        return fullText.trim() || (context.isCorrect ? context.correctContinuation : context.incorrectContinuation);
+    }
+    catch (error) {
+        // Fallback to template text if Claude fails
+        console.error('Claude generation failed, using template:', error);
+        return context.isCorrect ? context.correctContinuation : context.incorrectContinuation;
+    }
+}
+export async function generateStoryIntro(storyType, storyName, ageGroup, segmentIntro, firstQuestion) {
+    const systemPrompt = `You are a magical storyteller for children aged ${ageGroup}. You are narrating "${storyName}".
+Your voice is warm, inviting, and full of wonder. Write a captivating opening that draws the child immediately into the adventure.
+Keep it to 3-4 sentences. Age-appropriate. No scary themes. Pure excitement and possibility!`;
+    try {
+        let fullText = '';
+        const stream = await client.messages.create({
+            model: 'claude-opus-4-6',
+            max_tokens: 8000,
+            thinking: {
+                type: 'enabled',
+                budget_tokens: 4000,
+            },
+            system: systemPrompt,
+            messages: [{
+                    role: 'user',
+                    content: `Generate a captivating 3-4 sentence story introduction based on this template: "${segmentIntro}". End with a hint of the adventure ahead. The first challenge will involve: "${firstQuestion}". Make it irresistible!`,
+                }],
+            stream: true,
+        });
+        for await (const event of stream) {
+            if (event.type === 'content_block_delta') {
+                if (event.delta.type === 'text_delta') {
+                    fullText += event.delta.text;
+                }
+            }
+        }
+        return fullText.trim() || segmentIntro;
+    }
+    catch (error) {
+        console.error('Claude intro generation failed, using template:', error);
+        return segmentIntro;
+    }
+}

package/dist/database.d.ts

@@ -0,0 +1,43 @@
+import Database from 'better-sqlite3';
+export declare function getDatabase(): Database.Database;
+export interface SessionRow {
+    id: string;
+    profileId: string;
+    storyType: string;
+    ageGroup: string;
+    startedAt: number;
+    lastActivityAt: number;
+    questionsAnswered: number;
+    correctAnswers: number;
+    totalPoints: number;
+    conceptsCovered: string;
+    isComplete: number;
+}
+export interface AnswerRow {
+    id: string;
+    sessionId: string;
+    question: string;
+    userAnswer: string;
+    correct: number;
+    concept: string;
+    subject: string;
+    gradeLevel: number;
+    pointsEarned: number;
+    timestamp: number;
+}
+export interface ProfileRow {
+    id: string;
+    totalSessions: number;
+    totalPoints: number;
+    lastSessionAt: number | null;
+    streakDays: number;
+}
+export declare function createSession(session: Omit<SessionRow, 'questionsAnswered' | 'correctAnswers' | 'totalPoints' | 'conceptsCovered' | 'isComplete'>): void;
+export declare function getSession(sessionId: string): SessionRow | undefined;
+export declare function updateSession(sessionId: string, updates: Partial<Omit<SessionRow, 'id'>>): void;
+export declare function recordAnswer(answer: AnswerRow): void;
+export declare function getSessionAnswers(sessionId: string): AnswerRow[];
+export declare function getOrCreateProfile(profileId: string): ProfileRow;
+export declare function updateProfile(profileId: string, updates: Partial<Omit<ProfileRow, 'id'>>): void;
+export declare function getProfileSessions(profileId: string): SessionRow[];
+export declare function calculateStreakDays(profileId: string): number;

package/dist/database.js

@@ -0,0 +1,133 @@
+import Database from 'better-sqlite3';
+import { join } from 'path';
+import { homedir } from 'os';
+import { mkdirSync } from 'fs';
+const DB_DIR = join(homedir(), '.story-teacher');
+const DB_PATH = join(DB_DIR, 'story-teacher.db');
+let db;
+export function getDatabase() {
+    if (!db) {
+        mkdirSync(DB_DIR, { recursive: true });
+        db = new Database(DB_PATH);
+        db.pragma('journal_mode = WAL');
+        initializeSchema(db);
+    }
+    return db;
+}
+function initializeSchema(database) {
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      profileId TEXT NOT NULL,
+      storyType TEXT NOT NULL,
+      ageGroup TEXT NOT NULL,
+      startedAt INTEGER NOT NULL,
+      lastActivityAt INTEGER NOT NULL,
+      questionsAnswered INTEGER DEFAULT 0,
+      correctAnswers INTEGER DEFAULT 0,
+      totalPoints INTEGER DEFAULT 0,
+      conceptsCovered TEXT DEFAULT '[]',
+      isComplete INTEGER DEFAULT 0
+    );
+
+    CREATE TABLE IF NOT EXISTS answers (
+      id TEXT PRIMARY KEY,
+      sessionId TEXT NOT NULL,
+      question TEXT NOT NULL,
+      userAnswer TEXT NOT NULL,
+      correct INTEGER NOT NULL,
+      concept TEXT NOT NULL,
+      subject TEXT NOT NULL,
+      gradeLevel INTEGER NOT NULL,
+      pointsEarned INTEGER NOT NULL,
+      timestamp INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS profiles (
+      id TEXT PRIMARY KEY,
+      totalSessions INTEGER DEFAULT 0,
+      totalPoints INTEGER DEFAULT 0,
+      lastSessionAt INTEGER,
+      streakDays INTEGER DEFAULT 0
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_sessions_profileId ON sessions(profileId);
+    CREATE INDEX IF NOT EXISTS idx_answers_sessionId ON answers(sessionId);
+  `);
+}
+export function createSession(session) {
+    const database = getDatabase();
+    database.prepare(`
+    INSERT INTO sessions (id, profileId, storyType, ageGroup, startedAt, lastActivityAt)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(session.id, session.profileId, session.storyType, session.ageGroup, session.startedAt, session.lastActivityAt);
+}
+export function getSession(sessionId) {
+    const database = getDatabase();
+    return database.prepare('SELECT * FROM sessions WHERE id = ?').get(sessionId);
+}
+export function updateSession(sessionId, updates) {
+    const database = getDatabase();
+    const fields = Object.keys(updates).map(k => `${k} = ?`).join(', ');
+    const values = [...Object.values(updates), sessionId];
+    database.prepare(`UPDATE sessions SET ${fields} WHERE id = ?`).run(...values);
+}
+export function recordAnswer(answer) {
+    const database = getDatabase();
+    database.prepare(`
+    INSERT INTO answers (id, sessionId, question, userAnswer, correct, concept, subject, gradeLevel, pointsEarned, timestamp)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(answer.id, answer.sessionId, answer.question, answer.userAnswer, answer.correct, answer.concept, answer.subject, answer.gradeLevel, answer.pointsEarned, answer.timestamp);
+}
+export function getSessionAnswers(sessionId) {
+    const database = getDatabase();
+    return database.prepare('SELECT * FROM answers WHERE sessionId = ? ORDER BY timestamp ASC').all(sessionId);
+}
+export function getOrCreateProfile(profileId) {
+    const database = getDatabase();
+    const existing = database.prepare('SELECT * FROM profiles WHERE id = ?').get(profileId);
+    if (existing)
+        return existing;
+    database.prepare(`
+    INSERT INTO profiles (id, totalSessions, totalPoints, lastSessionAt, streakDays)
+    VALUES (?, 0, 0, NULL, 0)
+  `).run(profileId);
+    return database.prepare('SELECT * FROM profiles WHERE id = ?').get(profileId);
+}
+export function updateProfile(profileId, updates) {
+    const database = getDatabase();
+    const fields = Object.keys(updates).map(k => `${k} = ?`).join(', ');
+    const values = [...Object.values(updates), profileId];
+    database.prepare(`UPDATE profiles SET ${fields} WHERE id = ?`).run(...values);
+}
+export function getProfileSessions(profileId) {
+    const database = getDatabase();
+    return database.prepare('SELECT * FROM sessions WHERE profileId = ? ORDER BY startedAt DESC').all(profileId);
+}
+export function calculateStreakDays(profileId) {
+    const database = getDatabase();
+    const sessions = database.prepare(`
+    SELECT date(startedAt / 1000, 'unixepoch') as day
+    FROM sessions
+    WHERE profileId = ?
+    GROUP BY day
+    ORDER BY day DESC
+  `).all(profileId);
+    if (sessions.length === 0)
+        return 0;
+    let streak = 0;
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    for (let i = 0; i < sessions.length; i++) {
+        const sessionDate = new Date(sessions[i].day);
+        const expectedDate = new Date(today);
+        expectedDate.setDate(today.getDate() - i);
+        if (sessionDate.toDateString() === expectedDate.toDateString()) {
+            streak++;
+        }
+        else {
+            break;
+        }
+    }
+    return streak;
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export declare function createServer(): Server;