# grok-mcp

Claude Code 的 Grok AI 集成工具 — 粘贴 X 链接，获取中英混合深度解析。

## 它能做什么

在 Claude Code 中直接调用 Grok AI，无需切换浏览器：

- **分析 X/Twitter 链接** — 粘贴链接，自动提取内容并深度解读
- **X 实时搜索** — 查询 X 上的热点话题和讨论
- **通用问答** — 利用 Grok 的知识回答问题
- **预算管理** — 实时追踪 API 费用，防止超支

## 双模式架构

| 模式 | 费用 | 速度 | 输出控制 |
|------|------|------|---------|
| **免费模式**（默认） | 免费（SuperGrok 订阅） | 20-40s | 不可控 |
| **API 模式**（按需） | ~$0.02-0.15/次 | 3-10s | 精确控制 |

系统默认走免费模式。遇到以下情况自动切换到 API 模式：
- 需要结构化输出（TL;DR、表格、数学公式拆解）
- 免费模式失败（登录过期、超时）
- 你主动要求

每次切换都会显著通知你，并显示预估费用。

## 快速开始

### 1. 安装依赖

```bash
cd grok-mcp
npm install
npx playwright install chromium
```

### 2. 构建

```bash
npm run build
```

### 3. 配置免费模式（推荐先做这步）

```bash
npm run login
```

浏览器会打开 — 登录你的 X 账号（需要 SuperGrok 订阅），然后回到终端按 Enter。

### 4. 配置 API 模式（可选）

在项目根目录创建 `.env` 文件：

```
XAI_API_KEY=xai-你的key
```

API Key 在 https://console.x.ai/ 获取。

### 5. 在 Claude Code 中使用

项目已包含 `.mcp.json`，Claude Code 打开此目录时会自动注册。

或者手动添加到全局 MCP 配置（`~/.claude/mcp.json`）：

```json
{
  "mcpServers": {
    "grok-mcp": {
      "command": "node",
      "args": ["/完整路径/grok-mcp/dist/index.js"],
      "env": {
        "XAI_API_KEY": "xai-你的key"
      }
    }
  }
}
```

## 使用示例

在 Claude Code 中直接说：

```
用 Grok 分析这条推文 https://x.com/elonmusk/status/...
```

```
用 Grok 搜索最近 AI 领域的热点话题
```

```
用 Grok 深度分析这篇技术推文（用 TL;DR 格式）
```

```
查看 Grok 预算
```

### 输出效果

**免费模式：**
```
🟢 免费模式（SuperGrok）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Grok 回复的 Markdown 内容]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 耗时: 28.3s | 方式: browser
```

**API 模式：**
```
⚠️ API 模式（实际 $0.04）— 原因：需要结构化输出
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**TL;DR**（置信度：高）
[结构化深度分析...]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 tokens: 4,800 | 耗时: 5.2s | 今日: $1.39/$5.00
```

## 预算控制

默认配置：
- 单次上限：$1.00
- 单日上限：$5.00
- 总预存余额：$50.00

通过 `grok_budget` 工具管理：

| 说法 | 操作 |
|------|------|
| "查看 Grok 预算" | 显示余额、今日消耗、模式状态 |
| "把 Grok 单日上限改到 3 美元" | 调整日限额 |
| "给 Grok 充值 20 美元" | 增加余额 |

预算数据存储在 `~/.config/grok-mcp/budget.json`。

## 维护

### 免费模式登录过期

如果看到 `🔴 登录过期` 提示：

```bash
npm run login
```

### X 页面结构变化

如果免费模式返回空结果：

```bash
npm run inspect
```

检查输出，对照 `~/.config/grok-mcp/selectors.json` 更新选择器值。

### 自定义 Prompt

编辑 `~/.config/grok-mcp/prompts/default.md` 可以调整 API 模式的输出风格，无需改代码。

## 项目结构

```
src/
  index.ts              — MCP Server 入口
  config.ts             — 配置目录初始化
  router.ts             — 智能路由（自适应学习）
  client/               — API 模式（xAI REST 客户端 + Prompt 加载）
  browser/              — 免费模式（Playwright 生命周期 + DOM 提取）
  budget/               — 预算追踪（三道防线）
  tools/                — MCP 工具定义（grok + grok_budget）
  types/                — TypeScript 类型定义
scripts/
  login.ts              — 浏览器登录辅助
  inspect.ts            — DOM 选择器检查
```

## 命令

| 命令 | 用途 |
|------|------|
| `npm run build` | 构建到 dist/ |
| `npm test` | 运行测试（36 tests） |
| `npm run typecheck` | TypeScript 类型检查 |
| `npm run login` | 打开浏览器登录 X |
| `npm run inspect` | 检查 Grok 页面 DOM |
| `npm run dev` | 构建 + 启动 |

## License

MIT