# Nudocs MCP Server

An MCP (Model Context Protocol) server for [Nudocs.ai](https://nudocs.ai) - a document processing service by [Nutrient](https://www.nutrient.io).

## Features

This MCP server provides the following tools for working with Nudocs documents:

- **list_documents** - List all Nudocs documents
- **read_document** - Read document content as Markdown
- **get_document_access_link** - Get a shareable access link to a document
- **download_document** - Download documents in various formats
- **upload_file** - Upload files to Nudocs
- **delete_document** - Delete documents by ID
- **list_top_level_elements** - List top-level elements with IDs and text previews
- **find_elements_by_text** - Find element IDs by visible text
- **replace_paragraph_text** - Replace paragraph text while preserving inline formatting when possible
- **insert_paragraph_text** - Insert one plain-text paragraph at an anchor
- **insert_table** - Insert a table from plain-text cells
- **move_element** - Move one paragraph/table before or after a target paragraph
- **delete_element** - Delete one paragraph, table, or image by ID
- **set_paragraph_style** - Set paragraph style (`normal`, headings, bullet/number list)
- **insert_image** - Insert one image from URL at an anchor

### Recommended Edit Workflow

1. Discover IDs with `list_top_level_elements` or `find_elements_by_text`.
2. Apply the specific edit tool for the operation you want.
3. Verify result with `read_document`.

All editing tools use object-only payloads and simple, LLM-friendly inputs.

```json
{
  "documentId": "01H...",
  "text": "Anchor paragraph."
}
```

```json
{
  "documentId": "01H...",
  "id": "p-AAAAAAAAAAAAAAAAAAAAAA",
  "text": "Updated text"
}
```

```json
{
  "documentId": "01H...",
  "anchorId": "p-AAAAAAAAAAAAAAAAAAAAAA",
  "edge": "end",
  "rows": [
    ["A1", "B1"],
    ["A2", "B2"]
  ]
}
```

The first payload above is a complete `find_elements_by_text` call. The second is a
`replace_paragraph_text` call. The third is an `insert_table` call.

Successful edit responses include `summary` plus machine-readable metadata:
`affectedElementIds`, `idMap`, and `invalidatedSelectors`.
If Nudocs returns a conflict (`EDIT_CONFLICT`), the MCP error payload includes structured
details such as latest version/revision hints.

### Supported File Formats

**Input formats** (upload):
- Markdown (`.md`)
- HTML (`.html`, `.xhtml`)
- LaTeX (`.latex`, `.tex`)
- reStructuredText (`.rst`)
- Org mode (`.org`)
- Textile (`.textile`)
- DocBook XML
- EPUB (`.epub`)
- MediaWiki (`.wiki`)
- Jupyter Notebook (`.ipynb`)
- OpenDocument Text (`.odt`)
- Microsoft Word (`.doc`, `.docx`)
- Rich Text Format (`.rtf`)
- Plain Text (`.txt`)
- PDF (`.pdf`)

**Output formats** (download):
- Markdown (`.md`)
- HTML (`.html`, `.xhtml`)
- LaTeX (`.latex`, `.tex`)
- PDF (`.pdf`)
- reStructuredText (`.rst`)
- Org mode (`.org`)
- Textile (`.textile`)
- DocBook XML
- EPUB (`.epub`)
- Microsoft Word (`.doc`, `.docx`)
- OpenDocument Text (`.odt`)
- Rich Text Format (`.rtf`)
- Plain Text (`.txt`)
- MediaWiki (`.wiki`)
- AsciiDoc (`.adoc`, `.asciidoc`)
- Jupyter Notebook (`.ipynb`)

## Prerequisites

- Node.js >= 18.0.0
- A Nudocs account with an API key ([sign up at nudocs.ai](https://nudocs.ai))

## Configuration

### Environment Variables

Set your Nudocs API key:

```bash
export NUDOCS_API_KEY=your_api_key_here
```

You can find your API key in your Nudocs account settings.

## Integration

### Claude Desktop

Add this server to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "nudocs": {
      "command": "npx",
      "args": ["-y", "@nutrient-sdk/nudocs-mcp-server"],
      "env": {
        "NUDOCS_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

After updating the configuration, completely quit and restart Claude Desktop. You'll see an MCP indicator in the bottom-right corner of the chat input when successfully connected.

### Claude Code

Claude Code supports three configuration levels:

#### Local Configuration (Project-specific)
Create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "nudocs": {
      "command": "npx",
      "args": ["-y", "@nutrient-sdk/nudocs-mcp-server"],
      "env": {
        "NUDOCS_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

#### Global Configuration (All projects)
Create or edit `~/.claude.json`:

```json
{
  "mcpServers": {
    "nudocs": {
      "command": "npx",
      "args": ["-y", "@nutrient-sdk/nudocs-mcp-server"],
      "env": {
        "NUDOCS_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

#### Using the CLI
You can also use Claude Code's built-in configuration wizard:

```bash
claude mcp add --transport stdio nudocs --env NUDOCS_API_KEY=YOUR_KEY -- npx -y @nutrient-sdk/nudocs-mcp-server
```

### OpenAI Codex

OpenAI Codex supports MCP servers through its CLI and IDE extension.

#### Using the CLI
The easiest way to add the Nudocs MCP server:

```bash
codex mcp add nudocs --env NUDOCS_API_KEY=YOUR_KEY -- npx -y @nutrient-sdk/nudocs-mcp-server
```

#### Manual Configuration
Edit `~/.codex/config.toml` to add the server:

```toml
[mcp.nudocs]
command = "npx"
args = ["-y", "@nutrient-sdk/nudocs-mcp-server"]

[mcp.nudocs.env]
NUDOCS_API_KEY = "your_api_key_here"
```

The configuration file is shared between the Codex CLI and IDE extension, so you only need to configure it once.

For more information, visit the [OpenAI Codex MCP documentation](https://developers.openai.com/codex/mcp/).

## Development

### Building from Source

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

### Running Locally

```bash
npm run dev
```

### Unit Tests

```bash
npm run test:unit
```

### Testing with MCP Inspector

The MCP Inspector allows you to test the server interactively:

```bash
npm run inspector
```

## Issues & Support

Report issues at: https://github.com/PSPDFKit/nudocs-mcp-server/issues

## License

See [LICENSE](LICENSE) file for details.

---

Made by [Nutrient](https://www.nutrient.io) | Powered by [Nudocs.ai](https://nudocs.ai)