EuConquisto Composer MCP

# Claude Desktop Integration Guide **Version**: 1.0 **Date**: 2025-06-09 **Status**: Phase 3 Documentation **Author**: EuConquisto Development Team **Target**: TASK-F002 Phase 3 Deliverable ## 🎯 Overview This guide provides step-by-step instructions for integrating the EuConquisto Composer MCP Server with Claude Desktop. The integration enables direct access to educational widget analysis and Composer functionality within Claude Desktop conversations. ### ✅ What This Integration Provides - **Widget Analysis**: Access detailed analysis of 6 educational widgets (Text, Image, Header, List, Gallery, Hotspot) - **Composer Access**: Generate authenticated URLs for EuConquisto Composer access - **Connection Testing**: Validate MCP server status and functionality - **Educational Data**: Rich metadata for educational content creation ## 📋 Prerequisites ### System Requirements - **Node.js**: Version 18.0 or higher - **Claude Desktop**: Latest version installed - **Operating System**: macOS, Windows, or Linux - **Memory**: Minimum 512MB available RAM - **Disk Space**: 100MB for installation and dependencies ### Required Files Ensure you have access to the complete EuConquisto Composer MCP Server project: ``` /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/ ├── dist/index.js # Compiled MCP server ├── package.json # Project dependencies ├── tsconfig-minimal.json # Build configuration └── src/index.ts # Source implementation ``` ## 🚀 Quick Start (5 Minutes) ### Step 1: Verify Installation Navigate to the project directory and verify the build: ```bash cd /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc npm run build:minimal ``` **Expected Output**: ``` > euconquisto-composer-mcp@0.1.3 build:minimal > tsc --project tsconfig-minimal.json # No errors = successful build ``` ### Step 2: Test MCP Server Verify the server responds correctly: ```bash echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "test-connection", "arguments": {}}}' | node dist/index.js ``` **Expected Response Structure**: ```json { "result": { "content": [{ "type": "text", "text": "{\"success\": true, \"message\": \"🎉 EuConquisto Composer MCP Server is working!\", ...}" }] }, "jsonrpc": "2.0", "id": 1 } ``` ### Step 3: Configure Claude Desktop Open Claude Desktop configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **Linux**: `~/.config/Claude/claude_desktop_config.json` Add the EuConquisto Composer MCP server configuration: ```json { "mcpServers": { "euconquisto-composer": { "command": "node", "args": ["/Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/dist/index.js"], "env": { "NODE_ENV": "production" } } } } ``` **⚠️ Important**: Replace the path with your actual project location. ### Step 4: Restart Claude Desktop 1. **Quit Claude Desktop** completely 2. **Restart Claude Desktop** 3. **Wait 5-10 seconds** for MCP servers to initialize ### Step 5: Test Integration In a new Claude Desktop conversation, test the integration: ``` Can you test the EuConquisto MCP connection? ``` Claude should respond with connection status and available tools. ## 🔧 Detailed Configuration ### MCP Server Configuration Options #### Basic Configuration ```json { "mcpServers": { "euconquisto-composer": { "command": "node", "args": ["/absolute/path/to/dist/index.js"], "env": { "NODE_ENV": "production" } } } } ``` #### Advanced Configuration ```json { "mcpServers": { "euconquisto-composer": { "command": "node", "args": [ "/absolute/path/to/dist/index.js" ], "env": { "NODE_ENV": "production", "LOG_LEVEL": "info" }, "disabled": false, "alwaysAllow": [] } } } ``` ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `NODE_ENV` | `development` | Node.js environment mode | | `LOG_LEVEL` | `info` | Logging level (debug, info, warn, error) | ## 🛠 Available MCP Tools ### 1. test-connection **Purpose**: Validate MCP server functionality and status **Usage in Claude Desktop**: ``` Test the EuConquisto MCP server connection ``` **Response**: Server status, widget analysis summary, validation confirmation **Parameters**: None required --- ### 2. get-widget-info **Purpose**: Retrieve detailed analysis of educational widgets **Usage in Claude Desktop**: ``` Get information about the header widget ``` **Parameters**: - **widget** (required): Widget type to analyze - Valid options: `"text"`, `"image"`, `"header"`, `"list"`, `"gallery"`, `"hotspot"` **Response**: Detailed widget properties, subtypes, examples, and special features --- ### 3. get-composer-url **Purpose**: Generate authenticated URLs for EuConquisto Composer access **Usage in Claude Desktop**: ``` Generate a Composer URL for the course creation page ``` **Parameters**: - **path** (optional): Specific path within Composer - Example: `"course-creation"`, `"widget-library"`, `"templates"` **Response**: Authenticated embed URL with JWT token and usage instructions ## 📊 Widget Analysis Data ### Available Widgets | Widget Type | Properties | Subtypes | Special Features | |-------------|------------|----------|------------------| | **Text** | 8 | 9 | Rich text formatting, multiple text types | | **Image** | 12 | 5 | Zoom capabilities, gallery integration | | **Header** | 44 | 6 | SCORM LMS integration (Template 3) | | **List** | 10 | 3 | Numbered, bullet, checkbox options | | **Gallery** | 10 | 1 | Slideshow functionality | | **Hotspot** | 15 | 1 | 25+ interactive icons, overlay support | ### Example: Header Widget Analysis ```json { "success": true, "widget": "header", "type": "cabecalho", "status": "completed", "properties": 44, "subtypes": 6, "examples": ["template-1", "template-2", "template-3"], "special": "Template 3 includes SCORM LMS integration", "description": "Header sections with background media, categories, and author info" } ``` ## 🔍 Testing and Validation ### Basic Functionality Test Test all three tools in sequence: 1. **Connection Test**: ``` Test the MCP server connection ``` 2. **Widget Analysis Test**: ``` Get details about the image widget ``` 3. **URL Generation Test**: ``` Generate a Composer URL for widget testing ``` ### Performance Validation - **Response Time**: All tools should respond in <100ms - **Memory Usage**: Server should use <50MB RAM - **Connection Stability**: No connection drops during normal usage ### Error Scenarios Test error handling by requesting invalid widget types: ``` Get information about an "invalid-widget" type ``` Expected: Graceful error response with valid options ## 🚨 Troubleshooting ### Common Issues and Solutions #### Issue: "Field required" Error **Symptoms**: Claude Desktop shows "ClaudeAiToolResultRequest.content.0.text.text: Field required" **Solution**: This indicates an MCP response format issue 1. Verify you're using the latest compiled version: `npm run build:minimal` 2. Check that `dist/index.js` exists and is current 3. Restart Claude Desktop after rebuilding #### Issue: MCP Server Not Found **Symptoms**: Claude Desktop doesn't recognize the MCP server **Solution**: Configuration path issue 1. Verify the absolute path in `claude_desktop_config.json` 2. Ensure `dist/index.js` exists at that path 3. Check file permissions (should be readable) 4. Restart Claude Desktop #### Issue: Tools Not Available **Symptoms**: MCP server connects but tools aren't available **Solution**: Initialization problem 1. Check server startup logs for errors 2. Verify Node.js version compatibility (18+) 3. Rebuild with: `npm run build:minimal` 4. Test server independently with command-line #### Issue: Slow Response Times **Symptoms**: Tools take >5 seconds to respond **Solution**: Performance optimization 1. Check system resources (CPU, memory) 2. Verify Node.js isn't running other intensive processes 3. Test with minimal system load 4. Consider restarting Claude Desktop ### Debug Commands #### Test Server Independently ```bash # Test connection echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "test-connection", "arguments": {}}}' | node dist/index.js # Test widget info echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get-widget-info", "arguments": {"widget": "text"}}}' | node dist/index.js # Test URL generation echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get-composer-url", "arguments": {"path": "test"}}}' | node dist/index.js ``` #### Check Build Status ```bash cd /path/to/euconquisto-composer-mcp-poc npm run build:minimal ls -la dist/index.js # Should exist with recent timestamp ``` #### Validate Configuration ```bash # Check Claude Desktop config exists ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json # Validate JSON syntax cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq . ``` ## 📈 Performance Metrics ### Baseline Performance - **Server Startup**: <1 second - **Tool Response Time**: <100ms average - **Memory Usage**: <30MB steady state - **CPU Usage**: <5% during operation ### Optimization Tips 1. **Keep dist/index.js compiled** - Don't run from TypeScript source 2. **Use minimal configuration** - tsconfig-minimal.json for reliability 3. **Monitor system resources** - Ensure adequate RAM available 4. **Regular restarts** - Restart Claude Desktop if performance degrades ## 🔐 Security Considerations ### JWT Token Security - JWT tokens are embedded in generated URLs - Tokens have expiration dates (check response for validity) - Use generated URLs promptly (within token lifetime) - Don't share URLs containing authentication tokens ### Local Security - MCP server runs locally with user permissions - No network exposure outside Claude Desktop integration - Configuration file should have appropriate file permissions - Regularly update dependencies for security patches ## 📚 Integration Examples ### Educational Content Workflow 1. **Analyze Available Widgets**: ``` Show me all available widget types and their capabilities ``` 2. **Detailed Widget Investigation**: ``` Get detailed information about the hotspot widget including all its properties ``` 3. **Composer Access**: ``` Generate a Composer URL for creating interactive educational content ``` ### Development Workflow 1. **Connection Validation**: ``` Test the MCP server to make sure everything is working ``` 2. **Widget Research**: ``` Compare the properties of image and gallery widgets ``` 3. **Content Creation Setup**: ``` Get a Composer URL for the widget library page ``` ## 📋 Next Steps ### After Successful Integration 1. **Explore Widget Capabilities**: Test each of the 6 available widgets 2. **Create Educational Content**: Use Composer URLs to access the platform 3. **Develop Workflows**: Integrate widget analysis into your content creation process 4. **Performance Monitoring**: Monitor response times and system performance ### Advanced Usage 1. **Custom Workflows**: Combine multiple tool calls for complex educational content planning 2. **Integration Patterns**: Develop consistent approaches for widget selection and usage 3. **Content Strategy**: Use widget analysis to inform educational design decisions 4. **Quality Assurance**: Validate content against widget capabilities and limitations ## 🎯 Success Criteria ### Integration Complete When: - ✅ All three MCP tools respond correctly in Claude Desktop - ✅ Widget analysis data is accessible and accurate - ✅ Composer URLs generate successfully with valid authentication - ✅ Response times are consistently <100ms - ✅ No errors during normal usage patterns ### Quality Validation: - ✅ Error handling graceful for invalid inputs - ✅ Server performance stable under normal load - ✅ Configuration survives Claude Desktop restarts - ✅ Documentation accurate and complete --- ## 📜 Document Information **Document Version**: 1.0 **Creation Date**: 2025-06-09 **Last Updated**: 2025-06-09 **Review Status**: Phase 3 Documentation Complete **Target Audience**: Developers, Content Creators, System Administrators **Dependencies**: TASK-F002 Phase 2 Complete **Validation**: Claude Desktop Integration Tested ✅ **Quality Gate**: Integration Guide Complete --- *EuConquisto Composer MCP Server PoC - Claude Desktop Integration Guide* *TASK-F002 Phase 3 Documentation | Complete Integration Instructions | © 2025 EuConquisto Development Team*