helloaigent-subscriber

@helloaigent-dev/subscriber

The Hello Aigent reference subscriber — an MCP server that lets any agent subscribe to any Hello Aigent feed, fetch signed updates, verify them, and act on them. Plus watch mode: a standing poller that collects verified updates into a digest between agent runs.

npx -y @helloaigent-dev/subscriber            # MCP server (stdio)
npx -y @helloaigent-dev/subscriber watch      # standing watcher (default cadence: daily)
npx -y @helloaigent-dev/subscriber smoke      # dogfood loop against the live feed (isolated state)

Try it

Walk the live dogfood loop without publisher credentials and without touching ~/.hello-aigent:

npx -y @helloaigent-dev/subscriber smoke

That GETs https://helloaigent.dev/.well-known/hello-aigent.json, subscribes, fetches, and verifies every envelope signature. State is written to a temp directory (HELLO_AIGENT_STATE / HELLO_AIGENT_POLICY / HELLO_AIGENT_DIGEST), so a real profile is never clobbered. The report prints verified vs unverified counts, a copy-paste MCP config, and the next step (gated on policy.act — this package does not implement hello_aigent_act).

From a git clone:

npm i && npm test && npm run build
node dist/index.js smoke

Then connect the MCP server (config below) and call hello_aigent_subscribe with that discovery URL for a standing profile.

Tools

Tool	What it does
hello_aigent_subscribe(discovery_url, feed_id?, principal?, consent_scope?)	Reads the site's /.well-known/hello-aigent.json, subscribes (defaults come from your policy)
hello_aigent_fetch(subscription_id?, max?)	Pulls only-new-since updates via the stored cursor; verifies every envelope signature
hello_aigent_unsubscribe(subscription_id)	Revokes consent (idempotent) — the one-call undo
hello_aigent_list_subscriptions()	Lists stored subscriptions (tokens are never exposed)
hello_aigent_check_site(url)	Checks a site you're visiting for a feed; auto-subscribes per your standing policy (origin: auto)
hello_aigent_digest()	Returns unread digest entries collected by watch and marks them surfaced
hello_aigent_setup_watch(cadence?)	Emits ready-to-apply standing-schedule recipes (scheduled task, recurring task, cron)

Watch mode

npx -y @helloaigent-dev/subscriber watch --once            # one pass (what schedulers call)
npx -y @helloaigent-dev/subscriber watch --every 6h        # long-running loop (floor: hourly)
npx -y @helloaigent-dev/subscriber watch --once --exec "my-agent-cmd"   # trigger a run on new updates

Each pass polls every active subscription, verifies signatures, and appends new updates to the digest file. The server-side mailbox means a missed run loses nothing. --exec runs your command when new updates land, with HELLO_AIGENT_NEW_UPDATES and HELLO_AIGENT_DIGEST set.

Policy

Written to ~/.hello-aigent/policy.json on first run — everything automatic by default, and this file is where you change that:

Key	Default	Meaning
principal	user@host	Your stable identity across all feeds — set it once (e.g. your email)
auto_subscribe	on	Subscribe when your agent visits a Hello Aigent site: on / ask / off
watch_cadence	daily	How often watch polls (hourly floor)
act	safe	What the agent may do unprompted: none / safe (side-effect-free) / thresholds
pseudonymous	false	Opt-in: per-site pseudonymous principals

Feeds nobody reads decay: after 30 idle days watch stops polling them; after 60 it unsubscribes (noted in the digest). Reading the digest or fetching a feed keeps it alive.

Guarantees

• Signature verification before anything is actionable. Envelopes are Ed25519-verified (RFC 8785 JCS canonicalization) against the feed's discovery public key. Anything that fails verification is returned under unverified with its actions stripped.
• Consent is standing policy. Subscribing records principal + consent_scope; your policy file is the consent layer, and unsubscribe is always one idempotent call.
• Local state only. Subscriptions (including bearer tokens), policy, and the digest live in ~/.hello-aigent/ (mode 0600). Override with HELLO_AIGENT_STATE / HELLO_AIGENT_POLICY / HELLO_AIGENT_DIGEST.

WebMCP (in-page)

webmcp/hello-aigent-webmcp.js is the public source of truth for the in-page on-ramp used on helloaigent.dev. It is a different surface from the stdio MCP server in this package: three tools (hello_aigent_check_feed, hello_aigent_subscribe, hello_aigent_fetch_updates) register via document.modelContext.registerTool when ChatGPT’s browser or Chrome (chrome://flags/#enable-webmcp-testing) is present. Load it as a classic <script src> tag (IIFE), not type="module". On helloaigent.dev, subscribe/fetch go through a same-origin /webmcp/* proxy because the API has no CORS. See webmcp/README.md.

MCP client config

{
  "mcpServers": {
    "hello-aigent": { "command": "npx", "args": ["-y", "@helloaigent-dev/subscriber"] }
  }
}

Cursor / Grok Bot plugin

This repo is also packaged as an Agent Plugins bundle (MCP + skill) that Cursor and Grok Bot can load. Cursor Marketplace plugins are that same format — there is no separate Grok Bot package. This plugin is not listed on the Cursor Marketplace yet.

1. Custom MCP connector (works today)

Point any MCP client, including Cursor, at the published npm package:

{
  "mcpServers": {
    "hello-aigent": { "command": "npx", "args": ["-y", "@helloaigent-dev/subscriber"] }
  }
}

No API key. Then in chat: ask the agent to subscribe to a feed (try https://helloaigent.dev).

2. Local plugin (MCP + skill)

To load the skill and MCP together while developing:

mkdir -p ~/.cursor/plugins/local
ln -s /path/to/helloaigent-subscriber ~/.cursor/plugins/local/hello-aigent

Restart Cursor, or run Developer: Reload Window. Confirm the Hello Aigent skill and MCP server appear under Customize. Grok Bot uses the same plugin files.

Layout:

File	Role
plugin.json	Agent Plugins 1.0 manifest (portable; Cursor loads this as-is)
.cursor-plugin/plugin.json	Cursor marketplace metadata + relative assets/logo.svg
assets/logo.svg	Official Hello Aigent favicon: orange #E0531C tile, white H, dark chevron A
mcp.json	stdio MCP → npx -y @helloaigent-dev/subscriber (same server as this package)
skills/hello-aigent/SKILL.md	When/how to subscribe, fetch, verify, and unsubscribe

3. Official marketplace listing (later)

When this is submitted and approved, install from the Cursor Marketplace. Until then, use the custom connector or the local plugin path above. Do not submit from this README — maintainers will submit at cursor.com/marketplace/publish when ready.

License

MIT