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

package/src/types/global.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Global type declarations for GeoGebra integration
+ */
+
+declare global {
+  interface Window {
+    ggbApplet: {
+      evalCommand(command: string): boolean;
+      evalCommandGetLabels(command: string): string;
+      deleteObject(objName: string): void;
+      exists(objName: string): boolean;
+      isDefined(objName: string): boolean;
+      getAllObjectNames(type?: string): string[];
+      getObjectType(objName: string): string;
+      getValue(objName: string): number;
+      getValueString(objName: string): string;
+      getVisible(objName: string): boolean;
+      getXcoord(objName: string): number;
+      getYcoord(objName: string): number;
+      getZcoord(objName: string): number;
+      getColor(objName: string): string;
+      newConstruction(): void;
+      reset(): void;
+      refreshViews(): void;
+    };
+    ggbReady: boolean;
+    ggbOnInit: () => void;
+  }
+}
+
+export {}; 

package/src/types/mcp.ts

@@ -0,0 +1,141 @@
+/**
+ * Model Context Protocol (MCP) Types
+ * Following JSON-RPC 2.0 specification
+ */
+
+// JSON-RPC 2.0 Base Types
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  method: string;
+  params?: Record<string, unknown> | unknown[];
+  id?: string | number | null;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  result?: unknown;
+  error?: JsonRpcError;
+  id: string | number | null;
+}
+
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+// MCP Protocol - Initialize
+export interface McpInitializeRequest extends JsonRpcRequest {
+  method: 'initialize';
+  params: {
+    protocolVersion: string;
+    capabilities: {
+      tools?: {};
+      [key: string]: unknown;
+    };
+    clientInfo: {
+      name: string;
+      version: string;
+    };
+  };
+}
+
+export interface McpInitializeResponse extends JsonRpcResponse {
+  result?: {
+    protocolVersion: string;
+    capabilities: {
+      tools?: {
+        listChanged?: boolean;
+      };
+      [key: string]: unknown;
+    };
+    serverInfo: {
+      name: string;
+      version: string;
+    };
+  };
+  error?: JsonRpcError;
+}
+
+// MCP Protocol - Initialized Notification
+export interface McpInitializedNotification extends JsonRpcRequest {
+  method: 'notifications/initialized';
+  params?: Record<string, never>;
+}
+
+// MCP Specific Types
+export interface McpTool {
+  name: string;
+  description: string;
+  annotations?: { readOnlyHint: boolean; destructiveHint: boolean; idempotentHint: boolean; openWorldHint: boolean };
+  outputSchema?: Record<string, unknown>;
+  _meta?: Record<string, unknown>;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+    [key: string]: unknown; // Allow additional JSON Schema properties
+  };
+}
+
+export interface McpToolsListRequest extends JsonRpcRequest {
+  method: 'tools/list';
+  params?: Record<string, never>;
+}
+
+export interface McpToolsListResponse extends JsonRpcResponse {
+  result?: {
+    tools: McpTool[];
+  };
+  error?: JsonRpcError;
+}
+
+export interface McpToolCallRequest extends JsonRpcRequest {
+  method: 'tools/call';
+  params: {
+    name: string;
+    arguments?: Record<string, unknown>;
+  };
+}
+
+export interface McpToolCallResponse extends JsonRpcResponse {
+  result?: {
+    content: Array<{
+      type: 'text' | 'image' | 'resource';
+      text?: string;
+      data?: string;
+      mimeType?: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+    isError?: boolean;
+  };
+  error?: JsonRpcError;
+}
+
+// Error Codes (following JSON-RPC 2.0 and MCP conventions)
+export enum McpErrorCode {
+  ParseError = -32700,
+  InvalidRequest = -32600,
+  MethodNotFound = -32601,
+  InvalidParams = -32602,
+  InternalError = -32603,
+  ToolNotFound = -32000,
+  ToolExecutionError = -32001,
+}
+
+// Server Configuration
+export interface McpServerConfig {
+  name: string;
+  version: string;
+  description: string;
+  logLevel?: 'error' | 'warn' | 'info' | 'debug';
+}
+
+// Tool Registry Types
+export type ToolHandler = (params: Record<string, unknown>) => Promise<NonNullable<McpToolCallResponse['result']>>;
+
+export interface ToolDefinition {
+  tool: McpTool;
+  handler: ToolHandler;
+} 

package/src/utils/app-info.ts

@@ -0,0 +1,35 @@
+type AppInfo = {
+  name: string;
+  version: string;
+  description: string;
+  homepage?: string;
+};
+
+let cachedAppInfo: AppInfo | undefined;
+
+/**
+ * Load package metadata in one place so CLI/server/tools report the same version.
+ */
+export function getAppInfo(): AppInfo {
+  if (cachedAppInfo) {
+    return cachedAppInfo;
+  }
+
+  try {
+    const packageJson = require('../../package.json');
+    cachedAppInfo = {
+      name: packageJson.name || 'GeoGebra Studio',
+      version: packageJson.version || '0.0.0',
+      description: packageJson.description || 'Model Context Protocol server for GeoGebra mathematical visualization',
+      homepage: packageJson.homepage
+    };
+  } catch (_error) {
+    cachedAppInfo = {
+      name: 'GeoGebra Studio',
+      version: '0.0.0',
+      description: 'Model Context Protocol server for GeoGebra mathematical visualization'
+    };
+  }
+
+  return cachedAppInfo;
+}

package/src/utils/errors.ts

@@ -0,0 +1,97 @@
+import { JsonRpcError, McpErrorCode } from '../types/mcp';
+import logger from './logger';
+
+/**
+ * Custom error class for MCP-specific errors
+ */
+export class McpError extends Error {
+  public readonly code: number;
+  public readonly data?: unknown;
+
+  constructor(code: McpErrorCode, message: string, data?: unknown) {
+    super(message);
+    this.name = 'McpError';
+    this.code = code;
+    this.data = data;
+  }
+}
+
+/**
+ * Create a JSON-RPC error response
+ */
+export function createJsonRpcError(
+  code: McpErrorCode,
+  message: string,
+  data?: unknown
+): JsonRpcError {
+  return {
+    code,
+    message,
+    data
+  };
+}
+
+/**
+ * Handle and format errors for JSON-RPC responses
+ */
+export function handleError(error: unknown): JsonRpcError {
+  logger.error('Error occurred:', error);
+
+  if (error instanceof McpError) {
+    return createJsonRpcError(error.code, error.message, error.data);
+  }
+
+  if (error instanceof Error) {
+    return createJsonRpcError(
+      McpErrorCode.InternalError,
+      error.message,
+      { stack: error.stack }
+    );
+  }
+
+  return createJsonRpcError(
+    McpErrorCode.InternalError,
+    'Unknown error occurred',
+    { error: String(error) }
+  );
+}
+
+/**
+ * Validate JSON-RPC request structure
+ */
+export function validateJsonRpcRequest(request: unknown): request is { jsonrpc: '2.0'; method: string; id?: string | number | null } {
+  if (typeof request !== 'object' || request === null) {
+    return false;
+  }
+
+  const req = request as Record<string, unknown>;
+  
+  return (
+    req['jsonrpc'] === '2.0' &&
+    typeof req['method'] === 'string' &&
+    (req['id'] === undefined || typeof req['id'] === 'string' || typeof req['id'] === 'number' || req['id'] === null)
+  );
+}
+
+/**
+ * Common error creators
+ */
+export const errors = {
+  parseError: (data?: unknown) => 
+    new McpError(McpErrorCode.ParseError, 'Parse error', data),
+  
+  invalidRequest: (data?: unknown) => 
+    new McpError(McpErrorCode.InvalidRequest, 'Invalid Request', data),
+  
+  methodNotFound: (method: string) => 
+    new McpError(McpErrorCode.MethodNotFound, `Method not found: ${method}`),
+  
+  invalidParams: (message: string = 'Invalid params') => 
+    new McpError(McpErrorCode.InvalidParams, message),
+  
+  toolNotFound: (toolName: string) => 
+    new McpError(McpErrorCode.ToolNotFound, `Tool not found: ${toolName}`),
+  
+  toolExecutionError: (toolName: string, message: string) => 
+    new McpError(McpErrorCode.ToolExecutionError, `Tool execution failed for ${toolName}: ${message}`)
+}; 

package/src/utils/gemini-compatibility.ts

@@ -0,0 +1,193 @@
+/**
+ * Gemini Compatibility Utilities
+ * 
+ * Gemini 2.5 Pro Preview requires stricter JSON Schema compliance:
+ * - All properties MUST have explicit "type" fields
+ * - No support for oneOf/anyOf/allOf constructs
+ * - Type must be specified for all parameter properties
+ */
+
+export interface GeminiCompatibleSchema {
+  type: 'object';
+  properties: Record<string, {
+    type: 'string' | 'number' | 'boolean' | 'integer' | 'array' | 'object';
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+    items?: any;
+    properties?: any;
+    required?: string[];
+    [key: string]: any;
+  }>;
+  required?: string[];
+  [key: string]: any;
+}
+
+/**
+ * Transform a schema to be compatible with Gemini 2.5 Pro Preview
+ */
+export function makeGeminiCompatible(schema: any): GeminiCompatibleSchema {
+  if (!schema || typeof schema !== 'object') {
+    return {
+      type: 'object',
+      properties: {},
+      required: []
+    };
+  }
+
+  const result: GeminiCompatibleSchema = {
+    type: 'object',
+    properties: {},
+    required: schema.required || []
+  };
+
+  // Ensure all properties have explicit types
+  if (schema.properties && typeof schema.properties === 'object') {
+    for (const [key, prop] of Object.entries(schema.properties as Record<string, any>)) {
+      if (!prop || typeof prop !== 'object') {
+        continue;
+      }
+
+      const transformedProp: any = { ...prop };
+
+      // Ensure type is explicitly set
+      if (!transformedProp.type) {
+        // Infer type from other properties or default to string
+        if (transformedProp.minimum !== undefined || transformedProp.maximum !== undefined) {
+          transformedProp.type = 'number';
+        } else if (transformedProp.items !== undefined) {
+          transformedProp.type = 'array';
+        } else if (transformedProp.properties !== undefined) {
+          transformedProp.type = 'object';
+        } else {
+          transformedProp.type = 'string';
+        }
+      }
+
+      // Remove any oneOf/anyOf/allOf constructs as Gemini doesn't support them
+      delete transformedProp.oneOf;
+      delete transformedProp.anyOf;
+      delete transformedProp.allOf;
+
+      // Recursively transform nested objects
+      if (transformedProp.type === 'object' && transformedProp.properties) {
+        transformedProp.properties = makeGeminiCompatible({
+          type: 'object',
+          properties: transformedProp.properties,
+          required: transformedProp.required
+        }).properties;
+      }
+
+      // Transform array items if present
+      if (transformedProp.type === 'array' && transformedProp.items) {
+        if (typeof transformedProp.items === 'object' && !transformedProp.items.type) {
+          transformedProp.items = makeGeminiCompatible(transformedProp.items);
+        }
+      }
+
+      result.properties[key] = transformedProp;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Check if a schema needs Gemini compatibility fixes
+ */
+export function needsGeminiCompatibility(schema: any): boolean {
+  if (!schema || typeof schema !== 'object') {
+    return false;
+  }
+
+  // Check for missing type at root level
+  if (!schema.type) {
+    return true;
+  }
+
+  // Check for oneOf/anyOf/allOf constructs
+  if (schema.oneOf || schema.anyOf || schema.allOf) {
+    return true;
+  }
+
+  // Check properties for missing types
+  if (schema.properties && typeof schema.properties === 'object') {
+    for (const prop of Object.values(schema.properties as Record<string, any>)) {
+      if (prop && typeof prop === 'object' && !prop.type) {
+        return true;
+      }
+      
+      // Check for oneOf/anyOf/allOf in properties
+      if (prop && (prop.oneOf || prop.anyOf || prop.allOf)) {
+        return true;
+      }
+
+      // Recursively check nested objects
+      if (prop && prop.type === 'object' && prop.properties && needsGeminiCompatibility(prop)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Validate that a schema is Gemini-compatible
+ */
+export function validateGeminiCompatibility(schema: any): { 
+  isCompatible: boolean; 
+  issues: string[];
+} {
+  const issues: string[] = [];
+
+  if (!schema || typeof schema !== 'object') {
+    issues.push('Schema is not an object');
+    return { isCompatible: false, issues };
+  }
+
+  if (!schema.type) {
+    issues.push('Root schema missing type field');
+  }
+
+  if (schema.oneOf) {
+    issues.push('Root schema uses oneOf (not supported by Gemini)');
+  }
+
+  if (schema.anyOf) {
+    issues.push('Root schema uses anyOf (not supported by Gemini)');
+  }
+
+  if (schema.allOf) {
+    issues.push('Root schema uses allOf (not supported by Gemini)');
+  }
+
+  if (schema.properties && typeof schema.properties === 'object') {
+    for (const [key, prop] of Object.entries(schema.properties as Record<string, any>)) {
+      if (!prop || typeof prop !== 'object') {
+        continue;
+      }
+
+      if (!prop.type) {
+        issues.push(`Property "${key}" missing type field`);
+      }
+
+      if (prop.oneOf) {
+        issues.push(`Property "${key}" uses oneOf (not supported by Gemini)`);
+      }
+
+      if (prop.anyOf) {
+        issues.push(`Property "${key}" uses anyOf (not supported by Gemini)`);
+      }
+
+      if (prop.allOf) {
+        issues.push(`Property "${key}" uses allOf (not supported by Gemini)`);
+      }
+    }
+  }
+
+  return {
+    isCompatible: issues.length === 0,
+    issues
+  };
+}