npm package: @pricesylo/mcp-client
Description: Local MCP transport adapter — bridges stdio-based AI agents to the PriceSylo cloud MCP server over Streamable HTTP.
Latest version: 1.0.9

# @pricesylo/mcp-client

Official MCP (Model Context Protocol) client for **[PriceSylo](https://pricesylo.com)** — a real-time crypto trading intelligence platform that provides deep market analytics, order book profiling, flow engine analysis, and multi-exchange data aggregation.

This package is a local transport adapter that bridges stdio-based AI agents (Claude Desktop, Cursor, VS Code, etc.) to the PriceSylo cloud MCP server over Streamable HTTP. It enables AI assistants to directly query live market data, wallet information, engine snapshots, and chart generation through natural language.

```
IDE / AI Agent (stdio) ⇄ pricesylo-mcp ⇄ PriceSylo Cloud MCP Server (HTTPS)
```

## Prerequisites

To use this MCP client, you need a PriceSylo MCP Token.  
Get your token at **[https://pricesylo.com](https://pricesylo.com)** by creating an account or subscribing to the relevant tier.

## Quick Start

### Claude Desktop

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pricesylo": {
      "command": "npx",
      "args": ["-y", "@pricesylo/mcp-client"],
      "env": {
        "MCP_SERVER_URL": "https://gate.pricesylo.com/mcp",
        "MCP_API_KEY": "your-token-here"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "pricesylo": {
      "command": "npx",
      "args": ["-y", "@pricesylo/mcp-client"],
      "env": {
        "MCP_SERVER_URL": "https://gate.pricesylo.com/mcp",
        "MCP_API_KEY": "your-token-here"
      }
    }
  }
}
```

### VS Code

Add to `.vscode/settings.json`:

```json
{
  "mcp.servers": {
    "pricesylo": {
      "command": "npx",
      "args": ["-y", "@pricesylo/mcp-client"],
      "env": {
        "MCP_SERVER_URL": "https://gate.pricesylo.com/mcp",
        "MCP_API_KEY": "your-token-here"
      }
    }
  }
}
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `MCP_SERVER_URL` | ✅ | — | PriceSylo cloud MCP endpoint URL |
| `MCP_API_KEY` | ✅ | — | Your PriceSylo MCP authentication token |
| `MCP_REQUEST_TIMEOUT` | ❌ | `30000` | Per-request timeout in milliseconds |
| `MCP_DEBUG` | ❌ | `false` | Enable verbose debug logging (`1`, `true`, or `yes`) |

## Available Tools

Once connected, your AI agent will have access to **14+ PriceSylo tools** across four categories.

### ℹ️ Server Info

| Tool | Description |
|------|-------------|
| `get_server_info` | Returns server metadata, version, token acquisition URL, and client package link |
| `get_websocket_guide` | Returns the full WebSocket streaming API guide including connection, auth, message methods, and a JS quickstart |

### 📊 Market Data

| Tool | Description |
|------|-------------|
| `get_engine_snapshot` | Fetch a packed snapshot from a specific engine layer (`dominancy`, `ev_profile`, `cob_profile`, `best_deals`, `entities`, `discrete`, `rotation`, `kline`). Chart image URLs in the response require authentication (see Chart Access below) |
| `get_market_data_brief` | Get a summarized brief of market state: price, flow dominance, session EV, rotation, best deal, and live kline. The `snapshot.chart` URL requires authentication (see Chart Access below) |
| `get_historical_kline` | Fetch historical OHLCV candlesticks from the engine buffer (100–1000 candles) |
| `get_market_chart_image` | Snapshot a live chart image with configurable interval, indicators, theme, and style. Returns the image directly without requiring a chart token |
| `create_chart_preview_token` | Create a short-lived chart preview token (valid for 30 minutes) that can be appended to chart screenshot URLs as `chartToken=` to bypass API key authentication |
| `revoke_chart_preview_token` | Revoke an existing chart preview token so it can no longer be used to access chart screenshots |
| `fetch_market_pairs` | Fetch available market trading pairs for a specific exchange platform |

> **Chart Access:** Chart image URLs returned by `get_engine_snapshot` and `get_market_data_brief` require authentication. You have two options:
> 1. Use `get_market_chart_image` to fetch the chart image directly.
> 2. Use `create_chart_preview_token` to generate a short-lived token, then append it to the chart URL as `?chartToken=GENERATED_TOKEN`.

### 👤 Account

| Tool | Description |
|------|-------------|
| `get_user_profile` | Get the authenticated user profile including account details and settings |
| `fetch_wallet_info` | Fetch wallet balances across all supported currencies |
| `fetch_wallet_history` | Fetch wallet transaction history with pagination support |

### ⚡ Real-Time Streaming (WebSocket)

In addition to the MCP tools above, PriceSylo exposes a **separate WebSocket API** for live streaming market data. Use the `get_websocket_guide` tool to retrieve the full connection guide, or refer to the summary below.


**Endpoints:**
- Spot: `wss://stream_spot.pricesylo.com/?apiKey=YOUR_API_KEY`
- Futures: `wss://stream_futures.pricesylo.com/?apiKey=YOUR_API_KEY`

**Auth:** API key (separate from your MCP token) — obtain at [https://pricesylo.com](https://pricesylo.com)  
**Encoding:** Binary frames → [MessagePack](https://msgpack.org/) (`msgpackr`). String frames → plain JSON.

#### Methods

| Method | Param Format | Description |
|--------|-------------|-------------|
| `SUBSCRIBE` | `EXCHANGE:SYMBOL:MARKETTYPE@CHANNEL` | Stream live channel updates |
| `SNAPSHOT` | `EXCHANGE:SYMBOL:MARKETTYPE:TARGET` | Request a one-time engine layer snapshot |
| `BRIEFING` | `EXCHANGE:SYMBOL:MARKETTYPE` | Request a summarized market state briefing |
| `PING` | — | Heartbeat (send every ~25 s, server replies `PONG`) |

**SUBSCRIBE channels:** `BEST_DEAL`, `SCALPING_INDICATOR`, `KLINE_UPDATE`, `COB_STANDARD`, `COB_CUMULATIVE`, `DOMINANCY_UPDATE`, `ENTITIES_WALL_UPDATE`, `ENTITIES_WALL_DECAY`, `ENTITIES_EVENT`, `DISCRETE_EVENT`, `DISCRETE_BUBBLE`, `EVP_LEVEL_UPDATE`, `EVP_SESSION_UPDATE`, `ROTATION_UPDATE`, `ROTATION_CLOSURE`
**SNAPSHOT targets:** `ROTATION`, `DOMINANCY`, `EV_PROFILE`, `COB_PROFILE`, `BEST_DEALS`, `ENTITIES`, `DISCRETE`, `KLINE`

#### JavaScript Quickstart

```js
import { unpack } from 'msgpackr';

const ws = new WebSocket('wss://stream_spot.pricesylo.com/?apiKey=YOUR_API_KEY');
ws.binaryType = 'arraybuffer';

ws.onmessage = (event) => {
  let data = typeof event.data === 'string'
    ? JSON.parse(event.data)
    : unpack(new Uint8Array(event.data));

  // Handle stringified Buffer fallback
  if (data?.type === 'Buffer' && Array.isArray(data.data)) {
    data = unpack(new Uint8Array(data.data));
  }

  if (data.method === 'CONNECTED') {
    // Subscribe after connection confirmed
    ws.send(JSON.stringify({
      method: 'SUBSCRIBE',
      params: ['BINANCE:BTCUSDT:SPOT@BEST_DEAL'],
      id: Date.now()
    }));
    // Heartbeat
    setInterval(() => ws.send(JSON.stringify({ method: 'PING', id: Date.now() })), 25000);
  }
};
```

**Reconnection:** Use exponential back-off capped at 30 s (`Math.min(1000 * 2^attempt, 30000)`). Re-subscribe all channels after reconnect. Close code `1008` = rejected (do not reconnect). Close code `1006` = server restart (reconnect safe).

## Troubleshooting

**"Configuration Error" on startup**  
→ Make sure `MCP_SERVER_URL` and `MCP_API_KEY` are set in your IDE's MCP config `env` block.

**"HTTP transport error"**  
→ Check that the server URL is correct. Enable debug logging with `MCP_DEBUG=1`.

**No response from tools**  
→ Verify your MCP token is valid and has not expired.

**WebSocket connection rejected (code 1008)**  
→ Your API key is invalid or unauthorized. Obtain a valid key at [https://pricesylo.com](https://pricesylo.com).

## How It Works

This package uses the official [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) transports:

1. `StdioServerTransport` reads JSON-RPC messages from the IDE via stdin/stdout
2. `StreamableHTTPClientTransport` forwards them to the PriceSylo cloud MCP server over HTTPS
3. Responses flow back the same path in reverse

All logs go to **stderr** — stdout is exclusively reserved for the MCP protocol.

## License

MIT