GGB Web MCP

GeoGebra MCP 服务器 - 通过 Model Context Protocol 让 AI 与 GeoGebra 数学可视化软件交互。

功能特性

• MCP 协议支持 - 完整的 Model Context Protocol 实现，支持 stdio 和 HTTP/SSE 两种传输方式
• 实时 Web 可视化 - 内置 Web 服务器，通过浏览器实时查看数学构造
• 丰富的数学工具 - 25+ GeoGebra 工具，涵盖几何、函数、代数运算
• 教育模板 - 预置教育场景模板，快速创建课堂演示
• 多实例协调 - 智能锁文件机制，多个 MCP 实例共享同一 Web 服务器

快速开始

1. 安装依赖

git clone git@github.com:kms9/ggb-web-mcp.git
cd ggb-web-mcp
npm install

2. 构建项目

npm run build

3. 启动服务

npm start

服务启动后：

• MCP 服务器: 通过 stdin/stdout 与 AI 客户端通信
• Web 可视化: 访问 http://localhost:3000 查看实时数学构造

配置 AI 客户端

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "geogebra": {
      "command": "node",
      "args": ["/path/to/ggb-web-mcp/dist/cli.js"]
    }
  }
}

Cursor IDE

在 Cursor 设置中添加 MCP 服务器配置：

{
  "mcp": {
    "servers": {
      "geogebra": {
        "command": "node",
        "args": ["/path/to/ggb-web-mcp/dist/cli.js"]
      }
    }
  }
}

CLI 命令

# 启动 MCP 服务器
npm start

# 开发模式（热重载）
npm run dev

# 查看帮助
node dist/cli.js --help

# 设置日志级别
node dist/cli.js --log-level debug

# 指定端口
node dist/cli.js --port 3001

命令行参数

参数	说明	默认值
-h, --help	显示帮助信息	-
-v, --version	显示版本号	-
--log-level	日志级别 (error, warn, info, debug)	info
--port	Web 服务器端口	3000

HTTP API 端点

Web 服务器提供以下 HTTP API：

MCP 端点

端点	方法	说明
/mcp/sse	GET	SSE 连接，接收服务器推送消息
/mcp/message	POST	发送 JSON-RPC 请求
/mcp/tools	GET	获取可用工具列表
/mcp/tools/:name	POST	执行指定工具
/mcp/info	GET	获取服务器信息

GeoGebra API

端点	方法	说明
/api/geogebra/state	GET	获取当前构造状态
/api/geogebra/clear	POST	清空当前构造
/api/geogebra/command	POST	执行 GeoGebra 命令

示例请求

# 获取工具列表
curl http://localhost:3000/mcp/tools

# 创建一个点
curl -X POST http://localhost:3000/mcp/tools/geogebra_create_point \
  -H "Content-Type: application/json" \
  -d '{"name": "A", "x": 1, "y": 2}'

# 执行 GeoGebra 命令
curl -X POST http://localhost:3000/api/geogebra/command \
  -H "Content-Type: application/json" \
  -d '{"command": "Circle(A, 3)"}'

可用工具

基础工具

工具名	说明
geogebra_eval_command	执行任意 GeoGebra 命令
geogebra_get_objects	获取所有对象信息
geogebra_clear_construction	清空当前构造
geogebra_export_png	导出 PNG 图片
geogebra_export_svg	导出 SVG 图片

几何工具

工具名	说明
geogebra_create_point	创建点
geogebra_create_line	创建直线（两点）
geogebra_create_line_equation	创建直线（方程）
geogebra_create_circle	创建圆
geogebra_create_polygon	创建多边形

函数工具

工具名	说明
geogebra_plot_function	绘制函数图像
geogebra_plot_parametric	绘制参数方程
geogebra_plot_implicit	绘制隐函数
geogebra_plot_inequality	绘制不等式区域

代数工具

工具名	说明
geogebra_solve_equation	求解方程
geogebra_solve_system	求解方程组
geogebra_simplify	化简表达式
geogebra_expand	展开表达式
geogebra_factor	因式分解
geogebra_derivative	求导数
geogebra_integral	求积分

动画工具

工具名	说明
geogebra_create_slider	创建滑块
geogebra_animate_slider	启动/停止动画
geogebra_set_animation_speed	设置动画速度

教育工具

工具名	说明
geogebra_list_educational_templates	列出教育模板
geogebra_create_from_template	从模板创建构造

环境配置

创建 .env 文件（可选）：

# 服务器配置
PORT=3000
LOG_LEVEL=info
NODE_ENV=development

# GeoGebra 配置
GEOGEBRA_APP_NAME=classic
GEOGEBRA_WIDTH=800
GEOGEBRA_HEIGHT=600
GEOGEBRA_HEADLESS=true

# 性能配置
INSTANCE_POOL_SIZE=2
RESPONSE_TIMEOUT=30000

配置说明

变量	说明	默认值
PORT	Web 服务器端口	3000
LOG_LEVEL	日志级别	info
GEOGEBRA_HEADLESS	无头模式（不显示浏览器窗口）	true
INSTANCE_POOL_SIZE	GeoGebra 实例池大小	2

开发指南

项目结构

ggb-web-mcp/
├── src/
│   ├── cli.ts              # CLI 入口
│   ├── index.ts            # 主入口
│   ├── server.ts           # MCP 服务器
│   ├── tools/              # 工具定义
│   │   ├── geogebra-tools.ts
│   │   ├── educational-templates.ts
│   │   └── performance-tools.ts
│   ├── types/              # 类型定义
│   ├── utils/              # 工具函数
│   └── web/                # Web 服务器
│       └── server.ts
├── tests/                  # 测试文件
├── examples/               # 使用示例
└── docs/                   # 文档

常用脚本

# 开发模式
npm run dev

# 构建
npm run build

# 运行测试
npm test

# 测试覆盖率
npm run test:coverage

# 代码检查
npm run lint

# 清理构建产物
npm run clean

添加新工具

1. 在 src/tools/geogebra-tools.ts 中定义工具：

{
  tool: {
    name: 'geogebra_my_tool',
    description: '工具描述',
    inputSchema: {
      type: 'object',
      properties: {
        param1: { type: 'string', description: '参数说明' }
      },
      required: ['param1']
    }
  },
  handler: async (params) => {
    // 实现逻辑
    return {
      content: [{ type: 'text', text: JSON.stringify(result) }]
    };
  }
}

2. 工具会自动注册到工具注册表中

系统要求

• Node.js >= 18.0.0
• npm 或 yarn

许可证

MIT License

相关链接

• Model Context Protocol
• GeoGebra
• GeoGebra Apps API