Math Quiz with MCP Server

A demonstration application showing how an MCP (Model Context Protocol) server can act as a mathematical coprocessor. The LLM decides what calculations to perform, and the MCP server handles the computation using mathjs.

Architecture

• Frontend: React + Vite + Tailwind CSS - Simple math quiz interface
• MCP Server: Node.js + TypeScript - Mathematical evaluation service

Project Structure

mcp-math/
├── frontend/           # React quiz application
│   ├── src/
│   │   ├── App.tsx    # Main quiz component
│   │   ├── main.tsx   # React entry point
│   │   └── index.css  # Tailwind styles
│   └── package.json
├── mcp-server/        # MCP server for math operations
│   ├── src/
│   │   └── index.ts   # MCP server implementation
│   └── package.json
└── package.json       # Workspace root

Setup Instructions

1. Install Dependencies

From the root directory:

npm install
cd frontend && npm install
cd ../mcp-server && npm install
cd ..

Or use the convenience script:

npm run install:all

2. Build the MCP Server

cd mcp-server
npm run build

3. Configure MCP Client

For Cursor

Add the MCP server to your Cursor configuration file:

Location: ~/.cursor/mcp.json

Example configuration:

{
  "mcpServers": {
    "math": {
      "command": "node",
      "args": ["${HOME}/path/to/mcp-math/mcp-server/dist/index.js"]
    }
  }
}

Important: Replace path/to/mcp-math with the actual path from your home directory to your project directory. The ${HOME} variable will be automatically expanded.

After updating the configuration, restart Cursor for the changes to take effect.

For Claude Desktop

Add the MCP server to your Claude Desktop configuration file:

MacOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Example configuration:

{
  "mcpServers": {
    "math": {
      "command": "node",
      "args": ["${HOME}/path/to/mcp-math/mcp-server/dist/index.js"]
    }
  }
}

Important: Replace path/to/mcp-math with the actual path from your home directory to your project directory.

After updating the configuration, restart Claude Desktop for the changes to take effect.

Running the Application

Start the Frontend

cd frontend
npm run dev

The quiz app will be available at http://localhost:5173

Using the MCP Server with Claude/Cursor

Once configured, you can ask Claude (or Cursor AI) to use the math server:

Example prompts:

• "Use the math server to calculate 123 * 456"
• "Evaluate sqrt(144) + sin(pi/2) using the evaluate tool"
• "What is (25 + 75) / (10 - 5)?"

The AI will automatically use the evaluate tool from the MCP server to perform calculations.

MCP Server Tools

evaluate

Evaluates a mathematical expression and returns the result.

Input:

• expression (string): Mathematical expression to evaluate

Supported Operations:

• Basic arithmetic: +, -, *, /
• Exponents: ^ or **
• Parentheses: (, )
• Common functions: sqrt(), sin(), cos(), tan(), log(), etc.
• Constants: pi, e

Example:

{
  "expression": "2 * (3 + 4)"
}

Response:

{
  "expression": "2 * (3 + 4)",
  "result": "14",
  "success": true
}

Development

Frontend Development

npm run dev:frontend

MCP Server Development

After making changes to the MCP server:

cd mcp-server
npm run build

Then restart Claude Desktop to load the updated server.

Build for Production

# Build frontend
npm run build:frontend

# Build MCP server
npm run build:mcp

How It Works

The MCP Pattern

This application demonstrates the "coprocessor" pattern:

1. Frontend displays math problems to users
2. LLM (Claude) understands user intent and decides what calculations to perform
3. MCP Server executes the calculations accurately using mathjs
4. Result flows back through Claude to the application

Why Use MCP for Math?

• Accuracy: LLMs can struggle with precise calculations. The MCP server uses mathjs for exact results.
• Separation of Concerns: The LLM focuses on understanding and orchestration, while the MCP server handles computation.
• Extensibility: Easy to add new mathematical operations without retraining the model.

Notes

• The current frontend implementation calculates answers locally for demo simplicity
• In a production setup, you would connect the frontend to Claude (via API or desktop app) which would use the MCP server
• This is a demonstration project showing MCP architecture - not production-ready

Future Enhancements

Potential improvements:

• Add database for storing quiz results
• Connect frontend directly to Claude API with MCP
• Add more quiz types (algebra, geometry, etc.)
• Implement user authentication and progress tracking
• Add difficulty levels and adaptive quizzing

Troubleshooting

MCP Server not showing in Claude/Cursor

1. Check the configuration file path is correct (~/.cursor/mcp.json for Cursor)
2. Ensure the path to index.js is correct (use ${HOME}/... for portability)
3. Verify the server builds without errors: cd mcp-server && npm run build
4. Check logs:
   • Claude Desktop: Help → Show Logs
   • Cursor: Check the MCP server output in Cursor settings
5. Restart Claude Desktop or Cursor after configuration changes

Frontend not starting

1. Ensure dependencies are installed: cd frontend && npm install
2. Check Node.js version (requires Node 18+)
3. Try clearing node_modules and reinstalling

License

MIT