Metadata-Version: 2.4
Name: hermes-mcp-server
Version: 3.0.2
Summary: Hermes MCP Server — self-hosted gateway that bridges Android/Web clients to Hermes AI Agent via MCP (Model Context Protocol). WebSocket + HTTP SSE + REST.
Author-email: XuViGaN <xuvigan@hermes.dev>
License-Expression: MIT
Keywords: mcp,model-context-protocol,hermes,ai,server,gateway,fastapi,websocket
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: websockets>=13.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-multipart>=0.0.12

# Hermes MCP Server

**Автор: XuViGaN**

Self-hosted MCP (Model Context Protocol) gateway — bridges Android/Web clients to **Hermes AI Agent**. Разверни свой AI-сервер за 30 секунд.

[![PyPI version](https://img.shields.io/pypi/v/hermes-mcp-server)](https://pypi.org/project/hermes-mcp-server/)
[![Python](https://img.shields.io/pypi/pyversions/hermes-mcp-server)](https://pypi.org/project/hermes-mcp-server/)
[![License](https://img.shields.io/pypi/l/hermes-mcp-server)](https://pypi.org/project/hermes-mcp-server/)

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

```
┌──────────────────┐      ┌─────────────────────────┐      ┌──────────────────┐
│  Hermes Gateway  │      │   Hermes MCP Server      │      │  Hermes Agent    │
│  (Android App)   │◄────►│   (этот пакет)           │◄────►│  (hermes CLI)    │
│                  │ WS   │   Порт 8080              │ CLI  │                  │
│  • Чат           │ SSE  │   • MCP JSON-RPC 2.0     │      │  • LLM модели    │
│  • Стриминг      │ HTTP │   • SSE streaming        │      │  • Инструменты   │
│  • Файлы         │      │   • REST API             │      │  • Навыки        │
│  • Тёмная тема   │      │   • Управление сессиями  │      │  • Память        │
└──────────────────┘      └─────────────────────────┘      └──────────────────┘
```

## Быстрый старт

### Linux / macOS

```bash
# Рекомендуемый способ (Debian/Ubuntu):
pipx install hermes-mcp-server

# Или через pip (если не Debian):
pip install hermes-mcp-server

# На Debian/Ubuntu без pipx:
pip install --break-system-packages hermes-mcp-server

# Запуск
hermes-mcp-server
```

### Если ошибка «externally-managed-environment» (Debian/Ubuntu)

Это PEP 668 — система защищает Python от случайной поломки. Три решения:

```bash
# 1. pipx (рекомендуется) — ставит в изолированное окружение
apt install pipx
pipx install hermes-mcp-server
hermes-mcp-server

# 2. --break-system-packages (быстро)
pip install --break-system-packages hermes-mcp-server

# 3. Виртуальное окружение
python3 -m venv hermes-env
source hermes-env/bin/activate
pip install hermes-mcp-server
hermes-mcp-server
```

### Подключение с Android

1. Скачай **Hermes Gateway** APK
2. Открой → **Add Profile**
3. Введи IP своего сервера и порт 8080
4. Жми Connect — и общайся со своим ИИ!

### Подключение из терминала

```bash
pip install hermes-mcp-client
hermes-mcp connect http://localhost:8080 --name local
hermes-mcp chat "Привет, Hermes!" --server local
```

## Конфигурация

```bash
# Свой порт
hermes-mcp-server --port 9000

# Конкретная модель и провайдер
hermes-mcp-server --model deepseek-v4-pro --provider opencode-go

# Свой хост (для доступа из локальной сети)
hermes-mcp-server --host 0.0.0.0 --port 8080

# Полный список опций
hermes-mcp-server --help
```

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

| Переменная | По умолчанию | Описание |
|------------|-------------|----------|
| `HOST` | `0.0.0.0` | Адрес сервера |
| `PORT` | `8080` | Порт |
| `HERMES_PATH` | `hermes` | Путь к бинарнику hermes |
| `HERMES_HOME` | `~/.hermes` | Домашняя папка Hermes |
| `HERMES_MODEL` | — | Модель по умолчанию |
| `HERMES_PROVIDER` | — | Провайдер по умолчанию |
| `HERMES_UPLOAD_DIR` | `/tmp/hermes-uploads` | Папка для загрузок |

## Endpoints

| Метод | Путь | Описание |
|--------|------|-------------|
| `WS` | `/ws` | MCP WebSocket (JSON-RPC 2.0) |
| `GET` | `/stream` | HTTP SSE стриминг чата |
| `GET` | `/health` | Health check |
| `GET` | `/status` | Полный статус сервера |
| `POST` | `/chat` | One-shot чат |
| `POST` | `/upload` | Загрузка файла |
| `GET` | `/config/providers` | Список провайдеров |
| `GET` | `/config/models?provider=X` | Список моделей |
| `GET` | `/mcp/info` | Информация о сервере + тулы |
| `GET` | `/docs` | Swagger UI (автодокументация) |
| `GET` | `/` | Welcome page |

## MCP Tools

| Tool | Описание |
|------|----------|
| `hermes_chat` | Отправить сообщение Hermes |
| `hermes_status` | Статус агента |
| `hermes_execute` | Выполнить shell-команду |
| `hermes_analyze_file` | Анализ файла |
| `hermes_new_session` | Новая сессия |
| `hermes_send_file` | Загрузить файл |

## Установка как systemd-сервис

```bash
cat > /etc/systemd/system/hermes-mcp.service << 'EOF'
[Unit]
Description=Hermes MCP Server
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/hermes-mcp-server \
    --model deepseek-v4-pro \
    --provider opencode-go
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now hermes-mcp
systemctl status hermes-mcp
```

## Пример Docker-развёртывания

```dockerfile
FROM python:3.11-slim
RUN pip install hermes-mcp-server hermes-agent
EXPOSE 8080
CMD ["hermes-mcp-server", "--host", "0.0.0.0", "--port", "8080"]
```

```bash
docker build -t hermes-mcp .
docker run -d -p 8080:8080 -v ~/.hermes:/root/.hermes hermes-mcp
```

## Экосистема Hermes MCP

| Компонент | PyPI | Описание |
|-----------|------|----------|
| **hermes-mcp-server** | [PyPI](https://pypi.org/project/hermes-mcp-server/) | MCP сервер (этот пакет) |
| **hermes-mcp-client** | [PyPI](https://pypi.org/project/hermes-mcp-client/) | CLI клиент для терминала |
| **Hermes Gateway** | APK | Android приложение |

```bash
# Полный флоу для self-hosting:
pip install hermes-mcp-server hermes-mcp-client
hermes-mcp-server --port 8080 &
hermes-mcp connect http://localhost:8080 --name my
hermes-mcp chat "Hello" --server my
```

## Требования

- Python 3.10+
- Hermes Agent (`pip install hermes-agent`)
- Хотя бы один LLM-провайдер (API ключ в `~/.hermes/.env`)

## Лицензия

MIT — XuViGaN 2026
