DEVELOPMENT.md•14.2 kB
# Development Guide - EuConquisto Composer MCP
**Version**: v1.1.0 (Fail-Fast Reliability Suite)
**Last Updated**: January 21, 2025
**Purpose**: Complete guide for developers contributing to or extending the system
---
## 🏗️ **Architecture Overview**
### **System Architecture**
```
┌─────────────────────────────────────────────────────────────┐
│ Claude Desktop │
└─────────────────────┬───────────────────────────────────────┘
│ MCP Protocol
┌─────────────────────▼───────────────────────────────────────┐
│ Direct API Server v1.1.0 │
│ (dist/direct-api-server-v1.0.0.js) │
└─────────────────────┬───────────────────────────────────────┘
│ Tool Imports
┌─────────────────────▼───────────────────────────────────────┐
│ 7 JIT Workflow Tools │
│ (src/tools/*-v1.1.0.js) │
└─────────────────────┬───────────────────────────────────────┘
│ Direct API Calls
┌─────────────────────▼───────────────────────────────────────┐
│ EuConquisto Composer API │
│ (https://api.digitalpages.com.br/) │
└─────────────────────────────────────────────────────────────┘
```
### **Key Components**
1. **Main Server**: `dist/direct-api-server-v1.0.0.js`
- MCP protocol handler
- Tool registration and routing
- Environment configuration management
2. **Tool Modules**: `src/tools/*-v1.1.0.js`
- Individual workflow step implementations
- Fail-fast validation logic
- Direct API integration
3. **Configuration**: `src/config/`
- JWT token management
- API configuration
- Pedagogical context
---
## 🛠️ **Development Setup**
### **Prerequisites**
- Node.js 18+
- Git
- Code editor (VS Code recommended)
- EuConquisto Composer account with API access
### **Local Development Setup**
```bash
# Clone and setup
git clone https://github.com/yourusername/euconquisto-composer-mcp-poc.git
cd euconquisto-composer-mcp-poc
# Install dependencies
npm install
# Install development dependencies
npm install --save-dev
# Setup development environment
npm run setup:dev # If available
# Verify setup
npm run test
npm run lint
```
### **Development Environment Variables**
Create a `.env.development` file:
```bash
NODE_ENV=development
MCP_DEBUG=true
EUCONQUISTO_ACCESS_TOKEN=your_dev_token_here
EUCONQUISTO_PROJECT_UID=your_dev_project_uid
EUCONQUISTO_CONNECTORS=[{"uid":"your_dev_connector_uid","name":null,"type":"Composer_1","permissions":[]}]
```
---
## 🔧 **Development Workflow**
### **Making Changes**
1. **Create Feature Branch**
```bash
git checkout -b feature/your-feature-name
```
2. **Make Changes**
- Modify tool files in `src/tools/`
- Update tests in `tests/`
- Update documentation as needed
3. **Test Changes**
```bash
# Run tests
npm test
# Run linting
npm run lint
# Test MCP server
npm run mcp:dev
```
4. **Commit and Push**
```bash
git add .
git commit -m "feat: description of changes"
git push origin feature/your-feature-name
```
### **Testing Your Changes**
#### **Unit Testing**
```bash
# Run all tests
npm test
# Run specific test file
npm test tests/unit/tool-name.test.js
# Run with coverage
npm run test:coverage
```
#### **Integration Testing**
```bash
# Test MCP integration
npm run test:mcp
# Test end-to-end workflow
npm run test:e2e
```
#### **Manual Testing with Claude Desktop**
1. Update your Claude Desktop config to point to your development version
2. Restart Claude Desktop
3. Test tools individually and in workflow sequence
4. Verify error handling with invalid inputs
---
## 🏗️ **Adding New Tools**
### **Tool Structure Template**
Create `src/tools/new-tool-v1.1.0.js`:
```javascript
#!/usr/bin/env node
/**
* New Tool v1.1.0 - FAIL-FAST RELIABILITY
* Description of what this tool does
* @version 1.1.0 (January 21, 2025)
* @status ENHANCED - Fail-fast validation with comprehensive error messages
* @reference JIT workflow step X of 7
*/
export class NewToolV110 {
constructor() {
this.processingStartTime = null;
this.validationErrors = [];
}
/**
* Main tool entry point with FAIL-FAST validation
* @param {Object} input - Tool input parameters
* @returns {Object} Tool result OR detailed error
*/
async processRequest(input) {
this.processingStartTime = new Date();
this.validationErrors = [];
try {
console.error('[NEW_TOOL_V110] Starting fail-fast validation');
// FAIL-FAST VALIDATION PHASE
const validationResult = this.validateInputComprehensively(input);
if (!validationResult.valid) {
throw new Error(`New Tool validation failed:\n\n${validationResult.errors.join('\n\n')}\n\nReceived input: ${JSON.stringify(input, null, 2)}`);
}
// PROCESSING PHASE
const result = await this.processValidatedInput(validationResult.normalizedInput);
return {
success: true,
result: result,
processingTime: `${Date.now() - this.processingStartTime}ms`
};
} catch (error) {
return this.createFailFastErrorResponse(error, input);
}
}
/**
* Comprehensive input validation with detailed error reporting
*/
validateInputComprehensively(input) {
const errors = [];
// Add your validation logic here
if (!input || typeof input !== 'object') {
errors.push('❌ INPUT TYPE ERROR:\nInput must be a valid object.\n\nExample: { param1: "value1", param2: "value2" }');
}
// Add more validation rules...
return {
valid: errors.length === 0,
errors: errors,
normalizedInput: input
};
}
/**
* Create standardized fail-fast error response
*/
createFailFastErrorResponse(error, originalInput) {
return {
success: false,
error: {
code: 'NEW_TOOL_ERROR',
message: error.message,
failFast: true,
developmentMode: process.env.NODE_ENV === 'development',
troubleshooting: {
requiredInputStructure: {
param1: "string (required)",
param2: "string (optional)"
},
commonIssues: [
"Invalid input format",
"Missing required parameters"
],
debugSteps: [
"Check input is valid object",
"Verify required parameters are present",
"Enable MCP_DEBUG for detailed logs"
]
},
originalInput: originalInput,
timestamp: new Date().toISOString()
}
};
}
/**
* Process validated input - implement your tool logic here
*/
async processValidatedInput(input) {
// Implement your tool's main functionality
return {
message: "Tool processing complete",
data: input
};
}
}
/**
* Factory function for tool creation
*/
export function createNewToolV110() {
return new NewToolV110();
}
// CLI testing support
if (import.meta.url === `file://${process.argv[1]}`) {
const tool = createNewToolV110();
const testInput = { param1: "test value" };
console.log('Testing New Tool v1.1.0...');
const result = await tool.processRequest(testInput);
console.log(JSON.stringify(result, null, 2));
}
```
### **Register New Tool in Main Server**
Update `dist/direct-api-server-v1.0.0.js`:
```javascript
// Add import
import { createNewToolV110 } from '../src/tools/new-tool-v1.1.0.js';
// Add to constructor
this.newTool = createNewToolV110();
// Add to tool list
{
name: 'new_tool',
description: 'Description of what the tool does',
inputSchema: {
type: 'object',
properties: {
param1: {
type: 'string',
description: 'Parameter description'
}
},
required: ['param1']
}
}
// Add handler case
case 'new_tool':
return this.handleNewTool(request.params.arguments);
// Add handler method
async handleNewTool(args) {
try {
const result = await this.newTool.processRequest(args);
return {
content: [{
type: 'text',
text: JSON.stringify(result, null, 2)
}]
};
} catch (error) {
throw new McpError(ErrorCode.InternalError, `New tool error: ${error.message}`);
}
}
```
---
## 🧪 **Testing Guidelines**
### **Test Structure**
Create `tests/unit/new-tool.test.js`:
```javascript
import { describe, it, expect, beforeEach } from '@jest/globals';
import { createNewToolV110 } from '../../src/tools/new-tool-v1.1.0.js';
describe('NewToolV110', () => {
let tool;
beforeEach(() => {
tool = createNewToolV110();
});
describe('Input Validation', () => {
it('should reject null input', async () => {
const result = await tool.processRequest(null);
expect(result.success).toBe(false);
expect(result.error.code).toBe('NEW_TOOL_ERROR');
});
it('should reject empty input', async () => {
const result = await tool.processRequest({});
expect(result.success).toBe(false);
});
it('should accept valid input', async () => {
const input = { param1: 'test value' };
const result = await tool.processRequest(input);
expect(result.success).toBe(true);
});
});
describe('Error Handling', () => {
it('should provide detailed error messages', async () => {
const result = await tool.processRequest(null);
expect(result.error.troubleshooting).toBeDefined();
expect(result.error.troubleshooting.commonIssues).toBeInstanceOf(Array);
expect(result.error.troubleshooting.debugSteps).toBeInstanceOf(Array);
});
});
});
```
### **Testing Best Practices**
1. **Test Fail-Fast Validation**: Ensure all validation rules work correctly
2. **Test Error Messages**: Verify error messages are helpful and actionable
3. **Test Edge Cases**: Test with boundary conditions and invalid inputs
4. **Test Integration**: Verify tool works within the complete workflow
5. **Test Performance**: Ensure tool meets performance requirements
---
## 📝 **Code Standards**
### **JavaScript/ES6 Standards**
- Use ES6 modules (`import`/`export`)
- Use `async`/`await` for asynchronous operations
- Use template literals for string formatting
- Use destructuring for object/array operations
- Use arrow functions for short functions
### **Error Handling Standards**
- Always implement fail-fast validation
- Provide detailed error messages with troubleshooting
- Include original input in error responses
- Use standardized error response format
- Log errors with appropriate detail level
### **Documentation Standards**
- Use JSDoc comments for all functions
- Include version information in file headers
- Document input/output schemas
- Provide usage examples
- Keep documentation current with code changes
### **Naming Conventions**
- Files: `kebab-case-v1.1.0.js`
- Classes: `PascalCase`
- Functions: `camelCase`
- Constants: `UPPER_SNAKE_CASE`
- Variables: `camelCase`
---
## 🔍 **Debugging**
### **Debug Mode**
Enable comprehensive debugging:
```bash
export MCP_DEBUG=true
export NODE_ENV=development
```
### **Logging Best Practices**
```javascript
// Use console.error for debug logs (visible in Claude Desktop)
console.error('[TOOL_NAME] Debug message');
// Include context in logs
console.error(`[TOOL_NAME] Processing input: ${JSON.stringify(input, null, 2)}`);
// Log processing steps
console.error('[TOOL_NAME] Step 1: Validation complete');
console.error('[TOOL_NAME] Step 2: Processing data');
```
### **Common Debug Scenarios**
1. **Tool Not Loading**: Check import paths and syntax errors
2. **Validation Failing**: Enable debug mode and check validation logic
3. **API Errors**: Verify credentials and network connectivity
4. **Performance Issues**: Add timing logs and check memory usage
---
## 🚀 **Deployment**
### **Development Deployment**
```bash
# Test locally
npm run mcp:dev
# Update Claude Desktop config
# Restart Claude Desktop
# Test functionality
```
### **Production Deployment**
```bash
# Build if needed
npm run build
# Update production config
# Deploy to production environment
# Monitor logs and performance
```
---
## 📚 **Additional Resources**
### **Documentation**
- **[API Reference](docs/API-REFERENCE.md)** - Complete tool documentation
- **[Error Reference](docs/ERROR-REFERENCE.md)** - Error handling guide
- **[Getting Started](docs/GETTING-STARTED.md)** - Setup instructions
### **External Resources**
- **[MCP Protocol Specification](https://modelcontextprotocol.io/docs)** - Official MCP documentation
- **[EuConquisto API Documentation](https://api.digitalpages.com.br/docs)** - Platform API reference
- **[Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices)** - Node.js development guidelines
---
**Last Updated**: January 21, 2025
**Version**: v1.1.0 Fail-Fast Reliability Suite
**Status**: ✅ COMPLETE - Comprehensive development guide for contributors