# GGB Web MCP

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

## 功能特性

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

## 快速开始

### 1. 安装依赖

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

### 2. 构建项目

```bash
npm run build
```

### 3. 启动服务

```bash
npm start
```

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

## 配置 AI 客户端

### Claude Desktop

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

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

### Cursor IDE

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

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

## CLI 命令

```bash
# 启动 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 命令 |

### 示例请求

```bash
# 获取工具列表
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` 文件（可选）：

```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/                   # 文档
```

### 常用脚本

```bash
# 开发模式
npm run dev

# 构建
npm run build

# 运行测试
npm test

# 测试覆盖率
npm run test:coverage

# 代码检查
npm run lint

# 清理构建产物
npm run clean
```

### 添加新工具

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

```typescript
{
  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](https://modelcontextprotocol.io/)
- [GeoGebra](https://www.geogebra.org/)
- [GeoGebra Apps API](https://geogebra.github.io/docs/reference/en/GeoGebra_Apps_API/)