helloaigent-subscriber

@helloaigent-dev/subscriber

Hello Aigent リファレンスサブスクライバー — あらゆるエージェントが任意の Hello Aigent フィードをサブスクライブし、署名付き更新を取得して検証し、それに基づいて動作できる MCP サーバーです。 さらに watch モード では、エージェントの実行間に検証済み更新をダイジェストへ収集する常駐ポーラーとして動作します。

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)

試してみる

発行者の認証情報は不要で、~/.hello-aigent に触れることなく、実際の dogfood ループを試せます。

npx -y @helloaigent-dev/subscriber smoke

これは https://helloaigent.dev/.well-known/hello-aigent.json に GET リクエストを送り、サブスクライブして、すべてのエンベロープ署名を取得・検証します。状態は一時ディレクトリ（HELLO_AIGENT_STATE / HELLO_AIGENT_POLICY / HELLO_AIGENT_DIGEST）に書き込まれるため、実際のプロファイルが上書きされることはありません。レポートには検証済みと未検証の件数、コピーして貼り付けられる MCP 設定、次のステップが表示されます（policy.act が有効な場合に限ります。このパッケージでは hello_aigent_act は実装されていません）。

git clone から実行する場合：

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

次に、MCP サーバーを接続し（下記の設定を参照）、その検出 URL を指定して hello_aigent_subscribe を呼び出すと、継続的なプロファイルを設定できます。

ツール

ツール	機能
hello_aigent_subscribe(discovery_url, feed_id?, principal?, consent_scope?)	サイトの /.well-known/hello-aigent.json を読み取り、サブスクライブします（デフォルト値はポリシーから取得します）
hello_aigent_fetch(subscription_id?, max?)	保存済みカーソルを使って前回以降の更新のみを取得し、すべてのエンベロープ署名を検証します
hello_aigent_unsubscribe(subscription_id)	同意を取り消します（冪等）— 1 回の呼び出しで取り消せます
hello_aigent_list_subscriptions()	保存済みのサブスクリプションを一覧表示します（トークンが公開されることはありません）
hello_aigent_check_site(url)	閲覧中のサイトにフィードがあるか確認し、継続的なポリシー（origin: auto）に従って自動的にサブスクライブします
hello_aigent_digest()	watch が収集した未読のダイジェスト項目を返し、表示済みとしてマークします
hello_aigent_setup_watch(cadence?)	適用可能な常時スケジュールの設定例（スケジュール済みタスク、定期タスク、cron）を出力します

Watch モード

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

各実行では、アクティブなサブスクリプションすべてをポーリングし、署名を検証して、新しい更新をダイジェストファイルに追加します。サーバー側のメールボックスにより、実行を逃しても情報が失われることはありません。新しい更新が届いたときに --exec を指定すると、HELLO_AIGENT_NEW_UPDATES と HELLO_AIGENT_DIGEST を設定した状態でコマンドが実行されます。

ポリシー

初回実行時に ~/.hello-aigent/policy.json に書き込まれます。デフォルトではすべて自動になっており、変更する場合はこのファイルを編集します。

キー	デフォルト	意味
principal	user@host	すべてのフィードで使用する一貫した ID です。一度設定します（例：メールアドレス）
auto_subscribe	on	エージェントが Hello Aigent サイトを訪問したときにサブスクライブします：on / ask / off
watch_cadence	daily	watch のポーリング頻度（最小は hourly）
act	safe	エージェントがプロンプトなしで実行できる操作：none / safe（副作用なし） / thresholds
pseudonymous	false	オプトイン：サイトごとに仮名の principal を使用します

誰にも読まれないフィードは徐々に停止します。30 日間アイドル状態が続くと watch によるポーリングが停止し、60 日後にはサブスクライブが解除されます（その旨がダイジェストに記録されます）。ダイジェストを読んだり、フィードを取得したりすると、アクティブな状態が維持されます。

保証

• 操作可能にする前に署名を検証します。 エンベロープは、フィードの検出用公開鍵を使って Ed25519 で検証されます（RFC 8785 JCS 正規化）。検証に失敗したデータは unverified に含められ、actions は取り除かれます。
• 同意は継続的なポリシーとして扱われます。 サブスクライブ時に principal と consent_scope が記録されます。ポリシーファイルが同意レイヤーとなり、サブスクライブ解除は常に 1 回の冪等な呼び出しで行えます。
• 状態はローカルにのみ保存されます。 サブスクリプション（ベアラートークンを含む）、ポリシー、ダイジェストは ~/.hello-aigent/（モード 0600）に保存されます。HELLO_AIGENT_STATE / HELLO_AIGENT_POLICY / HELLO_AIGENT_DIGEST で保存先を変更できます。

WebMCP（ページ内）

webmcp/hello-aigent-webmcp.js は、helloaigent.dev で使用されるページ内オンランプの公開上の信頼できる情報源です。このパッケージの stdio MCP サーバーとは別のインターフェースです。ChatGPT のブラウザーまたは Chrome（chrome://flags/#enable-webmcp-testing）が存在すると、3 つのツール（hello_aigent_check_feed、hello_aigent_subscribe、hello_aigent_fetch_updates）が document.modelContext.registerTool を介して登録されます。type="module" ではなく、クラシックな <script src> タグ（IIFE）として読み込んでください。helloaigent.dev では、API に CORS がないため、subscribe/fetch は同一オリジンの /webmcp/* プロキシを経由します。webmcp/README.md をご覧ください。

MCP クライアント設定

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

Cursor / Grok Bot プラグイン

このリポジトリは、Cursor と Grok Bot が読み込める Agent Plugins バンドル（MCP + スキル）としてもパッケージ化されています。Cursor Marketplace のプラグインも同じ形式です。Grok Bot 専用のパッケージはありません。このプラグインはまだ Cursor Marketplace に掲載されていません。

1. カスタム MCP コネクター（現在利用可能）

公開済みの npm パッケージを、Cursor を含む任意の MCP クライアントに指定します。

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

API キーは不要です。その後、チャットでエージェントにフィードの登録を依頼します（https://helloaigent.dev をお試しください）。

2. ローカルプラグイン（MCP + スキル）

開発中にスキルと MCP を一緒に読み込むには、次の手順を実行します。

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

Cursor を再起動するか、Developer: Reload Window を実行します。Customize に Hello Aigent スキルと MCP サーバーが表示されることを確認してください。Grok Bot も同じプラグインファイルを使用します。

構成：

ファイル	役割
plugin.json	Agent Plugins 1.0 マニフェスト（移植可能。Cursor はそのまま読み込みます）
.cursor-plugin/plugin.json	Cursor Marketplace のメタデータ + 相対パスの assets/logo.svg
assets/logo.svg	公式の Hello Aigent ファビコン：オレンジ色の #E0531C のタイル、白い H、濃色のシェブロン A
mcp.json	stdio MCP → npx -y @helloaigent-dev/subscriber（このパッケージと同じサーバー）
skills/hello-aigent/SKILL.md	登録、取得、確認、登録解除の方法とタイミング

3. 公式マーケットプレイスへの掲載（後日）

申請して承認されたら、Cursor Marketplace からインストールしてください。それまでは、上記のカスタムコネクターまたはローカルプラグインの方法を使用してください。この README から申請しないでください。準備が整い次第、メンテナーが cursor.com/marketplace/publish から申請します。

ライセンス

MIT