@beingtmk/core-mcp

MCP (Model Context Protocol) server for the MathAI Core Service. Provides Claude Desktop with tools to manage educational games and content sets.

⚠️ Requirements

This MCP server requires:

1. MathAI Core API Server - You must have access to a running API instance

   • Deploy your own: See API Setup below
   • Use existing: Get API URL from your team

2. API Credentials - USER_SECRET token for authentication

   • Self-hosted: Set in your API .env file
   • Team deployment: Request from your administrator

Note: This is a client package that connects to the MathAI Core API backend. It cannot function standalone.

Features

• 14 MCP Tools for game and content management
• Game Registration - Upload games to cloud storage with metadata
• Content Creation - Create and validate educational content
• Version Management - Update existing games with changelogs
• Semantic Search - Find games using natural language
• Template Generation - Auto-generate content from 8 built-in templates
• Batch Operations - Process multiple content sets efficiently
• Analytics - Track content usage and performance

Installation

Option 1: Use with npx (Recommended - No Installation Required)

When using npx in your Claude Desktop config, no manual installation is needed. npx will automatically download and run the package.

Option 2: Global Installation

npm install -g @beingtmk/core-mcp

Option 3: Project Dependency

npm install --save-dev @beingtmk/core-mcp

Setup

1. Configure Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mathai-core": {
      "command": "npx",
      "args": ["-y", "@beingtmk/core-mcp"],
      "env": {
        "USER_SECRET": "your-api-secret-key"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "mathai-core": {
      "command": "npx",
      "args": ["-y", "@beingtmk/core-mcp"],
      "env": {
        "API_BASE_URL": "http://localhost:4000",
        "USER_SECRET": "your-local-dev-secret"
      }
    }
  }
}

2. Environment Variables

| Variable | Required | Description | Default | |----------|----------|-------------|---------| | API_BASE_URL | No | MathAI Core API endpoint | https://c.c.mathai.ai | | USER_SECRET | Yes | API authentication token | - |

3. Restart Claude Desktop

After configuration, restart Claude Desktop to load the MCP server.

Usage

Once configured, Claude Desktop will have access to the following tools:

Basic Tools

• register_game - Register a new game in the catalog
• create_content_set - Create validated content for a game
• search_content_sets - Find content by criteria
• load_game_with_content - Prepare game for browser
• generate_standalone_game - Generate standalone HTML with embedded content
• validate_content - Validate content against game schema
• list_games - Browse available games

Advanced Tools

• create_content_sets_batch - Create multiple content sets from file
• generate_content_from_template - Auto-generate content using templates
• validate_input_schema - Validate schema and content together
• update_game_version - Update game with version management
• get_game - Retrieve game details for continuing work
• search_games_semantic - Natural language search for games
• test_game_content - Run automated game tests with Playwright

Example Conversation

User: Register the game at /tmp/my-game.html

Claude: I'll register your game. Let me read the file and upload it...
[Uses register_game tool]

Game registered successfully!
- Game ID: game_my_game_v1_0_0
- Version: 1.0.0
- Artifact URL: https://storage.googleapis.com/...

API Server

This MCP server requires a running MathAI Core API instance.

Quick Start API

# Clone the repository
git clone https://github.com/the-hw-app/claude-core.git
cd claude-core

# Setup environment
cp api/.env.example api/.env
# Edit api/.env with your database and GCS credentials

# Install and build
npm install
npm run build

# Run migrations
psql mathai_feedback < api/migrations/001_create_core_schema.sql
psql mathai_feedback < api/migrations/002_create_games_table.sql
psql mathai_feedback < api/migrations/003_create_content_sets_table.sql
psql mathai_feedback < api/migrations/004_create_content_items_table.sql
psql mathai_feedback < api/migrations/005_advanced_features.sql

# Start API
npm run dev:api

For production deployment, see DEPLOYMENT.md.

Development

Local Development Setup

# Clone the monorepo
git clone https://github.com/the-hw-app/claude-core.git
cd claude-core

# Install dependencies
npm install

# Build the MCP server
npm run build

# Configure Claude Desktop to use local build
# Edit claude_desktop_config.json:
{
  "mcpServers": {
    "mathai-core": {
      "command": "node",
      "args": ["/path/to/claude-core/mcp-server/dist/index.js"],
      "env": {
        "API_BASE_URL": "http://localhost:4000",
        "USER_SECRET": "your-dev-secret"
      }
    }
  }
}

Running Tests

npm test

Architecture

┌─────────────────┐
│ Claude Desktop  │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│  MCP Server     │  (This package)
│  - 14 Tools     │
│  - API Client   │
└────────┬────────┘
         │ REST API
         │
┌────────▼────────┐
│  Core API       │
│  - PostgreSQL   │
│  - GCS Storage  │
└─────────────────┘

Tool Reference

register_game

Register a new game in the catalog. Reads game HTML from file path, uploads to GCS.

Parameters:

• gameArtifactPath (string) - Absolute path to game HTML file
• metadata (object) - Title, concepts, difficulty, grade range, etc.
• capabilities (object) - What the game tracks/provides
• inputSchema (object) - JSON Schema for content structure

create_content_set

Create a validated content set for a game.

Parameters:

• gameId (string) - Game ID
• name (string) - Content set name
• grade (number) - Grade level
• difficulty (string) - easy, medium, or hard
• concepts (array) - Educational concepts
• items (array) - Content items

update_game_version

Update an existing game with a new version.

Parameters:

• gameId (string) - Existing game ID
• newVersion (string) - New version number (e.g., "1.1.0")
• gameArtifactPath (string) - Path to new game HTML
• changelog (string) - What changed in this version
• metadata (object, optional) - Updated metadata

generate_content_from_template

Auto-generate content using built-in templates.

Parameters:

• gameId (string) - Game ID
• templateId (string) - Template to use
• templateConfig (object) - Template-specific configuration
• count (number) - Number of items to generate

Available Templates:

• arithmetic-problems - Basic math problems
• equation-solving - Linear/quadratic equations
• fraction-operations - Fraction arithmetic
• word-problems - Story-based problems
• geometry-calculations - Area, perimeter, volume
• number-patterns - Sequences and patterns
• unit-conversions - Measurement conversions
• mental-math-drills - Quick calculation practice

search_games_semantic

Natural language search for games.

Parameters:

• query (string) - Natural language query (e.g., "fraction games for 5th grade")
• limit (number, optional) - Max results to return

Troubleshooting

MCP Server Not Appearing in Claude Desktop

1. Check Claude Desktop config syntax (valid JSON)
2. Ensure environment variables are set correctly
3. Restart Claude Desktop
4. Check logs: View → Developer → Developer Tools → Console

API Connection Failed

1. Verify API_BASE_URL is correct
2. Ensure API server is running
3. Check USER_SECRET matches API configuration
4. Test API directly: curl http://localhost:4000/health

Tool Execution Errors

1. Check API logs for detailed error messages
2. Verify file paths are absolute (not relative)
3. Ensure game/content IDs exist in database
4. Validate JSON schemas are correct

Related Documentation

• Full API Documentation
• Deployment Guide
• Harness Integration
• MCP Protocol Specification

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Built with ❤️ by the MathAI Team