README.md•3.93 kB
# EuConquisto Composer MCP
Educational content creation system with direct API integration for EuConquisto Composer platform.
## Current Version: v1.1.0 (Fail-Fast Reliability Suite)
### ✨ What's New in v1.1.0
- **Fail-Fast Validation**: All 7 tools enhanced with comprehensive error reporting
- **Development Mode**: Clear, actionable error messages for faster debugging
- **Dynamic Content Adaptation**: Supports 6 different content formats automatically
- **No Breaking Changes**: Fully backward compatible with v1.0.0
- **Comprehensive API Documentation**: Complete reference for all 7 workflow tools
## Features
- 🎯 **Direct API Integration**: No browser automation complexity
- 🚀 **7-Step Workflow**: Complete lesson creation pipeline
- 📚 **Universal Content Support**: Any educational topic without templates
- 🔍 **Comprehensive Validation**: Immediate feedback on issues
- 🌐 **Brazilian Education Focus**: Grade levels and BNCC compliance
## Quick Start
### Prerequisites
- Node.js 18+
- Claude Desktop
- EuConquisto Composer account credentials
### Installation
```bash
# Clone repository
git clone https://github.com/yourusername/euconquisto-composer-mcp-poc.git
cd euconquisto-composer-mcp-poc
# Install dependencies
npm install
```
### Configuration
Update your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"euconquisto-composer-direct": {
"command": "node",
"args": [
"--max-old-space-size=4096",
"/absolute/path/to/euconquisto-composer-mcp-poc/dist/direct-api-server-v1.0.0.js"
],
"env": {
"EUCONQUISTO_ACCESS_TOKEN": "your_access_token_here",
"EUCONQUISTO_PROJECT_UID": "your_project_uid_here",
"EUCONQUISTO_CONNECTORS": "[{\"uid\":\"your_connector_uid\",\"name\":null,\"type\":\"Composer_1\",\"permissions\":[]}]",
"NODE_ENV": "development",
"MCP_DEBUG": "true"
}
}
}
}
```
**Important**: Replace `/absolute/path/to/euconquisto-composer-mcp-poc/` with your actual project path.
### Usage
1. Restart Claude Desktop
2. Use the 7-step workflow:
- `get_smart_guidance` - Get educational guidance with widget predictions
- `analyze_content_for_widgets` - Analyze content structure (6 formats supported)
- `get_widget_requirements` - Get widget specifications with validation rules
- `validate_lesson_data` - Validate lesson structure with fail-fast error reporting
- `format_for_composer` - Format for Composer API with structure verification
- `save_composition_direct_api` - Save to platform via direct API
- `open_composition_editor` - Open in browser with navigation checks
📚 **Complete Documentation Suite**:
- **[Getting Started](docs/GETTING-STARTED.md)** - Complete setup guide (10-15 minutes)
- **[API Reference](docs/API-REFERENCE.md)** - Detailed tool documentation with schemas and error handling
- **[Error Reference](docs/ERROR-REFERENCE.md)** - Comprehensive troubleshooting guide
- **[Development Guide](docs/DEVELOPMENT.md)** - Contributing and development workflow
- **[Documentation Index](docs/README.md)** - Complete documentation overview
## Development Mode
v1.1.0 introduces fail-fast validation with detailed error messages:
```javascript
// Example error response
{
success: false,
error: {
code: 'VALIDATION_FAILED',
message: 'Detailed error description',
troubleshooting: {
requiredInputStructure: { ... },
commonIssues: [ ... ],
debugSteps: [ ... ]
}
}
}
```
## Architecture
- **Direct API**: Environment-based authentication
- **No Browser Automation**: Simple, reliable HTTP calls
- **Modular Tools**: Each step is independent
- **Fail-Fast**: Immediate validation feedback
## License
MIT
## Support
For issues or questions, please open a GitHub issue.
**Status**: ✅ Production Ready with Enhanced Development Mode