Adding a Document Parser

MIRA’s document parsing is done entirely in TypeScript inside a Node.js worker_threads worker (src/workers/document-parser.worker.ts). This keeps the main process unblocked during heavy I/O or CPU parsing. Adding a new format means extending this worker.

How parsers work

When a document is uploaded, src/main/document-parser.ts spawns a Worker from src/workers/document-parser.worker.ts. The worker receives a raw Buffer, detects the format by MIME type and file extension, and posts a ParseResult back:

// src/workers/document-parser.worker.ts (simplified return shape)
interface ParseResult {
  content: string // Full extracted text
  chunks: DocumentChunk[] // Pre-chunked text slices
  chunkCount: number
  metadata: Record<string, unknown> // Format-specific metadata
}

1. Add the npm dependency (if needed)

If your format requires a parsing library, add it to package.json:

npm install my-format-parser

For type definitions:

npm install -D @types/my-format-parser

2. Add the parser branch to the worker

In src/workers/document-parser.worker.ts, add a new if branch. The worker uses MIME type first, file extension as fallback:

// src/workers/document-parser.worker.ts — inside the run() function

// My custom format
if (mimeType === 'application/x-my-format' || ext === 'myext') {
  try {
    const { parseMyFormat } = await import('my-format-parser')
    const result = await parseMyFormat(buffer)
    content = result.text
    metadata.version = result.version
  } catch (e) {
    content = `[my-format parse error: ${e instanceof Error ? e.message : String(e)}]`
  }
}

3. Register the supported extension

In src/shared/constants.ts, add the extension to SUPPORTED_EXTENSIONS:

export const SUPPORTED_EXTENSIONS = [
  '.pdf',
  '.docx',
  '.txt',
  '.md',
  '.csv',
  '.json',
  '.py',
  '.js',
  '.ts',
  '.html',
  '.myext', // ← add here
] as const

4. Add the MIME type mapping

In src/shared/types.ts, add the MIME type to the DocumentMimeType union so TypeScript accepts it:

export type DocumentMimeType =
  | 'application/pdf'
  | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
  | 'text/plain'
  // ...existing types
  | 'application/x-my-format' // ← add here
  | string

5. Add the file extension to the upload dialog filter

In src/main/ipc-handlers.ts, find where skills:open-file-dialog and workflows:open-file-dialog define Electron dialog.showOpenDialog filters, and add your extension to the documents upload filter:

filters: [
  {
    name: 'Documents',
    extensions: ['pdf', 'docx', 'txt', 'md', 'csv', 'json', 'py', 'js', 'ts', 'html', 'myext'],
  },
]

6. Update docs

Add your new format to the table in Supported File Formats.

Edit this page — Open a pull request

Get Started

Core Concepts

Features

Eval Framework

Configuration

Developer Guide

Community

Reference

Adding a Document Parser

How parsers work

1. Add the npm dependency (if needed)

2. Add the parser branch to the worker

3. Register the supported extension

4. Add the MIME type mapping

5. Add the file extension to the upload dialog filter

6. Update docs

​How parsers work

​1. Add the npm dependency (if needed)

​2. Add the parser branch to the worker

​3. Register the supported extension

​4. Add the MIME type mapping

​5. Add the file extension to the upload dialog filter

​6. Update docs

How parsers work

1. Add the npm dependency (if needed)

2. Add the parser branch to the worker

3. Register the supported extension

4. Add the MIME type mapping

5. Add the file extension to the upload dialog filter

6. Update docs