openclaw-mattermost-extension/docs/MIGRATION.md

Migration Guide

Guide for migrating from the stock Mattermost extension to the Enhanced Mattermost Extension.

Table of Contents

• Overview
• Before You Begin
• Configuration Migration
• Breaking Changes
• Feature Upgrades
• Code Migration
• Verification
• Rollback Plan

Overview

The Enhanced Mattermost Extension is a drop-in replacement for the stock extension with additional features and improved security. Most existing configurations will work without changes, but there are some differences to be aware of.

Key Differences

Aspect	Stock Extension	Enhanced Extension
Package name	@modelcontextprotocol/mattermost	@karti-ai/openclaw-mattermost
Token support	Bot token only	Bot token + PAT
Message operations	Send only	Send, edit, delete
File operations	None	Download with security
Interactive components	None	Buttons and selects
Security audit	None	Built-in
Error handling	Basic	Structured with retry
Configuration	Simple	Extended but backward compatible

Before You Begin

Prerequisites

1. Backup your configuration before making any changes
2. Review current usage of Mattermost features in your code
3. Check Node.js version - requires Node.js 22+ (up from 18+)
4. Plan for downtime during the migration window

Compatibility Check

Run this check to see if your current configuration is compatible:

# Install the enhanced extension alongside your current one
npm install @karti-ai/openclaw-mattermost

# Run the security audit to check configuration
npx openclaw doctor --channel=mattermost

Configuration Migration

Simple Migration (No Code Changes)

If you're using basic features, simply update your package.json:

{
  "dependencies": {
-   "@modelcontextprotocol/mattermost": "^0.x.x"
+   "@karti-ai/openclaw-mattermost": "^1.0.0"
  }
}

Your existing configuration will continue to work:

{
  "channels": {
    "mattermost": {
      "baseUrl": "https://chat.example.com",
      "botToken": "${MATTERMOST_BOT_TOKEN}",
      "team": "myteam"
    }
  }
}

Enhanced Configuration (Recommended)

Take advantage of new security features by updating your configuration:

Before (Stock Extension)

{
  "channels": {
    "mattermost": {
      "url": "https://chat.example.com",
      "token": "${MATTERMOST_TOKEN}",
      "team": "engineering"
    }
  }
}

After (Enhanced Extension)

{
  "channels": {
    "mattermost": {
      "baseUrl": "https://chat.example.com",
      "botToken": "${MATTERMOST_BOT_TOKEN}",
      "dmPolicy": "pairing",
      "allowFrom": ["user1-id", "user2-id"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["user1-id", "user2-id"],
      "interactions": {
        "callbackBaseUrl": "https://bot.example.com/callbacks",
        "allowedSourceIps": ["10.0.0.0/8"]
      },
      "actions": {
        "reactions": true,
        "downloadFile": true,
        "delete": true
      }
    }
  }
}

Multi-Account Configuration

The enhanced extension supports multiple Mattermost accounts:

{
  "channels": {
    "mattermost": {
      "accounts": {
        "production": {
          "baseUrl": "https://chat.company.com",
          "botToken": "${PROD_BOT_TOKEN}",
          "dmPolicy": "allowlist"
        },
        "staging": {
          "baseUrl": "https://chat-staging.company.com",
          "botToken": "${STAGING_BOT_TOKEN}",
          "dmPolicy": "open"
        }
      },
      "defaultAccount": "production"
    }
  }
}

Breaking Changes

1. Import Path Changes

Before:

import { sendMessage } from '@modelcontextprotocol/mattermost';

After:

import { sendMessage } from '@karti-ai/openclaw-mattermost';

2. Configuration Property Names

Some property names have changed for clarity:

Old Name	New Name	Notes
url	baseUrl	Both work, baseUrl preferred
token	botToken	Both work, botToken preferred

3. Environment Variable Names

If you used the stock extension's environment variables:

Old Variable	New Variable	Notes
MATTERMOST_URL	MATTERMOST_URL	No change
MATTERMOST_TOKEN	MATTERMOST_BOT_TOKEN	Recommended change
-	MATTERMOST_PAT	New optional PAT variable

Both old and new variable names are supported for backward compatibility.

4. Type Changes

Some TypeScript types have been renamed or extended:

Before:

import { MattermostConfig } from '@modelcontextprotocol/mattermost';

After:

import { MattermostAccountConfig, MattermostConfig } from '@karti-ai/openclaw-mattermost';

Feature Upgrades

Adding PAT Support

Step 1: Create a Personal Access Token in Mattermost

1. Log in to Mattermost as the bot owner
2. Go to Account Settings > Security > Personal Access Tokens
3. Create a new token

Step 2: Add PAT to your configuration

export MATTERMOST_PAT="your-pat-here"

{
  "channels": {
    "mattermost": {
      "baseUrl": "https://chat.example.com",
      "botToken": "${MATTERMOST_BOT_TOKEN}",
      "pat": "${MATTERMOST_PAT}"
    }
  }
}

Enabling Interactive Components

Add interaction configuration to enable buttons and selects:

{
  "channels": {
    "mattermost": {
      "baseUrl": "https://chat.example.com",
      "botToken": "${MATTERMOST_BOT_TOKEN}",
      "interactions": {
        "callbackBaseUrl": "https://your-bot.example.com/callbacks",
        "allowedSourceIps": ["10.0.0.0/8"]
      }
    }
  }
}

Enabling File Downloads

File downloads are enabled by default but can be controlled:

{
  "channels": {
    "mattermost": {
      "actions": {
        "downloadFile": true
      }
    }
  }
}

Code Migration

Sending Messages (No Change Required)

// Both versions work the same
import { sendMessage } from '@karti-ai/openclaw-mattermost';

await sendMessage({
  cfg: openclawConfig,
  channelId: 'channel123',
  message: 'Hello World'
});

Adding Reactions

Before: Limited or no support

After: Full support with type safety

import { addReaction } from '@karti-ai/openclaw-mattermost';

await addReaction({
  cfg: openclawConfig,
  postId: 'post123',
  emoji: 'thumbsup'
});

Editing Messages (New Feature)

import { editMessage } from '@karti-ai/openclaw-mattermost';

const result = await editMessage({
  cfg: openclawConfig,
  postId: 'post123',
  channelId: 'channel123',
  message: 'Updated content'
});

if (!result.ok) {
  console.error('Edit failed:', result.error);
}

Interactive Messages (New Feature)

const message = `
Please confirm:
[[mattermost_buttons: Yes:confirm:primary, No:cancel:danger]]
`;

await sendMessage({ cfg: openclawConfig, channelId: 'channel123', message });

File Downloads (New Feature)

import { downloadFile } from '@karti-ai/openclaw-mattermost';

const result = await downloadFile({
  cfg: openclawConfig,
  fileId: 'file123',
  destinationPath: '/tmp/download.pdf',
  maxSize: 50 * 1024 * 1024
});

if (result.ok) {
  console.log('Downloaded:', result.filePath);
}

Error Handling Improvements

Before: Basic error handling

try {
  await sendMessage({ cfg, channelId, message });
} catch (error) {
  console.error('Failed:', error);
}

After: Structured error handling with retry

import { MattermostError, isRetryableError } from '@karti-ai/openclaw-mattermost';

try {
  await sendMessage({ cfg, channelId, message });
} catch (error) {
  if (error instanceof MattermostError) {
    console.error(`[${error.code}] ${error.userMessage}`);
    
    if (error.retryable) {
      console.log(`Can retry after ${error.retryAfterMs}ms`);
    }
    
    if (error.code === 'AUTHENTICATION_FAILED') {
      // Refresh token and retry
    }
  }
}

Verification

After migration, verify everything works:

1. Run the Security Audit

import { collectMattermostSecurityAuditFindings } from '@karti-ai/openclaw-mattermost';

const findings = await collectMattermostSecurityAuditFindings({
  cfg: openclawConfig,
  accountId: 'default',
  account: resolvedAccount
});

const critical = findings.filter(f => f.severity === 'critical');
if (critical.length > 0) {
  console.error('Critical security issues found:', critical);
  process.exit(1);
}

2. Test Basic Operations

// Test connection
const me = await fetchMattermostMe(client);
console.log('Connected as:', me.username);

// Test message sending
const post = await sendMessage({ cfg, channelId: testChannel, message: 'Test' });
console.log('Sent message:', post.id);

// Test message editing
const editResult = await editMessage({
  cfg,
  postId: post.id,
  channelId: testChannel,
  message: 'Updated test'
});
console.log('Edit result:', editResult.ok);

// Test message deletion
const deleteResult = await deleteMessage({
  cfg,
  postId: post.id,
  channelId: testChannel
});
console.log('Delete result:', deleteResult.ok);

3. Checklist

• Messages send successfully
• Messages can be edited
• Messages can be deleted
• Reactions can be added
• Files can be downloaded (if enabled)
• Interactive components render (if configured)
• No critical security audit findings
• Error handling works as expected
• Rate limiting is handled gracefully

Rollback Plan

If you need to rollback to the stock extension:

Step 1: Revert Package

npm uninstall @karti-ai/openclaw-mattermost
npm install @modelcontextprotocol/mattermost

Step 2: Revert Configuration

Remove any enhanced-specific configuration:

{
  "channels": {
    "mattermost": {
      "url": "https://chat.example.com",
-     "baseUrl": "https://chat.example.com",
-     "botToken": "${MATTERMOST_BOT_TOKEN}",
-     "pat": "${MATTERMOST_PAT}",
-     "dmPolicy": "pairing",
+     "token": "${MATTERMOST_TOKEN}",
-     "interactions": { ... },
-     "actions": { ... }
    }
  }
}

Step 3: Revert Code Changes

Change imports back:

- import { sendMessage } from '@karti-ai/openclaw-mattermost';
+ import { sendMessage } from '@modelcontextprotocol/mattermost';

Remove any code using enhanced-only features:

• Message editing
• Message deletion
• File downloads
• Interactive components
• Security audit calls

Troubleshooting Migration Issues

Issue: "Cannot find module"

Solution: Ensure the package is installed:

npm install @karti-ai/openclaw-mattermost

Issue: "Configuration validation failed"

Solution: Check for legacy configuration properties:

import { MattermostConfigSchema } from '@karti-ai/openclaw-mattermost';

const result = MattermostConfigSchema.safeParse(yourConfig);
if (!result.success) {
  console.error('Config errors:', result.error.errors);
}

Issue: "Authentication failed"

Solution: Verify token format and permissions:

# Test token with curl
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://chat.example.com/api/v4/users/me

Issue: "Interactive components not working"

Solution: Check interaction callback configuration:

1. Verify interactions.callbackBaseUrl is HTTPS
2. Ensure allowedSourceIps includes your Mattermost server
3. Check that the callback endpoint is accessible
4. Verify Mattermost can reach your callback URL

Issue: "File download blocked"

Solution: Check file restrictions:

1. Verify file is not an executable type
2. Check file size against maxSize limit
3. Ensure bot has file access permissions
4. Check MIME type is in allowlist

Getting Help

If you encounter issues during migration:

1. Check the security audit output for configuration issues
2. Review the API Reference for correct usage
3. Search GitHub Issues for similar problems
4. Create a new issue with:
   • Your migration step
   • Error messages
   • Configuration (with secrets redacted)
   • Expected vs actual behavior

Migration Summary

Task	Effort	Notes
Package update	5 min	Simple npm/pnpm/yarn command
Basic config migration	10 min	Property name changes
PAT setup (optional)	15 min	Create token, update config
Interactive components	30 min	Add interaction config
Code migration	1-2 hours	Update imports, add features
Testing	30 min	Verify all operations work
Security audit	15 min	Fix any findings

Total estimated time: 2-4 hours for a complete migration with all features.