内容
# tradeos-mcp
TradeOS MCP 让您可以将 TradeOS 交易智能与 MCP 兼容的 AI 工具连接起来，以便您的助手可以直接从自然语言提示中分析市场、搜索股票代码、比较价差、使用宏观背景和管理自定义交易代理。
## 概述
该仓库发布 **`@tradeos/tradeos-mcp`** 到 npm：一个 **stdio MCP 桥接器**，它代理工具到 TradeOS Streamable HTTP (`mcp-call`)。您可以通过两种方式连接：
| 模式 | 最适合 | 身份验证 |
| ---------------------- | ------------------------------------------- | ------------------------------ |
| **HTTP** (推荐) | Cursor, Claude Code, 大多数 MCP 客户端 | 客户端浏览器 OAuth |
| **npm stdio** | 只支持 `command` / stdio 的客户端 | `TRADEOS_ACCESS_TOKEN` 环境变量 |
生产环境端点（两种模式最终都会调用此端点）：
```text
https://ai.tradeos.xyz/api/agent/mcp/mcp-call
```
产品文档：[TradeOS MCP 集成与使用](https://tradeos.gitbook.io/tradeosaifaq/tradeos-mcp-integration-and-usage)
---
## 前提条件
- [Node.js](https://nodejs.org/) **18+**
- 具有 MCP API 访问权限的 TradeOS 账户
- 对于 npm stdio：能够运行本地安装（参见 [Windows 说明](#windows-notes)）
---
## 选项 A — HTTP（推荐）
无需 npm 安装。客户端处理 OAuth。
### Cursor
编辑用户配置文件 `~/.cursor/mcp.json`（Windows: `%USERPROFILE%\.cursor\mcp.json`）：
```json
{
"mcpServers": {
"tradeos": {
"url": "https://ai.tradeos.xyz/api/agent/mcp/mcp-call"
}
}
}
```
保存，重启 Cursor（或在 **设置 → MCP** 中刷新 MCP），然后在提示时完成 OAuth。
### Claude Code（插件 — 推荐）
在 [`tradeos-skills/`](tradeos-skills/) 中使用捆绑插件：
```bash
claude --plugin-dir ./tradeos-skills
```
然后完成 OAuth 并运行 **`/tradeos:analyze`**. 完整的插件工作流程（验证，社区市场提交）： [`tradeos-skills/README.md`](tradeos-skills/README.md) — 与 [Claude 插件文档](https://code.claude.com/docs/en/plugins#submit-your-plugin-to-the-community-marketplace) 对齐。
---
## 选项 B — npm stdio 桥接器
当您的客户端需要本地进程（`command` + stdio）时使用。
### 1. 本地安装
**不要在 Windows 上依赖 `npx`**（缓存/路径问题）。安装到固定目录：
```bash
mkdir -p ~/tradeos-mcp-run # Windows: mkdir %USERPROFILE%\Downloads\tradeos-mcp-run
cd ~/tradeos-mcp-run # Windows: cd %USERPROFILE%\Downloads\tradeos-mcp-run
npm install @tradeos/tradeos-mcp
```
固定版本（如果需要）：`@tradeos/tradeos-mcp@1.0.0`.
### 2. 获取 `TRADEOS_ACCESS_TOKEN`
运行 OAuth 助手（打开浏览器 → 登录 TradeOS → 打印令牌）：
```bash
# Linux / macOS
npx -y -p @tradeos/tradeos-mcp tradeos-mcp-oauth
# 或主二进制文件的子命令：
npx -y @tradeos/tradeos-mcp oauth
# 或，从您的安装目录：
node node_modules/@tradeos/tradeos-mcp/scripts/fetch-token.mjs
```
**Windows（推荐）：**
```cmd
cd /d %USERPROFILE%\Downloads\tradeos-mcp-run
node node_modules\@tradeos\tradeos-mcp\scripts\fetch-token.mjs
```
复制打印的 JWT (`eyJ...`)。对于 **本地开发此仓库**，复制到 `.env`:
```bash
cp .example.env .env
# TRADEOS_ACCESS_TOKEN=eyJ...
```
仅安装该软件包的最终用户不需要 `.env` — 而是在 MCP 客户端配置（`mcp.json`）中设置令牌。
**不要将令牌提交到 git.**
### 3. 配置 Cursor
```json
{
"mcpServers": {
"tradeos-npm": {
"command": "node",
"args": [
"C:/Users/YOU/Downloads/tradeos-mcp-run/node_modules/@tradeos/tradeos-mcp/build/index.js"
],
"env": {
"TRADEOS_ACCESS_TOKEN": "eyJ..."
}
}
}
}
```
替换 `YOU` 和路径为您实际的安装位置。在 JSON 中使用正斜杠或转义的反斜杠。
如果 Cursor 找不到 `node`，请设置完整路径：
```json
"command": "C:/nvm4w/nodejs/node.exe"
```
在 **设置 → MCP** 中启用 **tradeos-npm**。状态应显示已连接并列出工具。
### 4. 在终端中验证（可选）
`mcp.json` 中的环境变量 **不** 适用于您的 shell。在 **同一** 终端会话中设置令牌：
```cmd
REM Windows CMD
set TRADEOS_ACCESS_TOKEN=eyJ...
node C:\Users\YOU\Downloads\tradeos-mcp-run\node_modules\@tradeos\tradeos-mcp\build\index.js
```
```bash
# Linux / macOS
export TRADEOS_ACCESS_TOKEN=eyJ...
node ~/tradeos-mcp-run/node_modules/@tradeos/tradeos-mcp/build/index.js
```
成功：
```text
[tradeos-mcp] remote: https://ai.tradeos.xyz/api/agent/mcp/mcp-call
[tradeos-mcp] stdio bridge ready
```
按 `Ctrl+C` 停止。Cursor 启动自己的进程；您不需要保持此终端打开。
---
## Windows 说明
1. **使用本地 `node` + `mcp.json` 中的安装路径**，而不是 `npx`，适用于 MCP。
2. 如果 npm 缓存错误提到 `C:\Program Files\nodejs\node_cache`，请运行一次：
```cmd
npm config set cache "%USERPROFILE%\.npm-cache"
```
3. **`npx @pkg tradeos-mcp-oauth`** 可能在 Windows 上运行错误的二进制文件。优先使用：
```cmd
npx -y -p @tradeos/tradeos-mcp tradeos-mcp-oauth
```
或 `node .../scripts/fetch-token.mjs` 从您的安装目录。
4. 清除损坏的 npx 缓存（首先退出 Cursor）：
```cmd
rmdir /s /q "%USERPROFILE%\.npm-cache\_npx"
```
---
## npm 软件包参考
| 项目 | 值 |
| ----------------- | ------------------------------------------ |
| 软件包 | `@tradeos/tradeos-mcp` |
| MCP 注册表名称 | `io.github.TradeOS-AI/tradeos-mcp` |
| 二进制文件：MCP 桥接器 | `tradeos-mcp` |
| 二进制文件：OAuth 令牌 | `tradeos-mcp-oauth` |
| OAuth 子命令 | `oauth` 在二进制文件 `tradeos-mcp` 上 |
安装：
```bash
npm install @tradeos/tradeos-mcp
```
---
## 开发（此仓库）
```bash
git clone https://github.com/TradeOS-AI/tradeos-mcp.git
cd tradeos-mcp
npm ci
npm run build
npm run oauth:token # 浏览器 OAuth → 打印令牌（如果需要复制到 .env）
npm run registry:verify
```
| 脚本 | 目的 |
| ------------------------------------- | --------------------------------------------------- |
| `npm run build` | 编译 stdio 桥接到 `build/` |
| `npm run oauth:token` | 浏览器 OAuth → 打印令牌 |
| `npm run registry:verify` | 发布前检查（`package.json` ↔ `server.json`） |
| `npm run registry:sync-version <ver>` | 从发布标签同步版本 |
---
## 发布（维护者）
推送版本标签以触发 [`.github/workflows/publish-mcp.yml`](.github/workflows/publish-mcp.yml)：
```bash
git tag v1.0.0
git push origin v1.0.0
```
- 稳定标签（`v1.0.0`）发布到 npm **`latest`** 和 [MCP 注册表](https://registry.modelcontextprotocol.io/)。
- 预发布标签（`v1.0.0-beta.1`）发布时带有与预发布标签匹配的 npm 分发标签（例如 `beta`）。
- 需要 GitHub Actions 机密 **`NPM_TOKEN`**（用于 `@tradeos` 的经典 **Automation** 令牌）。
在注册表 API 上验证：
```bash
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.TradeOS-AI/tradeos-mcp"
```
---
## 故障排除
| 症状 | 可能原因 | 修复 |
| ------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------ |
| `TRADEOS_ACCESS_TOKEN is required` | 环境变量或 `mcp.json` 中未设置令牌 | 运行 oauth 助手；设置 `env` 在 MCP 配置中 |
| 连接时 `unauthorized` | 令牌过期或无效 | 重新运行 oauth；粘贴新鲜的 JWT（无 `Bearer` 前缀） |
| `EPERM` / `node_cache` | npm 缓存位于 `Program Files` | `npm config set cache "%USERPROFILE%\.npm-cache"` |
| `TAR_ENTRY_ERROR` / `'tradeos-mcp' is not recognized` | Windows 上的 `npx` 失败 | 本地安装 + `node` 路径在 `mcp.json` 中 |
| `MODULE_NOT_FOUND` for `node_modules/...` | 从错误目录运行脚本 | `cd` 到安装目录或使用绝对路径 |
| 令牌在终端中有效，但在 Cursor 中无效 | `mcp.json` 路径或令牌不匹配 | 匹配路径；重启 Cursor / 刷新 MCP |
| MCP 连接但无工具 | 错误的服务器启用 | 禁用损坏的 `localhost` 条目；使用生产 HTTP URL 或有效的 `tradeos-npm` |
---
## 相关
- [`tradeos-skills/`](tradeos-skills/) — Claude Code 插件 + 分析技能
- [`server.json`](server.json) — MCP 注册表清单
- [TradeOS MCP 常见问题（GitBook）](https://tradeos.gitbook.io/tradeosaifaq/tradeos-mcp-integration-and-usage)
