<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)

```bash
# 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)

```bash
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)](https://modelcontextprotocol.io/) 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):

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

### Windsurf

Add to your MCP configuration:

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

### VS Code + GitHub Copilot

Add to your `.vscode/mcp.json`:

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

### Claude Desktop

Add to your `claude_desktop_config.json`:

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

### Antigravity (Google DeepMind)

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

```json
{
  "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

```bash
# 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:

```python
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

```bash
# 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](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

```bash
# 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:

```json
{
  "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