# GW X Research MCP

这是一个只读的 ChatGPT MCP 工具：GPT 负责与你对话和做二次分析，Grok 通过 xAI 的 `x_search` 检索指定 X 博主的帖子与线程。

## macOS + Codex 一键安装

需要 Node.js 20.6+、Codex CLI 和一个有效的 xAI API Key。运行下面这一条命令，安装器会隐藏输入并验证 Key、安装服务、设置开机自启，并注册到 Codex：

```bash
(tmp="$(mktemp)" && trap 'rm -f "$tmp"' EXIT && curl -fsSL --retry 3 -o "$tmp" https://raw.githubusercontent.com/wzh605574547gin/gw-x-research-mcp/a7606e567a8fedfb64126db3554ffdb4279ef2a7/install.sh && echo "b77d2ea593ab97496b00732d78b1877f2e9fd0970f11830e9a298f79a0cef7cb  $tmp" | shasum -a 256 -c - && bash "$tmp")
```

安装器会校验自身 SHA-256，并验证 `v1.0.0` 对应的源码 commit。安装完成后重启 Codex，用 `/mcp` 检查 `gw_x_research`。默认只监听 `127.0.0.1`，API Key 保存在权限为 `0600` 的本机 `.env` 中，不会写入 Codex 配置。

如果你习惯先审查脚本，可先打开 [install.sh](./install.sh)，确认后再运行上面的命令。v1.0.0 一键安装器仅支持全新安装；已存在安装目录时会安全退出。

## 它能做什么

- 限定 1–20 个 X 账号，不混入其他博主的帖子。
- 按主题、起止日期检索。
- 可分析推文里的图片。
- 返回中文研究报告、原帖链接和检索范围。
- 不登录你的 X 账号，不发帖、不点赞、不关注。

> 注意：`x_search` 是研究型检索，不等同于完整导出账号历史。工具会明确标记结果并非穷尽式归档。

## 第一步：准备 xAI API Key

1. 打开 <https://console.x.ai/>。
2. 创建 API Key，并为 API 账户充值。
3. 不要把 Key 发到聊天里。

## 第二步：在 Mac 本地启动

需要 Node.js 20.6 或更新版本。在终端进入本目录，然后执行：

```bash
npm install
cp .env.example .env
```

打开 `.env`，把下面一行改成你的真实 Key：

```text
XAI_API_KEY=xai-your-api-key
```

首次本地测试时，建议暂时删除或注释 `.env` 里的 `MCP_ACCESS_TOKEN`，然后执行：

```bash
set -a
source .env
set +a
npm start
```

浏览器打开 <http://localhost:3000/health>，看到 `"ok":true` 说明服务已启动。

## 第三步：接入 ChatGPT

推荐个人使用时采用 **Secure MCP Tunnel**，这样 xAI Key 留在你的 Mac，不需要公开服务器：

1. 在 ChatGPT 网页版打开“设置 → 安全与登录 → 开发者模式”。
2. 前往 ChatGPT Plugins，点加号创建连接。
3. Connection 选择 **Tunnel**，让 Tunnel 指向本机的 `http://localhost:3000/mcp`。
4. 名称填写 `GW X Research`，创建后检查工具列表里是否出现 `research_x_author`。
5. 新开一个对话，从“+ → Developer mode”选中 `GW X Research`。

如果你的账号暂时没有 Secure MCP Tunnel，也可以把 Docker 容器部署到支持 HTTPS 的平台；但公开部署必须增加可靠认证与限流。不要把没有认证的 `/mcp` 暴露到公网，也不要把 `XAI_API_KEY` 写进代码或 Docker 镜像。

## 直接可用的提问模板

```text
只使用 GW X Research 的 research_x_author 工具。
检索 @博主账号 从 2026-01-01 到今天关于 AVGO 的原创分析推文和线程，深度选择 deep，最多20条。
然后由你做二次分析：
1. 按时间线还原观点变化；
2. 区分事实、推断和预测；
3. 提取最重要的多头与空头论据；
4. 检查前后矛盾；
5. 每项结论附原帖链接；
6. 明确说明搜索是否可能遗漏内容。
```

## 工具输入

| 字段 | 说明 |
| --- | --- |
| `handles` | X 账号数组，最多20个，可带或不带 `@` |
| `topic` | 研究主题、公司、资产或具体问题 |
| `from_date` / `to_date` | 可选，格式为 `YYYY-MM-DD`，包含首尾日期 |
| `max_results` | 1–50，默认20 |
| `depth` | `quick`、`standard` 或 `deep` |
| `output_language` | 默认简体中文 |
| `include_images` | 默认开启图片理解 |

## Docker

```bash
docker build -t gw-x-research-mcp .
export MCP_ACCESS_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 3000:3000 \
  -e XAI_API_KEY="$XAI_API_KEY" \
  -e HOST=0.0.0.0 \
  -e MCP_ACCESS_TOKEN="$MCP_ACCESS_TOKEN" \
  gw-x-research-mcp
```

容器监听非 loopback 地址时，服务会强制要求 `MCP_ACCESS_TOKEN`。若映射端口，请再通过防火墙、HTTPS 反向代理或 OAuth 控制可达范围；不要把未认证端点暴露到公网。

## 本地检查

```bash
npm run check
npm test
```

## 卸载

卸载时先从 Codex 删除 `gw_x_research`，再卸载 `com.gwcapital.gw-x-research-mcp` LaunchAgent；最后按需删除 `~/.local/share/gw-x-research-mcp`。`.env` 内含 API Key，删除前请确认不再需要。

## 成本与安全

- xAI 会分别计算 Grok token 与 `x_search` 工具调用费用。
- 服务端仅从环境变量读取 Key。
- MCP 工具被标记为只读，但 X 上的内容仍可能包含提示注入；最终结论应以原帖链接为准。
- 若部署到公网，请使用标准 OAuth、ChatGPT Secure MCP Tunnel，或受信任的认证代理。`MCP_ACCESS_TOKEN` 只用于支持 Bearer Token 的客户端或代理测试，不代表完整的多用户认证方案。