@zypheragent/mcp 0.0.0-stage → 0.1.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,109 @@
-# 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.
+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.
+
+**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
+
+## 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, ...)`) 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": "testnet", "ZYPHER_ADDRESS": "0xYourPublicAddress" }
+}
+```
+
+## Tools (12)
+
+| 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. |
+| `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 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_candles` | Hyperliquid candles: summary statistics plus the last 20 candles. |
+| `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` | `testnet` | Hyperliquid network for perp reads: `testnet` or `mainnet`. Applies to Hyperliquid reads only; the Elysium tools always read Elysium testnet. |
+| `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"`). |
+
+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.
+- 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.
+
+## 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").
+- 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
+
+- Read-only by construction: the published bundle contains no signing or order code. Pass only public addresses.
+- 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`.