bh-pdfdoc-reader

<p align="center"> <h1 align="center">📄 bh-pdfdoc-reader</h1> <p align="center"> <strong>Lightweight document reader for AI-powered IDEs</strong> </p> <p align="center"> Read PDF & DOCX files directly in Cursor, Windsurf, VS Code, Antigravity, and Claude Desktop via MCP </p> <p align="center"> <a href="#installation">Installation</a> • <a href="#mcp-integration">MCP Integration</a> • <a href="#cli-usage">CLI Usage</a> • <a href="#supported-formats">Formats</a> </p> </p>

---

Why?

AI coding assistants in IDEs like Cursor, Windsurf, Antigravity, and VS Code Copilot can't natively read PDF or Word documents. When you need to reference API docs, specifications, or reports while coding, you're stuck copy-pasting.

bh-pdfdoc-reader solves this by:

• 🔌 MCP Server — Plugs directly into your IDE's AI assistant
• 📑 Structured output — Markdown, JSON, or plain text
• 📊 Table extraction — Preserves tables from both PDF and DOCX
• ⚡ Lightweight — Minimal dependencies, fast startup
• 🖥️ CLI tool — Also works standalone from the terminal

Installation

Quick install (from GitHub)

# With MCP server support (recommended for IDE integration)
pip install "bh-pdfdoc-reader[mcp] @ git+https://github.com/BilhosDev/bh-pdfdoc-reader.git"

# Core only (CLI, no MCP)
pip install "bh-pdfdoc-reader @ git+https://github.com/BilhosDev/bh-pdfdoc-reader.git"

From source (for development)

git clone https://github.com/BilhosDev/bh-pdfdoc-reader.git
cd bh-pdfdoc-reader
pip install -e ".[all]"

MCP Integration

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools. By running bh-pdfdoc-reader as an MCP server, your IDE's AI can read documents on demand.

Cursor

Add to your .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "bh-pdfdoc-reader": {
      "command": "bh-pdfdoc-reader-mcp",
      "args": []
    }
  }
}

Windsurf

Add to your MCP configuration:

{
  "mcpServers": {
    "bh-pdfdoc-reader": {
      "command": "bh-pdfdoc-reader-mcp",
      "args": []
    }
  }
}

VS Code + GitHub Copilot

Add to your .vscode/mcp.json:

{
  "servers": {
    "bh-pdfdoc-reader": {
      "type": "stdio",
      "command": "bh-pdfdoc-reader-mcp",
      "args": []
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bh-pdfdoc-reader": {
      "command": "bh-pdfdoc-reader-mcp",
      "args": []
    }
  }
}

Antigravity (Google DeepMind)

Antigravity supports MCP servers natively. Add to your MCP settings:

{
  "mcpServers": {
    "bh-pdfdoc-reader": {
      "command": "bh-pdfdoc-reader-mcp",
      "args": []
    }
  }
}

Note: If the command isn't found, use the full path: "command": "python" and "args": ["-m", "bh_pdfdoc_reader.mcp_server"]

Available MCP Tools

Once connected, your AI assistant can use these tools:

Tool	Description
read_document	Read a PDF/DOCX file and return content (markdown or json)
read_page	Read a specific page from a PDF (1-indexed)
get_document_info	Get document metadata without reading full content

Example prompts you can use in your IDE:

"Read the API documentation from docs/api-spec.pdf"
"What does page 5 of the contract say?"
"Summarize the report in reports/quarterly.docx"
"Extract the tables from data/pricing.pdf"

CLI Usage

# Read a PDF (plain text output)
bh-pdfdoc-reader document.pdf

# Read a specific page
bh-pdfdoc-reader document.pdf --page 3

# Output as Markdown (great for piping to AI tools)
bh-pdfdoc-reader document.pdf --format markdown

# Output as JSON (for programmatic use)
bh-pdfdoc-reader report.docx --format json

# Raw text only (no formatting)
bh-pdfdoc-reader document.pdf --text-only

Output Formats

Format	Flag	Best For
Plain Text	--format text (default)	Terminal reading
Markdown	--format markdown	AI assistants, documentation
JSON	--format json	Programmatic processing

Supported Formats

Format	Extension	Features
PDF	.pdf	Text extraction, table extraction, page selection, metadata
Word	.docx	Paragraphs, headings, tables, document properties

Python API

You can also use bh-pdfdoc-reader as a library:

from bh_pdfdoc_reader.readers import get_reader
from bh_pdfdoc_reader.formatters import get_formatter

# Read a document
reader = get_reader("report.pdf")
result = reader.read("report.pdf", page=1)

# Format output
formatter = get_formatter("markdown")
print(formatter.format(result))

# Or get raw text
print(result.get_full_text())

Project Structure

bh-pdfdoc-reader/
├── src/bh_pdfdoc_reader/
│   ├── __init__.py          # Package metadata
│   ├── __main__.py          # python -m support
│   ├── cli.py               # CLI entry point
│   ├── mcp_server.py        # MCP server for IDE integration
│   ├── readers/
│   │   ├── base.py          # Base reader class & factory
│   │   ├── pdf_reader.py    # PDF reader (pdfplumber)
│   │   └── docx_reader.py   # DOCX reader (python-docx)
│   └── formatters/
│       ├── markdown_fmt.py  # Markdown output
│       ├── json_fmt.py      # JSON output
│       └── text_fmt.py      # Plain text output
├── tests/                   # Unit tests
├── pyproject.toml           # Package configuration
└── README.md

Development

# Clone and install in dev mode
git clone https://github.com/BilhosDev/bh-pdfdoc-reader.git
cd bh-pdfdoc-reader
pip install -e ".[all]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=bh_pdfdoc_reader

Comparison with Alternatives

Feature	bh-pdfdoc-reader	markitdown	docling
MCP Server	✅ Built-in	❌ Separate package	❌ No
Lightweight	✅ ~200 lines	❌ Heavy	❌ Very heavy
PDF Support	✅	✅	✅
DOCX Support	✅	✅	✅
Table Extraction	✅	⚠️ Basic	✅
Multiple Formats	✅ MD/JSON/Text	Markdown only	JSON only
Install Size	~5 MB	~50 MB	~500 MB+
Page Selection	✅	❌	❌

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🇹🇷 Türkçe

bh-pdfdoc-reader, Cursor, Windsurf, Antigravity ve VS Code gibi AI destekli IDE'lerde PDF ve DOCX dosyalarını doğrudan okuyabilmenizi sağlayan hafif bir araçtır.

Ne İşe Yarar?

Yazılım geliştirirken API dökümanlarına, teknik şartnamelere veya raporlara başvurmanız gerektiğinde, PDF/Word dosyalarını kopyala-yapıştır yapmak zorunda kalırsınız. Bu araç, IDE'nizdeki AI asistanının dokümanları doğrudan okumasını sağlar.

Nasıl Çalışır?

1. MCP Server olarak çalışır — IDE'nizdeki AI asistanı bu aracı otomatik olarak kullanır
2. CLI aracı olarak da kullanılabilir — terminalden doğrudan dosya okuyabilirsiniz
3. Python kütüphanesi olarak da import edilebilir

Hızlı Kurulum

# Kurulum (tek komut)
pip install "bh-pdfdoc-reader[mcp] @ git+https://github.com/BilhosDev/bh-pdfdoc-reader.git"

# CLI kullanımı
bh-pdfdoc-reader belge.pdf
bh-pdfdoc-reader belge.pdf --page 3
bh-pdfdoc-reader rapor.docx --format markdown

IDE Entegrasyonu

IDE'nizin MCP ayarlarına aşağıdaki yapılandırmayı ekleyin:

{
  "mcpServers": {
    "bh-pdfdoc-reader": {
      "command": "bh-pdfdoc-reader-mcp",
      "args": []
    }
  }
}

Kurulumdan sonra IDE'nizde şu tür komutlar verebilirsiniz:

• "docs/api.pdf dosyasını oku"
• "Sözleşmenin 5. sayfasında ne yazıyor?"
• "rapor.docx dosyasındaki tabloları çıkar"

---

Roadmap

• [ ] .doc (legacy Word) support
• [ ] .pptx (PowerPoint) support
• [ ] .xlsx / .csv support
• [ ] OCR for scanned PDFs (via Tesseract)
• [ ] Streaming/chunked output for large documents
• [ ] PyPI package publishing