# Enhanced GeoGebra MCP

[English](README.md) | [简体中文](README.zh-CN.md)

Local stdio MCP server for a self-hosted GeoGebra Web bundle.

`enhanced-geogebra-mcp` wraps a modified GeoGebra 5.0 Web bundle under `geogebra/`. At runtime it starts a localhost-only static asset server, launches headless Chromium with Playwright, loads `public/harness.html`, obtains the GeoGebra JavaScript API through `GGBApplet.appletOnLoad`, and exposes a stdio MCP server.

## What Is Enhanced

The bundled applet is expected to expose `evalCommandResult(command)`, a modified API added to the GeoGebra runtime. `ggb_eval_command` uses that method directly.

Plain `evalCommand` only reports whether a command was accepted. `evalCommandResult` returns structured command feedback:

- `ok`: whether the command succeeded.
- `result`: command result text returned by the applet.
- `labels`: labels created by the command.
- `error`: command error text when execution fails.
- `objectCount`: construction object count after execution.
- `apiMethod`: the runtime method used by the server.

There is no fallback to `evalCommand`. If `evalCommandResult` is not present in the loaded bundle, command evaluation fails.

## Command Feedback Flow

```mermaid
flowchart LR
  A["Choose construction command"] --> B["ggb_query_commands<br/>GeoGebra 5.0 reference"]
  B --> C["ggb_eval_command<br/>call evalCommandResult"]
  C --> D{"Command feedback"}
  D -->|"ok"| E["Use labels/result"]
  D -->|"error"| F["Revise command"]
  F --> B
  E --> G["ggb_get_objects / ggb_export_image<br/>verify construction"]
```

## ReAct Comparison

The main difference is where command observation is produced. A conventional GeoGebra MCP wrapper built around `evalCommand` usually needs a follow-up inspection step to infer what changed. This package returns command-level observation from `ggb_eval_command` itself.

For LLM-driven construction loops, the practical advantages are:

- Command execution results add useful context immediately after each action.
- Failed commands return error text, giving the model a concrete correction signal and reducing unsupported guesses.

```mermaid
flowchart TD
  subgraph T["Conventional GeoGebra MCP"]
    direction LR
    T1["Thought<br/>choose command"] --> T2["Action<br/>evalCommand"]
    T2 --> T3["Limited feedback<br/>accepted / rejected"]
    T3 --> T4["Extra inspection<br/>objects / XML / image"]
    T4 --> T5["Infer result, labels, or error"]
  end

  T5 --> V["VS"]

  subgraph E["enhanced-geogebra-mcp"]
    direction LR
    E1["Thought<br/>choose command"] --> E2["Action<br/>ggb_eval_command"]
    E2 --> E3["Execution feedback<br/>ok + result + labels"]
    E3 --> E4["Error feedback<br/>concrete message on failure"]
    E4 --> E5["Revise command with more context"]
  end

  V --> E1
```

## GeoGebra 5.0 Scope

The bundled runtime is GeoGebra 5.0. Commands passed to `ggb_eval_command` should use GeoGebra 5.0 command names, syntax, and signatures. Use `ggb_query_commands` when command syntax is uncertain.

## Requirements

- Node.js 20 or newer.
- npm or npx.
- An MCP client that supports stdio servers.
- Chromium, either installed by Playwright or provided through an existing Chrome/Chromium executable.
- The modified GeoGebra 5.0 runtime that exposes `evalCommandResult`. The npm package includes this runtime under `geogebra/`.

## Distribution

This package is released under the MIT license and is intended for npm distribution as `enhanced-geogebra-mcp`.

This project is not affiliated with GeoGebra. The bundled runtime targets GeoGebra 5.0; command syntax, command reference data, and runtime behavior should stay aligned with that version.

## Security And Network

- The MCP server communicates over stdio.
- GeoGebra assets are served from a localhost-only static asset server.
- Browser execution is handled by Playwright and Chromium.
- Browser requests to non-local URLs are blocked by default.
- `--allow-external-network` explicitly allows non-local browser requests.
- Large state payloads can be returned as MCP resources when they exceed `--max-inline-chars`.

## Known Limitations

- Command syntax is scoped to GeoGebra 5.0.
- Commands should use English GeoGebra input-bar names.
- The server needs a working Chromium runtime.

## Versioning And Compatibility

- The npm package version tracks the MCP wrapper.
- The bundled GeoGebra runtime is currently GeoGebra 5.0.
- The bundled command reference is expected to match GeoGebra 5.0 syntax.
- Runtime or API changes that affect `evalCommandResult` should be documented in `CHANGELOG.md`.

## Install From npm

After the package is published to npm, it can be used directly with `npx`:

```bash
npx -y enhanced-geogebra-mcp --help
```

MCP client config example:

```json
{
  "mcpServers": {
    "enhanced-geogebra": {
      "command": "npx",
      "args": ["-y", "enhanced-geogebra-mcp"]
    }
  }
}
```

It can also be installed globally:

```bash
npm install -g enhanced-geogebra-mcp
enhanced-geogebra-mcp --help
```

Global install config example:

```json
{
  "mcpServers": {
    "enhanced-geogebra": {
      "command": "enhanced-geogebra-mcp",
      "args": []
    }
  }
}
```

The server uses Playwright to launch Chromium. If no compatible Chromium is available, install one:

```bash
npx playwright install chromium
```

Or point the server at an existing Chrome/Chromium executable with `GEOGEBRA_MCP_BROWSER_EXECUTABLE` or `--browser-executable-path`.

## Install From Source

```bash
npm install
npx playwright install chromium
npm run build
```

## Run As MCP Stdio Server

```bash
npm run build
node dist/index.js
```

Client config example:

```json
{
  "mcpServers": {
    "enhanced-geogebra": {
      "command": "node",
      "args": ["/absolute/path/to/enhanced-geogebra-mcp/dist/index.js"]
    }
  }
}
```

After packaging:

```bash
npm run pack:local
```

The package exposes an `enhanced-geogebra-mcp` binary.

## Tools

- `ggb_create_session`: create a headless GeoGebra applet session.
- `ggb_eval_command`: evaluate English GeoGebra input-bar commands through the bundled applet's
  `evalCommandResult` API. The payload includes `ok`, `result`, `labels`, `error`, `objectCount`, and `apiMethod`.
  This package expects that modified API to exist.
- `ggb_query_commands`: search the bundled GeoGebra command reference by name, syntax, examples, tags, or scope.
- `ggb_eval_cas`: evaluate a CAS expression.
- `ggb_get_objects`: list construction objects and compact metadata.
- `ggb_get_state`: return XML, base64 `.ggb`, or fileJSON state.
- `ggb_set_state`: load XML, base64 `.ggb`, or fileJSON state.
- `ggb_export_image`: export PNG, SVG, or screenshot.
- `ggb_set_view`: set common view options.
- `ggb_reset`: clear or reset the construction.
- `ggb_close_session`: close a browser-backed session.
- `ggb_list_sessions`: list active sessions.

## Options

```bash
enhanced-geogebra-mcp --help
```

Notable options:

- `--geogebra-root <path>`: use a different GeoGebra bundle root.
- `--asset-port <port>`: pin the internal localhost asset server port.
- `--browser-executable-path <path>`: use an existing Chrome/Chromium executable.
- `--allow-external-network`: allow the browser to load non-local URLs. Default is blocked.
- `--max-inline-chars <count>`: return larger payloads as MCP resources.

You can also set `GEOGEBRA_MCP_BROWSER_EXECUTABLE=/path/to/chrome-or-chromium` when Playwright's bundled Chromium is not installed.

## Smoke Checks

```bash
npm run smoke:harness
npm run smoke:mcp
```

`smoke:harness` tests the local asset server plus browser runtime directly. `smoke:mcp` builds the package, starts the stdio MCP server as a child process, and calls the core tools through an MCP client.