# Hyperagent MCP и локальный provider для OpenCode

Локальный мост к моделям **Fable 5** и **GPT-5.6 Sol**, использующий cookies активной браузерной сессии `hyperagent.com`.

Проект предоставляет два независимых режима:

1. **stdio MCP-сервер** с инструментами `hyperagent_models` и `hyperagent_chat`;
2. **OpenAI-совместимый локальный provider**, который добавляет обе модели в OpenCode и передаёт им локальные инструменты OpenCode (`bash`, `read`, `write`, `edit` и другие).

> [!WARNING]
> Проект обращается к внутренним, официально не документированным web API Hyperagent. Hyperagent может изменить модели, endpoint-ы или формат ответов без предупреждения.

## Возможности

- только две явно разрешённые модели;
- работа через существующую Hyperagent-сессию без копирования cookies в конфиг OpenCode;
- перечитывание cookie-файла перед каждым запросом;
- новые и продолжаемые Hyperagent threads через MCP;
- OpenAI Chat Completions API для подключения как отдельного provider OpenCode;
- streaming и non-streaming ответы;
- преобразование tool calls модели в реальные локальные инструменты OpenCode;
- защита от ложных заявлений о создании или изменении локальных файлов;
- привязка HTTP-provider только к `127.0.0.1`;
- автоматическое удаление временных Hyperagent threads provider-а.

## Поддерживаемые модели

| Алиас | Название | Hyperagent model ID | Runtime | Контекст | Максимальный ответ |
|---|---|---|---|---:|---:|
| `fable-5` | Fable 5 | `claude-fable-5` | `claude-agents-sdk` | 1 000 000 | 128 000 |
| `gpt-5.6-sol` | GPT-5.6 Sol | `openai/gpt-5.6-sol` | `langchain-deepagents` | 950 000 | 128 000 |

Для Fable 5 используются `effort=max` и `maxThinkingTokens=32000`. Для GPT-5.6 Sol используется `effort=max`.

## Как устроен проект

```text
OpenCode
├── MCP client ──stdio──> dist/src/index.js
│                         └── Hyperagent session API
└── AI provider ──HTTP──> 127.0.0.1:18457/v1
                          └── provider-server.js
                              ├── преобразование OpenAI messages/tools
                              ├── Hyperagent session API
                              └── возврат tool calls обратно в OpenCode
```

Удалённая песочница Hyperagent (`/agent/workspace`) **не является компьютером пользователя**. В режиме provider любые операции с текущей директорией, файлами, shell и процессами должны выполняться инструментами OpenCode на локальном компьютере. Сервер использует отдельные транспортные имена инструментов, чтобы они не пересекались со встроенными инструментами удалённой песочницы.

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

- Node.js 18 или новее;
- npm;
- активная учётная запись и браузерная сессия на `https://hyperagent.com`;
- OpenCode — только если требуется подключение моделей как provider или MCP в OpenCode.

## Установка

```bash
git clone <URL-ВАШЕГО-РЕПОЗИТОРИЯ>
cd hyperagent-mcp
npm ci
npm run build
```

Основные команды:

| Команда | Назначение |
|---|---|
| `npm run check` | Проверить TypeScript без создания `dist` |
| `npm run build` | Собрать JavaScript в `dist/src` |
| `npm start` | Запустить stdio MCP-сервер вручную |
| `npm run provider` | Запустить HTTP-provider в foreground |
| `npm run provider:start` | Запустить provider в фоне |
| `npm run provider:status` | Проверить provider и `/health` |
| `npm run provider:stop` | Корректно остановить provider |

## Cookies: расположение и формат

### Где лежит файл

По умолчанию сервер ищет файл `cookies.md` в текущей рабочей директории.

- в этой установленной копии: `/root/test/cookies.md`;
- в обычном клоне: `<корень-репозитория>/cookies.md`;
- рекомендуемый путь: рядом с `package.json`.

Путь можно переопределить переменной окружения:

```bash
export HYPERAGENT_COOKIES_FILE=/absolute/path/to/cookies.md
```

Фоновый service-скрипт по умолчанию всегда использует `<корень-репозитория>/cookies.md`, независимо от директории, из которой была запущена npm-команда.

Файл `cookies.md` включён в `.gitignore` и не должен попадать в GitHub, npm-пакет, логи или сообщения об ошибках. Безопасный шаблон находится в `cookies.example.md`.

### Как подготовить cookies.md

1. Войдите в `https://hyperagent.com` в браузере.
2. Откройте Chrome DevTools и таблицу Cookies для `hyperagent.com`.
3. Скопируйте строки cookies как табличные данные с разделителем TAB.
4. Сохраните данные в `<корень-репозитория>/cookies.md`.
5. Не преобразовывайте таблицу в Markdown с символами `|`.

Ожидаемый порядок первых колонок:

```text
Name<TAB>Value<TAB>Domain<TAB>Path<TAB>...
```

Заголовок `Name<TAB>Value...` допустим и будет пропущен. Сервер использует имя, значение и домен, но требует табличный формат минимум с четырьмя колонками. Допускаются только домены:

- `hyperagent.com`;
- `.hyperagent.com`.

Cookies перечитываются перед **каждым** запросом к Hyperagent. После замены `cookies.md` перезапуск обычно не нужен.

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

Cookies эквивалентны bearer-учётным данным и дают доступ к вашей сессии.

- не коммитьте `cookies.md`;
- не вставляйте значения в `opencode.jsonc`;
- не отправляйте файл в issue, gist или CI artifact;
- не передавайте cookies никакому домену кроме фиксированного `https://hyperagent.com`;
- после случайной публикации завершите сессию Hyperagent и получите новые cookies.

Клиент запрещает cross-origin redirects, проверяет домены строк и отклоняет символы, позволяющие внедрить дополнительные HTTP-заголовки.

## Режим 1: stdio MCP-сервер

После сборки entry point находится здесь:

```text
dist/src/index.js
```

### Подключение к OpenCode

Добавьте в `~/.config/opencode/opencode.jsonc`, заменив пути на абсолютные:

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hyperagent": {
      "type": "local",
      "command": ["node", "/absolute/path/to/hyperagent-mcp/dist/src/index.js"],
      "environment": {
        "HYPERAGENT_COOKIES_FILE": "/absolute/path/to/hyperagent-mcp/cookies.md"
      },
      "enabled": true
    }
  }
}
```

Проверка:

```bash
opencode mcp list
```

### Инструмент hyperagent_models

Не принимает параметров. Возвращает алиасы, API ID, runtime, лимиты и настройки поддерживаемых моделей.

### Инструмент hyperagent_chat

| Поле | Тип | Обязательно | Описание |
|---|---|---:|---|
| `model` | `fable-5` или `gpt-5.6-sol` | да | Алиас модели |
| `prompt` | string | да | Сообщение модели |
| `thread_id` | string | нет | ID существующего Hyperagent thread для продолжения |
| `system_prompt` | string | нет | System prompt нового thread или явное обновление существующего |
| `timeout_seconds` | integer 10–1800 | нет | Таймаут, по умолчанию 600 секунд |

Новый диалог:

```json
{
  "model": "fable-5",
  "prompt": "Ответь одним словом: OK"
}
```

Продолжение:

```json
{
  "model": "fable-5",
  "thread_id": "ID_ИЗ_ПРЕДЫДУЩЕГО_ОТВЕТА",
  "prompt": "Продолжи предыдущий ответ"
}
```

Ответ содержит `thread_id`, `created_thread`, алиас/ID модели и текст `response`. Продолжать thread нужно с исходной моделью и runtime.

MCP-режим управляет удалёнными Hyperagent threads. Сам по себе он не предоставляет модели доступ к локальным файлам OpenCode.

## Режим 2: модели как отдельный provider OpenCode

Этот режим нужен, если Fable 5 и GPT-5.6 Sol должны отображаться в `/models` и работать как coding models с локальными инструментами OpenCode.

### Запуск provider

```bash
npm run build
npm run provider:start
npm run provider:status
```

Provider слушает только:

```text
http://127.0.0.1:18457/v1
```

Остановка:

```bash
npm run provider:stop
```

Runtime-файлы создаются в корне проекта и игнорируются Git:

- `.hyperagent-provider.pid` — PID фонового процесса;
- `.hyperagent-provider.log` — stdout/stderr provider-а.

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

Добавьте provider в `~/.config/opencode/opencode.jsonc`:

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "hyperagent": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Hyperagent Session",
      "options": {
        "baseURL": "http://127.0.0.1:18457/v1",
        "apiKey": "local"
      },
      "models": {
        "fable-5": {
          "name": "Fable 5",
          "limit": { "context": 1000000, "output": 128000 }
        },
        "gpt-5.6-sol": {
          "name": "GPT-5.6 Sol",
          "limit": { "context": 950000, "output": 128000 }
        }
      }
    }
  }
}
```

Проверка моделей:

```bash
opencode models hyperagent
```

Идентификаторы моделей:

```text
hyperagent/fable-5
hyperagent/gpt-5.6-sol
```

### Как provider работает с локальными инструментами

1. OpenCode отправляет историю, JSON Schema инструментов и `tool_choice` в локальный provider.
2. Provider заменяет имена инструментов на уникальные транспортные aliases.
3. Модель получает явное указание, что Hyperagent sandbox не является компьютером пользователя.
4. Модель возвращает JSON-запрос tool call.
5. Provider восстанавливает настоящее имя инструмента и возвращает вызов OpenCode.
6. OpenCode выполняет инструмент локально и отправляет результат следующим сообщением.
7. Только локальный tool result считается подтверждением чтения, изменения или создания файла.

Для очевидных запросов на создание/редактирование/чтение файла и определение рабочей директории provider требует соответствующий локальный tool call. Если модель не возвращает обязательный вызов даже после repair-попытки, запрос завершается ошибкой вместо ложного сообщения об успехе.

Каждый OpenAI completion создаёт временный Hyperagent thread. После завершения или ошибки provider пытается удалить этот thread, поскольку OpenCode на каждом шаге передаёт всю историю заново.

## HTTP API provider-а

| Метод | Endpoint | Описание |
|---|---|---|
| `GET` | `/health` | Проверка процесса |
| `GET` | `/v1/models` | Список двух моделей |
| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completions |

Поддерживаются обычные и SSE-streaming ответы, OpenAI-style tool calls и `tool_choice`.

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

| Переменная | По умолчанию | Назначение |
|---|---|---|
| `HYPERAGENT_COOKIES_FILE` | `<cwd>/cookies.md` | Абсолютный или относительный путь к cookie-файлу |
| `HYPERAGENT_PROVIDER_PORT` | `18457` | Локальный порт provider-а |
| `HYPERAGENT_PROVIDER_DEBUG` | выключен | Значение `1` включает безопасные shape-логи запросов |

Debug-режим записывает роли, количество/имена инструментов и форму результата, но не должен записывать тексты prompt-ов или значения cookies.

## Структура репозитория

```text
.
├── src/
│   ├── index.ts              # stdio MCP entry point
│   ├── provider-server.ts    # OpenAI-compatible HTTP provider
│   ├── openai-compat.ts      # сообщения, tool aliases и tool-call parsing
│   ├── hyperagent.ts         # клиент Hyperagent session API
│   ├── cookies.ts            # безопасный разбор cookie-таблицы
│   └── models.ts             # разрешённые модели и runtime
├── scripts/
│   └── provider-service.mjs  # start/stop/status фонового provider-а
├── cookies.example.md        # безопасный шаблон формата
├── cookies.md                # реальные cookies; игнорируются Git
├── package.json
└── tsconfig.json
```

`dist/`, `node_modules/`, logs, PID и cookies не публикуются в Git.

## Проверка после установки

```bash
npm ci
npm run check
npm run build
npm run provider:start
curl --fail http://127.0.0.1:18457/health
curl --fail http://127.0.0.1:18457/v1/models
opencode models hyperagent
npm run provider:stop
```

Для live-запроса требуется актуальный `cookies.md`.

## Решение проблем

### 401 или 403

Браузерная сессия истекла или cookies были скопированы не полностью. Обновите `cookies.md` из активной сессии Hyperagent. Значения перечитаются при следующем запросе.

### Invalid cookie table/domain/value

Проверьте, что файл разделён TAB-ами, содержит минимум четыре колонки и включает только `hyperagent.com`/`.hyperagent.com`. Не вставляйте обычный HTTP `Cookie:` header вместо таблицы.

### Provider не запускается

```bash
npm run build
npm run provider:status
cat .hyperagent-provider.log
```

Также проверьте, свободен ли `127.0.0.1:18457`, либо задайте другой `HYPERAGENT_PROVIDER_PORT` и обновите `baseURL` OpenCode.

### Модель пишет, что файл создан, но файла нет

Убедитесь, что выбрана модель вида `hyperagent/fable-5` или `hyperagent/gpt-5.6-sol` через локальный provider, а не удалённый Hyperagent MCP/agent. Локальный provider должен вернуть tool call, после чего OpenCode покажет фактическое выполнение `write`, `edit` или `bash`.

### Hyperagent изменил внутренний API

Проверьте ответы `/api/threads`, `/api/threads/:id/messages` и chat SSE. Проект намеренно не использует cookies на сторонних доменах, поэтому нельзя автоматически переключать его на неизвестный endpoint.

## Подготовка публикации в GitHub

Перед первым commit:

```bash
git init
git check-ignore cookies.md
git status --short
npm ci
npm run check
npm run build
```

Убедитесь, что в staged-файлах отсутствуют:

- `cookies.md` и любые реальные cookie values;
- `.hyperagent-provider.log` и `.hyperagent-provider.pid`;
- `node_modules/`, `dist/`, `.env`;
- пользовательские файлы, не относящиеся к MCP/provider.

Затем:

```bash
git add .
git status --short
git commit -m "Initial Hyperagent MCP bridge"
git branch -M main
git remote add origin <URL-ВАШЕГО-РЕПОЗИТОРИЯ>
git push -u origin main
```

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

- Внутренние API Hyperagent могут измениться.
- Cookies истекают и требуют ручного обновления.
- Image input преобразуется в текстовое уведомление и не передаётся как изображение.
- Token usage в OpenAI-compatible ответе оценивается приблизительно по числу символов.
- Официальный удалённый MCP Hyperagent управляет агентами в удалённой песочнице и не даёт им прямой доступ к локальной файловой системе OpenCode.
- Этот проект не является официальным SDK или продуктом Hyperagent.