# pageindex-mcp

Self-hosted MCP server для Claude Code, реализующий [PageIndex](https://github.com/VectifyAI/PageIndex) vectorless RAG полностью локально.

## Архитектура

```
Claude Code (Max plan — handles all reasoning)
    │  stdio
    ▼
pageindex-mcp (TypeScript)
    ├── index_document    ──→ run_pageindex.py (Python, local)
    │                           └── OpenAI API (tree generation, one-time)
    ├── get_document_tree ──→ local JSON
    ├── get_page_content  ──→ pdftotext (local)
    ├── list_documents    ──→ local filesystem
    └── delete_document   ──→ local filesystem
```

**Никаких LLM-вызовов внутри сервера** — Claude Code сам навигирует дерево и анализирует контент. Не нужен ANTHROPIC_API_KEY.

## Предварительные требования

```bash
# 1. Node.js ≥ 18
node --version

# 2. Python PageIndex repo
git clone https://github.com/VectifyAI/PageIndex /opt/pageindex
cd /opt/pageindex && pip install -r requirements.txt

# 3. poppler-utils для извлечения текста из PDF
# Ubuntu/Debian:
sudo apt install poppler-utils
# macOS:
brew install poppler
```

## Установка и сборка

```bash
npm install
npm run build
```

## Переменные окружения

| Переменная            | Обязательна | Описание |
|-----------------------|-------------|----------|
| `OPENAI_API_KEY`      | да (для индексации) | PageIndex генерирует дерево через OpenAI |
| `PAGEINDEX_REPO_PATH` | да | Путь к клонированному репозиторию PageIndex |
| `INDEX_STORE_PATH`    | нет | Где хранить JSON индексы (default: `~/.pageindex-store`) |
| `PAGEINDEX_MODEL`     | нет | OpenAI модель (default: `gpt-4o-2024-11-20`) |

Для OpenRouter вместо прямого OpenAI:
```bash
OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_API_KEY=sk-or-v1-...
PAGEINDEX_MODEL=openai/gpt-4o
```

## Подключение к Claude Code

### Вариант A: локальный stdio (рекомендуется)

Добавить в `~/.claude.json` или `.mcp.json` в проекте:

```json
{
  "mcpServers": {
    "pageindex-local": {
      "command": "node",
      "args": ["/absolute/path/to/pageindex-mcp/build/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "PAGEINDEX_REPO_PATH": "/opt/pageindex"
      }
    }
  }
}
```

### Вариант B: dev-режим (tsx, без сборки)

```json
{
  "mcpServers": {
    "pageindex-local": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/pageindex-mcp/src/index.ts"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "PAGEINDEX_REPO_PATH": "/opt/pageindex"
      }
    }
  }
}
```

## Использование в Claude Code

```
# 1. Индексировать документ (один раз)
"Проиндексируй PDF /path/to/spec.pdf с id pam-spec"

# 2. Посмотреть структуру документа
"Покажи структуру документа pam-spec"

# 3. Извлечь контент конкретной секции
"Покажи содержимое ноды 0005 в документе pam-spec"

# 4. Список всех документов
"Какие документы проиндексированы?"

# 5. Удалить индекс
"Удали индекс pam-spec"
```

Claude Code сам навигирует дерево, выбирает нужные секции и отвечает — не нужны отдельные API-вызовы.

## Инструменты MCP

| Инструмент          | Описание |
|---------------------|----------|
| `index_document`    | Генерирует PageIndex tree из PDF (один раз, затем переиспользуется) |
| `get_document_tree` | Иерархическая структура документа для навигации |
| `get_page_content`  | Извлечение текста по node_id или диапазону страниц |
| `list_documents`    | Список проиндексированных документов с метаданными |
| `delete_document`   | Удалить документ из индекса |

## Стоимость

- **Индексация** (разово): ~$0.10–0.50 за документ (OpenAI gpt-4o)
- **Поиск**: бесплатно на Claude Code Max plan
- **Хранение**: локальные JSON файлы

## Ограничения

- Генерация дерева требует OpenAI API (hardcoded в Python PageIndex)
- Для больших PDF (500+ стр.) индексация может занять несколько минут
- Без `poppler-utils` текст страниц не извлекается (только метаданные дерева)