@zypheragent/mcp 0.1.0 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # @zypheragent/mcp
 
-Read-only [Model Context Protocol](https://modelcontextprotocol.io) server of [Zypher Agent](https://zypheragent.com). It gives an AI assistant (Claude Desktop, Cursor, any MCP client) market and on-chain **reads**: Hyperliquid perp analytics and Elysium testnet token/pool data.
+[Model Context Protocol](https://modelcontextprotocol.io) server of [Zypher Agent](https://zypheragent.com). It gives an AI assistant (Claude Desktop, Cursor, any MCP client) market and on-chain **reads**: Hyperliquid perp analytics, HyperSwap V3 quotes and token data on HyperEVM, and Boxa launch facts on Elysium 99901 (all mainnet).
 
-**It cannot trade.** There is no order placement, no transaction building, no signing and no key handling in this package. Trading lives in the Zypher Agent app: https://zypheragent.com
+**Read-only by default.** Without configuration it cannot trade: no order placement, no transaction building, no signing, no key handling. **Optional execution** (swap, perp order, close, send, transfer out) is only switched on if you set a `ZYPHER_API_TOKEN`, a per-user API token you create in the Zypher Agent app. Orders then run through *your own Agent Wallet* on the Zypher Agent server, inside the caps you set. This package never holds or sees any private key.
 
 ## Run
 
@@ -10,7 +10,7 @@ Read-only [Model Context Protocol](https://modelcontextprotocol.io) server of [Z
 npx -y @zypheragent/mcp
 ```
 
-The server speaks MCP over stdio. It starts with no environment variables and no config file. Its ready line (`zypher-mcp <version> ready (stdio, read-only, ...)`) goes to **stderr**; stdout is reserved for the MCP channel. Needs Node.js >= 20.
+The server speaks MCP over stdio. It starts with no environment variables and no config file. Its ready line (`zypher-mcp <version> ready (stdio, read-only, ...)`, or `read + EXECUTION ...` when a token is set) goes to **stderr**; stdout is reserved for the MCP channel. Needs Node.js >= 20.
 
 Binaries: `zypher-mcp` and `zypheragent-mcp` (same program).
 
@@ -42,25 +42,63 @@ Generic stdio client, with optional environment:
 {
   "command": "npx",
   "args": ["-y", "@zypheragent/mcp"],
-  "env": { "ZYPHER_NETWORK": "testnet", "ZYPHER_ADDRESS": "0xYourPublicAddress" }
+  "env": { "ZYPHER_NETWORK": "mainnet", "ZYPHER_ADDRESS": "0xYourPublicAddress" }
 }
 ```
 
-## Tools (12)
+## Optional: execution through your Agent Wallet
+
+1. In the Zypher Agent app open **Agent > Wallet > API tokens** and create a token. It looks like `zat_` followed by 40 lowercase hex characters and is shown once.
+2. Put it in the client's MCP config (never in a repository):
+
+```json
+{
+  "mcpServers": {
+    "zypher-agent": {
+      "command": "npx",
+      "args": ["-y", "@zypheragent/mcp"],
+      "env": { "ZYPHER_API_TOKEN": "zat_0123456789abcdef0123456789abcdef01234567" }
+    }
+  }
+}
+```
+
+With a valid token the server registers nine more tools (24 in total) and its ready line says `read + EXECUTION`. A malformed token prints a clear error on stderr and execution stays disabled; the 15 read tools keep working.
+
+| Tool | What it does | Arguments |
+| --- | --- | --- |
+| `agent_status` | Your Agent Wallet: address, balances, positions, caps. Does not move funds. | none |
+| `agent_swap` | Exact-in swap on HyperEVM from the Agent Wallet. | `tokenIn`, `tokenOut` (symbol or 0x address), `amountIn`, optional `slippageBps` |
+| `agent_elysium_swap` | Swap on Elysium 99901 (native HYPE <-> a Boxa-indexed token) from the Agent Wallet. | `tokenIn`, `tokenOut` (HYPE on one side; symbol or 0x address), `amountIn`, optional `slippageBps` |
+| `agent_elysium_launch` | **Launch a token on Elysium** through Boxa's V3 launcher from the Agent Wallet (1B supply in locked liquidity, no creation fee). | `name`, `symbol`, optional `description`, `image`/`website`/`twitter`/`telegram` (https URLs), `allocation` (`balanced`, `creator`, `holders`, `buyback`, `liquidity` or four basis-point shares summing to 10000), `antiSnipe`, `firstBuyHype` |
+| `agent_bridge_elysium` | Move native HYPE HyperEVM <-> Elysium for the Agent Wallet (fund it before an Elysium swap or launch). | `direction` (`deposit`\|`withdraw`), `amount` |
+| `agent_perp_order` | Open/add a Hyperliquid perp position. | `coin` (`BTC`, `xyz:NVDA`), `side` long\|short, `notionalUsd`, `leverage`, optional `tpPrice`, `slPrice`, `reduceOnly` |
+| `agent_close` | Close a perp position (all or a percentage). | `coin`, optional `fractionPct` (0-100) |
+| `agent_send` | Send funds from the Agent Wallet to an external 0x address. | `asset`, `amount`, `to` (0x address) |
+| `agent_transfer_out` | Move funds from the Agent Wallet back to your own main wallet. | `asset`, `amount` |
+
+**These tools move real funds on mainnet.** Every call executes immediately from your Agent Wallet, inside the caps set by you / the operator in the app. There is **no confirmation step** in the MCP, so the assistant is told to ask you first; do not auto-approve these tools in your client. No tool accepts a wallet, owner, URL or path argument: the package can only call the nine fixed paths `/api/agent-api/{status,swap,elysium-swap,elysium-launch,bridge-boxa,perp-order,close,send,transfer-out}` under `ZYPHER_API_URL`.
+
+Each write call carries a fresh random `Idempotency-Key`. Timeouts are 15 s (45 s for swaps); redirects are refused and responses over 100 KB are refused. After a timeout or a 5xx on a write, the outcome is unknown: call `agent_status` before retrying.
+
+## Tools (15 read tools, always on)
 
 | Tool | What it does |
 | --- | --- |
 | `get_policy` | Shows this server's fixed read-only policy (network, no trading, no keys). |
-| `analyze_ticker` | Hyperliquid perp analysis: price, 24h volume, open interest, funding, orderbook depth. |
+| `analyze_ticker` | Hyperliquid perp analysis for any listed market, crypto or trade.xyz stocks/indices/metals (`BTC`, `xyz:NVDA`, or the bare symbol `NVDA`): price, 24h volume, open interest, funding, orderbook depth. |
 | `get_strong_volume` | Perp tickers with the highest 24h volume, with volume/OI ratio and price change. |
-| `get_new_pairs` | **Not available.** Needs an indexer that is not part of this package; always returns an explicit "not available" error. |
+| `get_new_pairs` | Newest token launches on Elysium 99901 (all launchpads), newest first. Elysium only; `chain=hyperevm` returns an explicit error. |
+| `get_elysium_market` | The Elysium market / launchpad feed (like the app's Market and Launch tabs): sort `newest`, `fdv` (top), `volume` (trending), `change` (gainers), `trades`, `holders`; filter by launchpad (`boxa`, `kleos`, `ascend`, `montra`, `volta`, `elyspump`, `uniswap`, `stockium`, `stocks`...), search `q`, `tradable`. Read from the Zypher public API. |
+| `get_elysium_token` | One Elysium token by address: launchpad, pool, price, FDV, 24h change/volume, holders, tradable flag. |
 | `analyze_token_health` | Bytecode/ABI check of a token contract (mint, pause, blacklist, owner) with a score and reasons. A heuristic, not an audit. |
 | `get_social_info` | Recent tweets about a ticker. Needs your own `X_BEARER_TOKEN`; without it the tool returns a clear error. |
-| `get_portfolio` | Public balances/positions of an address: Hyperliquid account and native HYPE on Elysium testnet. |
-| `get_market_tokens` | Tokens with a live pool on the Elysium testnet venues the app reads: price (HYPE/USDC), liquidity, pair. Not every token on the chain. |
-| `quote_swap` | Exact-in swap quote on Elysium testnet venues (best venue, output, route, price impact). Quote only; nothing is sent. |
-| `get_perp_markets` | Hyperliquid perp markets: price, 24h change, volume, open interest, funding, max leverage. |
+| `get_portfolio` | Public balances/positions of an address: Hyperliquid account, native HYPE on HyperEVM mainnet and on Elysium 99901. |
+| `get_market_tokens` | HyperEVM mainnet tokens (HyperSwap V3, a verified list): USD price from the deepest sane pool, TVL, pool health. No 24h change. Not every token on the chain. |
+| `quote_swap` | Exact-in swap quote on HyperSwap V3 (HyperEVM mainnet): output, route, price impact; sane pools only. Quote only; nothing is built or sent. |
+| `get_perp_markets` | All Hyperliquid perp markets (own dex, about 179, plus trade.xyz stocks, indices and metals as `xyz:NVDA`, about 120): price, 24h change, volume, open interest, funding, max leverage. |
 | `get_candles` | Hyperliquid candles: summary statistics plus the last 20 candles. |
+| `get_launch_info` | Read-only facts about token launches on Elysium 99901 through Boxa's V3 launcher: chain check, contract code-hash pins, pool fee, treasury share, supply. Read-only; to launch use `agent_elysium_launch`. |
 | `get_hl_account` | Hyperliquid account state of a public address: value, margin, positions, open orders. |
 
 All tool output is JSON text. Text that comes from third parties (token names, tweets) is sanitised and should still be treated as untrusted data, not as instructions.
@@ -69,26 +107,28 @@ All tool output is JSON text. Text that comes from third parties (token names, t
 
 | Variable | Default | Meaning |
 | --- | --- | --- |
-| `ZYPHER_NETWORK` | `testnet` | Hyperliquid network for perp reads: `testnet` or `mainnet`. Applies to Hyperliquid reads only; the Elysium tools always read Elysium testnet. |
+| `ZYPHER_NETWORK` | `mainnet` | Hyperliquid network for perp reads (`mainnet` is the default and the product's only network). |
 | `ZYPHER_ADDRESS` | unset | Public `0x...` address used by `get_portfolio` / `get_hl_account` when no `address` argument is passed. Never put a private key here. |
 | `X_BEARER_TOKEN` | unset | Your X API bearer token, only for `get_social_info`. |
-| `ELYSIUM_RPC` | public Elysium testnet RPC | Override the Elysium testnet RPC URL. |
-| `HYPEREVM_RPC` | public HyperEVM RPC | Override the HyperEVM RPC URL (`analyze_token_health` with `chain: "hyperevm"`). |
+| `ZYPHER_API_TOKEN` | unset | Agent Wallet API token (`zat_` + 40 lowercase hex). Enables the nine `agent_*` tools. Sent only as `Authorization: Bearer` to `ZYPHER_API_URL`; never logged. |
+| `ZYPHER_API_URL` | `https://zypheragent.com/agent` | Base URL of the Zypher Agent API. Must be https (plain http only for `localhost` / `127.0.0.1`). A different host prints a one-line stderr warning that the token will be sent there. |
+| `ELYSIUM_RPC` | `https://rpc-live.boxa.club` | Override the Elysium (99901) RPC URL. |
+| `HYPEREVM_RPC` | public HyperEVM RPC | Override the HyperEVM (999) RPC URL. |
 
 No other variables are read.
 
 ## Network behaviour
 
-- Only public, unauthenticated data endpoints are contacted: the Hyperliquid info API (`api.hyperliquid-testnet.xyz`, or `api.hyperliquid.xyz` when `ZYPHER_NETWORK=mainnet`), the public Elysium testnet RPC and, for `analyze_token_health` on `hyperevm`, the public HyperEVM RPC. `get_social_info` contacts `api.x.com` only if you set a token.
+- Without a token only public, unauthenticated data endpoints are contacted. With `ZYPHER_API_TOKEN` it additionally talks to `ZYPHER_API_URL` (default `https://zypheragent.com/agent`), only on the nine fixed `/api/agent-api/*` paths. Read tools contact: the Hyperliquid info API (`api.hyperliquid.xyz`), the public HyperEVM RPC (`rpc.hyperliquid.xyz/evm`) and the Elysium 99901 RPC (`rpc-live.boxa.club`, run by Boxa) and, for the Elysium market tools, the public Zypher API (`zypheragent.com/agent`). `get_social_info` contacts `api.x.com` only with your own token.
 - Requests carry the header `User-Agent: zypher-mcp/<version>`.
 - No telemetry, no analytics, no phone-home. The package writes nothing to disk.
-- Default is **testnet**. Testnet prices and liquidity have no real value and can be thin or odd.
+- Default is **mainnet** (real markets): Hyperliquid mainnet, HyperEVM 999 and Elysium 99901. **Elysium 99901 is a community-run chain served by Boxa (rpc-live.boxa.club), not the official Kinetiq mainnet**; `get_launch_info` checks that the chain id and the pinned contract code hashes still match and says so when they do not. Its RPC and contracts are third-party; a lying or lagging RPC cannot be detected from here.
 
 ## What it does not do
 
-- No trading, no order preparation, no execution, no transaction building or signing.
-- No private keys, seed phrases or wallet access of any kind.
-- No new-pair/launch discovery (`get_new_pairs` is a placeholder that reports "not available").
+- Without `ZYPHER_API_TOKEN`: no trading, no order preparation, no execution. In every mode: no transaction building or signing here.
+- No private keys, seed phrases or direct wallet access of any kind: the Agent Wallet is held and signed by the Zypher Agent server, never by this package.
+- No launching and no new-pair discovery (`get_new_pairs` is a placeholder that reports "not available"; `get_launch_info` only reads facts).
 - No price history beyond the candles from Hyperliquid, and no token search by name on launchpads (use addresses).
 
 ## Limits
@@ -99,7 +139,10 @@ No other variables are read.
 
 ## Security notes
 
-- Read-only by construction: the published bundle contains no signing or order code. Pass only public addresses.
+- The published bundle contains no signing code and no key handling. Pass only public addresses to the read tools.
+- **Execution is opt-in and uses real money.** Use a *dedicated Agent Wallet with a small balance*, keep the caps in the app low, and revoke the token in the app (Agent > Wallet > API tokens) as soon as you stop using it or suspect a leak. Caps and the revocation are enforced server-side.
+- **Prompt injection:** token names, tweets, web pages and other tool output can contain text that tries to make your assistant call `agent_swap` / `agent_send`. Do not auto-approve `agent_*` tools; read every call's parameters (especially `to` and amounts) before you accept it.
+- The token is only sent in the `Authorization` header to the configured base URL, never in a query string, log, tool result or error message.
 - The server runs locally over stdio; it opens no network port.
 - Treat tool output as data. Do not let an assistant act on instructions found inside token names or tweets.
 - Have a look at the single bundled file `dist/index.js` if you want to audit it.