Twitter/X数据查询服务

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

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

{
  "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"
      }
    }
  }
}

# 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

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<K,V>: 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 < 5 s
npm test

# Unit tests with coverage report (thresholds: lines 60%, functions 60%, branches 50%)
npm run test:coverage

# Integration tests — makes real Grok API calls (requires XAI_API_KEY in .env.test)
cp .env.test.example .env.test
# Edit .env.test and set XAI_API_KEY=xai-..., then:
npm run test:integration

# All tests (unit + integration)
npm run test:all

MCP Host (e.g. Claude Desktop)
        │  stdio (JSON-RPC)
        ▼
  src/index.ts  ←── registers 12 tools, wraps errors via run()
        │
        ▼
  GrokClient.query()                GrokClient.analyzeMedia()
  (maxRetries: 3)                   (get_tweet only)
        │  HTTPS                            │  HTTPS
        ▼                                   ▼
  api.x.ai/v1  ── x_search ──▶  Twitter/X real-time data
  api.x.ai/v1  ── chat/completions (grok-2-vision-1212) ──▶  media_summary