Support implicit equations, live MCP sessions, and additive graph editing

.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: Checks
+on: [push, pull_request]
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm test
+      - run: npm run test:mcp
+      - run: npm run lint
+      - run: npm run build

AGENTS.md

@@ -1,70 +1,61 @@
-# Graphly Agent Instructions & MCP Tool Specification
+# Graphly agent integration
 
-Welcome, AI Assistant! If you have been provided this repository, you have been invited to interface with **Graphly**, a high-performance 2D & 3D mathematical plotter, calculus evaluator, and data visualization suite.
+Graphly plots 2D curves, 3D surfaces, and tabular data. Prefer the local MCP tools for an ongoing graphing conversation; preserve existing layers unless the user asks to edit or remove them.
 
----
+## Start the MCP server
 
-## 1. Quick MCP Server Installation & Launch
+Run `node /absolute/path/to/Graphly/mcp-server/index.js` over stdio with Node.js 20 or later. The MCP package has no dependencies.
 
-Graphly includes a built-in Model Context Protocol (MCP) server ready to execute over `stdio`.
+Set `GRAPHLY_BASE_URL` to the frontend running this revision. During development, run `npm run dev -- --host 127.0.0.1` from the repository and use `http://127.0.0.1:5173` (match the actual port). The default is `https://graphly.netlify.app`; live sessions and implicit surfaces require deploying the updated frontend first.
 
-### Local Execution Command
-```bash
-node mcp-server/index.js
-```
-
-### Automatic Configuration for Claude Desktop, Cursor, and IDEs
-To register Graphly with your client's MCP configuration (`claude_desktop_config.json`, `.cursor/mcp.json`, or `mcp_config.json`):
+Example client configuration:
 
 ```json
 {
   "mcpServers": {
     "graphly": {
       "command": "node",
-      "args": ["<PATH_TO_GRAPHLY_REPOSITORY>/mcp-server/index.js"],
-      "env": {
-        "GRAPHLY_BASE_URL": "https://graphly.netlify.app"
-      }
+      "args": ["/absolute/path/to/Graphly/mcp-server/index.js"],
+      "env": { "GRAPHLY_BASE_URL": "http://127.0.0.1:5173" }
     }
   }
 }
 ```
 
----
+## Live tools and workflow
+
+- `create_graph`: create a graph with `dimension: "2d"` or `"3d"` and optional `title`. Retain the returned graph ID and open its live URL once.
+- `upsert_expression`: send `graph_id` and `equation`. **Omit `expression_id` to append a new layer.** Reuse an existing ID only when intentionally editing that layer. Optional `visible` and six-digit hex `color` control display.
+- `get_graph`: inspect current server state, including stable expression IDs and revision.
+- `remove_expression`: remove only the specified `expression_id` from `graph_id`.
+- `set_view`: set `bounds` with ordered finite `xMin`, `xMax`, `yMin`, `yMax`, optional `zMin`, `zMax`; or set `camera` with `position` and `target` triples in mathematical x/y/z coordinates.
+- `export_graph`: return a standalone snapshot link containing every expression, title, and view. It contains no live capability token and survives MCP process restarts.
+
+Use dimension from the user's context. After discussing 3D surfaces, interpret an ambiguous shape in that context or clarify briefly. A 2D ellipse and a 3D ellipsoid are different objects.
+
+## Equations
+
+The updated 3D renderer accepts implicit equations directly:
 
-## 2. Tools Available to the Agent
+- Sphere: `x^2+y^2+z^2=9`
+- Ellipsoid: `x^2/9+y^2/4+z^2=1`
+- Vertical cylinder: `x^2+y^2=9` in a 3D graph
+- Paraboloid: `z=x^2+y^2`
+- Saddle (hyperbolic paraboloid): `z=(x^2-y^2)/4`
+- One-sheet hyperboloid: `x^2+y^2-z^2=1`
 
-When connected via MCP or when operating Graphly directly, use the following tools:
+Do not split spheres or ellipsoids into positive and negative square-root surfaces. Use full equations. Numerical extraction has finite resolution; singularities and very small features can require tighter bounds. Do not promise arbitrary equations render perfectly.
 
-### Tool A: `plot_function`
-Plots an explicit 2D mathematical curve $y = f(x)$.
-- **`expression`** *(string, required)*: The mathematical formula in terms of $x$ (e.g. `'sin(x)'`, `'x^2 - 4'`, `'1/x'`).
-- **`xMin` / `xMax`** *(number, optional)*: Explicit viewport bounds.
+## Legacy tools
 
-### Tool B: `plot_3d_surface`
-Renders an interactive 3D surface $z = f(x, y)$ with orbit controls and coordinate axes.
-- **`expression`** *(string, required)*: Formula in terms of $x$ and $y$ (e.g. `'(x^2 - y^2)/4'` for hyperboloid/saddle, `'(x^2 + y^2)/6'` for paraboloid, `'sin(x)*cos(y)'` for ripple).
+`plot_function` accepts an explicit 2D expression and optional paired `xMin`/`xMax`. `plot_3d_surface` accepts a 3D expression or full implicit equation with the updated viewer. `plot_data_table` accepts optional `name` and `rows: [{x: 1, y: 2}]` with finite numbers. These tools produce one-plot share links; use live tools for incremental multi-expression work.
 
-### Tool C: `plot_data_table`
-Plots tabular coordinates with scatter nodes and automatic regression trendlines.
-- **`name`** *(string)*: Name of dataset.
-- **`rows`** *(array of {x, y})*: Numeric data points.
+## Verification and session limits
 
----
+The server reports **accepted**, meaning it stored state; this does not verify rendering. Inspect the viewer before claiming a graph is displayed correctly. Report expression errors honestly. Never claim to have opened a viewer or changed a browser tab without doing so.
 
-## 3. Remote Web Integration (ChatGPT Actions & Claude Web)
+Live sessions use a loopback SSE bridge with an Origin check and capability token. They exist only for the MCP process lifetime, on the same computer as the viewer. Browser local-network restrictions may require local viewing. Keep live URLs private. Exported URLs contain graph data readable by anyone with the link.
 
-If you are operating in a web-only environment (e.g. ChatGPT Actions, Claude Web, or Custom GPT):
+The bridge currently sends server state to the viewer, not manual viewer edits back to the server. Later tool updates restore session-owned layers while preserving other user layers. Inline MCP Apps support depends on the host and is not implemented by this bridge. This server does not host or publish the frontend.
 
-1. **OpenAPI Schema**: Read and register `https://graphly.netlify.app/openapi.json`.
-2. **AI Plugin Manifest**: `https://graphly.netlify.app/.well-known/ai-plugin.json`.
-3. **Endpoint**: Call `POST https://graphly.netlify.app/api/plot` with:
-   ```json
-   {
-     "mode": "3d",
-     "expression": "(x^2 - y^2) / 4",
-     "name": "Hyperbolic Paraboloid"
-   }
-   ```
-4. Output the returned `url` to the user as a clickable markdown badge:
-   `[Open in Graphly](https://graphly.netlify.app/?state=...)`
+See `mcp-server/README.md` for setup details. Run `npm test --prefix mcp-server` with loopback networking permitted to verify protocol, session, bridge, and export behavior.

README.md

@@ -19,23 +19,19 @@ It features an **AI-powered scanner** that turns images of data tables into edit
 
 ---
 
-## **🤖 Connect to AI Assistants (Claude, ChatGPT, Cursor)**
+## Connect AI assistants
 
-Graphly comes with a built-in **Model Context Protocol (MCP)** server and **OpenAPI Action** specifications, allowing AI models to plot mathematical graphs and 3D surfaces directly.
+The local Node.js MCP server supports live graph sessions: create a graph once, then append or edit individual equations in the same browser tab. See [MCP setup and tools](mcp-server/README.md) and the optional [Codex / Claude Code skill plugin](integrations/graphly/README.md).
 
-### One-Prompt Setup for Any AI Coding Agent
-Simply prompt your AI assistant (Cursor, Antigravity, Claude Code, or Copilot):
-> *"Read https://github.com/Tajwarbot/Graphly/blob/main/AGENTS.md and configure the Graphly MCP server for my environment."*
+Run the updated frontend locally before using the new tools; the hosted website needs this build deployed before it can render live sessions. Client configuration and inline viewer support vary. The existing OpenAPI endpoint and legacy plot tools generate standalone links.
 
-The AI will automatically inspect the repository, register the `plot_function`, `plot_3d_surface`, and `plot_data_table` tools, and configure your local settings.
+## Equation support and current limits
 
-### ChatGPT Web (Custom GPT Action)
-1. Go to **ChatGPT** → **My GPTs** → **Create a GPT** → **Configure** → **Actions**.
-2. Click **Import from URL** and paste:
-   ```
-   https://graphly.netlify.app/openapi.json
-   ```
-3. Save. ChatGPT can now natively generate live Graphly 2D curves, 3D quadric surfaces, and scatter trendlines.
+Enter full equations such as `x^2/9+y^2/4=1` in 2D or `x^2/9+y^2/4+z^2=1` in 3D. Explicit surfaces such as `z=x^2+y^2` also work. New assistant plots append layers; targeted edits use layer IDs. Draft layers are restored from this browser's local storage.
+
+Implicit surfaces are sampled in a finite domain on a background worker. This is a numerical renderer, not a symbolic solver: very small features, isolated points, and equations without sign changes can be missed. Inequalities and parametric surfaces are not supported by this path. Live MCP state lasts for the server process; export a snapshot to retain all equations and view settings. Browser edits are currently one-way and do not update MCP state.
+
+Run `npm test`, `npm run test:mcp`, `npm run lint`, and `npm run build` to validate changes. MCP tests require loopback networking.
 
 ---
 
@@ -69,7 +65,7 @@ Follow these instructions to run the project locally.
      ```env
      VITE_GEMINI_API_KEY=your_actual_api_key_here
      ```
-   * **Note:** This is only for local convenience. The app now supports entering your key directly in the UI, which is saved securely in your browser's Local Storage.
+   * **Note:** This is only for local convenience. The app now supports entering your key directly in the UI, which is saved in your browser's Local Storage.
 
 4. **Run the development server:**
    ```bash

eslint.config.js

@@ -6,6 +6,7 @@ import { defineConfig, globalIgnores } from 'eslint/config'
 
 export default defineConfig([
   globalIgnores(['dist']),
+  { files: ['mcp-server/**/*.js', 'api/**/*.js', 'netlify/**/*.js'], languageOptions: { globals: globals.node } },
   {
     files: ['**/*.{js,jsx}'],
     extends: [

integrations/graphly/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "graphly",
+  "version": "1.1.0",
+  "description": "Graphly plotting workflow for local MCP sessions.",
+  "author": {
+    "name": "Tajwarbot"
+  },
+  "repository": "https://github.com/Tajwarbot/Graphly"
+}

integrations/graphly/.codex-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "graphly",
+  "version": "1.1.0",
+  "description": "Graphly plotting workflow for local MCP sessions.",
+  "author": {
+    "name": "Tajwarbot"
+  },
+  "repository": "https://github.com/Tajwarbot/Graphly",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Graphly",
+    "shortDescription": "Plot and refine equations in a live Graphly viewer.",
+    "developerName": "Tajwarbot",
+    "category": "Productivity",
+    "longDescription": "Create and refine mathematical plots with Graphly local MCP sessions and a browser viewer.",
+    "defaultPrompt": "Use Graphly to plot and refine my equations.",
+    "capabilities": [
+      "Interactive"
+    ]
+  }
+}

integrations/graphly/README.md

@@ -0,0 +1,7 @@
+# Graphly agent integration
+
+This plugin supplies a plotting skill for Codex and Claude Code. Register the local MCP server separately using [the setup and live-session guide](../../mcp-server/README.md). It intentionally contains no machine-specific executable paths or automatic config writes.
+
+For Claude Code, load this directory with `claude --plugin-dir /absolute/path/to/Graphly/integrations/graphly`. For Codex, install this plugin directory through your supported local-plugin workflow, or copy `skills/graphly` into your personal skills directory. Restart the client after registering MCP tools.
+
+The repository includes both `.codex-plugin/plugin.json` and `.claude-plugin/plugin.json`. A plugin skill alone does not start the viewer or server. Run the updated local frontend and configure `GRAPHLY_BASE_URL` as described in the server guide before testing live sessions.

integrations/graphly/skills/graphly/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: graphly
+description: Plot, compare, and refine mathematical equations with the Graphly MCP server and its live browser viewer. Use when the user requests Graphly plotting or edits to an existing Graphly graph.
+---
+
+Use the connected Graphly MCP tools. If unavailable, explain that the local MCP server must be registered using the repository's mcp-server/README.md; this skill does not install or start it.
+
+For a new workspace, call create_graph with the appropriate dimension and open its returned viewer URL once. Retain graph_id for follow-up requests. New plots append through upsert_expression without expression_id. Intentional edits reuse the exact expression_id from get_graph; removals use remove_expression. Preserve unrelated layers. Clarify only when the target of an edit is ambiguous.
+
+Pass equations directly: an ellipse is 2D (x^2/9+y^2/4=1), an ellipsoid is 3D (x^2/9+y^2/4+z^2=1), and a paraboloid can be z=x^2+y^2. Do not split closed surfaces into square-root halves. Use set_view for finite increasing bounds or a 3D camera.
+
+Tool acceptance confirms stored state, not successful rendering. Inspect the viewer before claiming visual verification; report any displayed evaluation errors. Implicit rendering samples a finite domain and may miss small features or zero sets without sign changes.
+
+Use export_graph for a durable, multi-expression snapshot link. Live sessions last only while their local MCP process runs. Keep capability-bearing live links private. Manual edits in the viewer are not synchronized back to the server and can be replaced by subsequent server revisions; use MCP edits for session-managed layers.
+
+Legacy plot_function, plot_3d_surface, and plot_data_table return standalone links. Prefer a live session for iterative equation work. Host inline-view support varies; do not promise an embedded graph when the client only supports browser links.