内容
<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/portfolio-mcp</h1>
<p align="center"><strong>一个AI代理的自身交易状态，通过MCP — 投资组合价值、利润和亏损、实时余额、公共交易动态，以及一个真正的写入：一个签名的链上Solana转账。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/portfolio-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/portfolio-mcp?logo=npm&color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/portfolio-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/portfolio-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代理提供对其 **自身** 交易状态的编程访问权限，涵盖标准输入/输出：它拥有的数据、价值如何随时间变化、单个代币的仓位与实时市场数据、平台范围内的已关闭交易动态及其 **已实现利润和亏损**、任何钱包的实时链上余额 — 以及一个真正的写入，一个 **签名的Solana转账**，涉及SOL或任何SPL代币。
读取操作直接访问three.ws实时API和Solana RPC — 不进行模拟。账户范围的读取操作针对您 **拥有** 的代理钱包（从您的three.ws会话中解析）。一个写入操作，即 `send_transfer`，在本地使用您自己的密钥签名，并将真实资金转移到主网。
## 安装
```bash
npm install @three-ws/portfolio-mcp
```
或使用 `npx`（无需安装）：
```bash
npx @three-ws/portfolio-mcp
```
## 快速入门
**Claude 代码**，一行：
```bash
claude mcp add portfolio -- npx -y @three-ws/portfolio-mcp
```
**Claude 桌面版 / Cursor** (`claude_desktop_config.json` 或 `mcp.json`）：
```json
{
"mcpServers": {
"portfolio": {
"command": "npx",
"args": ["-y", "@three-ws/portfolio-mcp"],
"env": {
"THREE_WS_SESSION": "<您的 __Host-sid cookie>",
"SOLANA_SECRET_KEY": "<发送钱包的base58私钥>"
}
}
}
}
```
`THREE_WS_SESSION` 仅在账户范围的读取操作时需要；`SOLANA_SECRET_KEY` 仅在 `send_transfer` 时需要。交易动态和链上余额读取操作无需任何配置即可工作。
使用MCP检查器检查接口：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/portfolio-mcp
```
## 工具
| 工具 | 类型 | 功能 |
| ------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `get_portfolio_summary` | 读取 · 会话 | 您拥有的所有代理钱包的实时持仓 + 美元价值，附有每个钱包的明细。可选快照。 |
| `get_portfolio_history` | 读取 · 会话 | 您的总投资组合美元价值随时间变化，从存储的快照中获取 — 性能图表。 |
| `get_portfolio_asset` | 读取 · 会话 | 一个代币的深入分析：哪些钱包持有它，您的总金额/美元价值，以及实时市场数据和价格历史图表。 |
| `get_trades_feed` | 读取 · 公共 | 平台范围内的已关闭仓位的动态及其 **已实现利润和亏损** — 最新退出记录优先，可按币种过滤。 |
| `get_wallet_balances` | 读取 · 公共 | 任何Solana地址的实时链上SOL + SPL（包括Token-2022）余额，直接从RPC获取。 |
| `send_transfer` | **写入 · 破坏性** | 签名并广播一个真实的、不可逆转的Solana主网转账，涉及SOL或任何SPL代币，从您自己的钱包中转移资金。 |
所有读取操作都访问实时状态 — 余额、动态和广播操作在调用之间移动 — 因此没有工具是幂等的。`send_transfer` 是唯一改变任何内容的工具。
### 输入参数
**`get_portfolio_summary`** — `snapshot`（布尔值，默认为 `false` — 同时持久化一个历史点）。
**`get_portfolio_history`** — `days`（1–365，默认为 `90`）。
**`get_portfolio_asset`** — `chain`（`solana` | `evm`，必填），`id`（`native` 或 base58的铸造地址 / 0x合约地址，必填），`days`（1–365，默认为 `30`）。
**`get_trades_feed`** — `network`（`mainnet` | `devnet`，默认为 `mainnet`），`window`（`1h` | `6h` | `24h` | `7d` | `30d` | `all`，默认为 `24h`），`min_pnl_pct`（默认为 `10`），`limit`（1–80，默认为 `40`），`cursor`（用于分页的ISO时间戳），`mint`（筛选到一个币种）。
**`get_wallet_balances`** — `address`（base58，必填），`include_tokens`（布尔值，默认为 `true`）。
**`send_transfer`** — `recipient`（base58，必填），`amount`（十进制字符串，必填），`mint`（base58 SPL铸造地址；省略 / `native` 表示SOL），`secret`（base58，覆盖 `SOLANA_SECRET_KEY`），`priorityMicroLamports`（0–50,000,000），`confirm`（必须为 `true` 以执行）。
## 已实现价值与实时价值
两个不同的问题，两个不同的工具：
- **"我现在值多少钱？"** → `get_portfolio_summary` / `get_portfolio_asset` — 实时持仓按美元计价。
- **"我的已关闭交易表现如何？"** → `get_trades_feed` — 按已关闭仓位计算的已实现利润和亏损（入场/出场价格以SOL计，利润百分比，倍数，持有时间）。
## 写入工具 — `send_transfer`
`send_transfer` **在Solana主网上广播一个真实的、不可逆转的交易**，并将资金从签名钱包中转移出去。它在本地使用每次调用的 `secret` 或 `SOLANA_SECRET_KEY` 进行签名 — three.ws API 永远不会持有您的密钥。防护措施：
- **`confirm: true` 在 `REQUIRE_CONFIRM` 启用时（默认为启用）必填** — 第一次调用如果没有它将返回一个拒绝，而不是广播。
- **`MAX_SOL_PER_TX`** 限制原生SOL发送（默认为0.5 SOL）。
- **`RECIPIENT_ALLOWLIST`**（当设置时）限制目标地址到一个已知的集合。
- `mint` 是 **运行时输入** — 传送 `$THREE` 铸造地址或您持有的任何SPL代币。没有铸造地址是硬编码的。
对于SPL转账，它读取链上铸造地址的十进制数，验证您的余额，并在缺少时自动创建接收者的关联代币账户。在确认超时时，它返回 `tx_unconfirmed` 以及签名 — 在重新发送之前请检查Solscan以避免重复支出。
## 要求
- **Node.js >= 20.**
- 可以访问 `https://three.ws`（或您自己的 `THREE_WS_BASE`）和Solana RPC。
### 环境变量
| 变量 | 是否必填 | 默认值 |
| ----------------------- | ------------------------- | --------------------------------------- |
| `THREE_WS_BASE` | 否 | `https://three.ws` |
| `THREE_WS_TIMEOUT_MS` | 否 | `20000` |
| `THREE_WS_SESSION` | 账户范围读取必填 | — |
| `SOLANA_RPC_URL` | 否 | `https://api.mainnet-beta.solana.com` |
| `SOLANA_SECRET_KEY` | `send_transfer`必填 | — |
| `MAX_SOL_PER_TX` | 否 | `0.5` |
| `RECIPIENT_ALLOWLIST` | 否 | — （任何有效的公钥地址均允许） |
| `REQUIRE_CONFIRM` | 否 | `true` |
`THREE_WS_SESSION` 是来自登录的three.ws浏览器会话的 `__Host-sid` cookie的值。请像密码一样保护它和 `SOLANA_SECRET_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>
## 许可证
版权所有 © 2026 nirholas。保留所有权利。
该软件是专有软件 — 请参阅 [LICENSE](./LICENSE)。未经版权所有者的明确书面许可，不得授予任何权利。
