使用说明

快速板配对MVP

这是一个 最小测试项目 这展示了MVP的核心思想：

教师提示→ 结构化的 MatchPairsActivity JSON → 简化的Excalidraw场景JSON。

该项目是用 TypeScript （Node.js），并且故意简单，所以你可以：

了解数据模型(MatchPairsActivity)
查看后端服务如何生成 交互式逻辑JSON
了解如何将JSON转换为 白板场景 代表
使用 MCP工具 AI代理（Cursor/Claude集成）

📚 快速链接

DOCS_INDEX.md -完整文档索引
MCP_TOOLS_REFERNCE.md -MCP工具参考
MCP_LOGGING.md -日志记录指南
示例/ -示例活动

1.项目结构

promptboard-mcp-mvp/
  ├─ src/
  │   ├─ main.ts                # Simple HTTP server exposing two endpoints
  │   ├─ types.ts               # TypeScript interfaces (MatchPairsActivity, etc.)
  │   ├─ designer.ts            # Prompt-ish input → MatchPairsActivity JSON
  │   ├─ renderer.ts            # MatchPairsActivity → simplified Excalidraw scene
  │   ├─ mcp-server.ts          # MCP server for Cursor/Claude integration
  │   └─ schemas.ts             # JSON schemas for MCP tools
  ├─ examples/                  # Example activities (see examples/README.md)
  │   ├─ 01-g3-english-animals/
  │   ├─ 02-g3-math-addition/
  │   ├─ 03-g5-english-plants/
  │   └─ 04-g4-science-weather/
  ├─ package.json
  ├─ tsconfig.json
  ├─ mcp-activity.log           # MCP server activity log (auto-generated)
  ├─ .cursorrules               # AI agent rules for understanding MCP features
  ├─ DOCS_INDEX.md              # Documentation index
  ├─ MCP_SETUP.md               # MCP server setup guide
  ├─ MCP_TOOLS_REFERENCE.md     # Complete MCP tools reference
  ├─ MCP_LOGGING.md             # Logging guide
  └─ README.md

2.安装并运行

2.1安装依赖项

npm install

2.2在开发模式下运行（使用ts节点）

npx ts-node src/main.ts

服务器将继续监听 http://localhost:3000.

3.API终点

3.1 `POST /api/design-match-pairs`

目的：
将教师友好的JSON输入（您可以将其视为结构化提示）转换为 MatchPairsActivity JSON格式 交互逻辑.

请求正文示例：

{
  "grade": "G3",
  "subject": "English",
  "topic": "clothes",
  "instructions": "Please connect the English words on the left to the correct Chinese words on the right.",
  "pairs": [
    { "left": "shirt", "right": "上衣" },
    { "left": "pants", "right": "褲子" },
    { "left": "hat", "right": "帽子" },
    { "left": "shoes", "right": "鞋子" }
  ]
}

服务器做什么：

生成：
- activityId, activityKey, eventPrefix
- 对于每对：
  - pairId （例如。 "pair_1")
  - itemId 左/右（例如。 "L1", "R1")
  - 默认 score （各得1分）
- 默认布局（列、行、位置）

响应示例（缩短）：

{
  "activityId": "act_8f3e3c99",
  "type": "match_pairs",
  "locale": "zh-TW",
  "grade": "G3",
  "subject": "English",
  "topic": "clothes",
  "instructions": "Please connect the English words on the left to the correct Chinese words on the right.",
  "pairs": [
    {
      "pairId": "pair_1",
      "score": 1,
      "left": { "itemId": "L1", "text": "shirt" },
      "right": { "itemId": "R1", "text": "上衣" }
    }
    // ...
  ],
  "layout": {
    "columns": 2,
    "rows": 4,
    "leftColumnX": 100,
    "rightColumnX": 500,
    "rowStartY": 100,
    "rowGap": 120
  },
  "tracking": {
    "activityKey": "eng_G3_clothes_match_pairs",
    "version": 1,
    "eventPrefix": "act_8f3e3c99_match_"
  }
}

这个JSON是“交互式逻辑层”：稍后，在Web/App端，您可以将这些ID用于：学生响应跟踪、评分和版本控制。

3.2 `POST /api/render-excalidraw`

目的：
拿一个 MatchPairsActivity JSON并将其转换为 简化的Excalidraw式场景.

输入：
完整的 MatchPairsActivity JSON（例如，来自上一个端点）。

输出：
一个JSON对象，表示Excalidraw样式的场景，具有：

elements：左/右项目的矩形+文本元素
每个元素包含 customData.csInteractive 其嵌入：
- activityId
- activityType
- itemId
- pairId
- role (left / right)
- eventKey

示例（缩短）：

{
  "type": "excalidraw",
  "version": 1,
  "source": "promptboard-mvp",
  "elements": [
    {
      "id": "rect_L1",
      "type": "rectangle",
      "x": 100,
      "y": 100,
      "width": 180,
      "height": 60,
      "customData": {
        "csInteractive": {
          "activityId": "act_8f3e3c99",
          "activityType": "match_pairs",
          "itemId": "L1",
          "pairId": "pair_1",
          "role": "left",
          "eventKey": "act_8f3e3c99_match_pair_1"
        }
      }
    },
    {
      "id": "text_L1",
      "type": "text",
      "x": 110,
      "y": 120,
      "text": "shirt"
    }
  ]
}

这一层是“白板视觉层”：

您的Web白板可以直接读取此JSON来绘制方框。

当学生在白板上划线时， customData.csInteractive 可用于映射到特定的问题/选项。

4.技术亮点

4.1类型(`src/types.ts`)

这定义了：

MatchPairsActivity：整个活动的根对象。
MatchPair / MatchItem：每个匹配的配对和左/右选项。
MatchPairsLayout：白板布局建议。
TrackingMeta：跟踪和版本控制信息。
ExcalidrawElement / ExcalidrawScene：简化的Excalidraw结构。
CsInteractiveMeta：嵌入交互式信息 customData.

这是 核心DSL 整个MVP。未来的活动类型（多项选择、测序）也将遵循这种模式。

4.2设计师(`src/designer.ts`)

此文件负责：

接收“类似提示”的输入(DesignMatchPairsInput).
自动完成：
- 活动ID
- 配对id/项目id
- 默认分数
- 布局和跟踪元

在实际产品中，您可以：

在此处连接LLM的输出（例如，Claude/GPT）。
或者让法学硕士首先将自然语言组织成 DesignMatchPairsInput，然后将其传递给此纯函数。

4.3渲染器(`src/renderer.ts`)

此文件负责：

转换 MatchPairsActivity → 排除样式场景。
计算每个项目的坐标（简单网格布局）。
添加 customData.csInteractive 每个矩形元素。

这是“关注点分离”的关键：

语义和内容：In MatchPairsActivity.
视觉布局和细节：In renderMatchPairsToScene.

4.4 MCP集成（下一步）

虽然这个项目目前是MVP，但你可以很容易地：

直接在MCP服务器内调用：
- designMatchPairsActivity(input)
- renderMatchPairsToScene(activity)
创建两个MCP工具：
- design_match_pairs_activity
- render_activity_to_excalidraw_scene

MCP服务器只需要：

描述 args 模式（可以重用 DesignMatchPairsInput / MatchPairsActivity).
在工具实现中调用这两个纯函数。

5.用于Cursor/Claude集成的MCP服务器

✅ 已实施！ 该项目现在包括一个完整的MCP服务器，允许Cursor或Claude Desktop AI直接调用工具来生成匹配活动。

5.1快速入门

安装（已完成）

MCP SDK已安装在项目中：

npm install  # @modelcontextprotocol/sdk is included in dependencies

配置光标

配置文件自动设置

地点： ~/.cursor/mcp.json
promptboard-matchpairs 服务器已添加到配置中。

手动配置示例:

{
  "mcpServers": {
    "promptboard-mcp-mvp": {
      "command": "node",
      "args": [
        "/Users/davis_chang/code/promptboard-mcp-mvp/node_modules/.bin/ts-node",
        "/Users/davis_chang/code/promptboard-mcp-mvp/src/mcp-server.ts"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

重新启动游标
- 关闭所有光标窗口。
- 重新打开以加载MCP服务器。

开始使用

Help me design a G3 English animal matching activity with 4 pairs, and generate an Excalidraw scene.

有关详细的设置说明，请参阅 MCP_SETUP.md.

5.2可用的MCP工具

工具1： `design_match_pairs`

函数：根据教师友好的输入设计匹配活动。

输入格式:

{
  "grade": "G3",
  "subject": "English",
  "topic": "animals",
  "instructions": "Please connect the English animal names on the left to the correct Chinese meanings on the right.",
  "pairs": [
    { "left": "dog", "right": "狗" },
    { "left": "cat", "right": "貓" }
  ]
}

输出：完成 MatchPairsActivity JSON，包括：

自动生成的activityId
pairId和itemId
跟踪元数据
布局信息

工具2： `render_excalidraw`

函数：将活动渲染为Excalidraw场景。

输入: MatchPairsActivity JSON（来自工具1）。

输出：完整的Excalidraw场景JSON，可以是：

直接粘贴到Excalidraw.com（Cmd+V）。
保存为 .excalidraw 文件。
包括所有视觉属性（笔划、填充、圆度等）。
保留 customData.csInteractive 用于交互跟踪。

5.3使用示例

游标中的自然语言生成

User: "Make me a G3 math addition matching activity with 5 pairs."

AI Automatically Executes:
1. Generates pair content (2+3→5, 4+1→5...)
2. Calls design_match_pairs(...)
3. Calls render_excalidraw(...)
4. Returns Excalidraw JSON

使用Node.js直接调用（无MCP）

import { designMatchPairsActivity } from './src/designer';
import { renderMatchPairsToScene } from './src/renderer';

const input = {
  grade: "G3",
  subject: "English",
  topic: "animals",
  pairs: [
    { left: "dog", right: "狗" },
    { left: "cat", right: "貓" }
  ]
};

// 1. Design Activity
const activity = designMatchPairsActivity(input);

// 2. Render Scene
const scene = renderMatchPairsToScene(activity);

// 3. Use scene JSON
console.log(JSON.stringify(scene, null, 2));

5.4手动运行MCP服务器

如果要手动测试MCP服务器：

npm run mcp

服务器将启动并监听MCP协议输入（stdin/stdout）。

5.5验证放行输出

生成场景后，有两种方法可以验证：

方法1：复制和粘贴

cat test_output_scene.json | pbcopy

然后转到https://excalidraw.com然后按Cmd+V。

方法2：查看JSON

cat test_output_scene.json | jq .

6.技术架构

6.1分层设计

Natural Language Input (Cursor AI)
      ↓
MCP Server (mcp-server.ts)
      ↓
  ┌───────────────┬────────────────┐
  │               │                │
Design Layer    Logic Layer      Visual Layer
designer.ts     types.ts         renderer.ts
  │               │                │
  └───────────────┴────────────────┘
              ↓
     Excalidraw Scene JSON

6.2核心文件

文件	功能	图层
`types.ts`	TypeScript类型定义	数据模型
`designer.ts`	教学内容→ 结构化JSON	业务逻辑
`renderer.ts`	结构化JSON→ 视觉场景	演示
`schemas.ts`	JSON模式定义	MCP集成
`mcp-server.ts`	MCP协议实施	MCP集成
`main.ts`	HTTP API服务器	HTTP API

6.3数据流

Teacher Input
    ↓
DesignMatchPairsInput
    ↓ (designMatchPairsActivity)
MatchPairsActivity
    ↓ (renderMatchPairsToScene)
ExcalidrawScene
    ↓
Excalidraw.com / Your App

6.4可扩展性设计

目前支持:

✅ 配对

将来的扩展:

单项选择
填空
测序
分类

每种新的活动类型只需要：

在中定义新的活动界面 types.ts.
在中添加相应的设计功能 designer.ts.
在中添加相应的渲染逻辑 renderer.ts.
在中注册新工具 mcp-server.ts.

7.开发指南

7.1添加新的活动类型

定义类型 (types.ts)

export interface MultipleChoiceActivity {
  activityId: string;
  type: "multiple_choice";
  question: string;
  options: string[];
  correctAnswer: number;
  // ...
}

实施设计逻辑 (designer.ts)

export function designMultipleChoice(input: any): MultipleChoiceActivity {
  // ...
}

实现渲染逻辑 (renderer.ts)

export function renderMultipleChoice(activity: MultipleChoiceActivity): ExcalidrawScene {
  // ...
}

注册MCP工具 (mcp-server.ts)

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      // ... existing tools
      {
        name: "design_multiple_choice",
        description: "...",
        inputSchema: MultipleChoiceInputSchema,
      }
    ]
  };
});

7.2自定义视觉样式

修改中的默认值 renderer.ts:

// Colors
strokeColor: "#1e1e1e"     // Change to your theme color
backgroundColor: "transparent"

// Stroke and Style
strokeWidth: 2             // Line width
roughness: 1               // Hand-drawn effect (0-2)
fillStyle: "solid"         // solid / hachure / cross-hatch

// Layout
const boxWidth = 200;      // Box width
const boxHeight = 60;      // Box height
leftColumnX: 100,          // Left column position
rightColumnX: 500,         // Right column position
rowGap: 120                // Row gap

8.常见问题

Q1：光标看不到MCP工具？

A.：检查以下步骤：

检查是否 ~/.cursor/mcp.json 包含 promptboard-matchpairs 配置。
确认项目路径(cwd)是正确的。
重新启动游标 （必填！）。
检查Cursor开发人员控制台是否有错误。

Q2：如何调试MCP服务器？

A.:

# Manually start server and view errors
npm run mcp

# View stderr output (MCP uses stdout for communication)

Q3：生成的Excalidraw JSON无法导入？

A.：确认JSON格式正确：

cat output.json | jq .  # Verify JSON format

如果格式正确但仍无法导入，则可能是Excalidraw版本问题。生成的格式与Excalidraw 2024+版本兼容。

Q4：如何在Claude Desktop中使用？

A.：配置类似于游标，但文件位置不同：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

配置格式：

{
  "mcpServers": {
    "promptboard-matchpairs": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/path/to/promptboard-mcp-mvp"
    }
  }
}

9.许可和贡献

这是一个MVP测试项目，欢迎访问：

分叉和延伸功能
提交问题以报告问题
提交PR以贡献代码

建议的延伸方向：

[]支持更多活动类型
[]添加自动难度调整
[]支持图像和音频内容
[]多语言支持
[]自动生成教学内容（集成法学硕士）