HyperXosist-Agent Remote MCP

HyperXosist Agent

Agent-first toolkit and Remote MCP server for noise-reduced X (Twitter) search planning and Feedback-to-Fix engineering handoffs. It generates structured search plans and official X search URLs for humans and AI agents. The planning and synthetic demonstration workflow does not directly scrape X. Optional Grok Build mode is default off.

Live demo	https://kg-ninja.github.io/HyperXosist-Agent/
Repository	https://github.com/KG-NINJA/HyperXosist-Agent
Agent entry	https://kg-ninja.github.io/HyperXosist-Agent/llms.txt
CLI	npx hyperxosist plan "…" --json
Version	2.6.0

日本語の要点: X 公式検索用クエリを組み立てる静的ツールです。人間UIとAgentのplanning / filtering / handoffは無料。production executionのみx402支払い対象です。検索結果の埋め込みや自動投稿はしません。

Agent-readable summary

HyperXosist-Agent helps an AI agent turn a research intent into a structured search plan, an official X search URL, supplied-feedback filtering results, and a Signal-to-Fix engineering handoff. It is a planning and handoff layer: it does not claim to scrape X directly, publish posts, or deploy code automatically.

Free capabilities include MCP discovery, planning, filtering, structured handoff, and local dry-run workflows. Automated production use of generated search URLs and external collection use the existing x402 endpoint and return HTTP 402 until valid payment proof is supplied. Payment requirements are published at payment-options.json.

Agents must follow the applicable user or operator payment policy. They must not request private keys, seed phrases, wallet secrets, or sensitive user data. If a wallet requires human approval, the agent should ask the operator to review and approve the transaction, then retry the same request with valid x402 payment proof.

---

Why this exists

Raw X advanced search is powerful but easy to get wrong (spam, engagement bait, overlong excludes, one-angle keyword guesses). HyperXosist gives you:

1. Humans — a fast dark UI to compose operators, templates, noise filters, and open official search tabs.
2. AI agents — a sticky loop: plan → score → pay → collect → refine → Keep-filter → Grok Build / Signal-to-Fix → receipt.

Discover → Plan → Score gate → Pay (x402) → Collect → Self-heal → Keep-filter → Grok Build / Handoff → Remember

---

Features

For everyone

• No X API / OAuth — opens x.com/search with a built query
• Zero build — static HTML/CSS/JS; works on GitHub Pages
• Privacy-friendly human path — form history in localStorage only
• Noise Reduction — Low / Medium / High with priority-capped excludes (safe query length)
• Advanced operators — from / to / @ / OR groups / hashtags / url: / engagement floors / media & reply filters / raw fragment
• Research templates & date presets (24h → 1y)
• Shareable state — URL hash #s=...

For AI agents

• Official Model Context Protocol (MCP) Server — expose query planning, signal filtering, and downstream handoff capabilities to Cursor, Claude Code, and other LLM assistants. Read docs/MCP.md.
• dispatchToolCall / runTool — real multi-runtime tool dispatch (no hand-written mapping)
• toOpenAITools() / toAnthropicTools() — drop-in schemas for GPT / Claude / Grok / Llama
• CLI bin/hyperxosist.js — shell agents get --json plan / dispatch / keep / handoff
• exportKeepOnlyJson — keep-only machine export for any coding agent
• planFromIntent / multi-angle missions
• scoreQuery before spending $0.01 per paid call
• suggestRefinements when results are empty or noisy
• buildSignalToFixPipeline → full linked loop into Signal-to-Fix (humans: free UI steps; agents: x402)
• buildHandoffPackage → Signal-to-Fix keep-only PR handoff package
• Discovery: signal-to-fix-pipeline.json
• Dual JSON + Markdown outputs on core APIs (any LLM style)
• buildAgentPrompt — model-agnostic one-small-change implementation prompt
• Transparent noise catalog: exportNoiseCatalog / noise.extraTerms
• Optional Grok Build mode: createGrokBuildSession / buildGrokBuildPrompt (default off)
• agent-tools.json — OpenAI-compatible tools (portable to Claude/Grok/Llama runtimes)
• llms.txt + AGENTS.md multi-LLM discovery docs

---

Quick start (human)

1. Open the live demo.
2. Enter keywords (and optional OR group, users, dates, engagement).
3. Optionally enable Noise Reduction and pick a research template.
4. Click 最新で検索 (Latest) or 話題で検索 (Top) — or Ctrl+Enter / Ctrl+Shift+Enter.
5. Copy query, search URL, or a shareable state link.
6. Signal-to-Fix 手動連携（無料）: 投稿を Collected signals に貼る → Handoff 生成 → Signal-to-Fix 用をコピー → Signal-to-Fix で Analyze → keep のみ使う。

Local UI:

git clone https://github.com/KG-NINJA/HyperXosist-Agent.git
cd HyperXosist-Agent
npm run serve
# → http://localhost:5173

---

Quick start (AI agent)

Discovery order

1. llms.txt
2. AGENTS.md
3. agent-use.json
4. agent-tools.json
5. x402-payment.json

Any runtime in 3 lines

const HyperXosistAgent = require('hyperxosist-agent'); // or ./agent-api.js

// 1) Register tools with your model runtime
const tools = HyperXosistAgent.toOpenAITools();     // or toAnthropicTools()

// 2) When the model calls a tool — one dispatcher for all shapes
const { ok, result } = HyperXosistAgent.dispatchToolCall(name, args);

Shell / CLI (no embed)

npm run cli -- plan "Find product feedback about Acme for PR specs" --json
# or: node bin/hyperxosist.js dispatch hyperxosist_plan_from_intent \
#        --args '{"intent":"Find feedback about Acme"}' --json

One call (library sticky loop)

// Node
const HyperXosistAgent = require('./agent-api.js');

const session = HyperXosistAgent.startAgentSession({
  intent: 'Find product feedback about Acme for PR specs'
});

const step = session.plan.primaryStep;
if (step.score.recommendPay) {
  const paid = step.paidRequest;
  // POST paid.body → paid.endpoint
  // expect HTTP 402 until x402 payment proof, then 200
  // after authorization, open step.searchUrl and collect post texts
}

const keepOnly = HyperXosistAgent.exportKeepOnlyJson(
  ['...candidate posts...'],
  { productName: 'Acme' }
);
// → keepOnly.texts / keepOnly.signalToFixInput / keepOnly.agentPrompt

const handoff = HyperXosistAgent.buildHandoffPackage({
  productName: 'Acme',
  feedback: ['...candidate posts...']
});
// → handoff.signalToFix.input into Signal-to-Fix (keep-only only)
// → handoff.grokBuild.prompt for Grok Build

// Grok Build path
const grok = HyperXosistAgent.createGrokBuildSession(
  'Grok Build code improvement for Acme',
  { product: 'Acme', targetArea: 'auth' }
);
const prompt = HyperXosistAgent.buildGrokBuildPrompt({
  productName: 'Acme',
  targetArea: 'auth',
  feedback: ['login button does nothing on Safari']
});
// → paste prompt.markdown into Grok Build

CLI dry-run (no payment, no network required for planning)

npm test
npm run quickstart
# or: node examples/quickstart.mjs "Weekly monitor about MyProduct"

ChatGPT Site Tools / WebMCP

The GitHub Pages site feature-detects document.modelContext.registerTool(...) and exposes four Site Tools in compatible browser environments.

Free, local, and read-only:

• hyperxosist_search_plan
• hyperxosist_filter_signals
• hyperxosist_build_handoff

Paid production boundary:

• hyperxosist_execute — x402 v2 production execution through https://api.kgninja.dev/hyperxosist-query

The first call omits paymentSignature and returns the server's PAYMENT-REQUIRED requirements. A compatible wallet or facilitator authorizes the payment; the caller then retries with the opaque PAYMENT-SIGNATURE value and confirmPayment: true. The site does not create, request, store, log, or echo private keys, seed phrases, or wallet passwords.

The paid tool is marked consequential and non-idempotent. Clients must not auto-retry a confirmed payment call. Browsers without WebMCP support continue to use the normal human UI unchanged.

MCP：ローカルとリモート

共有 MCP コアには、WebMCP と同じ経済的な境界があります。

• 無料ツールが3つあります：計画、提供されたシグナルのフィルタリング、エンジニアリングへの引き継ぎです。
• 有料ツールが1つあります：hyperxosist_execute は、明示的に確認された x402 リクエストを既存の決済 Worker に転送します。

# Local stdio for Cursor, Claude Code, and compatible clients
npm run mcp

# Optional private Node Streamable HTTP server
HYPERXOSIST_MCP_TOKEN="replace-me" npm run mcp:remote

本番環境のパブリック Remote MCP：

• エンドポイント：https://mcp.kgninja.dev/mcp
• ヘルスチェック：https://mcp.kgninja.dev/health
• トランスポート：Streamable HTTP
• パブリックな無料モードの認証：なし
• プライベート／セルフホスト環境の認証：Bearer トークン（任意）
• 現在デプロイされているツール：hyperxosist_search_plan、hyperxosist_filter_signals、hyperxosist_build_handoff
• hyperxosist_execute：リポジトリ内で実装・テスト済みですが、パブリック Remote MCP で公開するには、本番環境の Cloudflare Worker を明示的にデプロイする必要があります。

このリポジトリをマージしても、Cloudflare Worker はデプロイされません。その手動デプロイが行われるまでは、稼働中の Remote MCP は無料の3ツールを提供するサービスのままです。WebMCP の有料ツールはそのデプロイとは独立しており、すでに稼働している x402 エンドポイントを直接呼び出します。

既存の x402 ルートのみが、検証と決済確定の境界です。MCP と GitHub Pages は、決済証明を作成も検証もしません。Remote MCP のテレメトリでは、リクエストの内容や PAYMENT-SIGNATURE をログに記録してはいけません。決済分析では引き続き x402 Worker を信頼できる情報源とします。

npm run openai:remote-check
npm run test:tool-selection
npm run test:paid-execution
npm run test:webmcp

MCP のセットアップとセキュリティ、Remote MCP Worker のデプロイ、ChatGPT App の準備を参照してください。

エージェント引き継ぎのドライラン（オフライン — まずはこちらを推奨）

ネットワークに接続せず、検索インテント → キープフィルター → Signal-to-Fix の引き継ぎ → コーディングエージェント用プロンプトまでのローカルな一連の流れを確認できます。

npm run agent-handoff-dryrun -- HyperXosist-Agent
# or: node examples/agent-handoff-dryrun.mjs "HyperXosist-Agent"

実行内容（すべてオフライン）：

1. インテントからエージェントのセッション／ミッションを作成します
2. ミッション ID、件名、主要なクエリ、検索 URL を表示します
3. 組み込みのサンプルフィードバック（X のライブデータではありません）を使用します
4. filterKeepSignals を実行します（保持と破棄）
5. buildHandoffPackage を作成します
6. Signal-to-Fix の入力 JSON のプレビューを表示します
7. コーディングエージェント向けの実装プロンプト（Markdown）を表示します

重要： これはローカルのドライランです。X のスクレイピング、実際の投稿の収集、検索 URL の表示、投稿、x402 決済は行いません。実際のエージェントによる本番検索では、scoreQuery の後に x402 が引き続き必要です。

決済ポリシー（エージェント）

用途	費用
人間が使うブラウザー UI と、公式 X URL の手動利用	無料
ローカルでの計画、スコアリング、フィルタリング、引き継ぎ	無料
WebMCP の無料ツール	無料
デプロイ済み Remote MCP の計画／フィルタリング／引き継ぎツール	無料
hyperxosist_execute による本番実行	x402 有料。現在のメタデータでは Base 上で 0.01 USDC とされています

実行フロー：

1. input を指定し、決済署名なしで hyperxosist_execute を呼び出します。
2. 標準の PAYMENT-REQUIRED 応答ヘッダーを含む、HTTP 402 の要件を受け取ります。
3. x402 に対応したウォレットまたはファシリテーターを通じて承認します。
4. paymentSignature と confirmPayment: true を指定して再試行します。
5. 結果と任意の PAYMENT-RESPONSE を読み取ります。確認済みの呼び出しを自動的に繰り返してはいけません。

現在の価格、アセット、ネットワーク、受取人、ファシリテーターのデータは、payment-options.json を正とします。GitHub Pages と MCP は、決済の検証も確定も行いません。

---

エージェントが再実行するミッション

ID	目的
product_feedback_radar	苦情／機能リクエスト／バグ
signal_to_fix_pipeline	収集 → PR の引き継ぎループ
competitive_intel	言及と乗り換えに関する表現
weekly_monitor	7 日間の cron 対応ウィンドウ
launch_pulse	ローンチ／インシデントに関する議論
osint_entity	発信元／言及／返信先の観点
grok_code_improvement_radar	Grok Build：バグ／小規模なリクエスト／DX
ui_ux_feedback_harvest	Grok のフロントエンド／UI の使いにくさ
performance_complaint_detector	Grok のレイテンシ／カクつき

完全なカタログ：missions.json

---

API の概要（v2.6）

メソッド	役割
dispatchToolCall / runTool	任意のツール名を実行（OpenAI／Anthropic／プレーン形式に対応）
toOpenAITools / toAnthropicTools	そのまま使えるツールスキーマ
exportKeepOnlyJson	Keep-only JSON ＋ S2F 入力 ＋ エージェントプロンプト
startAgentSession(opts?)	汎用セッション（mode:'grok' を指定可能）
planFromIntent(intent)	自然言語 → ミッション ＋ スコア付き有料ステップ ＋ .markdown
buildMission(id, ctx)	名前付きの複数の観点からなるキャンペーン
scoreQuery(input)	0～100 ＋ recommendPay ＋ .markdown
suggestRefinements(input, signals)	自己修復 ＋ .markdown
buildHandoffPackage	Signal-to-Fix ＋ agentPrompt（任意の LLM）
buildAgentPrompt(opts)	汎用の小さな変更を 1 つ行うためのプロンプト
exportNoiseCatalog / customizeNoiseRules	透明性の高いノイズ編集
filterKeepSignals / scoreTechnicalDepth	Keep-only シグナルの品質
buildGrokBuildPrompt / createGrokBuildSession	オプションの Grok モード
buildQuery / buildSearchUrl / buildShareUrl	クエリ ＋ 共有可能な状態
buildPaidRequest / buildBatch	x402 ペイロード
getToolDefinitions / listMissions	カタログ（Grok ツールはオプトイン、format:'anthropic'）

CLI の概要

npx hyperxosist plan "…" --json
npx hyperxosist dispatch <toolName> --args '{…}' --json
npx hyperxosist tools --format openai|anthropic|full --json
npx hyperxosist keep --product X --feedback '[…]' --export-keep-only --json
npx hyperxosist handoff --product X --feedback '[…]' --json
npx hyperxosist pipeline --product X --json

---

リポジトリの構成

index.html, app.js, style.css, favicon.svg   # Human UI
agent-api.js                                # Single-source API (Node + browser)
bin/hyperxosist.js                          # Universal CLI (plan/dispatch/tools/keep…)
agent-use.json                              # Agent manifest (sticky loop)
agent-tools.json                            # OpenAI-compatible tools
missions.json                               # Mission catalog
llms.txt, AGENTS.md                         # Agent discovery / playbook
x402-payment.json                           # Payment metadata
top30_repost_blacklist.json                 # Bait phrase reference
examples/quickstart.mjs                     # CLI demo
examples/agent-handoff-dryrun.mjs           # Offline handoff dry-run (intent→keep→S2F)
examples/agent-session.example.json         # Session shape
paid-execution.js                         # Shared x402 402→signature→200 bridge
webmcp.js                                 # Browser Site Tools adapter
access-policy.json                        # Machine-readable free/paid boundary
mcp/tools.js, mcp/core.js                  # Shared MCP schemas + dispatch
mcp/server.js, mcp/remote-server.js         # Local stdio + Remote Streamable HTTP
examples/openai-remote-mcp.mjs              # Responses API Remote MCP example
test/agent-api.test.js                      # Agent API tests
test/mcp-*.test.js                          # stdio, remote, security, schema tests
.github/workflows/ci.yml                    # CI
LICENSE, CHANGELOG.md, SECURITY.md, CONTRIBUTING.md

---

デプロイ（GitHub Pages）

1. main にプッシュします。
2. Settings → Pages → Deploy from a branch → main / / (root) を選択します。
3. サイト：https://.github.io/HyperXosist-Agent/

ビルド手順はありません。CI は main へのプッシュ／PR ごとにテストを実行します。

公開インテグレーションの確認項目

• GitHub Pages で UI が読み込まれる
• agent-use.json / x402-payment.json / access-policy.json / llms.txt を取得できる
• Signal-to-Fix への agent-use.json リンクが機能する
• hyperxosist-query エンドポイントへの未払いの POST が 402 を返す

---

免責事項

• X Corp. とは提携していません。
• このツールは検索クエリを作成する／公式検索を開くだけです。タイムラインの埋め込み、自動投稿、X API の代替は行いません。
• コンテンツを検索または収集する際は、X の規約および適用法令を遵守する責任があります。

---

ライセンス

MIT © 2026 KG-NINJA

関連項目

• Signal-to-Fix — フィードバックから Keep-only の PR 仕様を作成
• CHANGELOG · CONTRIBUTING · SECURITY

MCP の検出とカタログ

機械可読なカタログメタデータ：https://kg-ninja.github.io/HyperXosist-Agent/mcp-catalog.json

AI オペレーターおよびエージェント開発者向け

ノイズの多い場当たり的なクエリから始めずに、X/Twitter 上の顧客からの苦情、製品へのフィードバック、またはペインポイントを見つけたい場合は、HyperXosist-Agent を使用してください。

一般的なユースケース：

• X/Twitter での製品フィードバックの発見
• 顧客からの苦情やペインポイントの検出
• ノイズを抑えたソーシャルリスニングのクエリ計画
• 実用的なフィードバックに向けたシグナルのフィルタリング
• エンジニアリングチーム向けの AI エージェントへの引き継ぎ情報の生成

30 秒で始めるリモート MCP：

1. Streamable HTTP を使用して、MCP クライアントを https://mcp.kgninja.dev/mcp に接続します。
2. initialize を呼び出し、続けて tools/list を呼び出します。
3. 自然言語の意図を指定して、hyperxosist_search_plan から始めます。
4. 収集したテキストに対して hyperxosist_filter_signals と hyperxosist_build_handoff を使用します。
5. 本番環境で実行する場合は、hyperxosist_execute を使用します。未署名の 402 要件を確認し、互換性のある x402 ウォレット／ファシリテーターで承認してから、明示的な確認を付けて一度だけ再試行してください。

無料の MCP 計画ツールと引き継ぎツールは、外部からのデータ収集を行いません。人間がブラウザーを使用する場合は引き続き無料です。自動化された本番検索の実行が有料となる境界です。

署名付き成果物レシート（任意）

下流のエージェントや監査ワークフローで、成果物のダイジェスト確認をサービス署名付きで記録する必要がある場合は、オプトイン方式の AVU buyer adapter を使用してください。引き継ぎは引き続き無料です。ローカルのみで行う確認ではネットワーク呼び出しは発生しません。このアダプターは、利用可能性、事前チェックのダイジェスト、紐付けられた x402 の取引条件、および署名付きの配信を確認します。支払いは、購入者が所有するウォレットで明示的に承認する必要があります。

npm run avu:demo    # offline synthetic example; never pays
npm run avu:status  # GET-only readiness check; never pays

これはソースアダプターであり、新たにデプロイされたリモート MCP ツールでも npm リリースでもありません。ウォレット／決済の実運用上の互換性を確認するには、サービス復旧後に承認を得たエンドツーエンドテストが引き続き必要です。

エージェント間のサービスマッチング（ソースのプレビュー）

agent-matchmaker.mjs または新しいローカル stdio MCP サーバーを使用して、エージェントの実際のタスク、予算、期限に合う既存の API サービス 5 件、または AVU 成果物レシートを見つけます。クライアントは無料の公開 /match エンドポイントを再利用し、提示された支払い条件を稼働中の OpenAPI と照合して、ローカルのみで必要なもの、未対応の機能、同一オペレーターへの既知の購入を除外します。

npm run marketplace:demo                   # offline; no purchase
npm run marketplace:demo -- --live         # free discovery using synthetic demand
node mcp/matchmaker-server.mjs             # connect from an MCP-capable buyer

マッチングガイドと機械可読エントリーをご覧ください。6 つの機能は 1 つのオペレーターに属しています。マッチングによって、外部の購入者需要、仲介手数料、実際の支払い、収益が生まれることはありません。新しいツールはローカルソースのみであり、本番のリモート MCP デプロイには影響しません。