CONFIGURATION.md•11.8 kB
# Configuration Reference - EuConquisto Composer MCP
**Version**: v1.1.0 (Fail-Fast Reliability Suite)
**Last Updated**: January 21, 2025
**Purpose**: Complete configuration reference for all deployment scenarios
---
## 🔧 **Claude Desktop Configuration**
### **Basic Configuration**
**File Location**:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
**Minimal Configuration**:
```json
{
"mcpServers": {
"euconquisto-composer-direct": {
"command": "node",
"args": [
"/absolute/path/to/euconquisto-composer-mcp-poc/dist/direct-api-server-v1.0.0.js"
],
"env": {
"EUCONQUISTO_ACCESS_TOKEN": "your_access_token",
"EUCONQUISTO_PROJECT_UID": "your_project_uid",
"EUCONQUISTO_CONNECTORS": "[{\"uid\":\"your_connector_uid\",\"name\":null,\"type\":\"Composer_1\",\"permissions\":[]}]"
}
}
}
}
```
### **Production Configuration**
```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_production_token",
"EUCONQUISTO_PROJECT_UID": "your_production_project_uid",
"EUCONQUISTO_CONNECTORS": "[{\"uid\":\"your_production_connector_uid\",\"name\":null,\"type\":\"Composer_1\",\"permissions\":[]}]",
"NODE_ENV": "production",
"MCP_DEBUG": "false"
}
}
}
}
```
### **Development Configuration**
```json
{
"mcpServers": {
"euconquisto-composer-direct": {
"command": "node",
"args": [
"--max-old-space-size=4096",
"--inspect=9229",
"/absolute/path/to/euconquisto-composer-mcp-poc/dist/direct-api-server-v1.0.0.js"
],
"env": {
"EUCONQUISTO_ACCESS_TOKEN": "your_dev_token",
"EUCONQUISTO_PROJECT_UID": "your_dev_project_uid",
"EUCONQUISTO_CONNECTORS": "[{\"uid\":\"your_dev_connector_uid\",\"name\":null,\"type\":\"Composer_1\",\"permissions\":[]}]",
"NODE_ENV": "development",
"MCP_DEBUG": "true",
"DEBUG": "*",
"LOG_LEVEL": "debug"
}
}
}
}
```
---
## 🌍 **Environment Variables**
### **Required Variables**
| Variable | Description | Format | Example |
|----------|-------------|--------|---------|
| `EUCONQUISTO_ACCESS_TOKEN` | JWT token for API authentication | JWT string | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| `EUCONQUISTO_PROJECT_UID` | Project identifier | UUID | `36c92686-c494-ec11-a22a-dc984041c95d` |
| `EUCONQUISTO_CONNECTORS` | Connector configuration | JSON array string | `[{"uid":"47e8da94-c994-ec11-a22a-dc984041c95d","name":null,"type":"Composer_1","permissions":[]}]` |
### **Optional Variables**
| Variable | Description | Default | Options |
|----------|-------------|---------|---------|
| `NODE_ENV` | Environment mode | `production` | `development`, `production`, `test` |
| `MCP_DEBUG` | Enable debug logging | `false` | `true`, `false` |
| `LOG_LEVEL` | Logging level | `info` | `error`, `warn`, `info`, `debug` |
| `DEBUG` | Debug namespace | `undefined` | `*`, `mcp:*`, `tool:*` |
| `API_TIMEOUT` | API request timeout (ms) | `30000` | Any positive integer |
| `BROWSER_TIMEOUT` | Browser operation timeout (ms) | `60000` | Any positive integer |
### **Advanced Variables**
| Variable | Description | Default | Purpose |
|----------|-------------|---------|---------|
| `EUCONQUISTO_API_BASE_URL` | API base URL | `https://api.digitalpages.com.br/` | Custom API endpoint |
| `BROWSER_HEADLESS` | Run browser in headless mode | `true` | `true`, `false` |
| `BROWSER_SLOW_MO` | Browser slow motion (ms) | `0` | Debugging browser actions |
| `MAX_CONCURRENT_REQUESTS` | Max concurrent API requests | `5` | Rate limiting |
| `RETRY_ATTEMPTS` | API retry attempts | `3` | Error recovery |
| `RETRY_DELAY` | Retry delay (ms) | `1000` | Error recovery timing |
---
## 🔐 **Authentication Configuration**
### **JWT Token Format**
The access token must be a valid JWT with the following structure:
```json
{
"header": {
"alg": "HS256",
"typ": "JWT"
},
"payload": {
"sub": "user_id",
"iat": 1642781234,
"exp": 1642867634,
"permissions": ["read", "write", "admin"]
}
}
```
### **Token Validation**
The system validates tokens for:
- **Format**: Valid JWT structure
- **Expiration**: Token not expired
- **Permissions**: Required permissions present
- **Signature**: Valid signature verification
### **Token Refresh**
Tokens are automatically refreshed when:
- Token expires within 5 minutes
- API returns 401 Unauthorized
- Manual refresh requested
---
## 🏗️ **Project Configuration**
### **Project UID Format**
Project UIDs must follow UUID format:
```
36c92686-c494-ec11-a22a-dc984041c95d
```
### **Connector Configuration**
Connectors are configured as JSON array:
```json
[
{
"uid": "47e8da94-c994-ec11-a22a-dc984041c95d",
"name": null,
"type": "Composer_1",
"permissions": []
}
]
```
**Connector Types**:
- `Composer_1`: Standard composer connector
- `Composer_2`: Advanced composer connector
- `Custom`: Custom connector type
---
## 🚀 **Performance Configuration**
### **Memory Settings**
```json
{
"args": [
"--max-old-space-size=4096", // 4GB heap size
"--max-new-space-size=512", // 512MB new space
"--optimize-for-size" // Optimize for memory usage
]
}
```
### **Node.js Optimization**
```json
{
"env": {
"NODE_OPTIONS": "--max-old-space-size=4096 --optimize-for-size",
"UV_THREADPOOL_SIZE": "16" // Increase thread pool
}
}
```
### **Browser Performance**
```json
{
"env": {
"BROWSER_HEADLESS": "true",
"BROWSER_ARGS": "--no-sandbox --disable-dev-shm-usage --disable-gpu"
}
}
```
---
## 🔍 **Debug Configuration**
### **Development Debug Setup**
```json
{
"env": {
"NODE_ENV": "development",
"MCP_DEBUG": "true",
"DEBUG": "mcp:*,tool:*,api:*",
"LOG_LEVEL": "debug"
}
}
```
### **Production Logging**
```json
{
"env": {
"NODE_ENV": "production",
"MCP_DEBUG": "false",
"LOG_LEVEL": "warn",
"LOG_FORMAT": "json"
}
}
```
### **Debug Namespaces**
| Namespace | Description | Usage |
|-----------|-------------|-------|
| `mcp:*` | All MCP protocol messages | General MCP debugging |
| `tool:*` | All tool execution logs | Tool-specific debugging |
| `api:*` | All API request/response logs | API debugging |
| `auth:*` | Authentication logs | Auth debugging |
| `browser:*` | Browser automation logs | Browser debugging |
---
## 🌐 **Network Configuration**
### **Proxy Settings**
```json
{
"env": {
"HTTP_PROXY": "http://proxy.company.com:8080",
"HTTPS_PROXY": "http://proxy.company.com:8080",
"NO_PROXY": "localhost,127.0.0.1,.local"
}
}
```
### **SSL Configuration**
```json
{
"env": {
"NODE_TLS_REJECT_UNAUTHORIZED": "1", // Strict SSL
"SSL_CERT_PATH": "/path/to/cert.pem",
"SSL_KEY_PATH": "/path/to/key.pem"
}
}
```
### **Timeout Settings**
```json
{
"env": {
"API_TIMEOUT": "30000", // 30 seconds
"BROWSER_TIMEOUT": "60000", // 60 seconds
"CONNECT_TIMEOUT": "10000" // 10 seconds
}
}
```
---
## 📊 **Monitoring Configuration**
### **Health Check Settings**
```json
{
"env": {
"HEALTH_CHECK_ENABLED": "true",
"HEALTH_CHECK_INTERVAL": "30000", // 30 seconds
"HEALTH_CHECK_TIMEOUT": "5000" // 5 seconds
}
}
```
### **Metrics Collection**
```json
{
"env": {
"METRICS_ENABLED": "true",
"METRICS_INTERVAL": "60000", // 1 minute
"METRICS_ENDPOINT": "/metrics"
}
}
```
### **Error Reporting**
```json
{
"env": {
"ERROR_REPORTING_ENABLED": "true",
"ERROR_REPORTING_ENDPOINT": "https://errors.company.com/api",
"ERROR_REPORTING_API_KEY": "your_error_reporting_key"
}
}
```
---
## 🔧 **Configuration Validation**
### **Validation Script**
Create `scripts/validate-config.js`:
```javascript
#!/usr/bin/env node
import { readFileSync } from 'fs';
import { join } from 'path';
function validateConfig() {
try {
// Read Claude Desktop config
const configPath = join(process.env.HOME, 'Library/Application Support/Claude/claude_desktop_config.json');
const config = JSON.parse(readFileSync(configPath, 'utf8'));
// Validate MCP server config
const mcpConfig = config.mcpServers['euconquisto-composer-direct'];
if (!mcpConfig) {
throw new Error('MCP server configuration not found');
}
// Validate required environment variables
const requiredVars = [
'EUCONQUISTO_ACCESS_TOKEN',
'EUCONQUISTO_PROJECT_UID',
'EUCONQUISTO_CONNECTORS'
];
for (const varName of requiredVars) {
if (!mcpConfig.env[varName]) {
throw new Error(`Required environment variable ${varName} not set`);
}
}
console.log('✅ Configuration validation passed');
} catch (error) {
console.error('❌ Configuration validation failed:', error.message);
process.exit(1);
}
}
validateConfig();
```
### **Run Validation**
```bash
node scripts/validate-config.js
```
---
## 📋 **Configuration Templates**
### **Development Template**
Save as `config/claude-desktop-dev.json`:
```json
{
"mcpServers": {
"euconquisto-composer-direct": {
"command": "node",
"args": [
"--max-old-space-size=4096",
"--inspect=9229",
"REPLACE_WITH_PROJECT_PATH/dist/direct-api-server-v1.0.0.js"
],
"env": {
"EUCONQUISTO_ACCESS_TOKEN": "REPLACE_WITH_DEV_TOKEN",
"EUCONQUISTO_PROJECT_UID": "REPLACE_WITH_DEV_PROJECT_UID",
"EUCONQUISTO_CONNECTORS": "[{\"uid\":\"REPLACE_WITH_DEV_CONNECTOR_UID\",\"name\":null,\"type\":\"Composer_1\",\"permissions\":[]}]",
"NODE_ENV": "development",
"MCP_DEBUG": "true",
"DEBUG": "*",
"LOG_LEVEL": "debug"
}
}
}
}
```
### **Production Template**
Save as `config/claude-desktop-prod.json`:
```json
{
"mcpServers": {
"euconquisto-composer-direct": {
"command": "node",
"args": [
"--max-old-space-size=4096",
"REPLACE_WITH_PROJECT_PATH/dist/direct-api-server-v1.0.0.js"
],
"env": {
"EUCONQUISTO_ACCESS_TOKEN": "REPLACE_WITH_PROD_TOKEN",
"EUCONQUISTO_PROJECT_UID": "REPLACE_WITH_PROD_PROJECT_UID",
"EUCONQUISTO_CONNECTORS": "[{\"uid\":\"REPLACE_WITH_PROD_CONNECTOR_UID\",\"name\":null,\"type\":\"Composer_1\",\"permissions\":[]}]",
"NODE_ENV": "production",
"MCP_DEBUG": "false",
"LOG_LEVEL": "warn"
}
}
}
}
```
---
## 🆘 **Configuration Troubleshooting**
### **Common Issues**
1. **Path Issues**: Use absolute paths, not relative paths
2. **JSON Syntax**: Validate JSON syntax with a JSON validator
3. **Environment Variables**: Ensure all required variables are set
4. **Permissions**: Check file permissions for config files
5. **Token Format**: Verify JWT token format and expiration
### **Debug Steps**
1. **Validate JSON**: Use `json_verify` or online JSON validator
2. **Check Paths**: Verify all file paths exist and are accessible
3. **Test Environment**: Run `node -e "console.log(process.env)"` to check variables
4. **Validate Tokens**: Use JWT decoder to verify token structure
5. **Check Logs**: Enable debug mode and check Claude Desktop logs
---
**Last Updated**: January 21, 2025
**Version**: v1.1.0 Fail-Fast Reliability Suite
**Status**: ✅ COMPLETE - Comprehensive configuration reference for all scenarios