HyperXosist-Agent Remote MCP

HyperXosist Agent

以 Agent 为先的工具包和远程 MCP 服务，用于降低噪声的 X（Twitter）搜索规划和从反馈到修复的工程交接。它会为人类和 AI Agent 生成结构化搜索计划和 X 官方搜索 URL。规划和合成演示工作流不会直接抓取 X。可选的 Grok Build 模式默认关闭。

在线演示	https://kg-ninja.github.io/HyperXosist-Agent/
代码仓库	https://github.com/KG-NINJA/HyperXosist-Agent
Agent 入口	https://kg-ninja.github.io/HyperXosist-Agent/llms.txt
CLI	npx hyperxosist plan "…" --json
版本	2.6.0

日文要点：这是一个用于构建 X 官方搜索查询的静态工具。人类界面和 Agent 的规划 / 筛选 / 交接均免费。只有生产环境执行需要通过 x402 付费。不会嵌入搜索结果，也不会自动发布帖子。

Agent 可读摘要

HyperXosist-Agent 可帮助 AI Agent 将研究意图转换为结构化搜索计划、X 官方搜索 URL、用户提供的反馈筛选结果，以及 Signal-to-Fix 工程交接。它是一个规划和交接层：不声称会直接抓取 X、发布帖子或自动部署代码。

免费功能包括 MCP 发现、规划、筛选、结构化交接和本地空运行工作流。生成的搜索 URL 的自动化生产环境使用以及外部数据收集会使用现有的 x402 端点；在提供有效的付款凭证之前，端点会返回 HTTP 402。付款要求发布在 payment-options.json。

Agent 必须遵循适用的用户或运营方付款政策。不得索要私钥、助记词、钱包机密或敏感用户数据。如果钱包需要人工批准，Agent 应请运营方检查并批准交易，然后使用有效的 x402 付款凭证重试同一请求。

---

存在的原因

X 高级搜索功能强大，但很容易用错（垃圾信息、互动诱饵、排除条件过长、只猜测单一角度关键词）。HyperXosist 提供：

1. 人类 — 快速的深色界面，可组合运算符、模板和降噪过滤条件，并打开 X 官方搜索标签页。
2. AI Agent — 持续循环：规划 → 评分 → 付款 → 收集 → 优化 → Keep 筛选 → Grok Build / Signal-to-Fix → 收据。

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

---

功能

适用于所有人

• 无需 X API / OAuth — 使用构建好的查询打开 x.com/search
• 零构建 — 静态 HTML/CSS/JS；可在 GitHub Pages 上运行
• 注重隐私的人类使用路径 — 表单历史仅保存在 localStorage 中
• 降噪 — 低 / 中 / 高级别，并采用优先级上限排除条件（确保查询长度安全）
• 高级运算符 — from / to / @ / OR 组 / 话题标签 / url: / 互动量门槛 / 媒体和回复筛选条件 / 原始片段
• 研究模板和日期预设（24h → 1y）
• 可分享状态 — URL 哈希 #s=...

面向 AI Agent

• 官方 Model Context Protocol（MCP）服务 — 向 Cursor、Claude Code 和其他大模型助手提供查询规划、信号筛选和下游移交能力。请阅读 docs/MCP.md。
• dispatchToolCall / runTool — 真正的多运行时工具调度（无需手写映射）
• toOpenAITools() / toAnthropicTools() — 可直接使用的 GPT / Claude / Grok / Llama 架构
• 命令行 bin/hyperxosist.js — shell Agent 可使用 --json 执行规划 / 调度 / 保留 / 移交
• exportKeepOnlyJson — 面向任何编码 Agent 的仅保留项机器导出
• planFromIntent / 多角度任务
• 在每次付费调用花费 $0.01 之前调用 scoreQuery
• 结果为空或噪声较多时调用 suggestRefinements
• buildSignalToFixPipeline → 完整衔接至 Signal-to-Fix 的闭环（人类：免费 UI 步骤；Agent：x402）
• buildHandoffPackage → Signal-to-Fix 仅保留项 PR 移交包
• 发现入口：signal-to-fix-pipeline.json
• 核心 API 同时输出 JSON + Markdown（适用于任何大模型风格）
• buildAgentPrompt — 与模型无关、只实现一项小改动的提示词
• 透明的噪声目录：exportNoiseCatalog / noise.extraTerms
• 可选的 Grok Build 模式：createGrokBuildSession / buildGrokBuildPrompt（默认关闭）
• agent-tools.json — 兼容 OpenAI 的工具（可移植到 Claude/Grok/Llama 运行时）
• llms.txt + AGENTS.md 多大模型发现文档

---

快速开始（人类）

1. 打开在线演示。
2. 输入关键词（以及可选的 OR 组、用户、日期、互动量）。
3. 可选择启用降噪并选择研究模板。
4. 点击按最新搜索（Latest）或按热度搜索（Top）——也可按 Ctrl+Enter / Ctrl+Shift+Enter。
5. 复制查询、搜索 URL 或可分享的状态链接。
6. 手动衔接 Signal-to-Fix（免费）：将帖子粘贴到 Collected signals → 生成移交包 → 复制 Signal-to-Fix 内容 → 在 Signal-to-Fix 中点击 Analyze → 仅使用 keep。

本地 UI：

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

---

快速开始（AI Agent）

发现顺序

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

任何运行时，只需 3 行

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 / 命令行（无需嵌入）

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

一次调用（库的持续循环）

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

命令行试运行（无需付款，规划无需网络）

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

ChatGPT Site Tools / WebMCP

GitHub Pages 网站会检测 document.modelContext.registerTool(...)，并在兼容的浏览器环境中提供四个 Site Tools。

免费、本地、只读：

• hyperxosist_search_plan
• hyperxosist_filter_signals
• hyperxosist_build_handoff

付费生产环境边界：

• hyperxosist_execute — 通过 https://api.kgninja.dev/hyperxosist-query 执行 x402 v2 生产环境调用

首次调用不提供 paymentSignature，并返回服务器的 PAYMENT-REQUIRED 要求。兼容的钱包或支付中介会授权付款；随后调用方使用不透明的 PAYMENT-SIGNATURE 值和 confirmPayment: true 重试。网站不会创建、索取、存储、记录或回显私钥、助记词或钱包密码。

付费工具被标记为具有重要后果且非幂等。客户端不得自动重试已确认的付款调用。不支持 WebMCP 的浏览器仍可照常使用原有的人类 UI。

MCP：本地与远程

共享的 MCP 核心具有与 WebMCP 相同的经济边界：

• 三个免费工具：规划、基于所提供信号的筛选，以及工程交接。
• 一个付费工具：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

公开生产环境中的远程 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：已在代码库中实现并测试，但需明确部署生产 Cloudflare Worker 后，公开远程 MCP 才会提供该工具

合并此代码库不会部署 Cloudflare Worker。在手动完成该部署之前，线上远程 MCP 仍是提供三个工具的免费服务。WebMCP 付费工具不依赖该部署，而是直接调用已上线的 x402 端点。

现有的 x402 路由是唯一的验证与结算边界。MCP 和 GitHub Pages 不会创建或验证支付凭证。远程 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 设置与安全性、远程 MCP Worker 部署和 ChatGPT App 准备工作。

Agent 交接试运行（离线 — 建议首先执行）

演示从搜索意图 → 保留筛选 → Signal-to-Fix 交接 → 编码 Agent 提示词的完整本地流程，无需网络连接：

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

运行内容（全部离线）：

1. 根据意图构建 Agent 会话/任务
2. 打印任务 ID、主题、主要查询和搜索 URL
3. 使用内置示例反馈（并非来自 X 的实时数据）
4. 运行 filterKeepSignals（保留与丢弃）
5. 构建 buildHandoffPackage
6. 打印 Signal-to-Fix 输入 JSON 预览
7. 打印编码 Agent 实施提示词（Markdown）

重要：这是一次本地试运行。它不会抓取 X、收集真实帖子、打开搜索 URL、发布任何内容，也不会执行 x402 支付。Agent 在生产环境中进行真实搜索，仍需在 scoreQuery 之后使用 x402。

支付政策（Agent）

用途	费用
人工使用浏览器 UI 和官方 X URL	免费
本地规划、评分、筛选和交接	免费
WebMCP 免费工具	免费
已部署的远程 MCP 规划/筛选/交接工具	免费
hyperxosist_execute 生产环境执行	x402 付费；当前元数据注明在 Base 上为 0.01 USDC

执行流程：

1. 调用 hyperxosist_execute，传入 input，且不提供支付签名。
2. 接收 HTTP 402 要求，其中包括标准的 PAYMENT-REQUIRED 响应头。
3. 通过兼容的 x402 钱包或协调器进行授权。
4. 使用 paymentSignature 和 confirmPayment: true 重试。
5. 读取结果和可选的 PAYMENT-RESPONSE；不要自动重复已确认的调用。

payment-options.json 是当前价格、资产、网络、收款方和协调器数据的权威来源。GitHub Pages 和 MCP 不会验证或结算支付。

---

可重新运行的任务 Agent

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：错误／小型需求／开发体验
ui_ux_feedback_harvest	Grok 的前端／UI 使用阻碍
performance_complaint_detector	Grok 的延迟／卡顿

完整目录：missions.json

---

API 接口（v2.6）

方法	作用
dispatchToolCall / runTool	执行任意工具名称（OpenAI／Anthropic／普通格式）
toOpenAITools / toAnthropicTools	可直接使用的工具架构
exportKeepOnlyJson	仅保留 JSON + S2F 输入 + Agent 提示词
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（适用于任意大模型）
buildAgentPrompt(opts)	通用的单项小改动提示词
exportNoiseCatalog / customizeNoiseRules	透明地编辑噪声规则
filterKeepSignals / scoreTechnicalDepth	仅保留信号质量
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://<user>.github.io/HyperXosist-Agent/

无需构建步骤。CI 会在每次推送或向 main 提交 PR 时运行测试。

公开集成检查

• UI 可在 GitHub Pages 上加载
• 可获取 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 — 根据反馈生成仅包含必要内容的 PR 规范
• CHANGELOG · CONTRIBUTING · SECURITY

MCP 发现与目录

机器可读的目录元数据：https://kg-ninja.github.io/HyperXosist-Agent/mcp-catalog.json

面向 AI 操作者和 Agent 构建者

当你需要在 X/Twitter 上发现客户投诉、产品反馈或痛点，而不想一开始就使用嘈杂的临时查询时，请使用 HyperXosist-Agent。

常见用例：

• 在 X/Twitter 上发现产品反馈
• 检测客户投诉和痛点
• 制定降噪的社交聆听查询计划
• 筛选可付诸行动的反馈信号
• 为工程团队生成 AI Agent 交接内容

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 规划和交接工具不会执行外部数据收集。人工使用浏览器仍然免费；自动化的生产搜索执行则需要付费。

可选的签名工件收据

如果下游 Agent 或审计工作流需要服务签名的工件摘要检查记录，请使用可选的 AVU 买方适配器。交接仍然免费；仅限本地的检查不会发出网络请求。该适配器会检查可用性、预检摘要、绑定的 x402 条款和签名交付。买方自有的钱包必须明确授权付款。

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

这是一个源适配器，不是新部署的远程 MCP 工具，也不是 npm 发布版本。服务恢复后，仍需经过授权的端到端测试，才能确认实时钱包/结算兼容性。

Agent 对 Agent 的服务匹配（源代码预览）

使用 agent-matchmaker.mjs 或新的本地 stdio MCP 服务，根据 Agent 的实际任务、预算和截止时间，从五种现有 API 服务或 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

请参阅匹配指南和机器可读入口。六种能力归属同一运营方；匹配不会带来外部买方需求、经纪费用、实际付款或收入。新工具仅存在于本地源代码中，不会改变生产环境中的远程 MCP 部署。