EuConquisto Composer MCP

# Getting Started with EuConquisto Composer MCP **Version**: v1.1.0 (Fail-Fast Reliability Suite) **Last Updated**: January 21, 2025 **Estimated Setup Time**: 10-15 minutes --- ## 🎯 **What You'll Build** By the end of this guide, you'll have: - ✅ EuConquisto Composer MCP running in Claude Desktop - ✅ Direct API integration with EuConquisto platform - ✅ 7-step workflow for creating educational content - ✅ Fail-fast validation with detailed error reporting --- ## 📋 **Prerequisites** ### **Required Software** - **Node.js 18+** - [Download here](https://nodejs.org/) - **Claude Desktop** - [Download here](https://claude.ai/desktop) - **Git** - For cloning the repository ### **Required Credentials** You'll need these from your EuConquisto Composer account: - **Access Token** - JWT token for API authentication - **Project UID** - Your project identifier - **Connector UID** - Your connector identifier **Don't have credentials?** Contact your EuConquisto administrator or see [Authentication Setup](docs/AUTHENTICATION.md). --- ## 🚀 **Installation Steps** ### **Step 1: Clone and Install** ```bash # Clone the repository git clone https://github.com/yourusername/euconquisto-composer-mcp-poc.git cd euconquisto-composer-mcp-poc # Install dependencies npm install # Verify installation node --version # Should be 18+ npm list @modelcontextprotocol/sdk # Should show installed version ``` ### **Step 2: Configure Claude Desktop** 1. **Locate your Claude Desktop config file**: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` 2. **Add the MCP server configuration**: ```json { "mcpServers": { "euconquisto-composer-direct": { "command": "node", "args": [ "--max-old-space-size=4096", "/REPLACE/WITH/YOUR/ACTUAL/PATH/euconquisto-composer-mcp-poc/dist/direct-api-server-v1.0.0.js" ], "env": { "EUCONQUISTO_ACCESS_TOKEN": "REPLACE_WITH_YOUR_ACCESS_TOKEN", "EUCONQUISTO_PROJECT_UID": "REPLACE_WITH_YOUR_PROJECT_UID", "EUCONQUISTO_CONNECTORS": "[{\"uid\":\"REPLACE_WITH_YOUR_CONNECTOR_UID\",\"name\":null,\"type\":\"Composer_1\",\"permissions\":[]}]", "NODE_ENV": "development", "MCP_DEBUG": "true" } } } } ``` 3. **Replace the placeholders**: - Replace `/REPLACE/WITH/YOUR/ACTUAL/PATH/` with your full project path - Replace `REPLACE_WITH_YOUR_ACCESS_TOKEN` with your JWT token - Replace `REPLACE_WITH_YOUR_PROJECT_UID` with your project UID - Replace `REPLACE_WITH_YOUR_CONNECTOR_UID` with your connector UID ### **Step 3: Test the Installation** 1. **Restart Claude Desktop** completely (quit and reopen) 2. **Verify MCP connection**: - Open a new conversation in Claude Desktop - Type: "Can you list the available MCP tools?" - You should see 7 EuConquisto tools listed 3. **Test basic functionality**: ``` Please use get_smart_guidance to help me create a lesson about photosynthesis for 7th grade science. ``` **Expected response**: Educational guidance with widget predictions and no errors. --- ## 🔧 **Troubleshooting Setup Issues** ### **Common Issues and Solutions** #### **Issue**: "MCP server not found" or no tools available **Solution**: 1. Check that the path in your config is absolute and correct 2. Verify Node.js is in your PATH: `which node` 3. Test the server directly: `node dist/direct-api-server-v1.0.0.js` 4. Check Claude Desktop logs for error messages #### **Issue**: "Authentication failed" or API errors **Solution**: 1. Verify your access token is valid and not expired 2. Check that project UID and connector UID are correct 3. Ensure credentials have proper permissions 4. Test with `MCP_DEBUG=true` for detailed error messages #### **Issue**: "Module not found" errors **Solution**: 1. Run `npm install` again to ensure all dependencies are installed 2. Check Node.js version: `node --version` (must be 18+) 3. Clear npm cache: `npm cache clean --force` #### **Issue**: Tools return validation errors **Solution**: 1. This is expected behavior in v1.1.0 (fail-fast validation) 2. Read the detailed error messages for specific issues 3. Check the [API Reference](docs/API-REFERENCE.md) for correct input formats 4. Enable debug mode with `MCP_DEBUG=true` --- ## 📚 **Next Steps** ### **Learn the Workflow** 1. **Read the [API Reference](docs/API-REFERENCE.md)** - Complete documentation for all 7 tools 2. **Try the [Tutorial](docs/TUTORIAL.md)** - Step-by-step lesson creation example 3. **Explore [Examples](docs/examples/)** - Real-world usage examples ### **Development Setup** If you plan to modify or extend the system: 1. **Read the [Development Guide](docs/DEVELOPMENT.md)** - Contributing and development workflow 2. **Set up testing**: `npm test` - Run the test suite 3. **Enable hot reload**: See development configuration options ### **Production Deployment** For production use: 1. **Read the [Deployment Guide](docs/DEPLOYMENT.md)** - Production setup and monitoring 2. **Configure logging**: Set up proper log management 3. **Set up monitoring**: Health checks and performance monitoring --- ## 🆘 **Getting Help** ### **Documentation Resources** - **[API Reference](docs/API-REFERENCE.md)** - Complete tool documentation - **[FAQ](docs/FAQ.md)** - Frequently asked questions - **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Common issues and solutions ### **Support Channels** - **GitHub Issues** - Bug reports and feature requests - **Documentation Issues** - Report documentation problems - **Community Forum** - General questions and discussions ### **Debug Information** When reporting issues, include: - Node.js version: `node --version` - Package version: `npm list euconquisto-composer-mcp-poc` - Error messages with `MCP_DEBUG=true` enabled - Your configuration (with credentials redacted) --- ## ✅ **Verification Checklist** Before proceeding, ensure: - [ ] Node.js 18+ installed and working - [ ] Repository cloned and dependencies installed - [ ] Claude Desktop config updated with correct paths and credentials - [ ] Claude Desktop restarted - [ ] 7 EuConquisto tools visible in Claude Desktop - [ ] Basic test with `get_smart_guidance` successful - [ ] No authentication or connection errors --- **Setup Complete!** 🎉 You're now ready to create educational content with EuConquisto Composer MCP. Start with the [Tutorial](docs/TUTORIAL.md) to learn the complete workflow. --- **Last Updated**: January 21, 2025 **Version**: v1.1.0 Fail-Fast Reliability Suite **Status**: ✅ COMPLETE - Ready for immediate use