quick-start.mdā¢9.67 kB
# Quick Start Guide
## š Getting Started with EuConquisto Composer MCP Server
This guide will help you quickly set up and start using the EuConquisto Composer MCP Server for educational content creation and automation.
### Prerequisites
Before you begin, ensure you have the following installed:
- **Node.js 18+** ([Download](https://nodejs.org/))
- **npm** (comes with Node.js) or **yarn**
- **Git** ([Download](https://git-scm.com/))
- **TypeScript** (will be installed automatically)
### Installation
1. **Clone the repository** (when available):
```bash
git clone [repository-url]
cd euconquisto-composer-mcp-poc
```
2. **Run the automated setup**:
```bash
chmod +x tools/setup-dev-environment.sh
./tools/setup-dev-environment.sh
```
3. **Configure environment**:
```bash
# Edit the .env file with your settings
cp .env.example .env
nano .env # or use your preferred editor
```
4. **Start the development server**:
```bash
npm run dev
```
The server will start on `http://localhost:3000` (or your configured port).
### Basic Usage
#### Creating Content Elements
```javascript
// Example: Creating a text element
const textElement = await mcpServer.createElement('text', {
content: 'Welcome to our course!',
formatting: {
bold: true,
fontSize: '18px'
}
});
// Example: Creating a quiz element
const quizElement = await mcpServer.createElement('quiz', {
questions: [
{
type: 'multiple-choice',
question: 'What is the capital of France?',
answers: [
{ text: 'London', isCorrect: false },
{ text: 'Paris', isCorrect: true },
{ text: 'Berlin', isCorrect: false }
]
}
]
});
```
#### Building Compositions
```javascript
// Create a lesson composition
const lesson = await mcpServer.createComposition({
name: 'Introduction to Geography',
elements: [
{ elementId: textElement.id, position: { x: 0, y: 0 } },
{ elementId: quizElement.id, position: { x: 0, y: 100 } }
],
layout: {
type: 'flow',
gap: 20
}
});
```
#### Generating Educational Content
```javascript
// Generate a complete course
const course = await mcpServer.generateCourse({
title: 'Introduction to Web Development',
subject: 'Computer Science',
level: 'beginner',
duration: { total: 2400, sessions: 8 }, // 40 hours, 8 sessions
objectives: [
{
description: 'Understand HTML fundamentals',
level: 'understand',
domain: 'cognitive'
}
],
targetAudience: {
demographics: { ageRange: { min: 16, max: 25 } },
priorKnowledge: ['Basic computer skills']
}
});
```
### Key Features
#### 1. Content Element Factory
Create various types of educational content:
- Text with rich formatting
- Images and multimedia
- Interactive quizzes and assessments
- Video and audio content
- Documents and resources
#### 2. Educational Automation
- Automated course generation
- Lesson plan creation
- Assessment building
- Learning objective mapping
- Progress tracking
#### 3. Export Capabilities
Export your content in multiple formats:
```javascript
// Export as JSON
const jsonExport = await mcpServer.exportComposition(lesson.id, 'json', {
includeAssets: true,
standalone: true
});
// Export as HTML package
const htmlExport = await mcpServer.exportComposition(lesson.id, 'html', {
responsive: true,
optimization: 'advanced'
});
```
### API Quick Reference
#### Server Management
```javascript
// Start server
await mcpServer.start();
// Check health
const health = await mcpServer.handleRequest({
id: 'health-check',
method: 'health',
params: {},
timestamp: new Date().toISOString()
});
// Get metrics
const metrics = mcpServer.getMetrics();
```
#### Content Management
```javascript
// List elements
const elements = await mcpServer.listElements({
type: 'quiz',
limit: 10,
sortBy: 'created',
sortOrder: 'desc'
});
// Update element
const updatedElement = await mcpServer.updateElement(elementId, {
content: 'Updated content'
});
// Delete element
await mcpServer.deleteElement(elementId);
```
#### Validation
```javascript
// Validate element
const validation = await mcpServer.validateElement(element);
if (!validation.isValid) {
console.log('Validation errors:', validation.errors);
}
// Validate composition
const compValidation = await mcpServer.validateComposition(composition);
```
### Development Workflow
#### 1. Daily Development
```bash
# Start development server
npm run dev
# Run tests in watch mode
npm run test:watch
# Check code quality
npm run lint
```
#### 2. Quality Assurance
```bash
# Run comprehensive quality checks
./tools/run-quality-checks.sh
# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e
# Check coverage
npm run test:coverage
```
#### 3. Building and Deployment
```bash
# Build for production
npm run build
# Validate build
npm run validate
# Generate documentation
npm run docs:generate
```
### Configuration
#### Environment Variables
Key environment variables to configure:
```bash
# Server Configuration
MCP_SERVER_NAME=euconquisto-composer
PORT=3000
HOST=localhost
PROTOCOL=http
# Authentication (optional)
AUTH_ENABLED=false
JWT_SECRET=your-secret-key
# Logging
LOG_LEVEL=info
LOG_CONSOLE=true
LOG_STRUCTURED=true
# Database (when implemented)
DATABASE_URL=postgresql://user:pass@localhost:5432/euconquisto
# EuConquisto Platform Integration
EUCONQUISTO_API_URL=https://api.euconquisto.com
EUCONQUISTO_API_KEY=your-api-key
```
#### Server Configuration
```javascript
const serverConfig = {
name: 'euconquisto-composer',
version: '0.1.0',
port: 3000,
host: 'localhost',
protocol: 'http',
authentication: {
enabled: false,
providers: ['jwt', 'oauth'],
sessionTimeout: 3600000
},
logging: {
level: 'info',
console: true,
structured: true
}
};
```
### Testing
#### Running Tests
```bash
# Run all tests
npm test
# Run specific test types
npm run test:unit # Unit tests
npm run test:integration # Integration tests
npm run test:e2e # End-to-end tests
# Run with coverage
npm run test:coverage
# Run in watch mode
npm run test:watch
```
#### Writing Tests
```javascript
// Example unit test
describe('ContentElementFactory', () => {
it('should create text element', async () => {
const factory = new ContentElementFactory();
const element = await factory.createElement('text', {
content: 'Test content'
});
expect(element.type).toBe('text');
expect(element.content).toBe('Test content');
});
});
// Example integration test
describe('MCP Server Integration', () => {
it('should handle create element request', async () => {
const response = await mcpServer.handleRequest({
id: 'test-123',
method: 'createElement',
params: {
type: 'text',
config: { content: 'Hello World' }
},
timestamp: new Date().toISOString()
});
expect(response.success).toBe(true);
expect(response.result.type).toBe('text');
});
});
```
### Troubleshooting
#### Common Issues
**1. Server won't start**
```bash
# Check port availability
lsof -i :3000
# Check Node.js version
node --version
# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install
```
**2. TypeScript compilation errors**
```bash
# Clean build directory
rm -rf dist/
# Rebuild
npm run build
# Check TypeScript version
npx tsc --version
```
**3. Test failures**
```bash
# Clear test cache
npm test -- --clearCache
# Run specific test file
npm test -- path/to/test.test.ts
# Run with verbose output
npm test -- --verbose
```
**4. Import/Export issues**
- Ensure all imports use relative paths
- Check TypeScript configuration
- Verify file extensions
#### Performance Issues
**1. Slow startup**
- Check environment configuration
- Verify database connectivity
- Review logging configuration
**2. Memory usage**
- Monitor with `npm run metrics`
- Check for memory leaks in tests
- Review large object allocations
### Next Steps
1. **Explore the codebase**:
- Review `src/interfaces/` for type definitions
- Examine `src/core/` for core implementations
- Check `docs/` for detailed documentation
2. **Follow the roadmap**:
- See `docs/project-management/ROADMAP.md` for current development status
- Understand the 4-phase execution methodology
- Track progress and milestones
3. **Contribute**:
- Follow the development workflow
- Ensure all quality checks pass
- Update documentation as needed
4. **Integration**:
- Set up EuConquisto platform integration
- Configure authentication providers
- Implement custom content types
### Support and Resources
- **Documentation**: `docs/` directory
- **API Reference**: `docs/api/`
- **Architecture**: `docs/architecture/`
- **Examples**: `docs/guides/examples/`
- **Roadmap**: `docs/project-management/ROADMAP.md`
- **Changelog**: `CHANGELOG.md`
### Quick Commands Reference
```bash
# Development
npm run dev # Start development server
npm run build # Build for production
npm run test # Run test suite
npm run lint # Run linting
npm run validate # Run full validation
# Quality Assurance
./tools/run-quality-checks.sh # Run all quality checks
./tools/setup-dev-environment.sh # Setup development environment
# Documentation
npm run docs:generate # Generate documentation
# Utilities
npm run test:coverage # Test with coverage
npm run lint:fix # Fix linting issues
```
Happy coding! š
For more detailed information, refer to the complete documentation in the `docs/` directory.