README.md•5.84 kB
# 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:
```bash
npm install
cd frontend && npm install
cd ../mcp-server && npm install
cd ..
```
Or use the convenience script:
```bash
npm run install:all
```
### 2. Build the MCP Server
```bash
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:
```json
{
"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:
```json
{
"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
```bash
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:**
```json
{
"expression": "2 * (3 + 4)"
}
```
**Response:**
```json
{
"expression": "2 * (3 + 4)",
"result": "14",
"success": true
}
```
## Development
### Frontend Development
```bash
npm run dev:frontend
```
### MCP Server Development
After making changes to the MCP server:
```bash
cd mcp-server
npm run build
```
Then restart Claude Desktop to load the updated server.
### Build for Production
```bash
# 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