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.

日本語の要点: X 公式検索用クエリを組み立てる静的ツールです。人間の UI は無料。AI エージェントの本番利用は 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.

Related MCP server: Social Search MCP

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"

MCP: Local and Remote

The same three read-only tools are available over two adapters:

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

# Remote Streamable HTTP for Responses API / ChatGPT integrations
HYPERXOSIST_MCP_TOKEN="replace-me" npm run mcp:remote

Remote endpoints are POST /mcp and GET /health. Public deployment requires HTTPS, Bearer authentication, allowed-host configuration, rate limiting, and monitoring. Public production Remote MCP:

• Endpoint: https://mcp.kgninja.dev/mcp

• Health: https://mcp.kgninja.dev/health

• Transport: Streamable HTTP

• Authentication: Bearer token

• Status: deployed; verify /health before use

• Free tools: hyperxosist_search_plan, hyperxosist_filter_signals, hyperxosist_build_handoff

MCP initialization, tools/list, planning, filtering, and handoff do not require x402. x402 applies only to production search URL usage, automated external collection, and the paid execution endpoint at https://api.kgninja.dev/hyperxosist-query.

# No API call: validate the OpenAI Remote MCP example
npm run openai:remote-check

# 20 positive/negative tool-selection cases
npm run test:tool-selection

GitHub Pages remains the static human UI and cannot host MCP. The repository includes a separate Cloudflare Worker Remote MCP adapter using Web Standard Streamable HTTP. It is intended for a custom-domain deployment with a required Bearer secret, closed-by-default origin/host allowlists, a 1 MiB request limit, and a zone-level WAF rate-limit rule. The Node stdio and node:http adapters do not run in Workers unchanged.

Planning, collected-post filtering, and handoff are free. Human manual use of generated X URLs is free. Automated production execution uses https://api.kgninja.dev/hyperxosist-query; staging MCP deployments preserve the existing staging payment Worker through HYPERXOSIST_PAYMENT_ENVIRONMENT=staging. This change does not modify x402 payment behavior. Remote MCP operations use optional SHA-256 token registry identities, structured Worker usage/error logs, request IDs, and optional KV daily limits. Raw tokens and request content are not logged. Payment analytics remain authoritative in the existing x402 Worker D1/Telegram pipeline; MCP requests are free and never treated as paid settlement events.

See MCP setup and security and ChatGPT App preparation.

Agent handoff dry-run (offline — recommended first step)

Demonstrates the full local path from search intent → keep filter → Signal-to-Fix handoff → coding-agent prompt without network access:

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

What it does (all offline):

1. Builds an agent session / mission from intent

2. Prints mission ID, subject, primary query, and search URL

3. Uses built-in sample feedback (not live X data)

4. Runs filterKeepSignals (keep vs discard)

5. Builds buildHandoffPackage

6. Prints Signal-to-Fix input JSON preview

7. Prints the coding-agent implementation prompt (Markdown)

Important: this is a local dry-run. It does not scrape X, collect real posts, open the search URL, post anything, or perform x402 payment. Real agent production search still requires x402 after scoreQuery.

Payment policy (agents)

On unpaid POST → 402. Complete payment using paymentOptionsEndpoint, then retry until 200.
Do not treat GitHub Pages as the payment verifier.

Missions agents re-run

Full catalog: missions.json

API surface (v2.5)

CLI surface

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

Repository layout

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
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

Deploy (GitHub Pages)

1. Push to main.

2. Settings → Pages → Deploy from a branch → main / / (root).

3. Site: https://<user>.github.io/HyperXosist-Agent/

No build step. CI runs tests on every push/PR to main.

Public integration checks

• UI loads on GitHub Pages

• agent-use.json / x402-payment.json / llms.txt fetchable

• Link to Signal-to-Fix agent-use.json works

• Unpaid POST to hyperxosist-query endpoint returns 402

Disclaimer

• Not affiliated with X Corp.

• This tool only builds search queries / opens official search. It does not embed timelines, auto-post, or replace the X API.

• You are responsible for complying with X’s terms and applicable law when searching or collecting content.

License

MIT © 2026 KG-NINJA

Related

• Signal-to-Fix — keep-only PR specs from feedback

• CHANGELOG · CONTRIBUTING · SECURITY

MCP discovery and catalog

Machine-readable catalog metadata: https://kg-ninja.github.io/HyperXosist-Agent/mcp-catalog.json

For AI operators and agent builders

Use HyperXosist-Agent when you need to discover customer complaints, product feedback, or pain points on X/Twitter without starting with noisy ad-hoc queries.

Common use cases:

• X/Twitter product-feedback discovery

• Customer complaint and pain-point detection

• Noise-reduced social listening query planning

• Signal filtering for actionable feedback

• AI-agent handoff generation for engineering teams

30-second Remote MCP quick start:

1. Connect an MCP client to https://mcp.kgninja.dev/mcp using Streamable HTTP.

2. Call initialize, then tools/list.

3. Start with hyperxosist_search_plan using a natural-language intent.

4. Use hyperxosist_filter_signals and hyperxosist_build_handoff on collected text.

5. For automated production X search execution, POST the returned request to https://api.kgninja.dev/hyperxosist-query and complete x402 at 0.01 USDC on Base.

Free MCP planning and handoff tools do not perform external collection. Human browser use remains free; automated production search execution is the paid boundary.