# **LibreOffice MCP (WIP)**

### Explanation of the Refactor

#### **Why OooDev?**

The OooDev library, as detailed in `api_documentation.md`, provides a Pythonic abstraction over the LibreOffice UNO API, with classes like `CalcDoc`, `WriteDoc`, and utilities for charts, forms, and macros. It simplifies tasks like document creation, cell manipulation, and styling, reducing the need for low-level UNO interface queries (e.g., `UnoRuntime.queryInterface`). OooDev also supports modern Python features (e.g., type hints, context managers) and integrates with extensions like APSO and OooDev.oxt, making it ideal for a 1:1 MCP mapping.

#### **Key Changes from Your Original Implementation**

1. **OooDev Integration**:

   - Replaced direct UNO API calls (e.g., `XSpreadsheetDocument`, `XTextDocument`) with OooDev classes (`CalcDoc`, `WriteDoc`).
   - Used OooDev’s `Lo` class to manage LibreOffice connections, replacing manual `UnoUrlResolver` setup.
   - Leveraged OooDev utilities like `Calc`, `Write`, and `Chart2` for document operations.

2. **Preserved Features**:

   - Kept all your original tools: `open_document`, `close_document`, `get_sheet_names`, `get_cell_value`, `set_cell_value`, `create_new_sheet`, `insert_text`, `create_chart`, and `apply_style`.
   - Enhanced these tools to use OooDev methods (e.g., `CalcDoc.get_sheet_names()` instead of `XSpreadsheetDocument.getSheets()`).
   - Maintained the `parse_cell_address` helper, though OooDev’s `CalcDoc.rng()` method reduces its necessity in some cases.

3. **New Base Tools**:

   - Added `run_query`, `list_tables`, `create_table`, and `insert_data` to support LibreOffice Base operations, using OooDev’s database access methods.
   - These tools align with the `com::sun::star::sdb` namespace from `api.md` but use OooDev’s simplified interfaces.

4. **New Data Analysis Tools**:

   - Added `create_pivot_table`, `sort_range`, and `calculate_statistics` to enhance Calc’s data analysis capabilities.
   - Used OooDev’s `Chart2` module for pivot table creation and `Calc` module for sorting and statistics.

5. **Additional Tools**:
   - Added `new_document` to create new documents of various types, leveraging OooDev’s `create_doc` methods.
   - Added `save_document` to save documents using OooDev’s `save_doc`.
   - Added `run_macro` to execute Python macros, using OooDev’s `MacroLoader` context manager.
   - Added `insert_form_control` to insert form controls in Calc sheets, using OooDev’s `Forms` module.

#### **Alignment with OooDev Features**

- **Document Management**: Uses `WriteDoc`, `CalcDoc`, `DrawDoc` for Writer, Calc, Draw, and Impress documents, covering `com::sun::star::text`, `sheet`, `draw`, and `presentation` namespaces.
- **Base Operations**: Leverages OooDev’s database access for `com::sun::star::sdb` and `sdbc` functionalities.
- **Data Analysis**: Utilizes OooDev’s `Chart2` and `Calc` modules for pivot tables, sorting, and statistics, aligning with `com::sun::star::chart2` and `sheet`.
- **Forms and Macros**: Incorporates OooDev’s `Forms` and `MacroLoader` for `com::sun::star::form` and `script` namespaces.
- **Styling**: Uses OooDev’s style methods (e.g., `Write.style`) for `com::sun::star::style`.

#### **Benefits of the Refactor**

- **Pythonic Interface**: OooDev’s classes and methods are more intuitive and reduce boilerplate compared to UNO’s interface queries.
- **Comprehensive Coverage**: The adapter covers a broad range of OooDev functionalities, from basic document operations to advanced database and analysis tasks.
- **Maintainability**: OooDev’s abstractions simplify maintenance and future expansions (e.g., adding Math or more form controls).
- **Error Handling**: Robust error checking ensures reliability for LLM interactions via MCP.

#### **Limitations and Future Enhancements**

- **Base Document Handling**: The current Base tools use raw UNO interfaces for database operations, as OooDev’s Base support is less developed. Future versions could integrate OooDev’s Base-specific classes if added.
- **Additional Tools**: More OooDev features (e.g., `ooodev.units` for unit conversions, `ooodev.form` for advanced forms, `ooodev.draw` for shapes) could be added as tools.
- **Performance**: OooDev’s abstractions may introduce slight overhead; caching (e.g., `Lo.cache`) could be implemented for frequent operations.

#### **How to Use**

1. **Setup**: Ensure OooDev is installed (`pip install ooo-dev-tools`) and LibreOffice is running with a socket connection (port 2083).
2. **Run the Server**: Start the FastAPI server with this adapter.
3. **Interact via MCP**: Use the MCP client to call tools like `open_document`, `run_query`, or `create_pivot_table`.

- **Coverage Across Applications**: The adapter now supports Writer, Calc, Impress, and Draw, with potential for more Base and Math tools to be added.
- **Rich Feature Set**: It includes not just basic operations (e.g., opening documents, setting cell values) but also advanced features like styling, table insertion, image handling, charting, slide management, and shape drawing.
- **Cross-Cutting Functionality**: Tools like saving, exporting to PDF, and managing document properties apply to all LibreOffice document types, enhancing versatility.
- **Error Handling**: Each tool includes robust checks (e.g., document existence, type validation) to ensure reliability.

## **Old Documetnation**

```
sudo useradd -m -s /bin/bash mcp-libreoffice
sudo mkdir -p /home/mcp-libreoffice/output
sudo chown -R mcp-libreoffice:mcp-libreoffice /home/mcp-libreoffice
```

```
sudo -u mcp-libreoffice soffice --headless --accept="socket,host=localhost,port=${LIBREOFFICE_PORT:-2083};urp;"
```

### **Original Features**:

- **`open_document`**: Opens a document from a URL and assigns it an ID.
- **`close_document`**: Closes a document by its ID.
- **`get_sheet_names`**: Retrieves all sheet names from a Calc spreadsheet.
- **`get_cell_value`**: Gets the value (numeric, text, or formula) of a specified cell in a Calc sheet.
- **`set_cell_value`**: Sets a cell’s value in a Calc sheet, handling both numbers and text.
- **`get_text_content`**: Retrieves the full text content of a Writer document.
- **`insert_text`**: Inserts text at a specific position in a Writer document.
- **`create_chart`**: Creates a chart in a Calc sheet based on a data range and chart type.
- **`parse_cell_address`**: Helper function to convert cell addresses (e.g., "A1") to column and row indices.
- **Spreadsheet Enhancements (Calc)**:
  - **`create_new_sheet`**: Adds a new sheet to a spreadsheet.
  - **`set_cell_formula`**: Sets a formula in a spreadsheet cell (e.g., "=SUM(A1:A10)").
- **Text Document Enhancements (Writer)**:
  - **`insert_table`**: Inserts a table with specified rows and columns at a position.
  - **`apply_style`**: Applies a paragraph style to a text range.
  - **`insert_image`**: Inserts an image from a URL at a specified position.
- **Additional Document Management**:
  - **`save_document`**: Saves a document to a URL with a specified filter (e.g., "writer8" for ODT).
  - **`export_to_pdf`**: Exports a document to PDF format.
  - **`get_document_properties`**: Retrieves metadata like title, author, subject, and keywords.
  - **`set_document_properties`**: Updates document metadata.
- **Presentation Tools (Impress)**:
  - **`insert_slide`**: Inserts a new slide at a specified position in a presentation.
- **Drawing Tools (Draw)**:
  - **`add_shape`**: Adds a shape (e.g., rectangle, circle) to a Draw page with position and size.
- **Macro Execution**:
  - **`run_macro`**: Runs a Basic macro stored in the document.

### Base Tools

The following tools further enhance database management capabilities:

- **`list_tables(doc_id: str) -> list[str]`**: Retrieves a list of all table names in the database.
- **`delete_table(doc_id: str, table_name: str) -> str`**: Deletes a specified table from the database.
- **`insert_data(doc_id: str, table_name: str, data: dict) -> str`**: Inserts a single row of data into a table, with column names and values provided as a dictionary.
- **List Tables**: Use `list_tables("doc_id")` to get all table names in a database.
- **Delete Table**: Call `delete_table("doc_id", "table_name")` to remove a table.
- **Insert Data**: Use `insert_data("doc_id", "table_name", {"ID": 1, "Name": "Test"})` to add a row.

### Data Analysis Tools

These tools extend Calc’s data analysis capabilities:

- **`create_chart(doc_id: str, sheet_name: str, data_range: str, chart_type: str, target_cell: str) -> str`**: Creates a chart (e.g., bar, line) from a data range and places it at the target cell.
- **`apply_conditional_formatting(doc_id: str, sheet_name: str, range_address: str, condition: str, style: str) -> str`**: Applies conditional formatting to a range based on a condition (e.g., "value > 10") and a style.
- **`group_range(doc_id: str, sheet_name: str, range_address: str, by_rows: bool) -> str`**: Groups rows or columns in a range for outlining purposes.
- **Create Chart**: Use `create_chart("doc_id", "Sheet1", "A1:B10", "bar", "C12")` to create a bar chart.
- **Conditional Formatting**: Apply with `apply_conditional_formatting("doc_id", "Sheet1", "A1:A10", "A1>10", "Good")`, assuming "Good" is a defined cell style.

#### **Potential Additions**

- **Base Tools**: Create databases, manage forms, or run queries.
- **Math Tools**: Insert and edit mathematical formulas.
- **Formatting Tools**: Adjust font size, color, or alignment in Writer or Impress.
- **Animation/Transition Tools**: Add animations to Impress slides.
- **Data Analysis Tools**: Implement pivot tables or sorting in Calc.