MCP X Query

mcp-x查询

A. 模型上下文协议（MCP） 服务器，让人工智能助手通过 格罗克API.

将此服务器连接到Claude Desktop（或任何兼容MCP的主机），并提出以下问题：

• *“@sama本周发了什么推特？”*
• *“给我看看从这条推文开始的完整帖子。”*
• *“现在科技界的趋势是什么？”*
• *“查找有关最新GPT版本的推文。”*

目录

• 特性
• 先决条件
• 安装
• 配置
• 可用工具
• Claude桌面设置
• 发展
• 测试
• 建筑
• 安全
• 贡献
• 许可证

______________________________________________________________________

特性

______________________________________________________________________

先决条件

• 20或更晚(.nvmrc 提供）
• 一 xAI API密钥 （开始于 xai-)

______________________________________________________________________

安装

git clone https://github.com/IvyNotFound/mcp-x-query.git
cd mcp-x-query
npm install
npm run build

______________________________________________________________________

配置

复制环境模板并添加您的API密钥：

cp .env.example .env
# Edit .env and set XAI_API_KEY=xai-...

服务器读取 XAI_API_KEY 启动时从环境中退出，如果丢失，则立即退出。

______________________________________________________________________

可用工具

get_tweet

检索一条包含完整元数据（媒体、引用推文、参与度指标）的推文。

当推文包含图像、视频或GIF时，每个媒体项目都会被自动分析 Grok Vision (grok-2-vision-1212)并丰富了a media_summary 描述视觉内容的字段。

get_tweet_replies

返回推特上参与度最高的回复，可选择按日期过滤。

get_user_tweets

获取用户最近的推文和转发（最新优先）。通过 enrich_media: true 让Grok Vision分析每个媒体项目（增加延迟）。

get_user_profile

返回完整的个人资料信息，包括个人简介、计数器和固定推文。

search_tweets

支持全文搜索 推特搜索运营商 (from:, to:, -is:retweet, lang:, #hashtag等等）。通过 enrich_media: true 用于Grok Vision对每个媒体项目的分析。

get_thread

从链中的任何推文（根、中间线程或叶子）重建完整的对话线程。

get_trending

返回Twitter/X上的当前趋势主题。结果缓存5分钟，以避免重复的API调用。

analyze_sentiment

对通过搜索查询或从特定帐户检索到的推文语料库进行情绪分析。返回细分（正/负/中性百分比）、热门主题和值得注意的推文。

analyze_thread

重建一个完整的线程，然后生成一个结构化的分析：总体情绪、每个参与者提出的关键论点、摘要和值得注意的引文。

extract_links

提取Twitter帐户共享的所有外部URL（或匹配搜索查询），并返回每个链接及其标题、域和共享内容的简要摘要。

get_user_mentions

返回其他帐户中提到给定用户的推文。可用于监控品牌提及、社区回复或跟踪围绕特定句柄的对话。

get_list_tweets

从Twitter/X列表中获取最近的推文。接受数字列表ID或完整列表URL(https://x.com/i/lists/).支持通过光标分页： next_cursor 响应中的字段是页面上最旧推文的ID——将其作为 cursor 在下一次调用中获取旧推文。通过 enrich_media: true 让Grok Vision分析每个媒体项目（增加延迟）。

______________________________________________________________________

Claude桌面设置

将服务器添加到Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-x-query": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-x-query/dist/index.js"],
      "env": {
        "XAI_API_KEY": "xai-your-api-key-here"
      }
    }
  }
}

保存文件后重新启动Claude Desktop。

______________________________________________________________________

发展

# Watch mode — recompiles on every file save
npm run dev

# Single build
npm run build

# Interactive MCP inspector (useful for manual tool testing)
npm run inspector

TypeScript源代码位于 src/。编译后的输出将转到 dist/ （忽略了）。

项目结构

src/
├── index.ts              # MCP server entry point — tool registration & startup (12 tools)
├── lib/
│   ├── grok-client.ts    # Grok API wrapper (OpenAI SDK + x_search tool, maxRetries: 3)
│   ├── errors.ts         # Typed error hierarchy: GrokError, GrokAuthError, GrokRateLimitError
│   ├── utils.ts          # Input helpers: URL→ID extraction, @ stripping, escapeForPrompt
│   └── cache.ts          # TtlCache: in-memory TTL cache (used by get_trending, get_user_profile)
├── schemas/
│   ├── tweet.ts          # TweetSchema, ThreadSchema, TweetArraySchema, MediaSchema
│   ├── user.ts           # UserProfileSchema
│   ├── trending.ts       # TrendingTopicsSchema
│   ├── sentiment.ts      # SentimentAnalysisSchema, SentimentBreakdownSchema, NotableTweetSchema
│   ├── thread-analysis.ts# ThreadAnalysisSchema
│   └── link-extract.ts   # LinkExtractSchema, ExtractedLinkSchema
└── tools/                # One file per MCP tool
    ├── get-tweet.ts
    ├── get-tweet-replies.ts
    ├── get-user-profile.ts
    ├── get-user-tweets.ts
    ├── get-thread.ts
    ├── get-trending.ts
    ├── search-tweets.ts
    ├── analyze-sentiment.ts
    ├── analyze-thread.ts
    ├── extract-links.ts
    ├── get-user-mentions.ts
    └── get-list-tweets.ts

______________________________________________________________________

测试

# Unit tests only — no API key required, runs in ` 随着 `‹`/`›` 在将所有自由文本输入（查询、类别、语言）插入提示之前，都使用Unicode|
| **用户名净化** | `src/lib/utils.ts` — `sanitizeUsername()` |条纹 `@` 并且仅强制使用字母数字+下划线|
| **推特ID验证** | `src/lib/utils.ts` — `extractTweetId()` |如果提取的ID不是纯数字，则抛出(`^\d+$`) |
| **输入长度上限** |Zod模式| `query` 字段的长度限制为500个字符|
| **日期格式验证** |Zod模式|全部 `from_date`/`to_date` 字段需要 `YYYY-MM-DD` 通过正则表达式格式化|
| **API超时** | `src/lib/grok-client.ts` | `timeout: 30_000` 所有API调用上的ms|
| **媒体域白名单** | `src/lib/grok-client.ts` | `analyzeMedia()` 只接受来自一组固定的受信任域的URL(`x.com`, `twimg.com`等等）|
| **TTL缓存** | `src/lib/cache.ts` |缓存趋势主题（5分钟）和用户配置文件（10分钟），以减少API表面积|

______________________________________________________________________

## 贡献

看 [贡献.md](CONTRIBUTING.md).

______________________________________________________________________

## 许可证

[麻省理工学院](LICENSE)