README.md

---

title: StepWise Math AI
emoji: 🎓
colorFrom: indigo
colorTo: red
sdk: docker
app_port: 7860
pinned: false
license: mit
tags:
  - building-mcp-track-consumer
  - building-mcp-track-creative
  - mcp
  - gradio
  - gemini
  - education
  - mathematics
  - ai
  - visualization
  - interactive-learning
---

# StepWise Math

**Transform Static Math Problems into Living, Interactive Step-by-Step Visual Proofs**

![](./img/hero.jpg)

This is a **Gradio MCP Framework** implementation of the StepWise Math React app, providing the same powerful features in a Python-based web interface.

[![MCP's 1st Birthday Hackathon](https://img.shields.io/badge/MCP%27s%201st%20Birthday-Hackathon-blue)](https://github.com/modelcontextprotocol)
[![Track 1: Building MCP](https://img.shields.io/badge/Track%201-Building%20MCP%20(Consumer)-blue)](https://huggingface.co/MCP-1st-Birthday)
[![Powered by Google Gemini](https://img.shields.io/badge/Powered%20by-Google%20Gemini%202.5%20Flash-blue)](https://ai.google.dev/)
[![Powered by Google Gemini](https://img.shields.io/badge/Powered%20by-Google%20Gemini%203.0%20Pro-blue)](https://ai.google.dev/)

## Overview

### What This Project Does

StepWise Math is an **MCP-capable service** that transforms static math problems into interactive, step-by-step visual proofs. Built as a Gradio-based MCP server, it provides both a user-friendly web interface and programmatic MCP endpoints for AI agents and developer tools.

The system operates through a **two-stage AI pipeline**:

- **Stage 1 — Concept Analysis** (Gemini 2.5 Flash): Generates a pedagogical JSON specification from text, URL, or image input
- **Stage 2 — Code Generation** (Gemini 3.0 Pro): Synthesizes a self-contained HTML/JS interactive proof application

### Why This Project Matters

- **Educational Impact**: Empowers teachers and students to visualize mathematical reasoning step-by-step, transforming abstract concepts into concrete, interactive experiences
- **MCP Showcase**: Demonstrates best practices for building MCP servers that integrate multi-step LLM workflows, streaming thoughts, and developer-facing prompts/resources
- **Reference Implementation**: Provides a complete example of combining AI-powered analysis with code generation in an MCP-compliant architecture

## Documentation

For complete product specifications, feature requirements, and technical implementation details, see the **[Product Requirements Document (PRD.md)](./PRD.md)**.

The PRD covers:
- Target audience and user personas (Grades 6-10 students, teachers, tutors)
- Detailed functional requirements and data models
- UI/UX design specifications
- Example use cases (Pythagorean Theorem, Slope-Intercept Form)
- System constraints and technical architecture

## Quick Start

### Using Gradio UI
1. Enter your **Gemini API Key** in the Configuration section (get one free at [ai.google.dev](https://ai.google.dev/)). This is needed only when the embedded API key is out of credits.
2. Choose your input method (Text, Image, or URL)
3. Describe a math problem or concept
4. Click **Generate Guided Proof**
5. Explore the interactive visualization!

### Using MCP Clients

1. Point your MCP client (e.g., Claude Desktop, VSCode) to the deployed MCP server URL: https://mcp-1st-birthday-stepwise-math-ai.hf.space/gradio_api/mcp/

2. Configure the MCP server settings in your client as follows:

      <details>

      <summary><strong>Claude Desktop</strong> (<code>claude_desktop_config.json</code>)</summary>



      ```json

      {

        "mcpServers": {

          "tracemind": {

            "url": "https://mcp-1st-birthday-stepwise-math-ai.hf.space/gradio_api/mcp/sse",
            "transport": "sse"

          }

        }

      }

      ```


    After updating, restart Claude Desktop.


    </details>


    <details>

    <summary><strong>VSCode</strong> (<code>settings.json</code>)</summary>


    ```json

    {

      "servers": {

        "stepwise": {

          "url": "https://mcp-1st-birthday-stepwise-math-ai.hf.space/gradio_api/mcp/",

          "type": "http"

        }

      }

    }

    ```


</details>

3. Open your MCP client and discover the available prompts and tools.
4. Invoke the `create_visual_math_proof` prompt or the underlying tools to generate interactive proofs programmatically.


## Features

### MCP Tools, Prompts & Resources
- **Prompts**: High-level conversational wrappers
- **Tools**: Programmatic calls
- **Resources**: JSON templates and examples
- **Discovery**: All prompts/tools are registered in the server schema for MCP client access
- **Authentication**: Use API keys (`GEMINI_API_KEY`)

### Multi-Modal Input
- **Text Input**: Describe any math problem in natural language
- **Image Upload**: Upload photos of textbook problems or handwritten equations
- **URL Import**: Reference YouTube videos, Khan Academy lessons, or web resources

### Dual-Stage AI Pipeline
- **Stage 1 - The Teacher** (Gemini 2.5 Flash): Analyzes concepts and designs pedagogical step sequences
- **Stage 2 - The Engineer** (Gemini 3.0 Pro + Extended Thinking): Generates production-ready interactive visualizations

### Interactive Step Navigation
- Progressive disclosure of mathematical concepts
- Back/Forward buttons to review at your own pace
- Visual state changes synchronized with each step
- Real-time equation updates as you interact

## System Architecture

The system utilizes a **Two-Stage AI Pipeline** orchestrated by a Python/Gradio core to transform abstract math concepts into interactive HTML5 applications.

1.  **Ingestion (MCP & Web):** Users submit requests via MCP-enabled clients (Claude Desktop, VSCode) or the direct Web UI.
2.  **Stage 1 - Analysis (Gemini 2.5 Flash):** The "Architect" model decomposes the mathematical concept into a structured `MathSpec` JSON, defining learning steps and visual logic.
3.  **Stage 2 - Implementation (Gemini 3.0 Pro):** The "Builder" model consumes the spec to generate self-contained, interactive HTML5/Canvas code.
4.  **Delivery:** The final executable app is rendered in the UI or returned to the MCP client for immediate use.

![architecture](./img/architecture.jpg)

**What's Included:**
- Functioning **MCP server** exposing tools for creating math specifications and building interactive proofs
- **Gradio UI** (`app.py`) for submitting text, URL, or image inputs and viewing generated proofs
- MCP **prompts** and **resources** accessible to MCP clients (Claude Desktop, VSCode, etc.)

## Usage Guide

### Generating Your First Proof

1. **Select Input Method**: Choose Text, Image, or URL
2. **Provide Your Problem**: 
   - Text: "Prove that the sum of angles in a triangle is 180 degrees"
   - Image: Upload a photo of a textbook problem or handwritten equation
   - URL: Paste a link to a Math problem. Example - https://cemc.uwaterloo.ca/sites/default/files/documents/2025/POTWC-25-G-11-P.html
3. **Click Generate**: The AI will analyze and create your interactive proof
4. **Explore**: Navigate through the steps in the Guided Proof tab

### Refining Your Proof

1. **View the Generated Proof**: Check the interactive simulation
2. **Provide Feedback**: Type suggestions like "Make the triangle larger" or "Add labels to the vertices"
3. **Apply Refinement**: The AI will regenerate with your feedback

## Technical Details

### MCP Integration Architecture & Programmatic Flow

The diagram illustrates how the Gradio application exposes its functionality for programmatic access via the Model Context Protocol (MCP). The **Gradio App Server** acts as the central hub, exposing capabilities in two categories:

* **MCP Prompts:** High-level, conversational wrappers (e.g., `create_visual_math_proof`) for guiding multi-step workflows.
* **MCP Resources / Tools:** Direct, callable functions (e.g., `create_math_specification_from_text`, `build_from_specification`) for specific tasks.

MCP-aware clients or agents can interact with these components by first **discovering** the available tools through the server schema and then **authenticating** with an API key.

The bottom section details a typical **programmatic flow**:
1.  **Discover** available prompts and resources.
2.  **Call** a `create_math_specification_from_*` tool with the appropriate input (Text, URL, or Image) to generate a structured `MathSpec JSON`.
3.  **Call** the `build_interactive_proof_from_specification` tool with the generated JSON to produce the final, self-contained `index.html` interactive proof.


![programmatic-flow](./img/programmatic-flow.jpg)

***Note**: All data is processed securely. Your API key is only used to communicate with Google's Gemini API.*



## Resources & Links



### Live Demo & Demo Video (Coming Soon)



- **Live Demo**: Coming Soon

- **Demo Video**: Coming Soon (TODO)



### Social Media (Coming Soon)



Read the announcement and join the discussion:

- **Blog Post**: Coming Soon (TODO)

- **Twitter/X**: Coming Soon (TODO)

- **LinkedIn**: Coming Soon (TODO)

- **Discord**: [HuggingFace Discord](https://discord.com/channels/879548962464493619/1439001549492719726/1442838638307180656) (TODO)



## Contributing & Support



**Contributions Welcome!** Areas of interest:
- Performance optimizations
- UI/UX improvements
- Additional mathematical domains
- Documentation and examples

**Support Channels:**
- **Discussions**: [HuggingFace Discussions](https://huggingface.co/spaces/MCP-1st-Birthday/StepWise-Math-AI/discussions)
- **Contact**: TODO - Project lead contact information

## Acknowledgments

- **Google AI** for the incredible Gemini models
- **Gradio** for the amazing Python web framework
- **Nano Banana** for image assets
- **GitHub Copilot** for Vibe Coding


## License

This project is licensed under the MIT License. Original work created for the MCP's 1st Birthday Hackathon (November 2025).

For attributions of third-party assets and libraries, see [ACKNOWLEDGMENTS](#-acknowledgments).



<div align="center">

**Built with ❤️ for visual learners everywhere**

*Making abstract math concrete, one proof at a time*

**Like this space if you found it helpful!**

</div>