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.

日本語の要点: 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: Local and Remote

The shared MCP core contains the same economic boundary as WebMCP:

• Three free tools: planning, supplied-signal filtering, and engineering handoff.
• One paid tool: hyperxosist_execute, which forwards an explicitly confirmed x402 request to the existing payment 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

Public production Remote MCP:

• Endpoint: https://mcp.kgninja.dev/mcp
• Health: https://mcp.kgninja.dev/health
• Transport: Streamable HTTP
• Public free-mode authentication: none
• Private/self-hosted authentication: optional Bearer token
• Currently deployed tools: hyperxosist_search_plan, hyperxosist_filter_signals, hyperxosist_build_handoff
• hyperxosist_execute: implemented and tested in the repository, but requires an explicit production Cloudflare Worker deployment before the public Remote MCP advertises it

Merging this repository does not deploy the Cloudflare Worker. Until that manual deployment occurs, the live Remote MCP remains the three-tool free service. The WebMCP paid tool is independent of that deployment and calls the already-live x402 endpoint directly.

The existing x402 route is the only verifier and settlement boundary. MCP and GitHub Pages never create or verify payment proofs. Remote MCP telemetry must not log request content or PAYMENT-SIGNATURE; settlement analytics remain authoritative in the x402 Worker.

npm run openai:remote-check

npm run test:tool-selection npm run test:paid-execution npm run test:webmcp

See MCP setup and security, Remote MCP Worker deployment, 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 doe