cognitive-framework-mcp-server/DEPLOYMENT.md

MCP Server for Advanced Cognitive Framework - Provides sophisticated AI reasoning capabilities through standardized protocol

# 🚀 Deployment Guide - Cognitive Framework MCP Server

## Overview

This guide covers deploying the Advanced Cognitive Framework MCP Server in various environments, from development to production.

## 📋 Prerequisites

- Node.js 18+ 
- NPM or Yarn package manager
- Advanced Cognitive Framework XML file
- MCP-compatible client application

## 🛠️ Installation Methods

### Method 1: From Source

```bash
# Clone the repository
git clone https://github.com/cognitive-framework/mcp-server.git
cd cognitive-framework-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Test the installation
npm test
```

### Method 2: NPM Package (Future)

```bash
# Install globally
npm install -g cognitive-framework-mcp-server

# Or install locally
npm install cognitive-framework-mcp-server
```

## ⚙️ Configuration

### Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `FRAMEWORK_PATH` | Path to cognitive framework XML file | `/home/zrald/test/improve context` | Yes |
| `LOG_LEVEL` | Logging level (error, warn, info, debug) | `info` | No |
| `NODE_ENV` | Environment (development, production) | `development` | No |
| `PORT` | Server port (if using HTTP transport) | `3000` | No |

### Framework File Setup

1. **Prepare Framework File**
   ```bash
   # Copy your framework file to a accessible location
   cp "improve context" /opt/cognitive-framework/framework.xml
   
   # Set appropriate permissions
   chmod 644 /opt/cognitive-framework/framework.xml
   ```

2. **Validate Framework File**
   ```bash
   # Test framework parsing
   FRAMEWORK_PATH="/opt/cognitive-framework/framework.xml" node test-server.js
   ```

## 🐳 Docker Deployment

### Dockerfile

```dockerfile
FROM node:18-alpine

# Set working directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy built application
COPY dist/ ./dist/

# Copy framework file
COPY framework.xml ./framework.xml

# Set environment variables
ENV FRAMEWORK_PATH=/app/framework.xml
ENV NODE_ENV=production
ENV LOG_LEVEL=info

# Create non-root user
RUN addgroup -g 1001 -S mcp && \
    adduser -S mcp -u 1001

# Change ownership
RUN chown -R mcp:mcp /app
USER mcp

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "console.log('Health check passed')" || exit 1

# Start the server
CMD ["node", "dist/index.js"]
```

### Docker Compose

```yaml
version: '3.8'

services:
  cognitive-framework-mcp:
    build: .
    container_name: cognitive-framework-mcp-server
    restart: unless-stopped
    environment:
      - FRAMEWORK_PATH=/app/framework.xml
      - NODE_ENV=production
      - LOG_LEVEL=info
    volumes:
      - ./logs:/app/logs
      - ./framework.xml:/app/framework.xml:ro
    networks:
      - mcp-network
    healthcheck:
      test: ["CMD", "node", "-e", "console.log('Health check')"]
      interval: 30s
      timeout: 10s
      retries: 3

networks:
  mcp-network:
    driver: bridge
```

### Build and Run

```bash
# Build the Docker image
docker build -t cognitive-framework-mcp-server .

# Run with Docker Compose
docker-compose up -d

# Check logs
docker-compose logs -f cognitive-framework-mcp
```

## 🖥️ Systemd Service (Linux)

### Service File

Create `/etc/systemd/system/cognitive-framework-mcp.service`:

```ini
[Unit]
Description=Cognitive Framework MCP Server
Documentation=https://github.com/cognitive-framework/mcp-server
After=network.target
Wants=network.target

[Service]
Type=simple
User=mcp-server
Group=mcp-server
WorkingDirectory=/opt/cognitive-framework-mcp
ExecStart=/usr/bin/node dist/index.js
ExecReload=/bin/kill -HUP $MAINPID

# Environment
Environment=NODE_ENV=production
Environment=FRAMEWORK_PATH=/opt/cognitive-framework-mcp/framework.xml
Environment=LOG_LEVEL=info

# Restart policy
Restart=always
RestartSec=10
StartLimitInterval=60s
StartLimitBurst=3

# Security
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/cognitive-framework-mcp/logs

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=cognitive-framework-mcp

[Install]
WantedBy=multi-user.target
```

### Setup and Management

```bash
# Create user and directories
sudo useradd --system --shell /bin/false mcp-server
sudo mkdir -p /opt/cognitive-framework-mcp
sudo chown mcp-server:mcp-server /opt/cognitive-framework-mcp

# Copy application files
sudo cp -r dist/ /opt/cognitive-framework-mcp/
sudo cp framework.xml /opt/cognitive-framework-mcp/
sudo chown -R mcp-server:mcp-server /opt/cognitive-framework-mcp

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable cognitive-framework-mcp
sudo systemctl start cognitive-framework-mcp

# Check status
sudo systemctl status cognitive-framework-mcp

# View logs
sudo journalctl -u cognitive-framework-mcp -f
```

## ☁️ Cloud Deployment

### AWS ECS

```json
{
  "family": "cognitive-framework-mcp",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "executionRoleArn": "arn:aws:iam::account:role/ecsTaskExecutionRole",
  "containerDefinitions": [
    {
      "name": "cognitive-framework-mcp-server",
      "image": "your-registry/cognitive-framework-mcp-server:latest",
      "essential": true,
      "environment": [
        {
          "name": "FRAMEWORK_PATH",
          "value": "/app/framework.xml"
        },
        {
          "name": "NODE_ENV",
          "value": "production"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/cognitive-framework-mcp",
          "awslogs-region": "us-west-2",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}
```

### Kubernetes

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cognitive-framework-mcp-server
  labels:
    app: cognitive-framework-mcp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: cognitive-framework-mcp
  template:
    metadata:
      labels:
        app: cognitive-framework-mcp
    spec:
      containers:
      - name: cognitive-framework-mcp-server
        image: cognitive-framework-mcp-server:latest
        ports:
        - containerPort: 3000
        env:
        - name: FRAMEWORK_PATH
          value: "/app/framework.xml"
        - name: NODE_ENV
          value: "production"
        - name: LOG_LEVEL
          value: "info"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          exec:
            command:
            - node
            - -e
            - "console.log('Health check')"
          initialDelaySeconds: 30
          periodSeconds: 30
        readinessProbe:
          exec:
            command:
            - node
            - -e
            - "console.log('Ready check')"
          initialDelaySeconds: 5
          periodSeconds: 10
        volumeMounts:
        - name: framework-config
          mountPath: /app/framework.xml
          subPath: framework.xml
      volumes:
      - name: framework-config
        configMap:
          name: cognitive-framework-config
---
apiVersion: v1
kind: Service
metadata:
  name: cognitive-framework-mcp-service
spec:
  selector:
    app: cognitive-framework-mcp
  ports:
  - protocol: TCP
    port: 80
    targetPort: 3000
  type: ClusterIP
```

## 📊 Monitoring and Logging

### Logging Configuration

```javascript
// winston logger configuration
const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ 
      filename: 'logs/error.log', 
      level: 'error' 
    }),
    new winston.transports.File({ 
      filename: 'logs/combined.log' 
    }),
    new winston.transports.Console({
      format: winston.format.simple()
    })
  ]
});
```

### Health Checks

```bash
# Basic health check
curl -f http://localhost:3000/health || exit 1

# Framework validation check
node -e "
const { FrameworkParser } = require('./dist/parsers/framework-parser.js');
const parser = new FrameworkParser(process.env.FRAMEWORK_PATH);
parser.parseFramework()
  .then(() => console.log('Framework OK'))
  .catch(() => process.exit(1));
"
```

### Metrics Collection

```javascript
// Example metrics collection
const metrics = {
  requestsProcessed: 0,
  averageProcessingTime: 0,
  errorRate: 0,
  cacheHitRate: 0,
  activeConnections: 0
};

// Export metrics for Prometheus
app.get('/metrics', (req, res) => {
  res.set('Content-Type', 'text/plain');
  res.send(`
# HELP cognitive_requests_total Total number of requests processed
# TYPE cognitive_requests_total counter
cognitive_requests_total ${metrics.requestsProcessed}

# HELP cognitive_processing_time_avg Average processing time in milliseconds
# TYPE cognitive_processing_time_avg gauge
cognitive_processing_time_avg ${metrics.averageProcessingTime}
  `);
});
```

## 🔒 Security Considerations

### File Permissions

```bash
# Set secure permissions
chmod 600 /opt/cognitive-framework-mcp/framework.xml
chmod 755 /opt/cognitive-framework-mcp/dist/
chown -R mcp-server:mcp-server /opt/cognitive-framework-mcp/
```

### Network Security

```bash
# Firewall rules (if using HTTP transport)
sudo ufw allow from 10.0.0.0/8 to any port 3000
sudo ufw deny 3000
```

### Environment Security

```bash
# Use environment files for sensitive configuration
echo "FRAMEWORK_PATH=/secure/path/framework.xml" > .env
chmod 600 .env
```

## 🚨 Troubleshooting

### Common Issues

1. **Framework Parse Error**
   ```bash
   # Validate XML structure
   xmllint --noout framework.xml
   
   # Check file permissions
   ls -la framework.xml
   ```

2. **Memory Issues**
   ```bash
   # Increase Node.js memory limit
   node --max-old-space-size=4096 dist/index.js
   ```

3. **Permission Denied**
   ```bash
   # Check user permissions
   sudo -u mcp-server node dist/index.js
   ```

### Log Analysis

```bash
# View recent errors
tail -f logs/error.log

# Search for specific issues
grep "Framework" logs/combined.log

# Monitor system resources
htop
iostat -x 1
```

## 📈 Performance Tuning

### Node.js Optimization

```bash
# Production environment variables
export NODE_ENV=production
export NODE_OPTIONS="--max-old-space-size=2048"

# Enable clustering for multiple CPU cores
export UV_THREADPOOL_SIZE=16
```

### Caching Configuration

```javascript
// Optimize cache settings
const cache = new NodeCache({ 
  stdTTL: 3600,           // 1 hour default TTL
  checkperiod: 600,       // Check for expired keys every 10 minutes
  useClones: false,       // Improve performance
  maxKeys: 10000          // Limit memory usage
});
```

---

**Deployment Guide v1.0** - Advanced Cognitive Framework MCP Server