antialias
/
soroban-abacus-flashcards
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
soroban-abacus-flashcards/apps/web/docs/mcp.md

18 KiB
Raw Blame History

Abaci.One MCP Integration

MCP (Model Context Protocol) allows external tools like Claude Code to access student skill data from Abaci.One.

Quick Start

1. Generate an API Key

Via API:

curl -X POST http://localhost:3000/api/settings/mcp-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: <your-session-cookie>" \
  -d '{"name": "Claude Code"}'

Via UI: Go to /settings/mcp-keys → Enter a name → Click "Generate"

2. Configure Claude Code

Add to your .mcp.json or run claude mcp add:

{
  "mcpServers": {
    "abaci": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

For production, use your server's URL (e.g., https://abaci.your-domain.com/api/mcp).

Available Tools

list_students

List all students accessible to this API key.

{
  "name": "list_students",
  "arguments": {}
}

Returns:

[
  { "playerId": "abc123", "name": "Sonia", "emoji": "🦊" },
  { "playerId": "def456", "name": "Fern", "emoji": "🌿" }
]

get_student_overview

Quick snapshot of a student's progress.

{
  "name": "get_student_overview",
  "arguments": { "player_id": "abc123" }
}

Returns:

{
  "playerId": "abc123",
  "name": "Sonia",
  "emoji": "🦊",
  "lastPracticed": "2026-01-15T10:30:00Z",
  "totalSkills": 34,
  "strong": 29,
  "developing": 5,
  "weak": 0
}

get_skills

Detailed skill mastery data with optional filtering.

{
  "name": "get_skills",
  "arguments": {
    "player_id": "abc123",
    "status": "developing", // optional: "strong", "developing", "weak"
    "category": "tenComplements" // optional: filter by category
  }
}

Returns:

[
  {
    "skillId": "tenComplementsSub.-1=+9-10",
    "displayName": "-1=+9-10",
    "category": "tenComplementsSub",
    "attempts": 6,
    "correct": 4,
    "errors": 2,
    "accuracy": 67,
    "lastPracticed": "2026-01-14T15:00:00Z",
    "status": "developing"
  }
]

Skill Categories:

  • basic - Direct addition/subtraction, heaven bead, simple combinations
  • fiveComplements - Five complements addition (1=5-4, 2=5-3, etc.)
  • fiveComplementsSub - Five complements subtraction
  • tenComplements - Ten complements addition (1=10-9, 2=10-8, etc.)
  • tenComplementsSub - Ten complements subtraction
  • advanced - Cascading carry/borrow

get_recent_errors

Get recent incorrect answers for targeted practice.

{
  "name": "get_recent_errors",
  "arguments": {
    "player_id": "abc123",
    "days": 7, // optional, default: 7
    "skill_id": "tenComplementsSub.-1=+9-10", // optional
    "limit": 20 // optional, default: 20
  }
}

Returns:

[
  {
    "timestamp": "2026-01-14T15:23:00Z",
    "skillsExercised": ["tenComplementsSub.-1=+9-10"],
    "responseTimeMs": 4200
  }
]

get_practice_sessions

Get practice session history.

{
  "name": "get_practice_sessions",
  "arguments": {
    "player_id": "abc123",
    "days": 14 // optional, default: 14
  }
}

Returns:

[
  {
    "date": "2026-01-15T10:30:00Z",
    "completedAt": "2026-01-15T10:42:00Z",
    "durationMinutes": 12
  }
]

get_recommended_focus

Get skills that need the most attention.

{
  "name": "get_recommended_focus",
  "arguments": {
    "player_id": "abc123",
    "count": 5 // optional, default: 5
  }
}

Returns:

[
  {
    "skillId": "tenComplementsSub.-1=+9-10",
    "displayName": "-1=+9-10",
    "category": "tenComplementsSub",
    "accuracy": 67,
    "attempts": 6,
    "status": "developing",
    "reason": "needs_practice"
  }
]

Reason values:

  • needs_practice - Weak skill, low accuracy
  • close_to_mastery - Developing, almost strong
  • maintenance - Strong but good to review

Session Management Tools

These tools allow you to create, control, and monitor practice sessions programmatically.

start_practice_session

Create and optionally start a new practice session for a student.

{
  "name": "start_practice_session",
  "arguments": {
    "player_id": "abc123",
    "duration_minutes": 10,
    "auto_start": true,
    "enabled_parts": {
      "abacus": true,
      "visualization": true,
      "linear": false
    },
    "max_terms": 5,
    "game_breaks": {
      "enabled": true,
      "max_minutes": 3,
      "selection_mode": "kid-chooses"
    }
  }
}

Parameters:

Parameter Required Default Description
player_id Yes - Student player ID
duration_minutes Yes - Session length (5-60 minutes)
auto_start No false If true, immediately approve and start the session
enabled_parts.abacus No true Include physical abacus practice
enabled_parts.visualization No true Include mental math with visualization
enabled_parts.linear No true Include mental math with equations
max_terms No 5 Maximum terms per problem (3-12)
game_breaks.enabled No true Allow game breaks between parts
game_breaks.max_minutes No 5 Maximum game break duration
game_breaks.selection_mode No "kid-chooses" "kid-chooses" or "auto-start"

Returns:

{
  "sessionId": "clxyz123",
  "status": "in_progress",
  "practiceUrl": "https://abaci.one/practice/abc123",
  "observeUrl": "https://abaci.one/practice/abc123/observe",
  "summary": {
    "totalProblemCount": 45,
    "estimatedMinutes": 10,
    "parts": [
      {
        "partNumber": 1,
        "type": "abacus",
        "problemCount": 15,
        "estimatedMinutes": 3
      },
      {
        "partNumber": 2,
        "type": "visualization",
        "problemCount": 15,
        "estimatedMinutes": 3
      },
      {
        "partNumber": 3,
        "type": "linear",
        "problemCount": 15,
        "estimatedMinutes": 4
      }
    ]
  }
}

get_active_session

Get the current active practice session for a student, including URLs and progress.

{
  "name": "get_active_session",
  "arguments": {
    "player_id": "abc123"
  }
}

Returns (when session exists):

{
  "hasActiveSession": true,
  "sessionId": "clxyz123",
  "status": "in_progress",
  "practiceUrl": "https://abaci.one/practice/abc123",
  "observeUrl": "https://abaci.one/practice/abc123/observe",
  "startedAt": 1736956200000,
  "progress": {
    "currentPart": 2,
    "currentProblem": 8,
    "totalProblems": 45,
    "completedProblems": 23,
    "accuracy": 91
  }
}

Returns (when no session):

{
  "hasActiveSession": false,
  "lastSessionAt": 1736869800000
}

control_session

Control an active session: approve, start, end early, or abandon.

{
  "name": "control_session",
  "arguments": {
    "player_id": "abc123",
    "session_id": "clxyz123",
    "action": "end_early"
  }
}

Actions:

Action Description
approve Approve a draft session (makes it ready to start)
start Start an approved session
end_early End the session early and save progress
abandon Abandon the session without saving

Returns:

{
  "success": true,
  "sessionId": "clxyz123",
  "newStatus": "completed",
  "message": "Session ended early"
}

create_observation_link

Generate a shareable URL that allows anyone (without login) to observe a practice session in real-time.

{
  "name": "create_observation_link",
  "arguments": {
    "player_id": "abc123",
    "session_id": "clxyz123",
    "expires_in": "24h"
  }
}

Parameters:

Parameter Required Description
player_id Yes Student player ID
session_id Yes Session plan ID
expires_in Yes "1h" or "24h"

Returns:

{
  "token": "aB3cDeFgH2",
  "url": "https://abaci.one/observe/aB3cDeFgH2",
  "expiresAt": 1737042600000
}

list_observation_links

List all active (non-expired, non-revoked) observation links for a session.

{
  "name": "list_observation_links",
  "arguments": {
    "player_id": "abc123",
    "session_id": "clxyz123"
  }
}

Returns:

{
  "shares": [
    {
      "token": "aB3cDeFgH2",
      "url": "https://abaci.one/observe/aB3cDeFgH2",
      "expiresAt": 1737042600000,
      "viewCount": 3,
      "createdAt": 1736956200000
    }
  ]
}

Worksheet Generation Tools

These tools allow you to create and manage math worksheets with configurable difficulty and scaffolding.

generate_worksheet

Create a math worksheet with configurable difficulty, scaffolding, and layout.

{
  "name": "generate_worksheet",
  "arguments": {
    "operator": "addition",
    "digit_range": { "min": 2, "max": 3 },
    "problems_per_page": 20,
    "pages": 2,
    "difficulty_profile": "earlyLearner",
    "include_answer_key": true,
    "title": "Morning Practice",
    "orientation": "landscape",
    "cols": 5
  }
}

Parameters:

Parameter Required Default Description
operator No addition "addition", "subtraction", or "mixed"
digit_range No {min: 2, max: 2} Min/max digits per number (1-5)
problems_per_page No 20 Problems per page (1-40)
pages No 1 Number of pages (1-20)
difficulty_profile No earlyLearner Preset difficulty (see list_difficulty_profiles)
include_answer_key No false Add answer key pages at end
title No - Optional worksheet title
orientation No landscape "portrait" or "landscape"
cols No 5 Number of columns (1-6)

Returns:

{
  "shareId": "aBc123X",
  "shareUrl": "https://abaci.one/worksheets/shared/aBc123X",
  "downloadUrl": "https://abaci.one/api/worksheets/download/aBc123X",
  "summary": {
    "shareId": "aBc123X",
    "operator": "addition",
    "digitRange": { "min": 2, "max": 3 },
    "totalProblems": 40,
    "pages": 2,
    "problemsPerPage": 20,
    "cols": 5,
    "orientation": "landscape",
    "difficultyProfile": "earlyLearner",
    "difficultyLabel": "Early Learner",
    "regroupingPercent": 25,
    "includeAnswerKey": true,
    "scaffolding": {
      "carryBoxes": "whenRegrouping",
      "answerBoxes": "always",
      "placeValueColors": "always",
      "tenFrames": "whenRegrouping"
    }
  }
}

get_worksheet_info

Get information about an existing shared worksheet.

{
  "name": "get_worksheet_info",
  "arguments": {
    "share_id": "aBc123X"
  }
}

Returns:

{
  "shareId": "aBc123X",
  "shareUrl": "https://abaci.one/worksheets/shared/aBc123X",
  "downloadUrl": "https://abaci.one/api/worksheets/download/aBc123X",
  "title": "Morning Practice",
  "worksheetType": "addition",
  "createdAt": "2026-01-15T10:30:00Z",
  "views": 5,
  "config": {
    "operator": "addition",
    "digitRange": { "min": 2, "max": 3 },
    "totalProblems": 40,
    "pages": 2,
    "problemsPerPage": 20,
    "cols": 5,
    "orientation": "landscape",
    "difficultyProfile": "earlyLearner",
    "difficultyLabel": "Early Learner",
    "regroupingPercent": 25,
    "includeAnswerKey": true
  }
}

list_difficulty_profiles

List all available difficulty profiles with their settings.

{
  "name": "list_difficulty_profiles",
  "arguments": {}
}

Returns:

{
  "profiles": [
    {
      "name": "beginner",
      "label": "Beginner",
      "description": "Full scaffolding with no regrouping. Focus on learning the structure of addition.",
      "regrouping": {
        "pAnyStart": 0,
        "pAllStart": 0,
        "percent": 0
      },
      "scaffolding": {
        "carryBoxes": "always",
        "answerBoxes": "always",
        "placeValueColors": "always",
        "tenFrames": "always",
        "borrowNotation": "always",
        "borrowingHints": "always"
      }
    },
    {
      "name": "earlyLearner",
      "label": "Early Learner",
      "description": "Scaffolds appear when needed. Introduces occasional regrouping.",
      "regrouping": {
        "pAnyStart": 0.25,
        "pAllStart": 0,
        "percent": 25
      },
      "scaffolding": {
        "carryBoxes": "whenRegrouping",
        "answerBoxes": "always",
        "placeValueColors": "always",
        "tenFrames": "whenRegrouping",
        "borrowNotation": "whenRegrouping",
        "borrowingHints": "always"
      }
    }
  ],
  "progression": [
    "beginner",
    "earlyLearner",
    "practice",
    "intermediate",
    "advanced",
    "expert"
  ]
}

Difficulty Profile Progression:

  1. beginner - Full scaffolding, no regrouping
  2. earlyLearner - Conditional scaffolding, 25% regrouping
  3. practice - High scaffolding, 75% regrouping (master WITH support)
  4. intermediate - Reduced scaffolding, 75% regrouping
  5. advanced - Minimal scaffolding, 90% regrouping
  6. expert - No scaffolding, 90% regrouping

Scaffolding Values:

  • always - Always show this scaffolding element
  • never - Never show this scaffolding element
  • whenRegrouping - Show only when problem requires regrouping
  • whenMultipleRegroups - Show only when problem has multiple regroups
  • when3PlusDigits - Show only when problem has 3+ digits

API Key Management

List Keys

curl http://localhost:3000/api/settings/mcp-keys \
  -H "Cookie: <session>"

Create Key

curl -X POST http://localhost:3000/api/settings/mcp-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: <session>" \
  -d '{"name": "My Key"}'

Revoke Key

curl -X DELETE http://localhost:3000/api/settings/mcp-keys/KEY_ID \
  -H "Cookie: <session>"

Security

  • API keys are scoped to the user who created them
  • Keys only grant access to players owned by that user (or linked via family code)
  • Keys can be revoked at any time
  • lastUsedAt is tracked for auditing
  • Use HTTPS in production

Protocol Details

The MCP endpoint uses JSON-RPC 2.0 over HTTP POST:

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_students",
      "arguments": {}
    }
  }'

Supported methods:

  • initialize - Capability negotiation
  • tools/list - List available tools
  • tools/call - Execute a tool
  • resources/list - List available documentation resources
  • resources/read - Read a specific resource

Resources (Documentation)

MCP Resources provide read-only documentation accessible to language models. Use these to understand worksheet configuration options.

List Resources

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "resources/list",
    "params": {}
  }'

Returns:

{
  "resources": [
    {
      "uri": "docs://worksheet/regrouping",
      "name": "Regrouping (Carrying/Borrowing)",
      "description": "What regrouping means pedagogically, and how pAnyStart/pAllStart control problem difficulty",
      "mimeType": "text/markdown"
    },
    {
      "uri": "docs://worksheet/scaffolding",
      "name": "Scaffolding Options",
      "description": "Visual aids on worksheets: carryBoxes, answerBoxes, placeValueColors, tenFrames, and display rule values",
      "mimeType": "text/markdown"
    },
    {
      "uri": "docs://worksheet/difficulty-profiles",
      "name": "Difficulty Profiles",
      "description": "The six preset profiles (beginner → expert), when to use each, and progression philosophy",
      "mimeType": "text/markdown"
    },
    {
      "uri": "docs://worksheet/digit-range",
      "name": "Digit Range",
      "description": "How digitRange.min and digitRange.max affect problem complexity",
      "mimeType": "text/markdown"
    },
    {
      "uri": "docs://worksheet/operators",
      "name": "Operators (Addition/Subtraction/Mixed)",
      "description": "Difference between operators, pedagogical sequence, and scaffolding differences",
      "mimeType": "text/markdown"
    }
  ]
}

Read Resource

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "resources/read",
    "params": {
      "uri": "docs://worksheet/scaffolding"
    }
  }'

Returns:

{
  "contents": [
    {
      "uri": "docs://worksheet/scaffolding",
      "mimeType": "text/markdown",
      "text": "# Scaffolding Options\n\nScaffolding elements are visual aids..."
    }
  ]
}

Available Resources

URI Purpose
docs://worksheet/regrouping Explains carrying/borrowing and how pAnyStart/pAllStart control regrouping frequency
docs://worksheet/scaffolding Describes visual aids: carryBoxes, answerBoxes, placeValueColors, tenFrames
docs://worksheet/difficulty-profiles The 6 preset profiles and when to use each
docs://worksheet/digit-range How min/max digits affect problem complexity
docs://worksheet/operators Addition vs subtraction vs mixed, with scaffolding differences

Tip: Read the difficulty-profiles resource before generating worksheets to understand how the profiles map to regrouping and scaffolding settings