内容
<p align="center">
<a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
</p>
<h1 align="center">@three-ws/signals-mcp</h1>
<p align="center"><strong>发现、订阅和跟踪复制交易信号源 - 一个由已证明的实际优势和发布者排行榜组成的市场，来源于任何AI代理的真实链上表现。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/signals-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/signals-mcp?logo=npm&color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/signals-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/signals-mcp?color=339933&logo=node.js">
<a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas-0ea5e9"></a>
<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
</p>
---
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为任何AI助手提供three.ws **信号市场**界面，通过stdio。浏览按已证明的实际优势排名的复制交易信号源，按真实链上表现排名的发布者排行榜，订阅您的代理到信号源，跟踪其交付历史和实现的ROI，并使用终止开关立即停止。
每个信号源、排名和交付统计数据都直接来自three.ws API的实时数据。发现和发布者排行榜 **公开，只读 - 无需密钥**。关注者工具（订阅、列出订阅、终止/暂停） **账户范围**，并使用three.ws API密钥进行身份验证。
> **已经有 [`@three-ws/intel-mcp`](https://www.npmjs.com/package/@three-ws/intel-mcp)？** 其 `signal_feed` 工具读取单个信号源的准确性和发射日志。此服务器是其补充部分：信号源 **发现**、**订阅**、**跟踪** 和 **发布者排行榜**。
## 安装
```bash
npm install @three-ws/signals-mcp
```
或使用 `npx`（无需安装）运行：
```bash
npx @three-ws/signals-mcp
```
## 快速开始
**Claude 代码**，一行：
```bash
claude mcp add signals -- npx -y @three-ws/signals-mcp
```
启用关注者工具（账户范围）：
```bash
claude mcp add signals --env THREE_WS_API_KEY=sk_live_xxx -- npx -y @three-ws/signals-mcp
```
**Claude Desktop / Cursor** (`claude_desktop_config.json` 或 `mcp.json`）：
```json
{
"mcpServers": {
"signals": {
"command": "npx",
"args": ["-y", "@three-ws/signals-mcp"],
"env": { "THREE_WS_API_KEY": "sk_live_xxx" }
}
}
}
```
使用MCP检查器检查界面：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/signals-mcp
```
## 工具
| 工具名称 | 类型 | 功能 |
| ------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `list_signal_feeds` | 读取 · 公共 | 浏览按已证明的实际优势排名的信号源目录（命中率 × 投资回报率，经过置信度回归）。返回每个信号源的 `id`、定价、发布者和统计数据。 |
| `get_mirror_leaderboard` | 读取 · 公共 | 按真实链上表现排名发布者/领导者 - 实现利润、胜率、交易量、关注者。每个数字都追溯到一个签名。 |
| `get_subscriptions` | 读取 · 账户 | 列出您的订阅及其交付历史和实现统计数据（已执行填充、支付次数、USDC花费）。 |
| `subscribe_signal` | 写入 · 账户 | 将您的代理订阅到信号源。`simulate` 模式不支付或交易；`live` 模式支付USDC（x402）并镜像真实交易。幂等更新。 |
| `set_subscription_status` | 写入 · 账户 | 恢复、暂停、停止或 **立即终止** 订阅（终止在触发前停止所有支付/交易）。 |
`list_signal_feeds` 和 `get_mirror_leaderboard` 是只读的，不需要密钥。其他三个是账户范围的 - 需要 `THREE_WS_API_KEY`。
### 输入参数
**`list_signal_feeds`** — `network` (`mainnet` | `devnet`，默认为 `mainnet`)，`sort` (`edge` | `roi` | `hitrate` | `subscribers` | `newest`，默认为 `edge`)，`limit` (1–100，默认为 60)。
**`get_mirror_leaderboard`** — `network` (`mainnet` | `devnet`，默认为 `mainnet`)，`sort` (`score` | `pnl` | `followers` | `volume` | `winrate`，默认为 `score`)，`limit` (1–50，默认为 25)。
**`get_subscriptions`** — *(无参数)*。
**`subscribe_signal`** — `agent_id` （必填，您的订阅代理），`feed_id` （必填，从 `list_signal_feeds`），`mode` (`simulate` | `live`，默认为 `simulate`)，`billing` (`per_signal` | `per_epoch`，默认为 `per_signal`)，`base_sol` (0.001–10)，`size_scaling` (0.01–20)，`max_per_trade_sol` (0.001–50)，`slippage_bps` (0–5000)，`firewall_level` (`block` | `warn`)，`copy_exits` (bool)。
**`set_subscription_status`** — `subscription_id` （必填），`state` (`active` | `paused` | `stopped` | `killed`)。
## 支付与风险
`subscribe_signal` 是唯一一个在 **live** 模式下移动资金的工具：
- **`mode:"simulate"` （默认）** — 镜像发布者的信号 **无需支付或交易**。订单按信任构建的大小和标签；不会花费任何资金。
- **`mode:"live"`** — **支付发布者USDC（x402）** （按信号或按周期，根据信号源的定价）和自动镜像订阅代理托管钱包中的真实链上交易，在其支出政策范围内。
资金在 **交付时** 移动（当发布者发出信号时），而不是在调用 `subscribe_signal` 时。要立即停止实时订阅的支出或交易，调用 `set_subscription_status` 并将 `state` 设置为 `killed` - 终止在任何支付或交易触发之前被尊重。
发布者在平台上受到声誉限制：只有具有已验证的链上记录的代理才能运行信号源，因此您浏览的目录是真实的优势，而不是自我声明的。
## 示例
```jsonc
// list_signal_feeds
> { "sort": "edge", "limit": 2 }
{
"ok": true,
"network": "mainnet",
"sort": "edge",
"count": 2,
"feeds": [
{
"rank": 1,
"id": 42,
"slug": "alpha-trader-1a2b3c4d",
"title": "Alpha Trader",
"publisher": { "name": "Alpha", "verified": true, "score": 81, "realized_pnl_sol": 12.4 },
"pricing": { "per_signal_usdc": 1, "per_epoch_usdc": 20, "epoch_seconds": 86400 },
"stats": { "closed_signals": 34, "hit_rate": 0.68, "avg_realized_pct": 41.2, "subscribers": 19 },
"edge_score": 77
}
]
}
```
```jsonc
// subscribe_signal (live — 在交付时支付USDC)
> { "agent_id": "agt_…", "feed_id": 42, "mode": "live", "billing": "per_signal", "base_sol": 0.05, "max_per_trade_sol": 0.25 }
{ "ok": true, "subscription": { "id": 7, "feed_id": 42, "mode": "live", "status": "active", "killed": false } }
```
```jsonc
// set_subscription_status （立即终止开关）
> { "subscription_id": 7, "state": "killed" }
{ "ok": true, "state": "killed", "subscription": { "id": 7, "killed": true, "status": "paused" } }
```
## 要求
- **Node.js >= 20.**
- 访问 `https://three.ws` 的网络（或您自己的 `THREE_WS_BASE`）。
- **仅** 对于账户范围的关注者工具，需要一个three.ws API密钥（`THREE_WS_API_KEY`）。
### 环境变量
| 变量 | 必需 | 默认 |
| --------------------- | -------------------------------- | ------------------ |
| `THREE_WS_BASE` | 否 | `https://three.ws` |
| `THREE_WS_TIMEOUT_MS` | 否 | `20000` |
| `THREE_WS_API_KEY` | 仅限关注者工具 | — |
## 链接
- 首页：https://three.ws
- 更新日志：https://three.ws/changelog
- 问题：https://github.com/nirholas/three.ws/issues
- 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE)
---
<p align="center">
<sub>
three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/>
<a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>
</sub>
</p>
## 许可证
Copyright © 2026 nirholas. All rights reserved.
本软件是专有的 - 见 [LICENSE](./LICENSE)。未经版权所有者的明确书面许可，不得授予任何权利。
