RuRussian Agent-Native MCP

Agent-native MCP server for rurussian.com and multi-agent learning workflows.

This version upgrades the original single-file wrapper into a production-oriented learning infrastructure with:

• strict JSON outputs backed by Pydantic schemas
• three explicit layers: atomic tools, workflow tools, and memory tools
• modular services for backend access, parsing, lesson generation, and learner modeling
• persistent JSON-backed learning memory designed for later migration to MongoDB or another database

Architecture

rurussian_mcp/
  schemas/   -> request/response contracts
  services/  -> backend access, parsing, workflows, memory
  tools/     -> MCP tool registration by layer
  memory/    -> persistence namespace
  server.py  -> thin FastMCP entrypoint

Installation

pip install rurussian-mcp

Configuration

{
  "mcpServers": {
    "rurussian": {
      "command": "rurussian-mcp",
      "args": [],
      "env": {
        "RURUSSIAN_API_URL": "https://rurussian.com/api",
        "RURUSSIAN_API_KEY": "YOUR_BOT_API_KEY",
        "RURUSSIAN_LEARNER_EMAIL": "learner@example.com"
      }
    }
  }
}

Optional environment variables:

• RURUSSIAN_MEMORY_STORE
• RURUSSIAN_LEARNER_ID
• RURUSSIAN_BUY_SESSION_ENDPOINTS
• RURUSSIAN_CONFIRM_PURCHASE_ENDPOINTS

Tool Surface

Support Tools

• authenticate
• authentication_status
• list_pricing_plans
• purchase_status
• create_key_purchase_session
• confirm_key_purchase

Layer A: Atomic Tools

• parse_sentence
• generate_examples
• generate_reading_passage

Layer B: Workflow Tools

• explain_text_for_learner
• create_daily_lesson
• create_review_session
• evaluate_user_answer
• simulate_conversation

Layer C: Memory Tools

• get_learning_profile
• update_learning_progress
• get_next_best_lesson

Examples

Structured request and response examples for every tool are in examples/tool_examples.json.

Notes

• The server reuses the real RuRussian backend where it already exists today: translation, Zakuska generation, sentence generation, and checkout flows.
• Sentence parsing, lesson assembly, learner scoring, and profile memory are implemented locally so autonomous agents can compose deterministic JSON outputs.
• Memory uses a simple JSON store now and is isolated behind a service layer for future database-backed scaling.