jp-learning-mcp

hiinaspace/jp-learning-mcp

3.1

If you are the rightful owner of jp-learning-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Japanese Tutor MCP Server is an experimental server that enhances AI Japanese language tutoring with persistent memory and spaced repetition.

Tools
9
Resources
0
Prompts
0

Japanese Tutor MCP Server

An experimental MCP (Model Context Protocol) server that provides persistent memory for AI Japanese language tutoring. This bridges the gap between AI's natural language teaching abilities and traditional spaced repetition systems (SRS) like Anki.

Features

  • Persistent Learning Memory: Tracks concepts, review history, and teacher notes across sessions
  • Spaced Repetition: Implements retrievability calculations with exponential decay
  • Concept Management: Create, split, merge, and rename learning concepts
  • Teacher Notes: Persistent observations that survive session boundaries
  • Transparent Operation: All tool calls are visible for debugging and refinement

Quick Start

  1. Install Dependencies:

    uv sync

  2. Test the Server:

    uv run python test_mcp_server.py

  3. Run the MCP Server:

    uv run python main.py

  4. Connect with Claude Desktop (or another MCP client) to start learning!

Architecture

  • FastMCP: Pythonic MCP server framework
  • SQLModel: Combined Pydantic + SQLAlchemy for clean data models
  • SQLite: Simple, portable database for single-user experiments
  • Database Location: Stored in user data directory via platformdirs
    • Linux: ~/.local/share/jp-learning-mcp/jp_tutor.db
    • macOS: ~/Library/Application Support/jp-learning-mcp/jp_tutor.db
    • Windows: %APPDATA%\hiina\jp-learning-mcp\jp_tutor.db

Core Tools

Learning Session Tools

  • get_current_state() - Load complete state with retrievability scores
  • batch_update_reviews(reviews) - Update performance after practice
  • add_concepts(concepts) - Create new learnable units

Note Management

  • add_note(text) - Record teacher observations
  • update_note(id, text) - Modify existing notes
  • delete_note(id) - Remove notes

Concept Organization

  • split_concept(old_name, new_concepts) - Break apart broad concepts
  • merge_concepts(old_names, new_concept) - Combine related concepts
  • rename_concept(old_name, new_name) - Update concept names

Session Flow

  1. Initialization: AI calls get_current_state() to load context
  2. Learning: Natural conversation covering various Japanese concepts
  3. Review: AI assesses performance and calls batch_update_reviews()
  4. Maintenance: Optional concept reorganization and note updates

Example Usage

The AI tutor can transparently discuss the system's internal state:

AI: "Let me check your current progress..."
[Calls get_current_state()]

AI: "I see you've been working on conditionals (retrievability: 0.3 - needs review),
    て-form (0.8 - still fresh), and keigo expressions (0.5 - could use practice).

    My notes mention you were confusing たら and なら conditionals last session.

    What would you like to focus on today?"

Testing

Run the test suite:

uv run pytest tests/ -v

The tests cover database operations, retrievability calculations, and MCP tool integration.

Design Philosophy

This experiment leverages each component for its strengths:

  • AI: Natural conversation, dynamic content generation, pedagogical adaptation
  • MCP Server: State persistence, spaced repetition calculations, data management
  • Client UI: Session continuity within conversations

The system aims to feel like working with a private tutor who maintains detailed notes and always knows exactly what you need to review next.