HyperXosist Agent MCP Server

HyperXosist Agent

API-free advanced X (Twitter) search launcher — for humans in the browser, and for any AI agent (GPT, Claude, Grok, Llama, shell tool-callers…) that needs multi-angle, noise-reduced search missions with an x402 paid path and Signal-to-Fix handoff. Optional Grok Build mode (default off).

日本語の要点: X 公式検索用クエリを組み立てる静的ツールです。人間の UI は無料。AI エージェントの本番利用は x402 支払い前提。検索結果の埋め込みや自動投稿はしません。

---

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