Content
# 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](https://jsxgraph.org/). 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
| Scenario | Command | Listen Port | Access Endpoint | Use Case |
|----------|---------|-------------|-----------------|----------|
| **STDIO (Default)** | `npx -y mcp-server-jsxgraph` | N/A | N/A | Desktop/IDE clients (Claude, Cursor, Cline) |
| **SSE (Local)** | `mcp-server-jsxgraph --transport sse` | 1122 | `http://localhost:1122/sse` | Web streaming applications |
| **Streamable (Local)** | `mcp-server-jsxgraph --transport streamable` | 1122 | `http://localhost:1122/mcp` | HTTP streaming clients |
| **Docker SSE** | `docker compose up -d` (sse service) | 1123 | `http://localhost:1123/sse` | Containerized SSE deployment |
| **Docker Streamable** | `docker compose up -d` (streamable service) | 1122 | `http://localhost:1122/mcp` | Containerized Streamable deployment |
### Minimal Working Configuration
**Desktop Clients (Claude Desktop, Cursor, Cline):**
```json
{
"mcpServers": {
"mcp-server-jsxgraph": {
"command": "npx",
"args": ["-y", "mcp-server-jsxgraph"]
}
}
}
```
**SSE Self-Test (Browser Verification):**
```bash
npx -y mcp-server-jsxgraph --transport sse --port 1122
# Open: http://localhost:1122/sse
```
## 📋 Table of Contents
- [✨ Features](#-features)
- [🏗️ System Architecture](#%EF%B8%8F-system-architecture)
- [🤖 Usage](#-usage)
- [🚰 Run with SSE or Streamable transport](#-run-with-sse-or-streamable-transport)
- [🎮 CLI Options](#-cli-options)
- [⚙️ Environment Variables](#%EF%B8%8F-environment-variables)
- [🔨 Development](#-development)
- [📄 License](#-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
```mermaid
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
| Transport | Use Case | Endpoint | Integration |
|-----------|----------|----------|-------------|
| **STDIO** | Desktop applications (Claude, VSCode, Cline, Cursor) | Standard I/O | Direct MCP client integration |
| **SSE** | Web streaming applications | `http://localhost:1122/sse` | Server-sent events |
| **HTTP Streamable** | Cloud deployment platforms | `http://localhost:1122/mcp` | HTTP streaming protocol |
#### 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
```mermaid
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:
```mermaid
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
| Category | Tools | Core Capabilities |
|----------|--------|------------------|
| **Function Analysis** | `generate_function_graph`<br/>`generate_function_transformation`<br/>`generate_function_properties` | Function graphs, transformations, comprehensive analysis with derivatives and integrals |
| **Polynomial Analysis** | `generate_polynomial_complete`<br/>`generate_polynomial_steps`<br/>`generate_quadratic_analysis` | Polynomial factorization, root finding, step-by-step analysis |
| **Geometry & Advanced** | `generate_geometry_diagram`<br/>`generate_parametric_curve`<br/>`generate_vector_field`<br/>`generate_conic_section` | Interactive geometry, parametric curves, vector field visualization |
| **Equation Systems** | `generate_linear_system`<br/>`generate_equation_system`<br/>`generate_exponential_logarithm`<br/>`generate_rational_function` | Linear/nonlinear systems, exponential and logarithmic functions |
| **Specialized Tools** | `generate_number_line_inequality` | Enhanced inequality visualization with interval notation |
### Technology Stack
```mermaid
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](https://cline.bot/mcp-marketplace), Cherry Studio, Cursor, use the standard STDIO configuration (see [Quick Reference](#-quick-reference) above).
**Cross-platform configuration (recommended):**
```json
{
"mcpServers": {
"mcp-server-jsxgraph": {
"command": "npx",
"args": ["-y", "mcp-server-jsxgraph"]
}
}
}
```
**Windows-specific (if npx doesn't work directly):**
```json
{
"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.
```bash
npm install -g mcp-server-jsxgraph
```
Run the server with your preferred transport option:
```bash
# 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.
```bash
cd docker
```
Deploy using docker-compose.
```bash
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`.
```plain
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
| Variable | Description | Default | Example |
|----------|:------------|---------|---------|
| `DISABLED_TOOLS` | Comma-separated list of tool names to disable | - | `generate_function_graph,generate_parametric_curve` |
### 🎛️ 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.
```json
{
"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:
```bash
npm install
```
Build the server:
```bash
npm run build
```
Start the MCP server:
```bash
npm run start
```
## 📄 License
MIT@[dxd214](https://github.com/dxd214).
