# ODT MCP Server

[![npm version](https://badge.fury.io/js/odt-mcp-server.svg)](https://badge.fury.io/js/odt-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3%2B-blue)](https://www.typescriptlang.org/)

A Model Context Protocol (MCP) server for handling OpenDocument Text (.odt) files. This server enables AI assistants to read, analyze, and extract data from ODT documents.

## Features

- **Read ODT text**: Extract clean text from ODT documents
- **Get metadata**: Retrieve document information like author, title, date, etc.
- **List archive contents**: See all files contained in the ODT archive
- **Extract raw XML**: Access the underlying XML files (content.xml, styles.xml, meta.xml)

## Prerequisites

- **Node.js** v18.0.0 or later
- **npm** (included with Node.js)

## Installation

```bash
npm install
npm run build
npm link
```

## Quick Start

### 🚀 Try the Interactive Demo

```bash
# Run the full-featured demo
cd examples
node demo.js

# Or test with your own ODT file  
node demo.js path/to/your/file.odt
```

### As MCP Server

The server is designed to be used as an MCP server with AI assistants like Claude or other MCP-compatible clients.

```bash
# Run the server directly
./build/index.js

# Or after npm link, run globally
odt-mcp-server
```

### Available Tools

#### 1. `read_odt`
Reads and extracts clean text from an ODT file.

**Input:**
- `file_path` (string): Path to the ODT file

**Output:** Clean text from the document

#### 2. `get_odt_metadata` 
Retrieves metadata from the ODT file's meta.xml.

**Input:**
- `file_path` (string): Path to the ODT file

**Output:** JSON object with document metadata

#### 3. `list_odt_files`
Lists all files in the ODT archive.

**Input:**
- `file_path` (string): Path to the ODT file

**Output:** List of filenames in the archive

#### 4. `extract_odt_xml`
Extracts raw XML content from a specific file in the ODT archive.

**Input:**
- `file_path` (string): Path to the ODT file
- `xml_file` (string): Name of the XML file (e.g., 'content.xml', 'styles.xml', 'meta.xml')

**Output:** Raw XML content

## MCP Configuration

To use this server with an MCP client, add the following to your configuration:

```json
{
  "mcpServers": {
    "odt": {
      "command": "odt-mcp-server"
    }
  }
}
```

**Note:** After running `npm link`, the `odt-mcp-server` command will be globally available.

## Development

```bash
# Build the project
npm run build

# Build in watch mode
npm run watch
```

## Technical Details

- **Runtime**: Node.js with ES modules
- **Dependencies**: 
  - `@modelcontextprotocol/sdk`: MCP SDK
  - `adm-zip`: ZIP archive handling
  - `xml2js`: XML parsing
- **Type definitions**: Full TypeScript support

## About the ODT Format

OpenDocument Text (.odt) files are ZIP archives that contain:
- `content.xml`: The document's main content
- `meta.xml`: Metadata (author, title, etc.)
- `styles.xml`: Formatting and styles
- `META-INF/manifest.xml`: Archive manifest
- Other resources (images, fonts, etc.)

This server provides structured access to all these components through the MCP protocol.

## Contributing

Contributions are welcome! Here's how you can help:

1. **Report Issues**: Found a bug or have a feature request? [Open an issue](https://github.com/PeterHeick/odt-mcp-server/issues)
2. **Submit Pull Requests**: Fork the repository, make your changes, and submit a pull request
3. **Improve Documentation**: Help make the documentation clearer and more comprehensive
4. **Test with ODT Files**: Test with various ODT files and report compatibility issues

### Development Setup

```bash
git clone https://github.com/PeterHeick/odt-mcp-server.git
cd odt-mcp-server
npm install
npm run build
npm run watch  # For development with auto-rebuild
```

Please ensure your code follows the existing style and includes appropriate tests.

## License

MIT - Feel free to use this project for any purpose, commercial or non-commercial. See the full license text for details.