hive-intelligence 1.1.0 → 1.1.3

package/README.md

@@ -1,269 +1,346 @@
 # Hive Intelligence
 
-MCP server and CLI for cryptocurrency, Web3, and financial market analytics. Access **389 tools** across **14 categories** from your AI assistant or terminal.
+Crypto intelligence for AI agents, shipped as an MCP server and CLI.
 
-## Install
+`hive-intelligence` gives Claude Code, Cursor, VS Code, ChatGPT Desktop,
+Gemini CLI, Codex, and custom agents one way to discover and call live crypto
+data. Agents get a compact MCP surface, schema lookup, bounded execution,
+provider provenance, and runtime status instead of a wall of raw endpoints.
 
 ```bash
-npm install -g hive-intelligence
+npx -y -p hive-intelligence@latest hive init --all --browser
 ```
 
-This gives you two commands:
+Use the hosted MCP when you want Hive to run the server, auth, rate limits, and
+provider infrastructure. Use local `stdio` when you want a desktop/self-hosted
+MCP process or provider-key experiments.
 
-| Command | Purpose |
-|---------|---------|
-| `hive-intelligence` | MCP stdio server for AI clients (Claude Desktop, Cursor, VS Code, etc.) |
-| `hive` | CLI tool for terminal usage |
+## What You Get
 
-> **Note:** `hive-intelligence` is an MCP stdio server — running it directly opens a stdio transport that waits for JSON-RPC messages. It is not interactive and does not accept subcommands. For terminal usage, use the `hive` CLI.
+- 351 provider tools across market data, wallets, DeFi, DEX, NFTs, token and
+  contract data, security risk, network infrastructure, search, Solana, and
+  prediction markets.
+- A compact root MCP endpoint with 13 discovery and execution tools, so agents
+  can route before they call.
+- Task toolsets for market research, token diligence, wallet investigation,
+  security checks, DEX pool analysis, DeFi research, NFT research, Solana
+  analysis, network infrastructure, and prediction markets.
+- A CLI for auth, client setup, tool discovery, schema inspection, direct tool
+  calls, diagnostics, aliases, and polling.
+- Runtime resources for providers, categories, full tool catalog, task
+  toolsets, canaries, skills, and status metadata.
+- Shipped agent skills that teach assistants how to use Hive through discovery,
+  schema lookup, bounded execution, and provenance-aware reporting.
 
-### Run without installing
+## Install Fast
 
-The CLI is a separate bin in the same package, so with `npx` you must select it explicitly via `-p`:
+Requirements:
 
-```bash
-# Run the CLI via npx (note: -p selects the package, `hive` is the bin)
-HIVE_API_KEY=hive_live_... npx -y -p hive-intelligence hive --help
-HIVE_API_KEY=hive_live_... npx -y -p hive-intelligence hive market price --ids bitcoin --vs usd
+- Node.js 20+
+- npm
+- A Hive API key for the hosted MCP or hosted REST API
 
-# Plain `npx -y hive-intelligence` launches the MCP stdio server, not the CLI.
-```
+Create a key in the Hive dashboard:
 
-## API Key
+```text
+https://www.hiveintelligence.xyz/login?next=/dashboard/keys
+```
 
-An API key is required. Get one at [hiveintelligence.xyz](https://hiveintelligence.xyz) and set it as an environment variable:
+Then configure your client:
 
 ```bash
-export HIVE_API_KEY="hive_live_..."
+npx -y -p hive-intelligence@latest hive auth login
+npx -y -p hive-intelligence@latest hive config claude-code
 ```
 
-Or use the CLI login:
+For one-command setup across detected local clients:
 
 ```bash
-hive auth login
+npx -y -p hive-intelligence@latest hive init --all --browser
 ```
 
-## MCP Server Setup
+## Connect Hosted MCP
 
-### Claude Desktop
+Hosted MCP URL:
 
-Add to your config file:
+```text
+https://mcp.hiveintelligence.xyz/mcp
+```
+
+Claude Code:
+
+```bash
+claude mcp add --transport http --header "Authorization: Bearer YOUR_HIVE_API_KEY" hive https://mcp.hiveintelligence.xyz/mcp
+```
 
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+Generic MCP JSON for clients that support remote HTTP and custom headers:
 
 ```json
 {
   "mcpServers": {
     "hive": {
-      "command": "npx",
-      "args": ["-y", "hive-intelligence"],
-      "env": {
-        "HIVE_API_KEY": "hive_live_..."
+      "url": "https://mcp.hiveintelligence.xyz/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_HIVE_API_KEY"
       }
     }
   }
 }
 ```
 
-### Cursor
+Header-based API key auth works for MCP clients that support custom headers,
+including Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, Codex, and
+ChatGPT Desktop. Claude.ai custom connectors and directory submissions require
+OAuth-compatible auth; Hive does not implement OAuth/CIMD yet.
+
+## Run Local stdio MCP
 
-Add to `.cursor/mcp.json`:
+Use local `stdio` when you want a self-hosted MCP process, local desktop config,
+or your own upstream provider keys.
 
 ```json
 {
   "mcpServers": {
-    "hive": {
+    "hive-local": {
       "command": "npx",
-      "args": ["-y", "hive-intelligence"],
+      "args": ["-y", "-p", "hive-intelligence@latest", "hive"],
       "env": {
-        "HIVE_API_KEY": "hive_live_..."
+        "COINGECKO_PRO_API_KEY": "optional",
+        "ALCHEMY_API_KEY": "optional",
+        "HELIUS_API_KEY": "optional",
+        "MORALIS_API_KEY": "optional"
       }
     }
   }
 }
 ```
 
-### VS Code
+Running `hive` with no subcommand starts the `stdio` MCP server. `hive-mcp`
+remains available as a backward-compatible binary alias.
 
-Add to `.vscode/mcp.json`:
+## Use The CLI
 
-```json
-{
-  "servers": {
-    "hive": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "hive-intelligence"],
-      "env": {
-        "HIVE_API_KEY": "hive_live_..."
-      }
-    }
-  }
-}
+Search the catalog:
+
+```bash
+npx -y -p hive-intelligence@latest hive tools search "token risk"
 ```
 
-### Claude Code
+Inspect a schema before execution:
 
 ```bash
-claude mcp add hive-intelligence -e HIVE_API_KEY=hive_live_... -- npx -y hive-intelligence
+npx -y -p hive-intelligence@latest hive tools info get_price
 ```
 
-### Remote MCP Server
+Call a tool from the terminal:
+
+```bash
+npx -y -p hive-intelligence@latest hive market price --ids bitcoin --vs usd --json
+```
 
-For clients that support HTTP transport:
+Check setup and provider status:
 
+```bash
+npx -y -p hive-intelligence@latest hive doctor
+npx -y -p hive-intelligence@latest hive status
 ```
-URL: https://mcp.hiveintelligence.xyz/mcp
-Headers: { "Authorization": "Bearer hive_live_..." }
+
+Useful setup commands:
+
+```bash
+npx -y -p hive-intelligence@latest hive config claude-desktop
+npx -y -p hive-intelligence@latest hive config cursor
+npx -y -p hive-intelligence@latest hive config vscode
 ```
 
-More details: https://hiveintelligence.xyz/crypto-mcp
+Use `--json` for scripts and agents. Use `--pretty` for human-readable output.
 
-## CLI Usage
+## How Agents Should Use Hive
 
-The `hive` CLI is a lightweight client that talks to the Hive API. Set `HIVE_API_KEY` (or run `hive auth login`) before making calls.
+Hive is designed for retrieval-led agent work:
 
-```bash
-# Get Bitcoin price
-hive market price --ids bitcoin --vs usd
+1. Discover the task surface with `search_tools`, `hive://toolsets`, or
+   `hive tools search`.
+2. Inspect exact parameters with `get_api_endpoint_schema` or
+   `hive tools info`.
+3. Execute through `invoke_api_endpoint`, category tools, REST, or the CLI.
+4. Preserve provider, freshness, cache, `_hive`, `meta`, and runtime status in
+   the final answer.
+5. Keep reads bounded with `limit`, `page`, `per_page`, or `offset`.
 
-# Top coins by market cap
-hive market top --vs usd --limit 10
+This flow lets an agent answer questions like:
 
-# DeFi protocol TVL
-hive defi tvl --protocol aave
+- "Is this token safe to buy?"
+- "What changed in this wallet over the last week?"
+- "Compare Aave and Curve by TVL, fees, chains, and risk."
+- "Find active prediction markets for the next Fed decision."
+- "Show the best pools for this token and explain liquidity risk."
 
-# Stock quote
-hive stocks quote --symbol AAPL
+## MCP Contract
 
-# Search across all tools
-hive tools search "price"
+Root endpoint:
 
-# Run any tool by name
-hive tools call get_price --args '{"ids": "ethereum", "vs_currencies": "usd"}'
+```text
+https://mcp.hiveintelligence.xyz/mcp
 ```
 
-### CLI Commands
-
-| Domain | Description |
-|--------|-------------|
-| `market` | Crypto prices, charts, rankings, stablecoins, gas |
-| `defi` | DeFi protocol TVL, fees, yields, bridges |
-| `portfolio` | Wallet balances, DeFi positions, NFTs |
-| `security` | Token security scans, approvals, simulations |
-| `stocks` | Stock quotes, candles, financials, analyst ratings |
-| `macro` | Economic calendar, market status, country data |
-| `prediction` | Prediction markets, events, traders, outcomes |
-| `exchange` | CEX tickers, orderbooks, trades, funding rates |
-| `dex` | DEX pools, trending pairs, trades, volume |
-| `wallet` | On-chain balances, transfers, transactions |
-| `nft` | NFT collections, markets, trends |
-| `network` | Chains, gas prices, blocks |
-| `search` | Search tokens and pools |
-| `altdata` | Insider trades, earnings, IPOs |
-
-### CLI Options
+Local development endpoint:
 
-```
---json          Force JSON output
---pretty        Force human-readable output
---fields <list> Comma-separated fields to include
---jq <expr>     Filter JSON output (jq-like syntax)
---csv           Output as CSV
---timeout <ms>  Request timeout (default: 30000)
---no-retry      Disable automatic retry
--q, --quiet     Suppress non-data output
--v, --verbose   Show debug info
+```text
+http://localhost:8080/mcp
 ```
 
-### Authentication and Profiles
+Root MCP tools:
 
-```bash
-# Log in with API key
-hive auth login
+- `search_tools`
+- 10 category listing tools, one per crypto domain
+- `get_api_endpoint_schema`
+- `invoke_api_endpoint`
 
-# Check connectivity
-hive doctor
+Discovery resources:
 
-# Show current profile
-hive auth whoami
+- `hive://providers`
+- `hive://categories`
+- `hive://tools`
+- `hive://toolsets`
+- `hive://task-canaries`
+- `hive://skills`
+- `hive://status`
 
-# Manage multiple profiles
-hive auth profiles
-hive auth switch production
-```
+Reusable prompts:
 
-### Shell Completion
+- `analyze_token`
+- `compare_protocols`
+- `portfolio_audit`
 
-```bash
-# Bash
-eval "$(hive completion bash)"
+Category-scoped MCP endpoints remain available for clients that need direct
+tool lists:
 
-# Zsh
-eval "$(hive completion zsh)"
+- `/hive_market_data/mcp`
+- `/hive_onchain_dex/mcp`
+- `/hive_portfolio_wallet/mcp`
+- `/hive_token_contract/mcp`
+- `/hive_defi_protocol/mcp`
+- `/hive_nft_analytics/mcp`
+- `/hive_security_risk/mcp`
+- `/hive_network_infrastructure/mcp`
+- `/hive_search_discovery/mcp`
+- `/hive_prediction_markets/mcp`
 
-# Fish
-hive completion fish > ~/.config/fish/completions/hive.fish
+## Providers
 
-# Auto-install
-hive completion bash --install
-```
+| Provider | Coverage | Env var |
+| --- | --- | --- |
+| Alchemy | EVM wallet, token, NFT, transfer, simulation, gas, and RPC data | `ALCHEMY_API_KEY` |
+| CoinGecko | Prices, OHLC, trending, news | `COINGECKO_PRO_API_KEY` |
+| DeFiLlama | TVL, yields, fees, bridges | Free |
+| CCXT | CEX data, funding rates, perpetuals | Free |
+| GoPlus | Token, wallet, and dApp security | `GOPLUS_APP_KEY` + `GOPLUS_APP_SECRET` |
+| Codex | DEX analytics and Polymarket prediction markets | `CODEX_API_KEY` |
+| Helius | Solana RPC, DAS, priority fees, wallet history | `HELIUS_API_KEY` |
+| Moralis | Wallet, token, NFT, PnL, DeFi positions | `MORALIS_API_KEY` |
+| Tenderly | EVM simulation, tracing, gas estimation | `TENDERLY_API_KEY` |
 
-### Aliases
+Providers without configured keys remain discoverable and return classified
+runtime status such as `missing_key`, `plan_required`, `rate_limited`,
+`degraded`, or `failing` when execution is unavailable.
 
-```bash
-hive alias set btc 'market price --ids bitcoin --vs usd'
-hive btc
-```
+## REST API
 
-## Analytics Categories (389 Tools)
+Use REST when your app does not speak MCP.
 
-| # | Category | Tools | Description |
-|---|----------|-------|-------------|
-| 1 | Market Data & Price | 70 | Real-time/historical prices, OHLCV, market caps, stablecoins, derivatives, funding rates |
-| 2 | On-Chain DEX & Pool | 58 | DEX pools, liquidity, trending pairs, volume, bridges, GoldRush XY=K analytics |
-| 3 | Portfolio & Wallet | 50 | Wallet balances, PnL, DeFi positions, swap history, Moralis & GoldRush intelligence |
-| 4 | Token & Contract | 44 | Token metadata, holders, Moralis analytics, ENS resolution, treasury tracking |
-| 5 | DeFi Protocol | 21 | TVL data, protocol fees, yield farming, chain metrics, treasuries |
-| 6 | NFT Analytics | 41 | Collection data, market charts, liquidity pools, GoldRush NFT metadata & traits |
-| 7 | Security & Risk | 37 | Token security, honeypot detection, Tenderly simulation, gas estimation |
-| 8 | Network & Infrastructure | 20 | Network health, block data, chain statuses, event logs |
-| 9 | Search & Discovery | 10 | Coin search, trending analysis, categories, token discovery |
-| 10 | Stocks & Equities | 8 | Real-time quotes, candles, company profiles, recommendations |
-| 11 | Forex & Commodities | 4 | Forex rates, commodity prices (gold, silver, platinum) |
-| 12 | Economic Indicators | 3 | Economic calendar, market status, country data |
-| 13 | Alternative Data | 5 | Insider trading, sentiment scores, earnings/IPO calendar |
-| 14 | Prediction Markets | 19 | Polymarket/Kalshi events, trader stats, outcome prices, trade history |
+List tools:
 
-## Data Providers
+```bash
+curl -X GET "https://mcp.hiveintelligence.xyz/api/v1/tools?search=price&limit=20" \
+  -H "Authorization: Bearer $HIVE_API_KEY"
+```
 
-CoinGecko, DefiLlama, GeckoTerminal, Codex (Defined.fi), Moralis, GoPlus, GoldRush (Covalent), Tenderly, CCXT, Finnhub
+Execute a tool:
 
-## Environment Variables
+```bash
+curl -X POST https://mcp.hiveintelligence.xyz/api/v1/execute \
+  -H "Authorization: Bearer $HIVE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "get_price",
+    "args": {
+      "ids": "bitcoin",
+      "vs_currencies": "usd"
+    }
+  }'
+```
 
-| Variable | Description |
-|----------|-------------|
-| `HIVE_API_KEY` | **Required.** API key (or use `hive auth login`) |
-| `HIVE_API_URL` | Custom server URL (default: `https://mcp.hiveintelligence.xyz`) |
-| `API_EXECUTE_ENDPOINT` | Override MCP server backend URL |
+## Develop Locally
 
-## Development
+Install:
 
 ```bash
-# Install dependencies
 npm install
+```
 
-# Build
-npm run build
+Run:
 
-# Test with MCP inspector
-npm run inspector
+```bash
+npm run dev          # stdio MCP
+npm run dev:http     # HTTP MCP and REST API on :8080
+```
 
-# Start MCP server locally
-npm start
+Verify:
+
+```bash
+npm run check
 ```
 
-## License
+Focused checks:
+
+```bash
+npm run build
+npm run test:unit
+npm run test:mcp-compliance
+npm run verify:toolsets
+npm run verify:agent-skills
+npm run env:render:check
+```
 
-MIT
+Use focused checks while iterating. Run `npm run check` before releases and
+after changes to shared MCP behavior, auth, middleware, provider routing, task
+toolsets, generated metadata, or CLI setup paths.
+
+## Package Contents
+
+The `hive-intelligence` npm package includes:
+
+- `hive`, `hive-intelligence`, `hive-mcp`, and `hive-mcp-server` binaries.
+- Built MCP server and CLI files in `build/`.
+- Bundled Hive agent skills in `agent-skills/`.
+- Local `stdio` MCP runtime for desktop clients and self-hosting.
+
+## Architecture Map
+
+- `src/mcpServer.ts` builds root/category MCP servers, tools, resources,
+  prompts, and runtime instructions.
+- `src/server.ts` runs Express, Streamable HTTP MCP, REST routes, auth, rate
+  limits, CORS, security headers, discovery descriptors, and shutdown.
+- `src/toolRegistry.ts` defines the 10 category surfaces.
+- `src/wrapper/allEndpoints.ts` maps provider tools into the public Hive tool
+  catalog.
+- `src/taskToolsets.ts` defines the workflow surface agents should prefer over
+  raw endpoint browsing.
+- `src/agentSkills.ts` and `agent-skills/` ship agent-installable Hive skills.
+- `src/cli.ts` and `src/cli/` expose auth, setup, discovery, execution,
+  diagnostics, config generation, aliases, and watch mode.
+- `packages/mcp-client/` contains the typed client adapter.
+- `tests/` covers unit, integration, E2E, MCP compliance, live, security, and
+  Docker readiness paths.
+
+## Links
+
+- Website: https://www.hiveintelligence.xyz
+- Hosted MCP: https://mcp.hiveintelligence.xyz/mcp
+- Docs overview: https://github.com/sharpe-labs/hive-mcp2/blob/master/docs/DOCUMENTATION.md
+- Tool reference: https://github.com/sharpe-labs/hive-mcp2/blob/master/docs/TOOLS_REFERENCE.md
+- Agent instructions: https://github.com/sharpe-labs/hive-mcp2/blob/master/AGENTS.md
+- Contributing: https://github.com/sharpe-labs/hive-mcp2/blob/master/CONTRIBUTING.md
+- Security: https://github.com/sharpe-labs/hive-mcp2/blob/master/SECURITY.md
+- Changelog: https://github.com/sharpe-labs/hive-mcp2/blob/master/CHANGELOG.md

package/agent-skills/.claude-plugin/plugin.json

@@ -0,0 +1,105 @@
+{
+  "name": "hive-agent-skills",
+  "version": "1.0.0",
+  "description": "Hive Intelligence skills for Claude Code, Cursor, Codex, and other agents. Covers Hive MCP setup, tool discovery, crypto workflows, CLI flows, and PKCE-based authentication. Install via `npx -y -p hive-intelligence@latest hive init --all --browser` or copy the packs into the target agent skills directory.",
+  "author": {
+    "name": "Hive Intelligence",
+    "url": "https://www.hiveintelligence.xyz",
+    "email": "support@hiveintelligence.xyz"
+  },
+  "homepage": "https://www.hiveintelligence.xyz",
+  "repository": "https://github.com/sharpe-labs/hive-mcp2",
+  "license": "MIT",
+  "skills": [
+    {
+      "name": "hive-cli",
+      "path": "../packs/hive-cli/SKILL.md",
+      "description": "Use the `hive` CLI inline from a chat — query prices, scan wallets, check token security, automate briefings."
+    },
+    {
+      "name": "hive-mcp",
+      "path": "../packs/hive-mcp/SKILL.md",
+      "description": "Add Hive's MCP server to Claude Code, Cursor, VS Code, Windsurf, Claude Desktop, ChatGPT, or Gemini CLI. Per-client instructions."
+    },
+    {
+      "name": "hive-build-onboarding",
+      "path": "../packs/hive-build-onboarding/SKILL.md",
+      "description": "Walk the user through PKCE-based browser auth. Use when the user has no API key or cannot find theirs."
+    },
+    {
+      "name": "hive-build",
+      "path": "../packs/hive-build/SKILL.md",
+      "description": "Integrate Hive into app code via REST or MCP SDK. Python, TypeScript, Go, Java, Rust patterns with retry / async / typed responses."
+    },
+    {
+      "name": "hive-query",
+      "path": "../packs/hive-query/SKILL.md",
+      "description": "Route crypto questions through canonical task toolsets, schema lookup, and exact tool invocation."
+    },
+    {
+      "name": "hive-tool-discovery",
+      "path": "../packs/hive-tool-discovery/SKILL.md",
+      "description": "Find the right Hive tool, task toolset, schema, or endpoint before execution."
+    },
+    {
+      "name": "hive-market-research",
+      "path": "../packs/hive-market-research/SKILL.md",
+      "description": "Research live prices, liquidity, exchanges, OHLC, order books, funding rates, and derivatives."
+    },
+    {
+      "name": "hive-token-diligence",
+      "path": "../packs/hive-token-diligence/SKILL.md",
+      "description": "Investigate token metadata, market context, liquidity, holders, enrichment, and risk."
+    },
+    {
+      "name": "hive-wallet-investigation",
+      "path": "../packs/hive-wallet-investigation/SKILL.md",
+      "description": "Inspect wallet balances, transfers, NFTs, PnL, DeFi positions, and notable activity."
+    },
+    {
+      "name": "hive-security-risk",
+      "path": "../packs/hive-security-risk/SKILL.md",
+      "description": "Check token, approval, address, dApp, phishing, contract, and simulation risk."
+    },
+    {
+      "name": "hive-dex-pool-analysis",
+      "path": "../packs/hive-dex-pool-analysis/SKILL.md",
+      "description": "Analyze pools, pairs, liquidity, trades, OHLCV, and DEX flow."
+    },
+    {
+      "name": "hive-defi-research",
+      "path": "../packs/hive-defi-research/SKILL.md",
+      "description": "Analyze DeFi protocols, TVL, fees, revenue, stablecoins, bridges, and yields."
+    },
+    {
+      "name": "hive-nft-research",
+      "path": "../packs/hive-nft-research/SKILL.md",
+      "description": "Research NFT collections, ownership, metadata, floors, sales, rarity, and spam checks."
+    },
+    {
+      "name": "hive-solana-analysis",
+      "path": "../packs/hive-solana-analysis/SKILL.md",
+      "description": "Analyze Solana wallets, SPL accounts, DAS assets, parsed transactions, and priority fees."
+    },
+    {
+      "name": "hive-network-infrastructure",
+      "path": "../packs/hive-network-infrastructure/SKILL.md",
+      "description": "Read chain state, gas, blocks, receipts, logs, transaction status, and RPC diagnostics."
+    },
+    {
+      "name": "hive-prediction-markets",
+      "path": "../packs/hive-prediction-markets/SKILL.md",
+      "description": "Research prediction markets, events, outcomes, market stats, traders, holders, and trades."
+    }
+  ],
+  "tags": [
+    "crypto",
+    "mcp",
+    "api",
+    "agent-skill",
+    "defi",
+    "wallet-analytics",
+    "token-security",
+    "solana"
+  ]
+}

package/{LICENSE → agent-skills/LICENSE}

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Hive Intelligence
+Copyright (c) 2026 Hive Intelligence
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal