API-REFERENCE.md•14.6 kB
# EuConquisto Composer MCP - API Reference
**Version**: v1.1.0 (Fail-Fast Reliability Suite)
**Last Updated**: January 21, 2025
**Status**: ✅ CURRENT - Complete API reference for all 7 tools
---
## 🚀 **7-Step Workflow Overview**
The EuConquisto Composer MCP implements a 7-step workflow for educational content creation:
1. **`get_smart_guidance`** - Educational guidance with widget predictions
2. **`analyze_content_for_widgets`** - Dynamic content analysis (6 formats supported)
3. **`get_widget_requirements`** - Widget requirements with validation
4. **`validate_lesson_data`** - Strict validation with fail-fast error reporting
5. **`format_for_composer`** - Composer API formatting with structure verification
6. **`save_composition_direct_api`** - Direct API save with comprehensive error handling
7. **`open_composition_editor`** - Browser navigation with fail-fast checks
---
## 🛠️ **Tool Reference**
### **1. get_smart_guidance**
**Purpose**: Provides educational guidance with widget predictions based on content analysis.
**Input Schema**:
```json
{
"type": "object",
"properties": {
"prompt": {
"type": "string",
"description": "Educational content description or topic",
"minLength": 10,
"example": "Create a lesson about photosynthesis for 7th grade"
},
"subject": {
"type": "string",
"description": "Subject area",
"enum": ["science", "math", "history", "geography", "language", "arts"],
"default": "science"
},
"gradeLevel": {
"type": "string",
"description": "Target grade level",
"pattern": "^[1-9]+(th|nd|rd|st)?\\s*(grade|ano)?$",
"example": "7th grade"
}
},
"required": ["prompt"]
}
```
**Success Response**:
```json
{
"success": true,
"guidance": {
"educationalFramework": {
"subject": "science",
"gradeLevel": "7th grade",
"duration": "45 minutes",
"objectives": ["Understand photosynthesis process", "..."]
},
"contentStructure": {
"introduction": "Brief overview approach",
"mainContent": "Core concepts to cover",
"activities": "Suggested interactive elements",
"assessment": "Evaluation methods"
},
"suggestedWidgets": [
{
"type": "head-1",
"purpose": "Lesson introduction with visual impact",
"confidence": 0.95
},
{
"type": "text-1",
"purpose": "Main content explanation",
"confidence": 0.90
},
{
"type": "image-1",
"purpose": "Visual representation of concepts",
"confidence": 0.85
},
{
"type": "quiz-1",
"purpose": "Knowledge assessment",
"confidence": 0.80
}
]
},
"processingTime": "245ms"
}
```
**Error Response**:
```json
{
"success": false,
"error": {
"code": "PROMPT_VALIDATION_ERROR",
"message": "Prompt is required and cannot be empty.",
"failFast": true,
"developmentMode": true,
"troubleshooting": {
"requiredInputStructure": {
"prompt": "string (required, min 10 characters)",
"subject": "string (optional, defaults to 'science')",
"gradeLevel": "string (optional, defaults to '7th grade')"
},
"commonIssues": [
"Empty or null prompt",
"Prompt too short (less than 10 characters)",
"Invalid subject not in enum list",
"Invalid grade level format"
],
"debugSteps": [
"Check that prompt is a non-empty string",
"Verify prompt length is at least 10 characters",
"Ensure subject is one of: science, math, history, geography, language, arts",
"Verify gradeLevel follows pattern: '7th grade', '5th ano', etc."
]
}
}
}
```
---
### **2. analyze_content_for_widgets**
**Purpose**: Analyzes educational content and maps it to appropriate widgets with confidence scoring.
**Input Schema**:
```json
{
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "Educational content to analyze",
"minLength": 50
},
"contentFormat": {
"type": "string",
"description": "Content format type",
"enum": ["markdown", "html", "plain_text", "structured", "lesson_plan", "mixed"],
"default": "plain_text"
},
"analysisDepth": {
"type": "string",
"description": "Analysis depth level",
"enum": ["basic", "detailed", "comprehensive"],
"default": "detailed"
}
},
"required": ["content"]
}
```
**Success Response**:
```json
{
"success": true,
"analysis": {
"contentStructure": {
"detectedFormat": "lesson_plan",
"sections": [
{
"type": "introduction",
"content": "What is photosynthesis?",
"suggestedWidget": "head-1",
"confidence": 0.92
},
{
"type": "explanation",
"content": "Photosynthesis is the process...",
"suggestedWidget": "text-1",
"confidence": 0.88
}
]
},
"widgetMapping": [
{
"widget": "head-1",
"confidence": 0.92,
"reasoning": "Strong introduction pattern detected",
"contentMatch": "Title and overview structure"
},
{
"widget": "image-1",
"confidence": 0.85,
"reasoning": "Visual concept references found",
"contentMatch": "References to plant structures"
}
],
"qualityMetrics": {
"readabilityScore": 8.2,
"educationalAlignment": 0.89,
"interactivityPotential": 0.76
}
},
"processingTime": "312ms"
}
```
---
### **3. get_widget_requirements**
**Purpose**: Retrieves specific requirements and validation rules for selected widgets.
**Input Schema**:
```json
{
"type": "object",
"properties": {
"selectedWidgets": {
"type": "array",
"items": {
"type": "string",
"enum": ["head-1", "text-1", "text-2", "text-3", "text-4", "text-5", "image-1", "image-2", "list-1", "list-2", "list-3", "quiz-1", "flashcards-1", "table-1"]
},
"minItems": 1,
"maxItems": 10
},
"includeExamples": {
"type": "boolean",
"description": "Include example data structures",
"default": true
}
},
"required": ["selectedWidgets"]
}
```
**Success Response**:
```json
{
"success": true,
"requirements": {
"head-1": {
"requiredFields": {
"category": {
"type": "string",
"format": "html",
"example": "<p>Science</p>",
"validation": "Must be wrapped in <p> tags"
},
"author_name": {
"type": "string",
"format": "html",
"example": "<p>Teacher Name</p>",
"validation": "Must be wrapped in <p> tags"
},
"author_office": {
"type": "string",
"format": "html",
"example": "<p>Science Department</p>",
"validation": "Must be wrapped in <p> tags"
}
},
"optionalFields": {
"background_image": {
"type": "string",
"format": "url",
"description": "Background image URL"
}
}
},
"quiz-1": {
"requiredFields": {
"quiz_questions": {
"type": "array",
"items": {
"question": {
"type": "string",
"format": "html",
"example": "<p>What is photosynthesis?</p>",
"validation": "Must be wrapped in <p> tags"
},
"choices": {
"type": "array",
"items": {
"type": "string",
"format": "html",
"example": "<p>Process of making food</p>",
"validation": "Must be wrapped in <p> tags"
}
},
"correct_answer": {
"type": "number",
"description": "Index of correct choice (0-based)"
}
}
}
}
}
},
"validationRules": {
"htmlWrapping": "All text content must be wrapped in <p> tags",
"fieldNaming": "Use exact field names as specified",
"arrayStructures": "Follow exact array item structure",
"requiredFields": "All required fields must be present"
}
}
```
---
### **4. validate_lesson_data**
**Purpose**: Validates lesson data structure with fail-fast error reporting and detailed troubleshooting.
**Input Schema**:
```json
{
"type": "object",
"properties": {
"lessonData": {
"type": "object",
"description": "Complete lesson data structure to validate"
},
"strictMode": {
"type": "boolean",
"description": "Enable strict validation (fail-fast)",
"default": true
}
},
"required": ["lessonData"]
}
```
**Success Response**:
```json
{
"success": true,
"validation": {
"status": "VALID",
"checkedRules": 68,
"passedRules": 68,
"failedRules": 0,
"warnings": [],
"structure": {
"metadata": "✅ Valid",
"widgets": "✅ Valid (4 widgets)",
"htmlFormatting": "✅ Valid",
"requiredFields": "✅ Valid"
}
},
"processingTime": "89ms"
}
```
**Error Response**:
```json
{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "Lesson data validation failed with 3 critical errors",
"failFast": true,
"developmentMode": true,
"validationErrors": [
{
"rule": "HTML_WRAPPING",
"field": "widgets[0].category",
"issue": "Text content not wrapped in HTML tags",
"current": "Science",
"expected": "<p>Science</p>",
"severity": "error"
},
{
"rule": "REQUIRED_FIELD",
"field": "metadata.duration",
"issue": "Required field missing",
"severity": "error"
}
],
"troubleshooting": {
"requiredInputStructure": {
"lessonData": {
"metadata": {
"category": "string (HTML wrapped)",
"duration": "string (required)",
"subject": "string"
},
"widgets": "array of widget objects"
}
},
"commonIssues": [
"Text fields not wrapped in <p> tags",
"Missing required metadata fields",
"Incorrect widget field names",
"Invalid array structures"
],
"debugSteps": [
"Check all text fields are HTML wrapped: <p>text</p>",
"Verify all required metadata fields are present",
"Validate widget field names match requirements",
"Ensure array structures follow specification"
]
}
}
}
```
---
### **5. format_for_composer**
**Purpose**: Formats validated lesson data for EuConquisto Composer API with structure verification.
**Input Schema**:
```json
{
"type": "object",
"properties": {
"validatedLessonData": {
"type": "object",
"description": "Validated lesson data from validate_lesson_data"
},
"formatOptions": {
"type": "object",
"properties": {
"preserveFormatting": {
"type": "boolean",
"default": true
},
"validateOutput": {
"type": "boolean",
"default": true
}
}
}
},
"required": ["validatedLessonData"]
}
```
---
### **6. save_composition_direct_api**
**Purpose**: Saves formatted composition to EuConquisto Composer platform via direct API.
**Input Schema**:
```json
{
"type": "object",
"properties": {
"formattedComposition": {
"type": "object",
"description": "Formatted composition from format_for_composer"
},
"saveOptions": {
"type": "object",
"properties": {
"autoOpen": {
"type": "boolean",
"description": "Automatically open in editor after save",
"default": true
}
}
}
},
"required": ["formattedComposition"]
}
```
---
### **7. open_composition_editor**
**Purpose**: Opens saved composition in EuConquisto Composer editor with fail-fast navigation checks.
**Input Schema**:
```json
{
"type": "object",
"properties": {
"compositionUid": {
"type": "string",
"description": "UID of saved composition",
"pattern": "^[a-f0-9-]{36}$"
}
},
"required": ["compositionUid"]
}
```
---
## 🔧 **Error Handling**
### **Common Error Codes**
- `PROMPT_VALIDATION_ERROR` - Invalid or missing prompt
- `CONTENT_ANALYSIS_ERROR` - Content analysis failed
- `WIDGET_REQUIREMENTS_ERROR` - Invalid widget selection
- `VALIDATION_FAILED` - Lesson data validation failed
- `FORMAT_ERROR` - Formatting for Composer API failed
- `API_SAVE_ERROR` - Direct API save operation failed
- `BROWSER_NAVIGATION_ERROR` - Editor opening failed
### **Fail-Fast Behavior**
All tools in v1.1.0 implement fail-fast validation:
- Immediate error reporting with detailed context
- No silent failures or auto-corrections
- Comprehensive troubleshooting information
- Development-friendly error messages
---
## 🚀 **Usage Examples**
### **Complete Workflow Example**
```javascript
// Step 1: Get guidance
const guidance = await callTool('get_smart_guidance', {
prompt: "Create a lesson about photosynthesis for 7th grade",
subject: "science",
gradeLevel: "7th grade"
});
// Step 2: Create content (Claude generates naturally)
const content = `
# Photosynthesis: How Plants Make Food
## Introduction
Photosynthesis is the amazing process that allows plants to create their own food using sunlight, water, and carbon dioxide.
## The Process
Plants use chlorophyll in their leaves to capture sunlight energy...
`;
// Step 3: Analyze content
const analysis = await callTool('analyze_content_for_widgets', {
content: content,
contentFormat: "markdown"
});
// Step 4: Get widget requirements
const requirements = await callTool('get_widget_requirements', {
selectedWidgets: ["head-1", "text-1", "image-1", "quiz-1"]
});
// Step 5: Validate lesson data
const validation = await callTool('validate_lesson_data', {
lessonData: constructedLessonData
});
// Step 6: Format for Composer
const formatted = await callTool('format_for_composer', {
validatedLessonData: validation.data
});
// Step 7: Save and open
const saved = await callTool('save_composition_direct_api', {
formattedComposition: formatted.composition
});
const opened = await callTool('open_composition_editor', {
compositionUid: saved.compositionUid
});
```
---
**Last Updated**: January 21, 2025
**Version**: v1.1.0 Fail-Fast Reliability Suite
**Status**: ✅ COMPLETE - All 7 tools documented with fail-fast error handling