@sureshotlabs/hunch-agent-tools 0.1.1

package/README.md

@@ -0,0 +1,260 @@
+# Hunch Agent Tools
+
+Public read-only MCP server, CLI, and Codex plugin for Hunch prediction-market
+research.
+
+This repository is intentionally separate from `hunch-monorepo`. The shipped
+package does not log in, read private account state, create intents, execute
+actions, sign wallet payloads, trade, bridge, redeem, fund, convert, transfer,
+or withdraw. It only calls public Hunch read APIs.
+
+## Packages
+
+- `packages/hunch-agent-client`: internal TypeScript client and response
+  shaping helpers.
+- `apps/mcp-hunch`: MCP stdio server and `hunch-agent` CLI binary.
+- `skills/hunch-trading`: Codex skill wrapper and references.
+- `.codex-plugin/plugin.json` and `.mcp.json`: Codex plugin distribution.
+- `plugin-dist/`: generated, ignored bundled runtime files for local plugin
+  testing.
+
+## Public Scope
+
+Available read surfaces:
+
+- Feed search and browsing.
+- Market and event details.
+- Discovery map data and ranked discovery top lists.
+- Cross-venue arbitrage clusters.
+- Exact market alternatives across matched venues.
+- Similar markets and events.
+- Public holders and recent public trade tape.
+- Market/event signals.
+- Market and event price history.
+- Public tracking overview, wallet intelligence, wallet activity, wallet
+  positions, wallet time series, and wallet signals.
+
+## Commands
+
+```bash
+pnpm install
+pnpm check
+pnpm build
+pnpm -F @sureshotlabs/hunch-agent-tools run dev:mcp
+pnpm -F @sureshotlabs/hunch-agent-tools run dev:cli -- discovery-browse --venues polymarket,kalshi --limit 10 --json
+pnpm -F @sureshotlabs/hunch-agent-tools run dev:cli -- discovery-search "election" --standard --json
+skills/hunch-trading/scripts/hunch discovery-search "election" --json
+```
+
+Set `HUNCH_API_BASE_URL` to point at a local or production Hunch API. It
+defaults to `https://api.hunch.trade`. Set `HUNCH_APP_BASE_URL` to control app
+links in compact/standard responses. It defaults to
+`https://app.hunch.trade`.
+
+CLI and MCP tools support `responseMode` values:
+
+- `compact` (default): small agent-friendly payloads.
+- `standard`: includes descriptions, metadata, and larger previews.
+- `full`: raw backend JSON for debugging or one-off inspection.
+
+The CLI aliases these as `--compact`, `--standard`, `--full`, or
+`--response-mode <mode>`.
+
+## MCP Tools
+
+- `hunch_search_discovery`
+- `hunch_browse_discovery`
+- `hunch_get_discovery_top_lists`
+- `hunch_get_discovery_map`
+- `hunch_get_market_detail`
+- `hunch_get_event_detail`
+- `hunch_get_arbitrage_clusters`
+- `hunch_get_market_alternatives`
+- `hunch_get_similar_markets`
+- `hunch_get_similar_events`
+- `hunch_get_market_holders`
+- `hunch_get_market_price_history`
+- `hunch_get_event_price_history`
+- `hunch_get_tracking_overview`
+- `hunch_get_wallet_intel`
+- `hunch_get_wallet_activity`
+- `hunch_get_wallet_positions`
+- `hunch_get_wallet_series`
+- `hunch_get_wallet_signals`
+- `hunch_get_signals`
+- `hunch_get_trades`
+
+The tools expose backend filters instead of adding local post-processing.
+Compact and standard responses include Hunch app links such as event, market,
+tracking wallet, tracking overview, and arbitrage URLs so agents do not need to
+present raw IDs as the primary user-facing output.
+
+For event-page context, combine event detail, signals, similar events, price
+history, trades, and market holders. Holders are market-scoped, so use the
+selected market ID from event detail. Use market alternatives when the user
+wants exact cross-venue versions of the same selected outcome; use similar
+markets/events when they want broader semantic neighbors.
+
+Price history uses `range` for the time window and `bucketMinutes` for candle
+size; `interval` remains a legacy alias for `range`.
+
+## Packaging
+
+Run local release packaging after a successful build:
+
+```bash
+pnpm release:local
+```
+
+Artifacts are written under ignored `artifacts/`:
+
+- `artifacts/npm/sureshotlabs-hunch-agent-tools-*.tgz` for the self-contained
+  npm MCP/CLI package.
+- `artifacts/plugin/hunch-agent-tools-plugin.tar.gz` for plugin installs.
+- `artifacts/skill/hunch-trading-skill.tar.gz` for standalone skill installs.
+
+Use `--dry-run` with `pack:npm`, `pack:plugin`, or `pack:skill` to verify the
+file list without creating tarballs.
+
+## Install Surfaces
+
+End users have four supported ways to use the package:
+
+- **MCP server via npm:** best default for Codex, Claude Code, and other MCP
+  clients. This exposes Hunch research tools to the agent.
+- **CLI via npm:** best for shell usage, smoke tests, and scripts.
+- **Codex plugin:** best for Codex users who want the MCP server plus bundled
+  Skill installed together through a plugin marketplace entry.
+- **Standalone Skill:** best when an agent only needs reusable instructions and
+  the lightweight `scripts/hunch` CLI wrapper.
+
+All install surfaces are public and read-only. They do not log in, read private
+accounts, create intents, execute, trade, bridge, redeem, transfer, withdraw,
+convert, fund, or sign.
+
+### MCP npm package
+
+The npm artifact is an `npx`-runnable MCP server package. It bundles the MCP
+server and Hunch client into one executable, so it does not require installing
+workspace packages separately.
+
+The same npm tarball also includes `skills/hunch-trading/` as a portable
+read-only Skill folder. The package root remains the npm/MCP package root;
+the Skill root is the subfolder containing `SKILL.md`. This keeps
+`npx -y @sureshotlabs/hunch-agent-tools@latest` launching the MCP server while
+also making the bundled Skill copyable into a Codex/agent skills directory when
+that install surface is preferred. The Skill wrapper uses its bundled
+`skills/hunch-trading/bin/hunch-agent.js` CLI, so it does not require workspace
+packages after extraction.
+
+After publishing `@sureshotlabs/hunch-agent-tools`, Codex can install it
+directly:
+
+```bash
+codex mcp remove hunch
+codex mcp add hunch -- npx -y @sureshotlabs/hunch-agent-tools@latest
+```
+
+Claude Code uses the same package:
+
+```bash
+claude mcp remove hunch
+claude mcp add --transport stdio hunch -- npx -y @sureshotlabs/hunch-agent-tools@latest
+```
+
+### CLI npm usage
+
+Use the CLI without installing globally:
+
+```bash
+npm exec --yes --package @sureshotlabs/hunch-agent-tools@latest -- hunch-agent discovery-search "election" --json
+npm exec --yes --package @sureshotlabs/hunch-agent-tools@latest -- hunch-agent market-detail polymarket:123 --standard --json
+```
+
+Or install it globally:
+
+```bash
+npm install -g @sureshotlabs/hunch-agent-tools
+hunch-agent discovery-browse --venues polymarket,kalshi --limit 10 --json
+```
+
+The MCP server binary is `hunch-agent-tools` or `hunch-mcp`. The CLI binary is
+`hunch-agent`.
+
+For local tarball validation before publishing:
+
+```bash
+pnpm release:local
+npx -y ./artifacts/npm/sureshotlabs-hunch-agent-tools-0.1.1.tgz
+```
+
+Publish with npm provenance from an authenticated environment:
+
+```bash
+npm publish ./artifacts/npm/sureshotlabs-hunch-agent-tools-0.1.1.tgz --provenance
+```
+
+### Codex Plugin
+
+The repository root is the plugin source. The packaged artifact is a Codex
+local marketplace root matching Codex's installed marketplace layout:
+
+- `.agents/plugins/marketplace.json`
+- `plugins/hunch-agent-tools/.codex-plugin/plugin.json`
+- `plugins/hunch-agent-tools/.mcp.json`
+- `plugins/hunch-agent-tools/skills/hunch-trading`
+
+Run `pnpm build` before local testing. The build generates ignored runtime
+bundles under `plugin-dist/` and `skills/hunch-trading/bin/`.
+
+The bundled MCP config does not rely on Codex launching from the plugin root.
+It locates `plugin-dist/hunch-mcp.js` from Codex's installed plugin cache or
+from the extracted local marketplace under `~/.codex/plugins`.
+
+For a local plugin install test, package and extract the self-contained local
+marketplace:
+
+```bash
+pnpm release:local
+mkdir -p ~/.codex/plugins
+tar -xzf artifacts/plugin/hunch-agent-tools-plugin.tar.gz -C ~/.codex/plugins
+```
+
+Then register the extracted local marketplace in `~/.codex/config.toml`:
+
+```toml
+[marketplaces.hunch-agent-tools]
+source_type = "local"
+source = "/Users/xorbot/.codex/plugins/hunch-agent-tools"
+
+[plugins."hunch-agent-tools@hunch-agent-tools"]
+enabled = true
+```
+
+Restart Codex after changing plugin configuration. If Codex has already cached
+an older local copy, remove `~/.codex/plugins/cache/hunch-agent-tools` before
+restarting so Codex reinstalls from the local marketplace source.
+
+### Standalone Skill
+
+The npm tarball and `artifacts/skill/hunch-trading-skill.tar.gz` both contain a
+portable Skill folder:
+
+```text
+hunch-trading/
+  SKILL.md
+  scripts/hunch
+  bin/hunch-agent.js
+  references/tools.md
+  agents/openai.yaml
+```
+
+For local Codex skill usage, copy or extract that folder into the user's skills
+directory. The wrapper can be called directly:
+
+```bash
+hunch-trading/scripts/hunch discovery-search "up or down" --json
+```
+
+The Skill is intentionally a subfolder, not the npm package root, so npm keeps
+normal package semantics while agents can still load `hunch-trading/SKILL.md`.