hyperagent_mcp

# Hyperagent MCP and Local Provider for OpenCode Local bridge to **Fable 5** and **GPT-5.6 Sol** models, using cookies of active browser session `hyperagent.com`. The project provides two independent modes: 1. **stdio MCP Server** with tools `hyperagent_models` and `hyperagent_chat`; 2. **OpenAI-compatible local provider**, which adds both models to OpenCode and passes them local OpenCode tools (`bash`, `read`, `write`, `edit`, etc.). > [!WARNING] > The project accesses internal, officially undocumented web API Hyperagent. Hyperagent may change models, endpoints, or response format without warning. ## Capabilities - Only two explicitly allowed models; - Work through existing Hyperagent session without copying cookies to OpenCode config; - Re-reading cookie file before each request; - New and continued Hyperagent threads through MCP; - OpenAI Chat Completions API for connecting as a separate OpenCode provider; - Streaming and non-streaming responses; - Conversion of tool calls of the model into real local OpenCode tools; - Protection against false statements about creating or modifying local files; - Binding HTTP-provider only to `127.0.0.1`; - Automatic removal of temporary Hyperagent threads of the provider. ## Supported Models | Alias | Name | Hyperagent model ID | Runtime | Context | Max Response | |---|---|---|---|---:|---:| | `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 | For Fable 5, `effort=max` and `maxThinkingTokens=32000` are used. For GPT-5.6 Sol, `effort=max` is used. ## Project Structure ```text OpenCode ├── MCP client ──stdio──> dist/src/index.js │ └── Hyperagent session API └── AI provider ──HTTP──> 127.0.0.1:18457/v1 └── provider-server.js ├── conversion of OpenAI messages/tools ├── Hyperagent session API └── return of tool calls back to OpenCode ``` Remote Hyperagent sandbox (`/agent/workspace`) **is not the user's computer**. In provider mode, any operations with the current directory, files, shell, and processes must be performed by OpenCode tools on the local computer. The server uses separate transport names for tools so that they do not intersect with built-in tools of the remote sandbox. ## Requirements - Node.js 18 or later; - npm; - Active account and browser session on `https://hyperagent.com`; - OpenCode — only if it is required to connect models as a provider or MCP in OpenCode. ## Installation ```bash git clone <URL-OF-YOUR-REPOSITORY> cd hyperagent-mcp npm ci npm run build ``` Main commands: | Command | Purpose | |---|---| | `npm run check` | Check TypeScript without creating `dist` | | `npm run build` | Build JavaScript in `dist/src` | | `npm start` | Run stdio MCP server manually | | `npm run provider` | Run HTTP-provider in foreground | | `npm run provider:start` | Run provider in background | | `npm run provider:status` | Check provider and `/health` | | `npm run provider:stop` | Correctly stop provider | ## Cookies: Location and Format ### Where is the file By default, the server looks for the `cookies.md` file in the current working directory. - In this installed copy: `/root/test/cookies.md`; - In a usual clone: `<repository-root>/cookies.md`; - Recommended path: next to `package.json`. The path can be overridden by an environment variable: ```bash export HYPERAGENT_COOKIES_FILE=/absolute/path/to/cookies.md ``` The background service script by default always uses `<repository-root>/cookies.md`, regardless of the directory from which the npm command was launched. The `cookies.md` file is included in `.gitignore` and should not get into GitHub, npm package, logs, or error messages. A safe template is located in `cookies.example.md`. ### How to prepare cookies.md 1. Log in to `https://hyperagent.com` in the browser. 2. Open Chrome DevTools and Cookies table for `hyperagent.com`. 3. Copy cookie rows as tabular data with TAB separator. 4. Save data in `<repository-root>/cookies.md`. 5. Do not convert the table to Markdown with `|` characters. Expected order of first columns: ```text Name<TAB>Value<TAB>Domain<TAB>Path<TAB>... ``` The header `Name<TAB>Value...` is allowed and will be skipped. The server uses name, value, and domain, but requires a tabular format with at least four columns. Only the following domains are allowed: - `hyperagent.com`; - `.hyperagent.com`. Cookies are re-read before **each** request to Hyperagent. After replacing `cookies.md`, restarting is usually not required. ### Cookie Security Cookies are equivalent to bearer credentials and provide access to your session. - Do not commit `cookies.md`; - Do not insert values into `opencode.jsonc`; - Do not send the file in issue, gist, or CI artifact; - Do not transfer cookies to any domain except the fixed `https://hyperagent.com`; - After accidental publication, terminate the Hyperagent session and obtain new cookies. The client prohibits cross-origin redirects, checks domain strings, and rejects characters that allow embedding additional HTTP headers. ## Mode 1: stdio MCP Server After building, the entry point is located here: ```text dist/src/index.js ``` ### Connection to OpenCode Add to `~/.config/opencode/opencode.jsonc`, replacing paths with absolute ones: ```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 } } } ``` Check: ```bash opencode mcp list ``` ### hyperagent_models Tool Does not accept parameters. Returns aliases, API ID, runtime, limits, and settings of supported models. ### hyperagent_chat Tool | Field | Type | Required | Description | |---|---|---:|---| | `model` | `fable-5` or `gpt-5.6-sol` | yes | Model alias | | `prompt` | string | yes | Model message | | `thread_id` | string | no | ID of existing Hyperagent thread for continuation | | `systemPrompt` | string | no | System prompt of new thread or explicit update of existing one | | `timeout_seconds` | integer 10–1800 | no | Timeout, default 600 seconds | New dialog: ```json { "model": "fable-5", "prompt": "Answer with one word: OK" } ``` Continuation: ```json { "model": "fable-5", "thread_id": "ID_FROM_PREVIOUS_RESPONSE", "prompt": "Continue previous answer" } ``` The response contains `thread_id`, `created_thread`, model alias/ID, and `response` text. You need to continue the thread with the original model and runtime. MCP mode manages remote Hyperagent threads. By itself, it does not provide models with access to local OpenCode files. ## Mode 2: Models as a Separate OpenCode Provider This mode is needed if Fable 5 and GPT-5.6 Sol must be displayed in `/models` and work as coding models with local OpenCode tools. ### Running the Provider ```bash npm run build npm run provider:start npm run provider:status ``` The provider listens only to: ```text http://127.0.0.1:18457/v1 ``` Stopping: ```bash npm run provider:stop ``` Runtime files are created in the project root and are ignored by Git: - `.hyperagent-provider.pid` — PID of the background process; - `.hyperagent-provider.log` — stdout/stderr of the provider. ### OpenCode Configuration Add the provider to `~/.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 } } } } } } ``` Model check: ```bash opencode models hyperagent ``` Model identifiers: ```text hyperagent/fable-5 hyperagent/gpt-5.6-sol ``` ### How the provider works with local tools 1. OpenCode sends history, JSON Schema of tools, and `tool_choice` to the local provider. 2. The provider replaces tool names with unique transport aliases. 3. The model receives an explicit indication that the Hyperagent sandbox is not the user's computer. 4. The model returns a JSON request for tool calls. 5. The provider restores the actual tool name and returns the call to OpenCode. 6. OpenCode executes the tool locally and sends the result with the next message. 7. Only the local tool result is considered confirmation of reading, modifying, or creating a file. For obvious requests to create/edit/read files and determine the working directory, the provider requires the corresponding local tool calls. If the model does not return the required call even after a repair attempt, the request ends with an error instead of a false success message. Each OpenAI completion creates a temporary Hyperagent thread. After completion or an error, the provider attempts to delete this thread since OpenCode transmits the entire history anew at each step. ## HTTP API of the provider | Method | Endpoint | Description | |---|---|---| | `GET` | `/health` | Process check | | `GET` | `/v1/models` | List of two models | | `POST` | `/v1/chat/completions` | OpenAI-compatible chat completions | Both regular and SSE-streaming responses, OpenAI-style tool calls, and `tool_choice` are supported. ## Environment variables | Variable | Default | Purpose | |---|---|---| | `HYPERAGENT_COOKIES_FILE` | `<cwd>/cookies.md` | Absolute or relative path to the cookie file | | `HYPERAGENT_PROVIDER_PORT` | `18457` | Local port of the provider | | `HYPERAGENT_PROVIDER_DEBUG` | disabled | Value of `1` enables secure shape logs of requests | Debug mode records roles, number/names of tools, and result shape but should not record prompt texts or cookie values. ## Repository structure ```text . ├── src/ │ ├── index.ts # stdio MCP entry point │ ├── provider-server.ts # OpenAI-compatible HTTP provider │ ├── openai-compat.ts # messages, tool aliases, and tool-call parsing │ ├── hyperagent.ts # Hyperagent session API client │ ├── cookies.ts # secure cookie table parsing │ └── models.ts # allowed models and runtime ├── scripts/ │ └── provider-service.mjs # start/stop/status of the background provider ├── cookies.example.md # secure format template ├── cookies.md # actual cookies; ignored by Git ├── package.json └── tsconfig.json ``` `dist/`, `node_modules/`, logs, PID, and cookies are not published to Git. ## Post-installation checks ```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 ``` A live request requires an up-to-date `cookies.md`. ## Troubleshooting ### 401 or 403 The browser session has expired, or cookies were copied incompletely. Update `cookies.md` from an active Hyperagent session. Values are re-read at the next request. ### Invalid cookie table/domain/value Ensure the file is TAB-separated, contains at least four columns, and includes only `hyperagent.com` or `.hyperagent.com`. Do not paste a regular HTTP `Cookie:` header instead of the table. ### Provider does not start ```bash npm run build npm run provider:status cat .hyperagent-provider.log ``` Also, check if `127.0.0.1:18457` is free or set another `HYPERAGENT_PROVIDER_PORT` and update OpenCode's `baseURL`. ### Model writes that a file is created, but the file does not exist Ensure a model like `hyperagent/fable-5` or `hyperagent/gpt-5.6-sol` is selected via the local provider, not the remote Hyperagent MCP/agent. The local provider must return tool calls, after which OpenCode shows the actual execution of `write`, `edit`, or `bash`. ### Hyperagent changed its internal API Check the responses of `/api/threads`, `/api/threads/:id/messages`, and chat SSE. The project intentionally does not use cookies on third-party domains, so it cannot be automatically switched to an unknown endpoint. ## Preparing for publication on GitHub Before the first commit: ```bash git init git check-ignore cookies.md git status --short npm ci npm run check npm run build ``` Ensure that staged files do not include: - `cookies.md` and any real cookie values; - `.hyperagent-provider.log` and `.hyperagent-provider.pid`; - `node_modules/`, `dist/`, `.env`; - user-specific files unrelated to the MCP/provider. Then: ```bash git add . git status --short git commit -m "Initial Hyperagent MCP bridge" git branch -M main git remote add origin <YOUR-REPOSITORY-URL> git push -u origin main ``` ## Limitations - Internal Hyperagent APIs may change. - Cookies expire and require manual updates. - Image input is converted into a text notification and not transmitted as an image. - Token usage in OpenAI-compatible responses is estimated approximately by the number of characters. - The official remote MCP Hyperagent manages agents in a remote sandbox and does not give them direct access to OpenCode's local file system. - This project is not an official SDK or product of Hyperagent.