<p align="center"><img src="./assets/leostrange-project-banner.svg" alt="4PDA MCP Server" width="100%" /></p>

<p align="center">
  <img src="https://img.shields.io/badge/MCP-Streamable_HTTP-7C3AED?style=flat-square" alt="MCP Streamable HTTP" />
  <img src="https://img.shields.io/badge/Python-3B82F6?style=flat-square&logo=python&logoColor=white" alt="Python" />
  <img src="https://img.shields.io/badge/Remote-ready-22D3EE?style=flat-square" alt="Remote ready" />
</p>

<p align="center"><b>Удалённый MCP-сервер для поиска тем и чтения постов открытого форума 4PDA.</b><br/>Один HTTPS endpoint, Streamable HTTP и возможность работать без постоянно включённого домашнего компьютера.</p>

---

## Что умеет

| Tool | Назначение |
|---|---|
| `search_4pda(query, pages=1)` | Поиск тем, от 1 до 5 страниц. |
| `parse_4pda_topic(url, pages=1)` | Чтение постов из темы, от 1 до 5 страниц. |

Ссылки для парсинга ограничены `https://4pda.to/...showtopic=...`, чтобы сервер нельзя было превратить в универсальный прокси к внутренним адресам.

> Учитывайте правила 4PDA и не используйте сервер для массового сбора данных.

## Как это работает

```text
AI client
   │
   │ Streamable HTTP
   ▼
4PDA MCP Server
   │
   │ search / topic parsing
   ▼
4pda.to
```

После деплоя клиент подключается к одному публичному адресу:

```text
https://YOUR-DOMAIN/mcp
```

## Быстрый деплой

1. Разверните репозиторий на Railway, Render или Fly.io.
2. Dockerfile определяется автоматически — отдельный start command не нужен.
3. Получите публичный домен платформы.
4. Используйте `https://ВАШ-ДОМЕН/mcp` в AI-клиенте с поддержкой remote MCP / Streamable HTTP.

Контейнер слушает переменную `PORT`, которую задаёт хостинг. Проброс портов и постоянно включённый ПК не требуются.

Для публичного инстанса рекомендуется HTTPS и авторизация на уровне прокси, например Cloudflare Access.

## Прокси для 4PDA

4PDA может блокировать IP-адреса облачных дата-центров. Сервер поддерживает HTTP/SOCKS-совместимый прокси через секрет `PROXY_URL`.

```text
Key:   PROXY_URL
Value: http://USERNAME:PASSWORD@HOST:PORT
```

`PROXY_URL` должен храниться только как секрет окружения и не должен попадать в исходный код, README или логи. Shared/datacenter IP могут быть заблокированы; в таком случае может понадобиться residential/ISP-прокси.

## Локальный запуск

```powershell
python -m pip install -r requirements.txt
python mcp_server.py
```

Endpoint:

```text
http://localhost:8000/mcp
```

## Claude Desktop — локальный режим

```json
{
  "mcpServers": {
    "4pda-parser": {
      "command": "python",
      "args": ["C:\\path\\to\\4pda-mcp-server\\mcp_server.py"]
    }
  }
}
```

Для удалённого режима используйте URL `https://ВАШ-ДОМЕН/mcp`; поддержка remote MCP зависит от конкретного AI-клиента.

## Безопасность

- парсинг ограничен URL тем 4PDA;
- секрет прокси хранится через переменные окружения;
- для публичного endpoint рекомендуется внешняя авторизация;
- не публикуйте credentials и приватные proxy URLs.

---

<p align="center"><sub>Part of the <a href="https://github.com/Leostrange">Leostrange</a> open-source projects.</sub></p>