@zypheragent/mcp 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zypher Agent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# @zypheragent/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[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).
+
+**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
+
+```sh
+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, ...)`, 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).
+
+## Client configuration
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "zypher-agent": { "command": "npx", "args": ["-y", "@zypheragent/mcp"] }
+  }
+}
+```
+
+Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "zypher-agent": { "command": "npx", "args": ["-y", "@zypheragent/mcp"] }
+  }
+}
+```
+
+Generic stdio client, with optional environment:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@zypheragent/mcp"],
+  "env": { "ZYPHER_NETWORK": "mainnet", "ZYPHER_ADDRESS": "0xYourPublicAddress" }
+}
+```
+
+## 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 six more tools (19 in total) and its ready line says `read + EXECUTION`. A malformed token prints a clear error on stderr and execution stays disabled; the 13 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_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 six fixed paths `/api/agent-api/{status,swap,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 (13 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 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. |
+| `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, 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. Launching itself is not possible through this MCP. |
+| `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.
+
+## Environment variables (all optional)
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `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`. |
+| `ZYPHER_API_TOKEN` | unset | Agent Wallet API token (`zat_` + 40 lowercase hex). Enables the six `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
+
+- 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 six 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). `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 **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
+
+- 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
+
+- Data comes from public APIs and RPCs; it can be stale, rate-limited, incomplete or wrong. Public RPCs may throttle heavy use.
+- `analyze_token_health` inspects bytecode patterns and basic ERC-20 metadata only. A high score is not a safety guarantee.
+- Nothing here is financial advice.
+
+## Security notes
+
+- 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.
+
+## License
+
+MIT, see `LICENSE`.