Enhanced GeoGebra MCP

English | 简体中文

面向本地 GeoGebra Web bundle 的 stdio MCP server。

enhanced-geogebra-mcp 封装了 geogebra/ 目录下的魔改版 GeoGebra 5.0 Web 运行时。启动后，它会在本机开启一个仅 localhost 可访问的静态资源服务，通过 Playwright 启动 headless Chromium，加载 public/harness.html，再通过 GGBApplet.appletOnLoad 获取 GeoGebra JavaScript API，并对外提供 stdio MCP server。

Enhanced 在哪里

这个包依赖魔改运行时暴露的 evalCommandResult(command) 方法。ggb_eval_command 会直接调用这个方法。

普通 evalCommand 只能返回命令是否被接受。evalCommandResult 会返回结构化的命令执行反馈：

• ok：命令是否执行成功。
• result：运行时返回的命令结果文本。
• labels：命令创建出的对象标签。
• error：执行失败时的错误文本。
• objectCount：执行后的构造对象数量。
• apiMethod：server 实际调用的运行时方法。

这里不做 evalCommand fallback。如果加载的 GeoGebra bundle 没有 evalCommandResult，命令执行会直接失败。

命令反馈流程

flowchart LR
  A["选择构造命令"] --> B["ggb_query_commands<br/>查询 GeoGebra 5.0 命令参考"]
  B --> C["ggb_eval_command<br/>调用 evalCommandResult"]
  C --> D{"命令反馈"}
  D -->|"ok"| E["使用 labels/result"]
  D -->|"error"| F["修正命令"]
  F --> B
  E --> G["ggb_get_objects / ggb_export_image<br/>验证构造结果"]

ReAct 对比

差异主要在 observation 从哪里产生。基于普通 evalCommand 的 GeoGebra MCP wrapper 通常需要在执行命令后再检查对象、XML 或图像，然后推断命令实际造成了什么变化。本项目通过 ggb_eval_command 在 action 返回里直接给出命令级反馈。

对 LLM 驱动的构造循环来说，优势主要有两点：

• 反馈命令执行结果，为 LLM 补充更多有价值的上下文。
• 出错时返回错误提示，给模型明确的修正信号，有效抑制幻觉式补救。

flowchart TD
  subgraph T["普通 GeoGebra MCP"]
    direction LR
    T1["Thought<br/>选择命令"] --> T2["Action<br/>evalCommand"]
    T2 --> T3["有限反馈<br/>accepted / rejected"]
    T3 --> T4["额外检查<br/>objects / XML / image"]
    T4 --> T5["推断 labels、result 或 error"]
  end

  T5 --> V["VS"]

  subgraph E["enhanced-geogebra-mcp"]
    direction LR
    E1["Thought<br/>选择命令"] --> E2["Action<br/>ggb_eval_command"]
    E2 --> E3["执行结果反馈<br/>ok + result + labels"]
    E3 --> E4["错误反馈<br/>失败时返回明确提示"]
    E4 --> E5["带着更多上下文修正命令"]
  end

  V --> E1

GeoGebra 5.0 范围

当前 bundle 是 GeoGebra 5.0。传给 ggb_eval_command 的命令应该使用 GeoGebra 5.0 的命令名、语法和参数形式。命令不确定时，先用 ggb_query_commands 查询本地命令参考。

运行要求

• Node.js 20 或更新版本。
• npm 或 npx。
• 支持 stdio server 的 MCP 客户端。
• Chromium，可以由 Playwright 安装，也可以指向已有 Chrome/Chromium 可执行文件。
• 暴露 evalCommandResult 的魔改版 GeoGebra 5.0 运行时。npm package 会在 geogebra/ 下包含这份运行时。

分发说明

这个包使用 MIT license，目标是以 enhanced-geogebra-mcp 发布到 npm。

本项目不隶属于 GeoGebra。当前 bundle 针对 GeoGebra 5.0；命令语法、命令参考数据和运行时行为都应该与 GeoGebra 5.0 保持一致。

安全和网络边界

• MCP server 通过 stdio 通信。
• GeoGebra assets 通过仅 localhost 可访问的静态资源服务提供。
• 浏览器执行由 Playwright 和 Chromium 负责。
• 默认阻止浏览器访问非本地 URL。
• --allow-external-network 会显式放开浏览器的非本地网络请求。
• 超过 --max-inline-chars 的大状态内容会作为 MCP resource 返回。

已知限制

• 命令语法限定在 GeoGebra 5.0。
• 命令应该使用英文 GeoGebra input-bar command name。
• server 需要可用的 Chromium 运行时。

版本和兼容性

• npm package version 跟随 MCP wrapper。
• 当前内置 GeoGebra runtime 是 GeoGebra 5.0。
• 内置命令参考应该匹配 GeoGebra 5.0 语法。
• 如果运行时或 evalCommandResult API 发生兼容性变化，需要记录到 CHANGELOG.md。

从 npm 安装

发布到 npm 后，可以直接通过 npx 使用：

npx -y enhanced-geogebra-mcp --help

MCP 客户端配置示例：

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

也可以全局安装：

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

全局安装后的配置示例：

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

server 使用 Playwright 启动 Chromium。如果当前机器没有可用的 Chromium，可以安装：

npx playwright install chromium

也可以通过 GEOGEBRA_MCP_BROWSER_EXECUTABLE 或 --browser-executable-path 指向已有的 Chrome/Chromium 可执行文件。

从源码安装

npm install
npx playwright install chromium
npm run build

作为 MCP Stdio Server 运行

npm run build
node dist/index.js

客户端配置示例：

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

本地打包：

npm run pack:local

打包后会提供 enhanced-geogebra-mcp binary。

工具

• ggb_create_session：创建一个 headless GeoGebra applet session。
• ggb_eval_command：通过 evalCommandResult 执行英文 GeoGebra input-bar command，并返回 ok、result、labels、error、objectCount 和 apiMethod。
• ggb_query_commands：按命令名、语法、示例、标签或 scope 查询内置 GeoGebra 命令参考。
• ggb_eval_cas：执行 CAS 表达式。
• ggb_get_objects：列出构造对象及其紧凑元数据。
• ggb_get_state：返回 XML、base64 .ggb 或 fileJSON 状态。
• ggb_set_state：加载 XML、base64 .ggb 或 fileJSON 状态。
• ggb_export_image：导出 PNG、SVG 或 screenshot。
• ggb_set_view：设置常用视图选项。
• ggb_reset：清空或重置构造。
• ggb_close_session：关闭一个 browser-backed session。
• ggb_list_sessions：列出当前 active sessions。

选项

enhanced-geogebra-mcp --help

常用选项：

• --geogebra-root <path>：使用其他 GeoGebra bundle 根目录。
• --asset-port <port>：指定内部 localhost 静态资源服务端口。
• --browser-executable-path <path>：使用已有 Chrome/Chromium 可执行文件。
• --allow-external-network：允许浏览器加载非本地 URL。默认阻止。
• --max-inline-chars <count>：较大的返回内容会作为 MCP resource 返回。

如果没有安装 Playwright 自带的 Chromium，也可以设置：

GEOGEBRA_MCP_BROWSER_EXECUTABLE=/path/to/chrome-or-chromium

Smoke Checks

npm run smoke:harness
npm run smoke:mcp

smoke:harness 直接测试本地静态资源服务和浏览器运行时。smoke:mcp 会构建包、以子进程启动 stdio MCP server，并通过 MCP client 调用核心工具。