# hao-yicheng/macpdf-ocr-mcp architecture

> Architecture diagram of the GitHub repository hao-yicheng/macpdf-ocr-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hao-yicheng/macpdf-ocr-mcp
- Repository: https://github.com/hao-yicheng/macpdf-ocr-mcp

## Overview

macpdf-ocr-mcp is a local stdio MCP server that helps clients read PDFs and inspect image regions. The main workflow is a batched PDF read with PDFKit text extraction where available and Vision OCR when needed, plus optional previews and region hints; clients can then request a focused crop or save a region. The README documents four tools and their behavior. The excerpts show server and extraction paths but omit some implementations, so uncertain internal wiring is not expanded.

Main entry points: [`Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift`](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift) (PDF Read), [`Sources/macpdf-ocr-mcp/MCPStdIOServer.swift`](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/MCPStdIOServer.swift) (Stdio Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["MCP Interface"]
  node_entry["CLI Entry"]
  node_server["Stdio Server"]
end

subgraph group_reading["PDF Reading"]
  node_pdfread["PDF Read"]
  node_batch["Page Batching"]
  node_extract["Text Extraction"]
  node_pdfkit["PDFKit"]
  node_vision["Vision OCR"]
  node_render["Page Rendering"]
  node_regions["Region Hints"]
  node_artifacts[("Preview Files")]
end

subgraph group_regions["Region Tools"]
  node_focus["PDF Focus"]
  node_save["Save Region"]
  node_detect["Image OCR Regions"]
end

node_client(("MCP Client"))
node_pdf["PDF or Image"]

node_client -->|"sends MCP requests"| node_server
node_entry -->|"starts stdio"| node_server
node_server -->|"dispatches tool"| node_pdfread
node_server -->|"dispatches tool"| node_focus
node_server -->|"dispatches tool"| node_save
node_server -->|"dispatches tool"| node_detect
node_pdfread -->|"opens PDF"| node_pdf
node_pdfread -->|"limits pages"| node_batch
node_pdfread -->|"extracts page text"| node_extract
node_extract -->|"reads text"| node_pdfkit
node_extract -->|"runs OCR"| node_vision
node_pdfread -->|"renders previews"| node_render
node_pdfread -->|"derives hints"| node_regions
node_render -->|"writes previews"| node_artifacts
node_focus -->|"opens PDF"| node_pdf
node_focus -->|"extracts region text"| node_extract
node_focus -->|"renders crop"| node_render
node_save -->|"reads source"| node_pdf
node_save -->|"writes crop"| node_artifacts
node_detect -->|"reads image"| node_pdf
node_detect -->|"runs OCR"| node_vision

click node_entry "https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift"
click node_server "https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/MCPStdIOServer.swift"
click node_pdfread "https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift"
click node_batch "https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift"
click node_extract "https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift"
click node_render "https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift"
click node_regions "https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift"
click node_focus "https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift"
click node_save "https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift"
click node_detect "https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_server,node_client toneBlue
class node_pdfread,node_batch,node_extract,node_pdfkit,node_vision,node_render,node_regions,node_artifacts toneAmber
class node_focus,node_save,node_detect toneMint
class node_pdf toneIndigo
```

## Components

### MCP Interface

- [CLI Entry](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift): `Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift`
- [Stdio Server](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/MCPStdIOServer.swift): `Sources/macpdf-ocr-mcp/MCPStdIOServer.swift`

### PDF Reading

- [PDF Read](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift): `Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift`
- [Page Batching](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift): `Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift`
- [Text Extraction](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift): `Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift`
- **PDFKit**
- **Vision OCR**
- [Page Rendering](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift): `Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift`
- [Region Hints](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift): `Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift`
- **Preview Files**

### Region Tools

- [PDF Focus](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift): `Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift`
- [Save Region](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift): `Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift`
- [Image OCR Regions](https://github.com/hao-yicheng/macpdf-ocr-mcp/blob/main/Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift): `Sources/macpdf-ocr-mcp/macpdf_ocr_mcp.swift`

### Other components

- **MCP Client**
- **PDF or Image**

## Connections

- MCP Client → Stdio Server: sends MCP requests
- CLI Entry → Stdio Server: starts stdio
- Stdio Server → PDF Read: dispatches tool
- Stdio Server → PDF Focus: dispatches tool
- Stdio Server → Save Region: dispatches tool
- Stdio Server → Image OCR Regions: dispatches tool
- PDF Read → PDF or Image: opens PDF
- PDF Read → Page Batching: limits pages
- PDF Read → Text Extraction: extracts page text
- Text Extraction → PDFKit: reads text
- Text Extraction → Vision OCR: runs OCR
- PDF Read → Page Rendering: renders previews
- PDF Read → Region Hints: derives hints
- Page Rendering → Preview Files: writes previews
- PDF Focus → PDF or Image: opens PDF
- PDF Focus → Text Extraction: extracts region text
- PDF Focus → Page Rendering: renders crop
- Save Region → PDF or Image: reads source
- Save Region → Preview Files: writes crop
- Image OCR Regions → PDF or Image: reads image
- Image OCR Regions → Vision OCR: runs OCR