libreoffice-mcp

# **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.