# Hermes Plugin Tinyfish

> TinyFish web_search/web_extract provider plugin for Hermes Agent

- **Type:** MCP server
- **Install:** `agentstack add mcp-gabeosx-hermes-plugin-tinyfish`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gabeosx](https://agentstack.voostack.com/s/gabeosx)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gabeosx](https://github.com/gabeosx)
- **Source:** https://github.com/gabeosx/hermes-plugin-tinyfish
- **Website:** https://docs.tinyfish.ai/

## Install

```sh
agentstack add mcp-gabeosx-hermes-plugin-tinyfish
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Hermes TinyFish Plugin

[](https://github.com/gabeosx/hermes-plugin-tinyfish/actions/workflows/ci.yml)
[](https://pypi.org/project/hermes-plugin-tinyfish/)
[](https://pypi.org/project/hermes-plugin-tinyfish/)
[](LICENSE)
[](SECURITY.md)

TinyFish Search and Fetch providers, plus optional TinyFish Browser
infrastructure, for
[Hermes Agent](https://hermes-agent.nousresearch.com/docs/).

Hermes remains the agent: it plans, chooses tools, and controls browser
interaction. This plugin supplies web data and, when explicitly enabled, a
remote browser session underneath Hermes's own browser loop.

This is an independent community plugin. It is not affiliated with, endorsed
by, or maintained by TinyFish or Hermes / Nous Research.

TinyFish documentation currently describes Search and Fetch as free and
Browser as credit-consuming. This plugin treats Search and Fetch as the safe
default entry point. Pricing and free-use assumptions are based only on current
TinyFish documentation and may change; Browser defaults to `deny`.

## Install

Hermes Git plugin install:

```bash
hermes plugins install gabeosx/hermes-plugin-tinyfish --enable
hermes tinyfish setup
```

Python package install:

```bash
pip install hermes-plugin-tinyfish
hermes tinyfish setup
```

## Update

Update an existing Hermes Git plugin installation:

```bash
hermes plugins update web-tinyfish
hermes tinyfish status
hermes tinyfish doctor
```

If the plugin was installed as a Python package instead, update it with:

```bash
python -m pip install --upgrade hermes-plugin-tinyfish
hermes tinyfish status
hermes tinyfish doctor
```

## Safe Default Setup

`hermes tinyfish setup` configures TinyFish for Hermes `web_search` and
`web_extract` only:

```yaml
mcp_servers:
  tinyfish:
    url: https://agent.tinyfish.ai/mcp
    auth: oauth
    tools:
      include: [search, fetch_content]
      resources: false
      prompts: false

web:
  search_backend: tinyfish
  extract_backend: tinyfish

tinyfish:
  credit_policy:
    browser: deny
```

The plugin prefers TinyFish's hosted OAuth MCP server and falls back to REST
with `TINYFISH_API_KEY` when MCP OAuth is unavailable. It may save
`TINYFISH_API_KEY` to `~/.hermes/.env` if you choose API-key fallback.

Verify Search and Fetch:

```bash
hermes tinyfish doctor
hermes tinyfish doctor --live
hermes tinyfish doctor --live --transport mcp
hermes tinyfish doctor --live --transport rest
```

`doctor --live` runs independent Search and Fetch checks and exits nonzero if
either fails. The default `auto` transport remains MCP-first and may use the
REST fallback. Use `--transport mcp` to test OAuth without allowing REST to
hide an MCP failure, or `--transport rest` to test only the API-key path.

If MCP reports that authorization must be renewed:

```bash
hermes tinyfish reauth
```

The command replaces the current plugin CLI process with Hermes's supported
`hermes mcp login tinyfish` command; it does not start a nested Hermes process.
If a gateway or another Hermes process shares the same Hermes home, pause that
process and any supervisor or watchdog for the maintenance window. The plugin
does not stop host services automatically.

Complete the browser flow, restore and reload or restart affected Hermes
processes, then verify the recovered OAuth path with
`hermes tinyfish doctor --live --transport mcp`. The plugin never deletes,
rewrites, or validates Hermes's OAuth token files itself.

For browser authorization from a headless or remote terminal:

- Complete one authorization flow at a time and never combine an authorization
  URL with a callback URL from another attempt.
- Terminal wrapping is visual. Copy the entire URL and do not manually edit
  OAuth characters such as `state` or the PKCE challenge.
- If copied terminal text contains line breaks, remove only whitespace. In a
  local Blink shell on iOS/iPadOS, for example:

  ```bash
  pbpaste | tr -d '\r\n\t ' | pbcopy
  ```

- If Hermes prints another authorization URL before reporting success, stop
  that attempt rather than authorizing multiple URLs.
- Treat the MCP-only doctor as authoritative. Some Hermes versions can print
  an authentication failure while still returning shell status 0.

## Search and Fetch Options

Optional REST fallback defaults can be configured in `config.yaml`:

```yaml
tinyfish:
  search:
    location: US
    language: en
    recency_minutes: 1440
    domain_type: web
    page: 0
  fetch:
    format: markdown
    links: false
    image_links: false
    ttl: 3600
```

MCP remains the preferred path when configured. These options apply only to
REST fallback calls.

## Optional Browser Provider

TinyFish Browser can supply remote browser infrastructure for Hermes after
explicit opt-in:

```yaml
browser:
  cloud_provider: tinyfish
tinyfish:
  credit_policy:
    browser: request
```

Browser policy values are:

- `deny`: fail closed; this is the default.
- `request`: use Hermes's approval flow for each `browser_*` tool invocation.
- `allow`: run Browser tools without per-invocation approval.

Manage the policy with:

```bash
hermes tinyfish credits status
hermes tinyfish credits set browser request
hermes tinyfish credits reset
```

`credits reset` restores `browser: deny` and removes retired Agent/Profile
policy keys left by plugin `0.2.x`.

## Why TinyFish Agent Is Not Included

TinyFish Agent performs delegated goal-based web automation. Hermes already
owns planning and browser interaction, so exposing a second agent loop through
this provider is duplicative and makes control, approval, and billing less
clear. The plugin therefore does not register TinyFish Agent tools or manage
Browser Context Profiles.

Users who specifically need TinyFish's delegated Agent, Profile, Vault, batch,
or streaming capabilities can configure TinyFish's full MCP service
independently in Hermes. Those tools are outside this plugin's setup, policy,
diagnostics, and compatibility guarantees. The plugin-managed `tinyfish` MCP
entry intentionally remains restricted to `search` and `fetch_content`.

## Diagnostics and Migration

```bash
hermes tinyfish status
hermes tinyfish usage
hermes tinyfish doctor --live
hermes tinyfish doctor --live --transport mcp
hermes tinyfish doctor --live-paid
```

- `status` is non-secret and reports ignored `0.2.x` policy keys under
  `retired_credit_policy_keys`.
- `mcp_token_cached` reports only whether Hermes's expected cache file is
  present. It does not mean the access or refresh token is valid.
- `/tinyfish-status` shows non-networked status inside CLI or gateway sessions;
  `/tinyfish-status live` explicitly runs Search and Fetch checks.
- `usage` reads TinyFish Fetch operation history; it is not Agent or Browser
  billing data.
- `doctor --live-paid` only creates and closes a TinyFish Browser session. It
  refuses under `deny`, requests approval under `request`, and never prints
  connection URLs or credentials.
- The former `agent` and `profiles` commands and model-callable Agent tools are
  intentionally removed. Existing remote TinyFish runs, profiles, credentials,
  and saved state are not changed.

## Upgrade Safety

This plugin uses public Hermes extension points:

- `ctx.register_web_search_provider(...)`
- `ctx.register_browser_provider(...)`
- `ctx.register_hook("pre_tool_call", ...)` for Browser credit policy
- `ctx.register_cli_command(...)`
- `ctx.register_command(...)` for `/tinyfish-status`
- `ctx.dispatch_tool(...)` for registered TinyFish MCP calls
- Hermes MCP configuration under `mcp_servers`
- Hermes environment helpers for optional API-key fallback

It does not patch Hermes Agent, update scripts, Dockerfiles, or files inside a
Hermes installation or source checkout. A narrow legacy compatibility shim
still asks Hermes to discover configured MCP servers when TinyFish tools have
not been registered in the current process. It is retained because removing it
reintroduces a previously observed MCP-to-REST regression; it will be removed
only after every supported Hermes surface owns discovery through a public API.

## Development

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
ruff format .
ruff check .
mypy hermes_plugin_tinyfish
pytest --cov=hermes_plugin_tinyfish --cov-fail-under=70
python -m build
```

Live tests are opt-in:

```bash
TINYFISH_LIVE_TESTS=1 TINYFISH_API_KEY=... pytest tests/test_live.py
```

## Maintainer Docs

- [Release operations](docs/operations/release.md)
- [Compatibility testing](docs/operations/compatibility-testing.md)
- [OAuth hardening compatibility report](docs/operations/oauth-hardening-compatibility-report.md)
- [User install smoke test](docs/operations/user-install-smoke-test.md)
- [Hermes extension points](docs/reference/hermes-extension-points.md)
- [TinyFish integration notes](docs/reference/tinyfish-integration.md)
- [Roadmap and non-goals](docs/roadmap.md)

## References

- [TinyFish MCP Integration](https://docs.tinyfish.ai/mcp-integration)
- [TinyFish Authentication](https://docs.tinyfish.ai/authentication)
- [TinyFish Search API](https://docs.tinyfish.ai/search-api)
- [TinyFish Fetch API](https://docs.tinyfish.ai/fetch-api)
- [TinyFish Browser API](https://docs.tinyfish.ai/browser-api)
- [Hermes Web Search Provider Plugins](https://hermes-agent.nousresearch.com/docs/developer-guide/web-search-provider-plugin)
- [Hermes Browser Provider Plugins](https://hermes-agent.nousresearch.com/docs/developer-guide/browser-provider-plugin)
- [Hermes Plugins](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins)
- [Hermes MCP](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gabeosx](https://github.com/gabeosx)
- **Source:** [gabeosx/hermes-plugin-tinyfish](https://github.com/gabeosx/hermes-plugin-tinyfish)
- **License:** MIT
- **Homepage:** https://docs.tinyfish.ai/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-gabeosx-hermes-plugin-tinyfish
- Seller: https://agentstack.voostack.com/s/gabeosx
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.