> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mira-app.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding a Document Parser

> Extend MIRA's document context with support for new file formats.

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:

```typescript theme={null}
// 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`:

```bash theme={null}
npm install my-format-parser
```

For type definitions:

```bash theme={null}
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:

```typescript theme={null}
// 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`:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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](../features/document-context/supported-formats).

<Note>
  Edit this page — [Open a pull
  request](https://github.com/satyendra2013/mira-app/edit/main/docs/developer-guide/adding-parser.mdx)
</Note>