dxd214/mcp-server-jsxgraph

MCP Server JSXGraph

Latest Stable Version: 0.1.2 | NPM Package: mcp-server-jsxgraph

A Model Context Protocol server for generating mathematical visualizations using JSXGraph. This MCP server provides interactive mathematical chart generation capabilities for functions, geometry, parametric curves, and educational mathematics.

This is a TypeScript-based MCP server that provides mathematical visualization capabilities. It allows you to create various types of mathematical charts and diagrams through MCP tools, perfect for educational mathematics, engineering, and scientific applications.

🚀 Quick Reference

Transport & Connection Matrix

Minimal Working Configuration

Desktop Clients (Claude Desktop, Cursor, Cline):

{
  "mcpServers": {
    "mcp-server-jsxgraph": {
      "command": "npx",
      "args": ["-y", "mcp-server-jsxgraph"]
    }
  }
}

SSE Self-Test (Browser Verification):

npx -y mcp-server-jsxgraph --transport sse --port 1122
# Open: http://localhost:1122/sse

📋 Table of Contents

• ✨ Features
• 🏗️ System Architecture
• 🤖 Usage
• 🚰 Run with SSE or Streamable transport
• 🎮 CLI Options
• ⚙️ Environment Variables
• 🔨 Development
• 📄 License

✨ Features

13 mathematical visualization tools powered by JSXGraph for interactive mathematical graphics.

Mathematical Visualization Charts (JSXGraph)

1. generate_function_graph: Generate mathematical function graphs with support for derivatives, integrals, tangent lines, and multiple functions.
2. generate_parametric_curve: Generate parametric curves like circles, Lissajous curves, spirals, and cycloids with optional animated traces.
3. generate_geometry_diagram: Create interactive geometry diagrams with points, lines, circles, polygons, angles, and geometric constructions.
4. generate_vector_field: Visualize 2D vector fields with arrows, streamlines, singular points, and magnitude color coding.
5. generate_linear_system: Visualize systems of linear equations and inequalities with feasible regions and linear programming optimization.
6. generate_function_transformation: Show function transformations including translations, scaling, reflections, and compositions with animation.
7. generate_quadratic_analysis: Comprehensive quadratic function analysis with vertex, roots, axis of symmetry, focus, and directrix.
8. generate_exponential_logarithm: Plot exponential and logarithmic functions with asymptotes, growth/decay analysis, and inverse relationships.
9. generate_rational_function: Visualize rational and irrational functions with asymptotes, holes, domain restrictions, and critical points.
10. generate_equation_system: Solve and visualize linear and nonlinear equation systems with numerical solutions and phase portraits.
11. generate_conic_section: Generate conic sections (circles, ellipses, parabolas, hyperbolas) and high-degree polynomials with geometric properties.
12. generate_polynomial_steps: Interactive step-by-step polynomial analysis with roots, derivatives, and graphical representations.
13. generate_number_line_inequality: Visualize inequalities on number lines with support for simple inequalities (x > 2), compound inequalities (1 < x < 4), and multiple inequality systems with custom styling.

🏗️ System Architecture

The MCP Server JSXGraph follows a layered architecture with clear separation between protocol handling, mathematical analysis, and visualization rendering.

High-Level System Architecture

graph TB
    subgraph "Entry Layer"
        CLI["CLI Entry Point<br/>src/index.ts"]
        PKG["package.json<br/>Build Configuration"]
    end
    
    subgraph "MCP Protocol Layer"
        SERVER["MCP Server Core<br/>src/server.ts"]
        HANDLERS["Request Handlers<br/>ListToolsRequestSchema<br/>CallToolRequestSchema"]
    end
    
    subgraph "Transport Abstractions"
        STDIO["Desktop Integration<br/>startStdioMcpServer()"]
        SSE["Web Streaming<br/>startSSEMcpServer()"]
        HTTP["Cloud Deployment<br/>startHTTPStreamableServer()"]
    end
    
    subgraph "Tool Execution Framework"
        DISPATCHER["callTool()<br/>Request Dispatcher"]
        REGISTRY["Tool Registry<br/>jsxgraph/index.ts"]
        ENGINE["MathAnalysisEngine<br/>Mathematical Core"]
    end
    
    subgraph "Mathematical Tools"
        FUNC["Function Analysis Tools"]
        POLY["Polynomial Tools"] 
        GEO["Geometry Tools"]
        NUM["Number Line Tool"]
    end
    
    CLI --> SERVER
    PKG --> CLI
    SERVER --> HANDLERS
    HANDLERS --> STDIO
    HANDLERS --> SSE
    HANDLERS --> HTTP
    STDIO --> DISPATCHER
    SSE --> DISPATCHER
    HTTP --> DISPATCHER
    DISPATCHER --> REGISTRY
    DISPATCHER --> ENGINE
    REGISTRY --> FUNC
    REGISTRY --> POLY
    REGISTRY --> GEO
    REGISTRY --> NUM

Core Components

MCP Protocol Implementation

• Server Core: Implements Model Context Protocol through @modelcontextprotocol/sdk
• Request Handling: Supports ListToolsRequestSchema and CallToolRequestSchema
• Tool Discovery: Dynamic tool registration with environment-based filtering
• Error Management: Comprehensive error handling with MCP-compliant error codes

Transport Layer Support

Mathematical Analysis Engine

The MathAnalysisEngine provides sophisticated mathematical computation capabilities:

• Function Analysis: Domain, range, intercepts, extrema, asymptotes, monotonicity
• Polynomial Analysis: Root finding, factorization, end behavior analysis
• Inequality Solving: Simple, compound, absolute value, and logical inequalities
• Numerical Methods: Bisection method, numerical differentiation, interval calculations

MCP Protocol Communication Flow

sequenceDiagram
    participant Client as MCP Client
    participant Server as Server Instance
    participant Handler as CallToolRequestSchema Handler
    participant Dispatcher as callTool() Function
    participant Validator as Zod Schema Validation
    participant Engine as MathAnalysisEngine
    participant Generator as JSXGraph Code Generator
    
    Client->>Server: CallToolRequest
    Server->>Handler: request.params
    Handler->>Dispatcher: callTool(name, arguments)
    Dispatcher->>Validator: z.object(schema).safeParse(args)
    Validator-->>Dispatcher: Validation Result
    
    alt Valid Request
        Dispatcher->>Engine: Mathematical Analysis
        Engine-->>Dispatcher: Analysis Data
        Dispatcher->>Generator: generateJSXGraphCode(config)
        Generator-->>Dispatcher: JavaScript Code
        Dispatcher-->>Handler: Tool Response
        Handler-->>Server: Success Response
        Server-->>Client: JSXGraph Visualization
    else Invalid Request
        Dispatcher-->>Handler: McpError(ErrorCode.InvalidParams)
        Handler-->>Server: Error Response
        Server-->>Client: Error Message
    end

Tool Execution Framework

The system manages 15+ mathematical visualization tools through a unified execution framework:

graph LR
    subgraph "Tool Registry"
        CHARTS["Charts Object<br/>All Tool Definitions"]
        ENABLED["getEnabledTools()<br/>Environment Filtering"]
        DISABLED["getDisabledTools()<br/>Environment Variables"]
    end
    
    subgraph "Type System"
        MAP["CHART_TYPE_MAP<br/>Tool Name Mapping"]
        JSXSET["JSXGRAPH_CHARTS Set<br/>Type Validation"]
        CONFIG["JSXGraphConfig Interface<br/>Common Parameters"]
    end
    
    subgraph "Code Generation"
        CONTAINER["Dynamic Container IDs<br/>jxgbox_[type]_[timestamp]"]
        GENERATOR["generateJSXGraphCode()<br/>HTML Generation"]
        SPECIAL["Special Handling<br/>polynomial-steps<br/>number-line"]
    end
    
    CHARTS --> ENABLED
    ENABLED --> MAP
    MAP --> JSXSET
    JSXSET --> CONFIG
    CONFIG --> CONTAINER
    CONTAINER --> GENERATOR
    GENERATOR --> SPECIAL

Mathematical Tool Categories

Technology Stack

graph TD
    subgraph "Core Framework"
        TS["TypeScript"]
        NODE["Node.js Runtime"]
    end
    
    subgraph "MCP Integration"
        SDK["@modelcontextprotocol/sdk"]
        PROTO["MCP Protocol Implementation"]
    end
    
    subgraph "Mathematical Libraries"
        JSX["JSXGraph"]
        ZOD["Zod Schema Validation"]
        MATH["Mathematical Analysis Engine"]
    end
    
    subgraph "Development Tools"
        VITEST["Vitest Testing Framework"]
        BIOME["Biome Linting & Formatting"]
        BUILD["TypeScript Build System"]
    end
    
    TS --> NODE
    SDK --> PROTO
    JSX --> MATH
    ZOD --> MATH
    VITEST --> BUILD
    BIOME --> BUILD
    
    NODE --> SDK
    PROTO --> JSX
    MATH --> VITEST

🤖 Usage

Desktop Applications

For desktop MCP clients like Claude Desktop, VSCode, Cline, Cherry Studio, Cursor, use the standard STDIO configuration (see Quick Reference above).

Cross-platform configuration (recommended):

{
  "mcpServers": {
    "mcp-server-jsxgraph": {
      "command": "npx",
      "args": ["-y", "mcp-server-jsxgraph"]
    }
  }
}

Windows-specific (if npx doesn't work directly):

{
  "mcpServers": {
    "mcp-server-jsxgraph": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mcp-server-jsxgraph"]
    }
  }
}

🚰 Run with SSE or Streamable transport

Run directly

Install the package globally.

npm install -g mcp-server-jsxgraph

Run the server with your preferred transport option:

# For SSE transport (default endpoint: /sse)
mcp-server-jsxgraph --transport sse

# For Streamable transport with custom endpoint
mcp-server-jsxgraph --transport streamable

Then you can access the server at:

• SSE transport: http://localhost:1122/sse
• Streamable transport: http://localhost:1122/mcp

Docker deploy

Enter the docker directory.

cd docker

Deploy using docker-compose.

docker compose up -d

Then you can access the server at:

• SSE transport: http://localhost:1123/sse
• Streamable transport: http://localhost:1122/mcp

🎮 CLI Options

You can also use the following CLI options when running the MCP server. Command options by run cli with -h.

MCP Server JSXGraph CLI

Options:
  --transport, -t  Specify the transport protocol: "stdio", "sse", or "streamable" (default: "stdio")
  --port, -p       Specify the port for SSE or streamable transport (default: 1122)
  --endpoint, -e   Specify the endpoint for the transport:
                   - For SSE: default is "/sse"
                   - For streamable: default is "/mcp"
  --help, -h       Show this help message

⚙️ Environment Variables

🎛️ Tool Filtering

You can disable specific mathematical visualization tools using the DISABLED_TOOLS environment variable. This is useful when certain tools have compatibility issues with your MCP client or when you want to limit the available functionality.

{
  "mcpServers": {
    "mcp-server-jsxgraph": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-jsxgraph"
      ],
      "env": {
        "DISABLED_TOOLS": "generate_function_graph,generate_parametric_curve"
      }
    }
  }
}

Available tool names for filtering:

• generate_function_graph
• generate_parametric_curve
• generate_geometry_diagram
• generate_vector_field
• generate_linear_system
• generate_function_transformation
• generate_quadratic_analysis
• generate_exponential_logarithm
• generate_rational_function
• generate_equation_system
• generate_conic_section
• generate_polynomial_steps

🔒 Compatibility & Stability Promise

Never Break Userspace Commitment:

• Published CLI parameters and default behavior will remain stable across minor versions
• Existing transport endpoints (/sse, /mcp) will not change
• Package name mcp-server-jsxgraph will remain consistent
• New features will use new flags/endpoints, leaving existing behavior intact
• Deprecation warnings will provide 2-3 minor version transition periods before removal

Current Stable APIs:

• NPM Package: mcp-server-jsxgraph@0.1.2
• CLI Arguments: --transport, --port, --endpoint
• STDIO Transport: Default behavior for desktop clients
• SSE Endpoint: /sse on specified port
• Streamable Endpoint: /mcp on specified port
• Environment Variables: DISABLED_TOOLS

🔨 Development

Install dependencies:

npm install

Build the server:

npm run build

Start the MCP server:

npm run start

📄 License

MIT@dxd214.