PRD.md

# **Product Requirements Document: StepWise Math (Gradio MCP Implementation)**

| Document Info          | Details                                                                          |
| :--------------------- | :------------------------------------------------------------------------------- |
| **Product Name**       | StepWise Math - Gradio MCP Framework                                             |
| **Version**            | 2.0 (MCP Server with Two-Stage Pipeline)                                         |
| **Status**             | Active                                                                           |
| **Target Demographic** | Middle School (Grades 6-8) to High School (Grades 9-10)                          |
| **Tech Stack**         | **Gradio 6.0+**, Python, **Google Gemini 2.5 Flash & 3.0 Pro**, **MCP Protocol** |
| **Deployment**         | Hugging Face Spaces, Docker, Local Development                                   |

## **1. Executive Summary**

**StepWise Math** is a Gradio-based web application with **Model Context Protocol (MCP) server capabilities** that converts static mathematical problems—supplied via text, screenshots, or URLs—into **interactive, step-by-step visual proofs**. 

Unlike a calculator that just gives the answer, StepWise Math builds a bespoke HTML5 application that guides students through the logical stages of a proof or concept. It breaks down complex ideas into incremental steps (e.g., "Step 1: Construct the shape", "Step 2: Apply the transformation", "Step 3: Observe the result"), allowing students to manipulate variables at each stage to internalize the logic.

### **Key Architecture Features**

* **MCP Server Integration:** Exposes proof generation tools via the Model Context Protocol, enabling AI agents and external tools to programmatically generate mathematical proofs
* **Two-Stage AI Pipeline:** Separates concept analysis (fast, ~10-15s) from code generation (moderate, ~20-30s) to comply with MCP timeout constraints
* **Gradio Framework:** Provides both web UI and MCP server endpoints through a single application instance
* **Docker-Ready:** Fully containerized for deployment to Hugging Face Spaces or any Docker-compatible environment

## **2. Target Audience**

* **Students (Grades 6-10):** Visual learners who need structured guidance to understand abstract concepts in Geometry, Algebra, and Trigonometry.
* **Math Teachers:** Need "digital manipulatives" that walk the class through a concept phase-by-phase.
* **Tutors:** Need to generate custom step-by-step explanations for specific homework problems.
* **AI Agents & Developers:** Can programmatically generate mathematical proofs via MCP protocol integration for educational tools, chatbots, or automated tutoring systems.

## **3. User Flow & Experience**

### **3.1 High-Level Flow (Gradio Web UI)**

1. **Initial Load:** Application automatically loads first example proof to demonstrate capabilities
2. **Input Selection:** User chooses input mode (Text, URL, or Image) via Gradio interface
3. **Content Entry:** User provides the mathematical concept or problem
4. **API Key (Optional):** User can override default API key in settings
5. **Two-Stage Generation:**
   - **Stage 1:** Concept Analysis (Gemini 2.5 Flash, ~10-15s) → JSON Specification
   - **Stage 2:** Code Generation (Gemini 3.0 Pro, ~20-30s) → Interactive HTML/JS Application
6. **Visualization:** Generated proof displays in iframe with step navigation
7. **Actions:** Save to library, export as JSON, or refine with feedback

![High-Level User Flow Diagram](./img/gradio-ui-user-flow.jpg)
### **3.2 MCP Server Flow (Programmatic Access)**

1. **Tool Discovery:** AI agent connects to Gradio MCP server endpoint
2. **Available Tools:**
   - `analyze_concept_from_text`: Analyzes text-based mathematical concept → returns JSON spec
   - `analyze_concept_from_url`: Analyzes concept from URL → returns JSON spec
   - `analyze_concept_from_image`: Analyzes concept from image → returns JSON spec
   - `generate_code_from_concept`: Generates interactive proof code from JSON spec → returns HTML/JS
3. **Two-Step Invocation:**
   - **Step 1:** Agent calls `analyze_concept_from_text/url/image` with input
   - **Step 2:** Agent calls `generate_code_from_concept` with JSON from Step 1
4. **Output Handling:** Agent receives HTML/JS code for rendering or further processing

![MCP Server Flow Diagram](./img/mcp-server-flow.jpg)

**MCP Architecture Diagram:**

![MCP Architecture Diagram](./img/architecture-diagram.jpg)

### **3.3 Feedback & Iteration Flow**

The user can view the generated proof and provide text feedback (e.g., "Make the triangle red" or "Add a step for area calculation").
1. **User Feedback:** User enters text in the "Refinement" panel (Gradio Textbox)
2. **Intent Analysis:** The system determines if the request requires a structural change (new steps) or just a visual update
3. **Regeneration:**
    - **Stage 1 (Refine Spec):** Gemini 2.5 Flash updates the JSON spec based on feedback
    - **Stage 2 (Refine Code):** Gemini 3.0 Pro rewrites the application code using the new spec and specific user instructions
4. **Update:** The Gradio HTML component refreshes with the modified application

## **4. Functional Requirements**

### **4.1 Multi-Modal Input Handling**

The app must accept three distinct types of input:
1. **Natural Language Text:** e.g., "Prove the Pythagorean Theorem."
2. **Image/Screenshot:** A photo of a textbook problem.
3. **URL:** A link to a math concept video or page.
*   **Validation:** The system must strictly validate inputs (e.g., check for empty text, valid URL format, or missing image files) before communicating with the AI to prevent "hallucinated" default responses.

### **4.2 The "Thinking" Engine (Gemini Integration)**

**Two-Stage Pipeline Architecture (MCP-Optimized)**

The application uses a **two-stage AI pipeline** specifically designed to comply with MCP protocol timeout constraints (typically <30 seconds per tool call):

* **Stage 1: Concept Decomposition (The Teacher)**
  * **Model:** `gemini-2.5-flash`
  * **Role:** Identifies the mathematical concept and breaks it down into a logical teaching sequence
  * **Execution Time:** ~10-15 seconds
  * **Output:** JSON Spec containing a list of **Steps**. Each step defines what the user should do and what they should see
  * **MCP Exposure:** Three separate tools based on input type:
    - `analyze_concept_from_text(text_input, api_key)` 
    - `analyze_concept_from_url(url_input, api_key)`
    - `analyze_concept_from_image(image_input, api_key)`
  * **Return Value:** JSON string containing the `MathSpec`
  
* **Stage 2: Implementation (The Engineer)**
  * **Model:** `gemini-3-pro-preview`
  * **Config:** `thinkingConfig: { thinkingBudget: 4096 }`
  * **Role:** Writes the HTML5/Canvas code based on the JSON specification
  * **Execution Time:** ~20-30 seconds
  * **Requirement:** The generated app must include a **Step Navigation System** (Next/Previous buttons, Progress bar) and distinct visual states for each step
  * **MCP Exposure:** Single tool for code generation:
    - `generate_code_from_concept(concept_json, api_key)`
  * **Return Value:** HTML string containing complete interactive application

**Why Two Stages for MCP?**

MCP protocol has strict timeout limitations. The original single-step `generate_proof` operation took 30-60 seconds, exceeding MCP timeout windows. By splitting into two independent operations:
- Each operation completes within timeout constraints
- AI agents can cache the JSON spec and regenerate code multiple times without re-analyzing
- More granular control over the generation process
- Better error recovery (if Stage 2 fails, Stage 1 results are preserved)

### **4.3 Output & Interaction**

* **Guided Experience:** The app starts at "Step 1". The user reads an instruction, interacts with the visual, and clicks "Next" to proceed
* **Interactive Canvas:** Graphics update based on the current step. For example, construction lines might appear only in Step 2
* **Live Feedback:** Equations and values update in real-time as user drags elements
* **Gradio Components:**
  - **HTML Component:** Displays the generated interactive proof application
  - **JSON Component:** Shows the MathSpec structure for debugging/inspection
  - **Textbox Components:** Display process logs and thinking streams
  - **Accordion/Tab Layouts:** Organize different views (Proof, Spec, Code, Logs)

### **4.4 Feedback Loop**

* **Refinement Interface:** A text input field below the simulation area allows users to request changes.
* **Context Awareness:** The AI must receive the *previous* JSON specification and the *new* user feedback to generate a delta or a completely new version.
* **Logic:**
    *   If the feedback changes the math concept (e.g., "Switch to Isosceles"), Stage 1 must regenerate the steps.
    *   If the feedback is cosmetic (e.g., "Dark mode"), Stage 2 must implement it while preserving the logic.

### **4.5 Export & Sharing** [Coming Soon]

* **Export Button:** A Gradio Button to download the current session
* **Format:** A JSON file containing:
    *   **Input Data:** The original problem text, URL, or image data
    *   **Math Concept:** The JSON Specification (Steps, Explanation)
    *   **Source Code:** The Generated HTML/JS
    *   **Metadata:** Timestamp, input mode
    *   **Exclusion:** Process Logs are **not** included in the export file to keep it clean
* **Import Capability:** A Gradio File Upload component to restore a previously exported JSON file. This restores the input fields, the concept specification, and the interactive proof code
* **Implementation:** Uses Gradio's `gr.DownloadButton` and `gr.File` components

### **4.6 Persistence (Local Storage via ProofLibrary)**  [Coming Soon]

*   **Save Capability:** Users can save the currently generated proof (Math Spec + Code) using a Gradio Button
*   **Backend Storage:** Python-based `ProofLibrary` class manages proof persistence:
    - Saves to `saved_proofs/` directory as JSON files
    - Each proof file contains: title, timestamp, input data, concept spec, generated code
    - Filename format: `proof_YYYYMMDD_HHMMSS.json`
*   **Library View:** A Gradio component (Dropdown or Gallery) lists previously saved items with timestamps and concept titles
*   **Load Capability:** Users can instantly restore a previously generated proof from the library without re-querying the AI
*   **File System:** Unlike browser Local Storage, Gradio implementation uses server-side file system storage for better reliability and Docker compatibility

### **4.7 Configuration & API Key Management** 

*   **Configuration Interface:** Gradio Accordion component in settings panel
*   **API Key Management:**
    *   The app defaults to using the `GEMINI_API_KEY` from environment variables (`os.getenv("GEMINI_API_KEY")`)
    *   Users can optionally provide their own API Key via a Gradio Textbox (type="password")
    *   **Logic:** If a custom key is provided to MCP tools or web UI, it takes precedence over the environment variable
    *   **MCP Tools:** API key is an optional parameter in all MCP-exposed functions:
        - `analyze_concept_from_text(text_input, api_key: Optional[str] = None)`
        - `generate_code_from_concept(concept_json, api_key: Optional[str] = None)`
    *   **Security:** Custom API keys are passed per-request and not persisted server-side
*   **Environment Variable Setup:**
    ```bash

    # Linux/Mac

    export GEMINI_API_KEY="your-api-key-here"

    

    # Windows PowerShell

    $env:GEMINI_API_KEY="your-api-key-here"

    

    # Docker

    docker run -e GEMINI_API_KEY="your-key" -p 7860:7860 hf-stepwise-math

    ```


### **4.8 Thinking Process Streaming (Enhanced UI)**  [Coming Soon]

*   **Streaming Thoughts:** The application utilizes Gemini's `thinkingConfig` with `includeThoughts: true` to capture the model's internal reasoning process
*   **Gradio Implementation:**
    *   **Textbox Component:** Displays thinking stream with `max_lines=20` for scrollable content
    *   **Real-time Updates:** Uses Gradio's streaming capabilities to update UI as thoughts arrive
    *   **Markdown Rendering:** Gradio automatically renders Markdown in textboxes when configured
*   **Display Features:**
    *   **Timer:** Progress message showing elapsed time (e.g., "Running for 12s")
    *   **Structured Layout:** Separate sections for "Analysis Phase" and "Code Generation Phase"
    *   **Collapsible Accordions:** Users can expand/collapse thought details to focus on results
*   **Process Logs:**
    *   Separate from thinking stream
    *   Shows high-level pipeline progress: "Starting Stage 1...", "Concept analyzed", "Generating code..."
    *   Stored in `GeminiPipeline.process_logs` list for debugging

### **4.9 Pre-loaded Examples Library**

*   **Examples Section:** Gradio Dropdown component populated from `examples/` directory
*   **File Format:** Each example is a JSON file containing:
    ```json

    {

      "title": "Visual Proof: Pythagorean Theorem",

      "input_mode": "Text",

      "input_data": "Prove the Pythagorean theorem...",

      "concept": { /* MathSpec JSON */ },

      "code": "<!DOCTYPE html>..."

    }

    ```

*   **Initial Load Behavior:** On application startup, automatically load the first example (or a designated default example) to:

    - Provide immediate visual demonstration of app capabilities

    - Avoid empty/blank initial state

    - Give users instant understanding of the output format

    - Enable immediate interaction without waiting for AI generation

*   **One-Click Loading:** Selecting an example from dropdown triggers a Gradio event handler that:

    - Populates input fields with example data

    - Loads the pre-generated concept spec into JSON viewer

    - Renders the code in the HTML iframe

    - Bypasses AI generation for instant loading

*   **Content:** The library covers diverse topics:

    - Geometry: Pythagorean Theorem, Area of Quadrilaterals, Altitude-Hypotenuse Ratios

    - Probability: Probability of Odd Sums

    - Algebra: Diagonals in Rhombus

*   **Example Files:** Located in `examples/` directory with naming convention `001-visual-proof-{topic}.json`

*   **Default Example:** First example in alphabetical order (`001-visual-proof-probability-of-an-odd-sum.json`) loads automatically on app initialization


### **4.10 MCP Server Integration**

*   **Gradio MCP Support:** Application launches with `mcp_server=True` flag to enable MCP protocol endpoints
*   **Tool Exposure Mechanism:** 
    - Gradio only exposes methods that are connected to UI components as MCP tools
    - Hidden UI components (created with `visible=False` in a `gr.Group`) are used to expose MCP-specific methods
    - Event handlers connect methods to hidden buttons/textboxes for MCP discovery
*   **Exposed MCP Tools (4 Total):**
    

    1. **analyze_concept_from_text**

       - **Parameters:** `text_input: str`, `api_key: Optional[str]`

       - **Returns:** JSON string containing MathSpec

       - **Purpose:** Fast concept analysis for text input

       - **Timeout:** ~10-15 seconds

    

    2. **analyze_concept_from_url**

       - **Parameters:** `url_input: str`, `api_key: Optional[str]`

       - **Returns:** JSON string containing MathSpec

       - **Purpose:** Fast concept analysis from URL content

       - **Timeout:** ~10-15 seconds

    

    3. **analyze_concept_from_image**

       - **Parameters:** `image_input: str` (base64 or file path), `api_key: Optional[str]`

       - **Returns:** JSON string containing MathSpec

       - **Purpose:** Fast concept analysis from image

       - **Timeout:** ~10-15 seconds

    

    4. **generate_code_from_concept**

       - **Parameters:** `concept_json: str`, `api_key: Optional[str]`

       - **Returns:** HTML string containing interactive proof application

       - **Purpose:** Generate code from previously analyzed concept

       - **Timeout:** ~20-30 seconds


*   **MCP Usage Pattern:**
    ```python

    # Step 1: Analyze concept

    concept_json = mcp_client.call_tool(

        "analyze_concept_from_text",

        {"text_input": "Prove Pythagorean theorem", "api_key": "optional-key"}

    )

    

    # Step 2: Generate code

    html_code = mcp_client.call_tool(

        "generate_code_from_concept", 

        {"concept_json": concept_json, "api_key": "optional-key"}

    )

    ```


*   **Testing MCP Server:**
    ```bash

    # Launch MCP Inspector

    npx @modelcontextprotocol/inspector

    

    # Connect to: http://localhost:7860/mcp

    # Available tools will appear in inspector UI

    ```


*   **Hidden UI Components (MCP Exposure):**
    ```python

    with gr.Group(visible=False) as mcp_hidden_group:

        # Analysis tools

        mcp_analyze_text_input = gr.Textbox()

        mcp_analyze_text_btn = gr.Button()

        mcp_analyze_text_output = gr.Textbox()

        

        # Code generation tool

        mcp_generate_concept_input = gr.Textbox()

        mcp_generate_concept_btn = gr.Button()

        mcp_generate_concept_output = gr.Textbox()

    

    # Event handlers connect methods for MCP

    mcp_analyze_text_btn.click(

        fn=analyze_concept_from_text,

        inputs=[mcp_analyze_text_input],

        outputs=[mcp_analyze_text_output]

    )

    ```


## **5. Feature Specifications (Examples)**

### **Example 1: The Pythagorean Theorem**
* **Generated App Steps:**
  * **Step 1: Setup:** Display a right triangle. User drags vertices to resize. "Observe the legs a, b and hypotenuse c."
  * **Step 2: Geometric Construction:** Squares appear on each side. "We build a square on each side of the triangle."
  * **Step 3: Area Calculation:** The app calculates the area of each square. "Note the values: A = a², B = b², C = c²."
  * **Step 4: The Proof:** The app rearranges the areas or shows the equation `Area A + Area B = Area C`. User drags vertices to verify it holds true for *any* right triangle.

### **Example 2: Slope Intercept Form**

* **Input:** Text: "Explain y = mx + b"
* **Generated App Steps:**
  * **Step 1: The Grid:** Shows a coordinate plane.
  * **Step 2: The Y-Intercept:** User adjusts slider `b`. The line moves up/down. "b controls where the line crosses the Y-axis."
  * **Step 3: The Slope:** User adjusts slider `m`. The line rotates. "m controls the steepness."
  * **Step 4: Prediction:** User is asked to set sliders to match a target line.

## **9. Development & Testing**

### **9.1 Local Development**
```bash

# Clone repository

git clone <repo-url>

cd hf-StepWise-Math/gradio-app



# Install dependencies

pip install -r requirements.txt



# Set API key

export GEMINI_API_KEY="your-api-key"  # Linux/Mac

$env:GEMINI_API_KEY="your-api-key"    # Windows PowerShell



# Run application

python app.py

```

### **9.2 Testing MCP Integration**
```bash

# Terminal 1: Launch Gradio app with MCP server

cd gradio-app

python app.py



# Terminal 2: Launch MCP Inspector

npx @modelcontextprotocol/inspector



# In Inspector UI:

# 1. Connect to: http://localhost:7860/mcp

# 2. Verify 4 tools appear: analyze_concept_from_text/url/image, generate_code_from_concept

# 3. Test two-step workflow:

#    - Call analyze_concept_from_text with test input

#    - Copy JSON result

#    - Call generate_code_from_concept with JSON

```

### **9.3 Docker Testing**
```bash

# Build image

docker build -t hf-stepwise-math .



# Run container

docker run --rm -it -e GEMINI_API_KEY="your-key" -p 7860:7860 hf-stepwise-math



# Access at: http://localhost:7860

# MCP endpoint: http://localhost:7860/mcp

```

### **9.4 Test Files**
* `test_app.py`: Unit tests for Gradio components
* `test_generate_proof.py`: Integration tests for AI pipeline
* `test_logging.py`: Logging system validation
* Example files in `examples/`: Pre-generated proofs for UI testing

### **9.5 Deployment Checklist**
- [ ] GEMINI_API_KEY environment variable configured
- [ ] Docker image builds successfully
- [ ] MCP server accessible at `/mcp` endpoint
- [ ] All 4 MCP tools discoverable
- [ ] Example library loads correctly
- [ ] **Default example auto-loads on app initialization**
- [ ] Save/Load functionality works with file system
- [ ] Export/Import produces valid JSON
- [ ] Two-stage pipeline completes within timeout constraints

**MathSpec (JSON)**

```json

{

  "conceptTitle": "Pythagorean Theorem",

  "educationalGoal": "Prove a^2 + b^2 = c^2",

  "explanation": "In a right-angled triangle...",

  "steps": [

    {

      "stepTitle": "The Triangle",

      "instruction": "Drag the red dots to change the shape of the right triangle.",

      "visualFocus": "Triangle ABC"

    },

    {

      "stepTitle": "Adding Squares",

      "instruction": "Click Next to visualize squares attached to each side.",

      "visualFocus": "Squares on sides a, b, c"

    }

  ],

  "visualSpec": {

    "elements": ["Triangle", "Squares", "Grid"],

    "interactions": ["Drag Vertex", "Hover info"],

    "mathLogic": "Calculate distances..."

  }

}

```

## **7. UI/UX Design (Gradio Components)**

* **Input Panel (Left Column):**
  - **Radio Buttons:** Select input mode (Text/URL/Image)
  - **Conditional Components:** Show relevant input field based on mode
  - **Textbox:** For text input
  - **Textbox:** For URL input
  - **Image Upload:** For image input
  - **Textbox (Password):** Optional API key override
  - **Button:** "Generate Proof"
  - **Dropdown:** Example selection
  - **Accordion:** Settings panel

* **Output Panel (Right Column):**
  - **Tabs Component:**
    1. **Interactive Proof:** `gr.HTML()` component displaying generated application
    2. **Concept Spec:** `gr.JSON()` component showing MathSpec structure
    3. **Source Code:** `gr.Code(language="html")` for viewing/editing generated code
    4. **Process Logs:** `gr.Textbox()` with process execution details
    5. **Thinking Stream:** `gr.Textbox()` with AI reasoning (collapsible accordion)

* **Action Buttons:**
  - **Save to Library:** Stores proof to `saved_proofs/` directory
  - **Export/Download:** `gr.DownloadButton()` for JSON export
  - **Import/Upload:** `gr.File()` for JSON import
  - **Load from Library:** `gr.Dropdown()` with saved proofs

* **Refinement Panel (Below Output):**
  - **Textbox:** Multi-line input for feedback
  - **Button:** "Refine Proof" to trigger regeneration

## **8. Technical Constraints & Requirements**

### **8.1 MCP Protocol Constraints**
* **Timeout Limitation:** Each MCP tool call must complete within ~30 seconds
* **Solution:** Two-stage pipeline splits 30-60s operation into 10-15s + 20-30s stages
* **Tool Discovery:** Tools must be connected to Gradio UI components (even if hidden) to be exposed via MCP
* **Parameter Handling:** All MCP tool parameters must be either required or properly typed with `Optional[]`
* **No Conditional Parameters:** Cannot require different parameters based on conditions (e.g., url_input required when mode="URL")



### **8.2 Gemini API Configuration**

* **Thinking Budget:** Uses high reasoning budget (4096) for Stage 2 (code generation) to ensure robust logic

* **Model Selection:** 

  - Stage 1: `gemini-2.5-flash` for fast analysis

  - Stage 2: `gemini-3-pro-preview` for extended thinking during code generation

* **API Key Management:** Supports environment variable fallback with optional per-request override



### **8.3 Gradio Framework**

* **Version:** Gradio 6.0+ (supports `mcp_server=True` flag)
* **Launch Command:** `demo.launch(mcp_server=True, share=False, server_port=7860)`
* **Hidden Components:** Required for MCP tool exposure without cluttering UI
* **Event Handlers:** Connect Python methods to Gradio components for both UI and MCP access

### **8.4 Visual Clarity (Generated Code)**
* **Layout Requirements:** Generated code **MUST** prioritize visual clarity
* **Separation:** Overlapping elements are strictly prohibited
* **CSS/Layout:** Must use Flexbox/Grid to strictly separate graphics area (Canvas/SVG) from controls and textual instructions
* **Step Navigation:** Generated apps must include prominent navigation UI (buttons, progress indicators)

### **8.5 Docker & Deployment**
* **Containerization:** Application is fully Docker-ready with `Dockerfile` and `requirements.txt`
* **Port Mapping:** Exposes port 7860 for web UI and MCP server
* **Environment Variables:** API key passed via `-e GEMINI_API_KEY="..."`
* **Hugging Face Spaces:** Compatible with HF Spaces deployment (uses `gradio` template)
* **Build Command:** `docker build -t hf-stepwise-math .`
* **Run Command:** `docker run -e GEMINI_API_KEY="key" -p 7860:7860 hf-stepwise-math`

### **8.6 Security & Safety**
* **Content Filtering:** Image inputs should be validated for appropriate educational content
* **API Key Security:** Custom keys are per-request only, not persisted server-side
* **CORS:** Gradio handles CORS automatically for web UI and MCP endpoints
* **Rate Limiting:** Consider implementing rate limits for MCP tool calls in production

## **10. Data Models (Python Implementation)**

**MathSpec (Python Class)**

```python

class MathSpec:

    """Structured mathematical concept specification"""

    def __init__(self, data: dict):

        self.concept_title = data.get("conceptTitle", "")

        self.educational_goal = data.get("educationalGoal", "")

        self.explanation = data.get("explanation", "")

        self.steps = data.get("steps", [])

        self.visual_spec = data.get("visualSpec", {})

    

    def to_dict(self):

        return {

            "conceptTitle": self.concept_title,

            "educationalGoal": self.educational_goal,

            "explanation": self.explanation,

            "steps": self.steps,

            "visualSpec": self.visual_spec

        }

```

**MathSpec JSON Format**

```json

{

  "conceptTitle": "Pythagorean Theorem",

  "educationalGoal": "Prove a^2 + b^2 = c^2",

  "explanation": "In a right-angled triangle...",

  "steps": [

    {

      "stepTitle": "The Triangle",

      "instruction": "Drag the red dots to change the shape of the right triangle.",

      "visualFocus": "Triangle ABC"

    },

    {

      "stepTitle": "Adding Squares",

      "instruction": "Click Next to visualize squares attached to each side.",

      "visualFocus": "Squares on sides a, b, c"

    }

  ],

  "visualSpec": {

    "elements": ["Triangle", "Squares", "Grid"],

    "interactions": ["Drag Vertex", "Hover info"],

    "mathLogic": "Calculate distances..."

  }

}

```

**Export/Save Format**

```json

{

  "title": "Visual Proof: Pythagorean Theorem",

  "timestamp": "2025-11-25T10:30:00",

  "input_mode": "Text",

  "input_data": "Prove the Pythagorean theorem using visual methods",

  "concept": {

    "conceptTitle": "Pythagorean Theorem",

    "educationalGoal": "...",

    "steps": [...]

  },

  "code": "<!DOCTYPE html>...",

  "metadata": {

    "generated_by": "StepWise Math Gradio MCP",

    "version": "2.0"

  }

}

```

## **11. File Structure**

```

gradio-app/

├── app.py                          # Main Gradio application with MCP server

├── requirements.txt                # Python dependencies

├── Dockerfile                      # Container configuration

├── setup.sh / setup.bat            # Environment setup scripts

├── README.md                       # Documentation

├── saved_proofs/                   # User-generated proofs (persistent storage)

│   ├── proof_20251125_103000.json

│   └── proof_20251125_154500.json

├── examples/                       # Pre-loaded example proofs

│   ├── 001-visual-proof-pythagorean-theorem.json

│   ├── 002-visual-proof-probability-odd-sum.json

│   └── ...

├── test_app.py                     # Unit tests

├── test_generate_proof.py          # Integration tests

└── docs/                           # Additional documentation

    ├── DEPLOYMENT.md

    ├── TEST_GUIDE.md

    └── MCP_SCHEMA_README.md

```

## **12. Appendix: MCP Tool Schema**

### **Tool 1: analyze_concept_from_text**

```json

{

  "name": "analyze_concept_from_text",

  "description": "Analyze a text-based mathematical concept and generate structured JSON specification",

  "inputSchema": {

    "type": "object",

    "properties": {

      "text_input": {

        "type": "string",

        "description": "Mathematical concept or problem description"

      },

      "api_key": {

        "type": "string",

        "description": "Optional Gemini API key (uses environment variable if not provided)"

      }

    },

    "required": ["text_input"]

  },

  "outputSchema": {

    "type": "string",

    "description": "JSON string containing MathSpec structure"

  }

}

```



### **Tool 2: analyze_concept_from_url**
```json

{

  "name": "analyze_concept_from_url",

  "description": "Analyze mathematical concept from URL and generate structured JSON specification",

  "inputSchema": {

    "type": "object",

    "properties": {

      "url_input": {

        "type": "string",

        "description": "URL to mathematical concept page or video"

      },

      "api_key": {

        "type": "string",

        "description": "Optional Gemini API key"

      }

    },

    "required": ["url_input"]

  }

}

```

### **Tool 3: analyze_concept_from_image**

```json

{

  "name": "analyze_concept_from_image",

  "description": "Analyze mathematical concept from image and generate structured JSON specification",

  "inputSchema": {

    "type": "object",

    "properties": {

      "image_input": {

        "type": "string",

        "description": "Base64-encoded image or file path"

      },

      "api_key": {

        "type": "string",

        "description": "Optional Gemini API key"

      }

    },

    "required": ["image_input"]

  }

}

```



### **Tool 4: generate_code_from_concept**
```json

{

  "name": "generate_code_from_concept",

  "description": "Generate interactive HTML/JS proof application from JSON concept specification",

  "inputSchema": {

    "type": "object",

    "properties": {

      "concept_json": {

        "type": "string",

        "description": "JSON string containing MathSpec (from analyze_concept_* tools)"

      },

      "api_key": {

        "type": "string",

        "description": "Optional Gemini API key"

      }

    },

    "required": ["concept_json"]

  },

  "outputSchema": {

    "type": "string",

    "description": "HTML string containing complete interactive proof application"

  }

}

```


## **13. Model Context Protocol (MCP) Integration**

StepWise Math functions as a complete **MCP Server**, exposing its capabilities to external AI agents and automation tools. This enables programmatic access to the visual proof generation pipeline.

### **13.1 MCP Tools**

The application exposes **4 primary MCP tools** organized in a two-step workflow:

#### **Step 1: Specification Creation Tools**
1. **`create_math_specification_from_text`**
   - Creates a structured teaching specification from natural language descriptions
   - Input: Text description of the math problem
   - Output: JSON specification with teaching steps
   - Processing time: ~10-15 seconds

2. **`create_math_specification_from_url`**
   - Creates a specification from web resources (Wikipedia, Khan Academy, etc.)
   - Input: URL pointing to math content
   - Output: JSON specification with teaching steps
   - Processing time: ~10-15 seconds

3. **`create_math_specification_from_image`**
   - Creates a specification from uploaded images (textbook problems, screenshots, handwritten notes)
   - Input: PIL Image object
   - Output: JSON specification with teaching steps
   - Processing time: ~10-15 seconds

#### **Step 2: Application Building Tool**
4. **`build_interactive_proof_from_specification`**
   - Builds a complete HTML/JavaScript application from a specification
   - Input: JSON specification from any Step 1 tool
   - Output: Self-contained HTML document
   - Processing time: ~20-30 seconds

### **13.2 MCP Prompts**

Pre-defined prompts guide agents on effective tool usage:

1. **`create_visual_math_proof`** - Complete workflow for creating visual proofs

2. **`create_math_specification`** - Focus on pedagogical design

3. **`build_from_specification`** - Focus on implementation with customization



### **13.3 MCP Resources**



The server provides helpful templates and examples:



| Resource URI                        | Description                           | Type     |

| ----------------------------------- | ------------------------------------- | -------- |

| `stepwise://specification-template` | JSON template for math specifications | JSON     |

| `stepwise://example-pythagorean`    | Complete Pythagorean theorem example  | JSON     |

| `stepwise://example-probability`    | Probability visualization example     | JSON     |

| `stepwise://workflow-guide`         | Two-step workflow documentation       | Markdown |



### **13.4 MCP Use Cases**



**For AI Agents:**

- Automatically generate visual proofs from student questions

- Create custom teaching materials on-demand

- Build interactive homework help applications



**For Automation:**

- Batch-process textbook problems into interactive visualizations

- Convert curriculum PDFs into step-by-step interactive lessons

- Generate proof variations for different learning styles



**For Integration:**

- Embed in learning management systems (LMS)

- Connect to homework platforms

- Integrate with educational chatbots



### **13.5 MCP Server Configuration**



The application launches with MCP server enabled:



```python

demo.launch(

    server_name="0.0.0.0",

    server_port=7860,

    mcp_server=True,  # Enable MCP protocol

    theme=theme,

    debug=True

)

```



**Access Points:**
- **Web UI:** `http://localhost:7860`
- **MCP Inspector:** Compatible with `@modelcontextprotocol/inspector`
- **API Endpoints:** Auto-generated for all 4 tools + resource endpoints