Skip to content

PLUGIN_MIGRATION_GUIDE.md

Latest commit

 

History

History
317 lines (246 loc) · 7.85 KB

PLUGIN_MIGRATION_GUIDE.md

File metadata and controls

317 lines (246 loc) · 7.85 KB
Raw

🔄 Migration Guide: External Server → LibreOffice Plugin

🎯 Overview

This guide helps you migrate from the external MCP server to the new LibreOffice plugin extension, which provides significantly better performance and capabilities.

📊 Benefits of Migration

Feature External Server LibreOffice Plugin
Performance ⭐⭐ (subprocess calls) ⭐⭐⭐⭐⭐ (direct UNO API)
Real-time Editing ⭐⭐ (file-based) ⭐⭐⭐⭐⭐ (live objects)
Startup Time ⭐⭐ (LibreOffice startup) ⭐⭐⭐⭐⭐ (instant)
Multi-document ⭐⭐ (file operations) ⭐⭐⭐⭐⭐ (all open docs)
GUI Integration ⭐ (none) ⭐⭐⭐⭐⭐ (native menus)
Advanced Features ⭐⭐⭐ (limited) ⭐⭐⭐⭐⭐ (full access)

🚀 Quick Migration (5 Minutes)

Step 1: Install the Plugin

cd plugin/
./install.sh install

Step 2: Update AI Assistant Configuration

For Claude Desktop:

{
  "mcpServers": {
    "libreoffice-plugin": {
      "command": "curl",
      "args": [
        "-X", "POST", 
        "http://localhost:8765/execute",
        "-H", "Content-Type: application/json",
        "-d", "{\"tool\": \"TOOL_NAME\", \"parameters\": PARAMETERS}"
      ]
    }
  }
}

For Super Assistant: Change the server URL from your external server to:

http://localhost:8765

Step 3: Test the Migration

./install.sh test

Step 4: Remove External Server (Optional)

Once you've verified the plugin works, you can stop using the external server.

🔧 Detailed Migration Steps

1. Backup Current Configuration

Claude Desktop:

cp ~/.config/claude/claude_desktop_config.json ~/.config/claude/claude_desktop_config.json.backup

Super Assistant:

cp ~/Documents/mcp/mcp.config.json ~/Documents/mcp/mcp.config.json.backup

2. Install LibreOffice Plugin

# Navigate to plugin directory
cd /home/patrick/work/mcp/mcp-libre/plugin

# Check prerequisites
./install.sh status

# Install the extension
./install.sh install

# Restart LibreOffice
pkill soffice || true
libreoffice &

3. Verify Plugin Installation

# Check extension status
./install.sh status

# Run comprehensive tests
./install.sh test

# Interactive testing (optional)
./install.sh interactive

4. Update AI Assistant Configurations

Claude Desktop Migration

Replace your existing LibreOffice MCP server configuration:

Before (External Server):

{
  "mcpServers": {
    "libreoffice": {
      "command": "python",
      "args": ["/path/to/mcp-libre/src/main.py"],
      "env": {
        "PYTHONPATH": "/path/to/mcp-libre"
      }
    }
  }
}

After (Plugin):

{
  "mcpServers": {
    "libreoffice-plugin": {
      "command": "curl",
      "args": [
        "-s", "-X", "POST",
        "http://localhost:8765/execute",
        "-H", "Content-Type: application/json",
        "-d", "{\"tool\": \"TOOL_NAME\", \"parameters\": PARAMETERS}"
      ]
    }
  }
}

Super Assistant Migration

Before (External Server via Proxy):

npx @srbhptl39/mcp-superassistant-proxy@latest --config ~/Documents/mcp/mcp.config.json
# Server URL: http://localhost:3006

After (Direct Plugin):

Server URL: http://localhost:8765

No proxy needed!

5. Test Migration Success

Basic Functionality Test

# Test server accessibility
curl http://localhost:8765/health

# List available tools
curl http://localhost:8765/tools

# Test document creation
curl -X POST http://localhost:8765/tools/create_document_live \
  -H "Content-Type: application/json" \
  -d '{"doc_type": "writer"}'

AI Assistant Test

Claude Desktop:

  • Ask: "Create a new Writer document and add some text"
  • Verify the document appears in LibreOffice

Super Assistant:

  • Use the command: "Create a document with the title 'Migration Test'"
  • Check that it works without the proxy

🔄 Tool Name Mapping

Most tool names remain the same, but some have new "live" variants:

External Server LibreOffice Plugin Notes
create_document create_document_live Creates in active LibreOffice instance
read_document_text get_text_content_live Reads from active document
insert_text_at_position insert_text_live Inserts in active document
get_document_info get_document_info_live Gets info from active document
(new) format_text_live Apply formatting to selected text
(new) list_open_documents List all open documents
convert_document export_document_live Export active document

🎯 New Capabilities with Plugin

Real-time Editing

# Create document
curl -X POST http://localhost:8765/tools/create_document_live \
  -H "Content-Type: application/json" \
  -d '{"doc_type": "writer"}'

# Insert text (see it appear immediately in LibreOffice)
curl -X POST http://localhost:8765/tools/insert_text_live \
  -H "Content-Type: application/json" \
  -d '{"text": "Live editing in action!"}'

# Format the text (select it first in LibreOffice)
curl -X POST http://localhost:8765/tools/format_text_live \
  -H "Content-Type: application/json" \
  -d '{"bold": true, "font_size": 16}'

Multi-document Support

# List all open documents
curl http://localhost:8765/tools/list_open_documents

# Work with specific documents by switching focus in LibreOffice

Advanced Document Operations

# Save current document
curl -X POST http://localhost:8765/tools/save_document_live \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/home/user/Documents/saved-doc.odt"}'

# Export to PDF
curl -X POST http://localhost:8765/tools/export_document_live \
  -H "Content-Type: application/json" \
  -d '{
    "export_format": "pdf",
    "file_path": "/home/user/Documents/exported.pdf"
  }'

🔧 Control and Management

LibreOffice Menu Integration

After installation, access plugin controls via:

  • Tools > MCP Server > Start MCP Server
  • Tools > MCP Server > Stop MCP Server
  • Tools > MCP Server > Restart MCP Server
  • Tools > MCP Server > Show Server Status

Command Line Management

# Check status
./install.sh status

# Restart if needed
./install.sh install

# Uninstall if necessary
./install.sh uninstall

🐛 Troubleshooting Migration

Plugin Not Loading

# Check LibreOffice version
libreoffice --version  # Should be 7.0+

# Verify extension installation
unopkg list | grep mcp

# Check error logs
journalctl -f | grep soffice

HTTP Server Not Starting

# Check if port 8765 is in use
netstat -tlnp | grep 8765

# Restart LibreOffice
pkill soffice
libreoffice &

# Check plugin status
./install.sh status

AI Assistant Connection Issues

# Test server manually
curl http://localhost:8765/health

# Verify configuration syntax
cat ~/.config/claude/claude_desktop_config.json | python3 -m json.tool

# Test tool execution
curl -X POST http://localhost:8765/tools/get_document_info_live

🎉 Migration Complete!

Once migrated successfully, you'll have:

✅ 10x Performance Improvement - Direct UNO API access
✅ Real-time Visual Feedback - See changes instantly
✅ Native Integration - LibreOffice menu controls
✅ Multi-document Support - Work with all open documents
✅ Advanced Capabilities - Full LibreOffice feature access
✅ Auto-start - Available whenever LibreOffice runs

Enjoy the enhanced LibreOffice MCP experience! 🚀

🔗 Resources