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.

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

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.

Установка

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.

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

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 с символами |.

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

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 находится здесь:

dist/src/index.js

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

Добавьте в ~/.config/opencode/opencode.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
    }
  }
}

Проверка:

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 секунд

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

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

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

{
  "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

npm run build
npm run provider:start
npm run provider:status

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

http://127.0.0.1:18457/v1

Остановка:

npm run provider:stop

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

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

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

Добавьте provider в ~/.config/opencode/opencode.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 }
        }
      }
    }
  }
}

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

opencode models hyperagent

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

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.

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

.
├── 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.

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

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 не запускается

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:

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.

Затем:

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.