Metadata-Version: 2.4
Name: perplexity-polza-mcp-server
Version: 0.1.1
Summary: An MCP server for Perplexity models through the Polza.ai chat API
Project-URL: Homepage, https://github.com/ivanantigravity-lgtm/perplexity-polza-mcp-server
Project-URL: Repository, https://github.com/ivanantigravity-lgtm/perplexity-polza-mcp-server.git
Project-URL: Documentation, https://github.com/ivanantigravity-lgtm/perplexity-polza-mcp-server#readme
Project-URL: Bug Tracker, https://github.com/ivanantigravity-lgtm/perplexity-polza-mcp-server/issues
Author: Ivan Khokholkov
License: MIT
License-File: LICENSE
Keywords: claude,fastmcp,mcp,perplexity,polza,search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.11.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.8.2
Requires-Dist: python-dotenv>=1.0.1
Provides-Extra: dev
Requires-Dist: build>=1.4.2; extra == 'dev'
Requires-Dist: pytest>=8.3.5; extra == 'dev'
Requires-Dist: ruff>=0.11.8; extra == 'dev'
Requires-Dist: twine>=6.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Perplexity MCP Server via Polza.ai

`mcp-name: io.github.ivanantigravity-lgtm/perplexity-polza-mcp-server`

MCP сервер для `Claude Desktop` и `Claude Code`, который ходит в модели Perplexity (`Sonar`, `Sonar Pro`, `Sonar Reasoning`, `Sonar Deep Research`) через агрегатор [Polza.ai](https://polza.ai).

## Что умеет

- `perplexity_model_guide` — шпаргалка по выбору модели под задачу
- `perplexity_ask` — обычный вопрос в Perplexity
- `perplexity_research` — более глубокий ресёрч с веб-поиском
- `list_perplexity_models` — список доступных `perplexity/*` моделей из каталога Polza

## Что нужно для установки

- `Claude Desktop` или `Claude Code` (или любой другой MCP-клиент)
- [`uv`](https://docs.astral.sh/uv/) (ставится одной командой, см. ниже)
- Python 3.11+
- `POLZA_AI_API_KEY` — ключ берётся на [polza.ai/dashboard/api-keys](https://polza.ai/dashboard/api-keys)

Поставить `uv`:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

## Установка за 2 минуты (через PyPI + uvx)

Это самый простой путь: ничего клонировать не надо, `uvx` сам скачает пакет из PyPI.

### Claude Code / VS Code

Создай файл `.mcp.json` в корне своего проекта:

```json
{
  "mcpServers": {
    "perplexity-polza": {
      "command": "uvx",
      "args": ["perplexity-polza-mcp-server@latest"],
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here"
      }
    }
  }
}
```

Перезапусти Claude Code — готово.

### Claude Desktop (macOS)

Открой файл `~/Library/Application Support/Claude/claude_desktop_config.json` и добавь:

```json
{
  "mcpServers": {
    "perplexity-polza": {
      "command": "uvx",
      "args": ["perplexity-polza-mcp-server@latest"],
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here"
      }
    }
  }
}
```

Перезапусти Claude Desktop.

### Claude Desktop (Windows)

Файл: `%APPDATA%\Claude\claude_desktop_config.json`. Содержимое такое же, как на macOS.

## Как проверить, что работает

После перезапуска Claude попроси:

> Покажи доступные модели Perplexity через polza

Claude должен вызвать tool `list_perplexity_models` и вернуть список.

## Когда какую модель брать

- `Sonar` — быстрый поиск + ответ. Новости, факты, Q&A, короткие суммаризации.
- `Sonar Pro` — плотнее структура, сравнения, follow-up вопросы.
- `Sonar Pro Search` — глубже поиск, больше поисковых шагов.
- `Sonar Reasoning Pro` — не просто найти, а разобрать и сделать вывод.
- `Sonar Deep Research` — полноценный ресёрч, market scan, длинный отчёт.

Переключить дефолтную модель можно через переменные окружения `PERPLEXITY_MODEL` и `PERPLEXITY_RESEARCH_MODEL` — полный список ниже.

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

| Переменная | Обязательная | По умолчанию | Описание |
| --- | --- | --- | --- |
| `POLZA_AI_API_KEY` | да | — | Ключ с polza.ai |
| `POLZA_BASE_URL` | нет | `https://polza.ai/api/v1` | Base URL для chat completions (с `/v1` — это ожидаемо, endpoint OpenAI-совместим) |
| `PERPLEXITY_MODEL` | нет | `perplexity/sonar` | Модель для `perplexity_ask` |
| `PERPLEXITY_RESEARCH_MODEL` | нет | `perplexity/sonar-deep-research` | Модель для `perplexity_research` |
| `LOG_LEVEL` | нет | `INFO` | — |

## Локальная разработка

```bash
git clone https://github.com/ivanantigravity-lgtm/perplexity-polza-mcp-server.git
cd perplexity-polza-mcp-server
uv sync
POLZA_AI_API_KEY=your_key uv run python -m perplexity_polza_mcp_server.server
```

Для локального подключения из source в Claude:

```json
{
  "mcpServers": {
    "perplexity-polza-local": {
      "command": "uv",
      "args": ["run", "python", "-m", "perplexity_polza_mcp_server.server"],
      "cwd": "/absolute/path/to/perplexity-polza-mcp-server",
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here"
      }
    }
  }
}
```

## Под капотом

- Chat completions: `POST https://polza.ai/api/v1/chat/completions` (OpenAI-совместимый формат)
- Model catalog: `GET https://polza.ai/api/v1/models/catalog`

## Важные файлы в репозитории

- `pyproject.toml` — метаданные пакета и entry points
- `server.json` — описание для MCP Registry
- `fastmcp.json` — локальная конфигурация FastMCP
- `.github/workflows/publish-pypi.yml` — публикация в PyPI через GitHub Actions

## Лицензия

MIT.
