@lydt/geogebra-studio 0.0.0-stage → 0.4.0-rc.2

package/src/tools/educational-templates.ts

@@ -0,0 +1,299 @@
+import { ToolDefinition } from '../types/mcp';
+import { toolRegistry } from './index';
+import logger from '../utils/logger';
+
+/**
+ * Educational Templates for GeoGebra MCP Tool - GEB-8 Implementation
+ * 
+ * Pre-built mathematical scenarios for common educational use cases:
+ * - Geometry fundamentals
+ * - Algebra visualizations  
+ * - Calculus demonstrations
+ * - Statistics and probability
+ * - Mathematical proofs
+ */
+
+// Check if we're in MCP mode (stdio communication)
+// When piping input, process.stdin.isTTY is undefined, not false
+const isMcpMode = !process.stdin.isTTY;
+
+// Template categories
+export type TemplateCategory = 'geometry' | 'algebra' | 'calculus' | 'statistics' | 'proofs';
+
+// Template metadata
+export interface EducationalTemplate {
+  id: string;
+  name: string;
+  category: TemplateCategory;
+  description: string;
+  gradeLevel: string;
+  objectives: string[];
+  prerequisites: string[];
+  estimatedTime: number; // minutes
+  setup: () => Promise<any>;
+}
+
+/**
+ * Educational template registry
+ */
+export class EducationalTemplateRegistry {
+  private templates: Map<string, EducationalTemplate> = new Map();
+
+  register(template: EducationalTemplate): void {
+    this.templates.set(template.id, template);
+    if (!isMcpMode) {
+      logger.info(`Registered educational template: ${template.id}`);
+    }
+  }
+
+  getTemplate(id: string): EducationalTemplate | undefined {
+    return this.templates.get(id);
+  }
+
+  getTemplatesByCategory(category: TemplateCategory): EducationalTemplate[] {
+    return Array.from(this.templates.values()).filter(t => t.category === category);
+  }
+
+  getAllTemplates(): EducationalTemplate[] {
+    return Array.from(this.templates.values());
+  }
+}
+
+export const templateRegistry = new EducationalTemplateRegistry();
+
+/**
+ * Core educational template tools
+ */
+export const educationalTemplateTools: ToolDefinition[] = [
+  {
+    tool: {
+      name: 'geogebra_list_educational_templates',
+      description: 'List all available educational templates by category',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          category: {
+            type: 'string',
+            enum: ['geometry', 'algebra', 'calculus', 'statistics', 'proofs'],
+            description: 'Filter templates by category (optional)'
+          },
+          gradeLevel: {
+            type: 'string',
+            description: 'Filter by grade level (e.g., "6-8", "9-12", "college")'
+          }
+        },
+        required: []
+      }
+    },
+    handler: async (params: Record<string, unknown>) => {
+      const { category, gradeLevel } = params;
+      
+      let templates = templateRegistry.getAllTemplates();
+      
+      if (category) {
+        templates = templates.filter(t => t.category === category);
+      }
+      
+      if (gradeLevel) {
+        templates = templates.filter(t => t.gradeLevel === gradeLevel);
+      }
+
+      const templateList = templates.map(template => ({
+        id: template.id,
+        name: template.name,
+        category: template.category,
+        description: template.description,
+        gradeLevel: template.gradeLevel,
+        estimatedTime: template.estimatedTime,
+        objectives: template.objectives
+      }));
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            success: true,
+            count: templateList.length,
+            templates: templateList
+          }, null, 2)
+        }]
+      };
+    }
+  },
+
+  {
+    tool: {
+      name: 'geogebra_load_educational_template',
+      description: 'Load and execute a specific educational template',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          templateId: {
+            type: 'string',
+            description: 'The ID of the educational template to load'
+          },
+          customizations: {
+            type: 'object',
+            description: 'Optional customizations for the template (colors, parameters, etc.)',
+            properties: {
+              colors: {
+                type: 'object',
+                description: 'Custom color scheme'
+              },
+              parameters: {
+                type: 'object', 
+                description: 'Custom parameter values'
+              },
+              showLabels: {
+                type: 'boolean',
+                description: 'Whether to show object labels'
+              }
+            }
+          }
+        },
+        required: ['templateId']
+      }
+    },
+    handler: async (params: Record<string, unknown>) => {
+      const { templateId } = params;
+      // Note: customizations parameter is accepted but not yet implemented
+      // Future enhancement: apply color schemes, parameters, and display options
+      // const customizations = params['customizations'] || {};
+      
+      const template = templateRegistry.getTemplate(templateId as string);
+      if (!template) {
+        throw new Error(`Educational template not found: ${templateId}`);
+      }
+
+      logger.info(`Loading educational template: ${template.name}`);
+      
+      // Clear existing construction
+      await toolRegistry.executeTool('geogebra_clear_construction', {});
+      
+      // Execute template setup
+      const result = await template.setup();
+      
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            success: true,
+            template: {
+              id: template.id,
+              name: template.name,
+              category: template.category,
+              loaded: true
+            },
+            objectives: template.objectives,
+            instructions: `Template "${template.name}" loaded successfully. Estimated time: ${template.estimatedTime} minutes.`,
+            result
+          }, null, 2)
+        }]
+      };
+    }
+  },
+
+  {
+    tool: {
+      name: 'geogebra_create_lesson_plan',
+      description: 'Generate a complete lesson plan using multiple educational templates',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          topic: {
+            type: 'string',
+            description: 'The mathematical topic for the lesson'
+          },
+          gradeLevel: {
+            type: 'string',
+            description: 'Target grade level'
+          },
+          duration: {
+            type: 'number',
+            description: 'Lesson duration in minutes'
+          },
+          templateIds: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Specific template IDs to include in the lesson'
+          }
+        },
+        required: ['topic', 'gradeLevel', 'duration']
+      }
+    },
+    handler: async (params: Record<string, unknown>) => {
+      const { topic, gradeLevel, duration, templateIds } = params;
+      
+      // Auto-select templates if not specified
+      let selectedTemplates: EducationalTemplate[];
+      
+      if (templateIds && Array.isArray(templateIds)) {
+        selectedTemplates = templateIds
+          .map(id => templateRegistry.getTemplate(id as string))
+          .filter(Boolean) as EducationalTemplate[];
+      } else {
+        // Auto-select based on topic and grade level
+        selectedTemplates = templateRegistry.getAllTemplates()
+          .filter(t => t.gradeLevel === gradeLevel)
+          .filter(t => t.estimatedTime <= (duration as number))
+          .reduce((chosen: EducationalTemplate[],t)=>{if(chosen.length<3&&chosen.reduce((sum,item)=>sum+item.estimatedTime,0)+t.estimatedTime<=(duration as number))chosen.push(t);return chosen;},[]);
+      }
+
+      const lessonPlan = {
+        topic,
+        gradeLevel,
+        duration,
+        templates: selectedTemplates.map(t => ({
+          id: t.id,
+          name: t.name,
+          category: t.category,
+          gradeLevel: t.gradeLevel,
+          estimatedTime: t.estimatedTime,
+          objectives: t.objectives,
+          prerequisites: t.prerequisites
+        })),
+        totalTime: selectedTemplates.reduce((sum, t) => sum + t.estimatedTime, 0),
+        structure: {
+          introduction: "5 minutes - Review prerequisites and introduce objectives",
+          activities: selectedTemplates.map((t, i) => 
+            `Activity ${i + 1}: ${t.name} (${t.estimatedTime} min) - ${t.description}`
+          ),
+          conclusion: "5 minutes - Summary and assessment"
+        }
+      };
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify(lessonPlan, null, 2)
+        }]
+      };
+    }
+  }
+];
+
+/**
+ * Initialize and register all educational templates
+ */
+export function initializeEducationalTemplates(): void {
+  // Import templates from different categories
+  const { geometryTemplates } = require('./templates/geometry-templates');
+  const { algebraTemplates } = require('./templates/algebra-templates');
+  
+  // Register geometry templates
+  geometryTemplates.forEach((template: EducationalTemplate) => {
+    templateRegistry.register(template);
+  });
+  
+  // Register algebra templates  
+  algebraTemplates.forEach((template: EducationalTemplate) => {
+    templateRegistry.register(template);
+  });
+  
+  if (!isMcpMode) {
+    logger.info(`Registered ${templateRegistry.getAllTemplates().length} educational templates`);
+  }
+}
+
+// Initialize templates when module is loaded
+initializeEducationalTemplates(); 

package/src/tools/export-tools.ts

@@ -0,0 +1,110 @@
+import { buildArtifact } from '../studio/artifact';
+import { HtmlOptions } from '../export/html';
+import { ToolDefinition } from '../types/mcp';
+import { constructionHtml } from '../export/html';
+import { sceneFromXML, exportSource, SourceFormat } from '../export/semantic';
+import { cleanWithGikz } from '../export/gikz';
+import { saveText } from '../export/files';
+import { instancePool } from './geogebra-tools';
+
+const textResult = (value: Record<string, unknown>) => ({content:[{type:'text' as const,text:JSON.stringify(value)}],structuredContent:value});
+const safe = (handler: ToolDefinition['handler']): ToolDefinition['handler'] => async params => {
+  try { return await handler(params); }
+  catch(e) { return {...textResult({success:false,error:e instanceof Error?e.message:String(e)}),isError:true}; }
+};
+const scene = async (params: Record<string, unknown>) => sceneFromXML(
+  typeof params['xml']==='string' ? params['xml'] : await (await instancePool.getDefaultInstance()).getConstructionXML()
+);
+/** Both named TikZ export and format=tikz use native PGF, then mandatory Gikz.
+ * Optional XML is loaded temporarily; restore the shared live construction even on failure.
+ */
+async function nativeCleanedTikz(p: Record<string, unknown>) {
+  const engine = await instancePool.getDefaultInstance();
+  const xml = typeof p['xml'] === 'string' ? sceneFromXML(p['xml']).xml : undefined;
+  const previous = xml ? await engine.getConstructionXML() : undefined;
+  let source: string;
+  try {
+    if (xml) await engine.callAppsApi('setXML', [xml]);
+    source = await engine.exportNativeTikZ();
+  } finally {
+    if (previous) await engine.callAppsApi('setXML', [previous]);
+  }
+  const code = await cleanWithGikz(source, {standalone: p['standalone'] !== false});
+  const saved = await saveText(p['filename'], code);
+  return textResult({success:true,format:'tikz',code,backend:'native-pgf+gikz',cleaned:true,
+    semantics:'visual-snapshot',complete:false,coordinateFallbacks:[],unsupportedObjects:[],
+    warnings:['Native PGF followed by Gikz produces a visual snapshot; construction dependencies are retained in GGB/XML, not guaranteed in TikZ.',
+      'Gikz normalizes colors, line widths, labels and coordinate precision. Inspect the printed result.'],
+    ...(saved ? {filename:saved} : {}),renderVerified:false});
+}
+const filename = {type:'string',description:'Optional new file within workspace; existing files are not overwritten.'};
+export const exportTools: ToolDefinition[] = [
+  {
+    tool:{name:'geogebra_build_artifact',description:'Default geometry delivery: execute ordered commands in an isolated GeoGebra engine, check visible definitions, embed a packed editable GGB into local HTML, reopen and check equal axes, and return a preview for visual review. Requires Chrome and GeoGebra network access; writes new workspace files only.',
+      _meta:{ui:{resourceUri:'ui://geogebra/preview.html'}},
+      inputSchema:{type:'object',properties:{
+        commands:{type:'array',items:{type:'string',maxLength:10000},maxItems:2000},ggbBase64:{type:'string'},
+        title:{type:'string',maxLength:500},filename:{type:'string',description:'New .html file within the workspace; a sibling .preview.png is also created.'},
+        width:{type:'integer',minimum:200,maximum:4000},height:{type:'integer',minimum:200,maximum:4000},
+        visibleLabels:{type:'array',items:{type:'string'}},captionOverrides:{type:'object',additionalProperties:{type:'string'}}
+      },required:['filename'],additionalProperties:false}},
+    handler:safe(async p=>buildArtifact(p as unknown as HtmlOptions & {filename:string})),
+  },
+  {
+    tool:{name:'geogebra_create_html',description:'Generate an unverified command-template GeoGebra HTML; prefer geogebra_build_artifact for default checked delivery. This generates an interactive GeoGebra HTML with current-state GGB, PNG, SVG, Gikz-cleaned native TikZ, PDF, XML and HTML downloads. No Chromium needed to generate; opening requires GeoGebra network access.',
+      annotations:{readOnlyHint:false,destructiveHint:false,idempotentHint:false,openWorldHint:false},
+      _meta:{ui:{resourceUri:'ui://geogebra/preview.html'}},
+      inputSchema:{type:'object',properties:{
+        title:{type:'string',maxLength:500},commands:{type:'array',items:{type:'string',maxLength:10000},maxItems:2000},
+        ggbBase64:{type:'string',description:'Optional packed GGB; commands run after loading it.'},
+        width:{type:'integer',minimum:200,maximum:4000},height:{type:'integer',minimum:200,maximum:4000},
+        visibleLabels:{type:'array',items:{type:'string'}},
+        captionOverrides:{type:'object',description:'Optional LaTeX or plain-text captions keyed by GeoGebra object name.',additionalProperties:{type:'string'}},
+        filename,
+      },additionalProperties:false}},
+    handler:safe(async p=>{
+      if(!p['commands']&&!p['ggbBase64']) throw new Error('Provide commands or ggbBase64');
+      const html=constructionHtml(p);
+      const saved=await saveText(p['filename'],html);
+      return textResult({success:true,format:'html',html,...(saved?{filename:saved}:{}),requiresNetwork:true,renderVerified:false});
+    }),
+  },
+  {
+    tool:{name:'geogebra_export_html',description:'Package the current server-side construction in an interactive HTML, preserving its GGB styling and definitions.',_meta:{ui:{resourceUri:'ui://geogebra/preview.html'}},inputSchema:{type:'object',properties:{title:{type:'string'},filename},additionalProperties:false}},
+    handler:safe(async p=>{
+      const ggbBase64=await (await instancePool.getDefaultInstance()).exportGGB();
+      const html=constructionHtml({title:typeof p['title']==='string'?p['title']:'GeoGebra construction',ggbBase64});
+      const saved=await saveText(p['filename'],html);
+      return textResult({success:true,format:'html',html,...(saved?{filename:saved}:{}),requiresNetwork:true});
+    }),
+  },
+  {
+    tool:{name:'geogebra_get_semantic_scene',description:'Read the original construction XML, command dependencies, coordinates, visibility, captions, and styles for editable export or AI-assisted reconstruction.',
+      inputSchema:{type:'object',properties:{xml:{type:'string',description:'Optional original XML; omit to inspect live GeoGebra.'}},additionalProperties:false}},
+    handler:safe(async p=>textResult({success:true,scene:await scene(p)})),
+  },
+  {
+    tool:{name:'geogebra_export_tikz',description:'Export current GeoGebra native PGF through mandatory Gikz cleanup. Returns a visual snapshot, not editable construction dependencies. No raw fallback.',
+      inputSchema:{type:'object',properties:{xml:{type:'string'},standalone:{type:'boolean',default:true},filename},additionalProperties:false}},
+    handler:safe(nativeCleanedTikz),
+  },
+  {
+    tool:{name:'geogebra_export_source',description:'TikZ always uses GeoGebra native PGF followed by mandatory Gikz cleanup (visual snapshot). Asymptote and mixed TSQX/Asymptote use the explicit semantic subset with strict validation; strict applies to those formats only.',
+      inputSchema:{type:'object',properties:{format:{type:'string',enum:['tikz','asymptote','tsqx']},xml:{type:'string'},strict:{type:'boolean',default:true},standalone:{type:'boolean',default:true},filename},required:['format'],additionalProperties:false}},
+    handler:safe(async p=>{
+      if (p['format'] === 'tikz') return nativeCleanedTikz(p);
+      const result=exportSource(await scene(p),p['format'] as SourceFormat,p['strict']!==false,p['standalone']!==false);
+      const saved=await saveText(p['filename'],result.code);
+      return textResult({success:true,...result,...(saved?{filename:saved}:{}),renderVerified:false});
+    }),
+  },
+  {
+    tool:{name:'geogebra_clean_tikz',description:'Clean native GeoGebra TikZ text or convert XML through built-in Gikz. This is visual cleanup, not a guarantee of preserved construction semantics.',
+      inputSchema:{type:'object',properties:{source:{type:'string',maxLength:10000000},standalone:{type:'boolean'},points:{type:'boolean'},labels:{type:'boolean'},round:{type:'boolean'},filename},required:['source'],additionalProperties:false}},
+    handler:safe(async p=>{
+      const code=await cleanWithGikz(p['source'] as string,p);
+      const saved=await saveText(p['filename'],code);
+      return textResult({success:true,format:'tikz',code,...(saved?{filename:saved}:{}),backend:'built-in-gikz',semantics:'not-guaranteed',renderVerified:false});
+    }),
+  },
+];