x-search-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konark Mangudkar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# x-search-mcp
+
+Minimal MCP server for xAI X search using the Responses API and structured outputs.
+
+## Features
+- Single MCP tool: `x_search`
+- Uses xAI Responses API with `x_search` tool calling
+- Structured output parsing + citation normalization
+
+## Requirements
+- Node.js >= 18
+- `XAI_API_KEY` environment variable
+
+## Install
+```bash
+npm install
+npm run build
+```
+
+## Run (stdio)
+```bash
+XAI_API_KEY=your-key-here node dist/index.js
+```
+
+## Codex MCP config (example)
+```toml
+[mcp_servers.x-search]
+command = "node"
+args = ["/path/to/x-search-mcp/dist/index.js"]
+[mcp_servers.x-search.env]
+XAI_API_KEY = "your-key-here"
+```
+
+## Smoke test (optional)
+```bash
+XAI_API_KEY=your-key-here npm run build
+XAI_API_KEY=your-key-here npm run smoke-test
+```
+Note: this test requires network access and may fail in restricted environments.
+
+## MCP Tool
+### `x_search`
+Searches X with optional filters.
+
+**Input**
+```json
+{
+  "query": "string",
+  "allowed_x_handles": ["string"],
+  "excluded_x_handles": ["string"],
+  "from_date": "YYYY-MM-DD",
+  "to_date": "YYYY-MM-DD",
+  "enable_image_understanding": true,
+  "enable_video_understanding": true,
+  "include_raw_response": false
+}
+```
+
+**Output**
+```json
+{
+  "answer": "string",
+  "citations": ["https://x.com/..."],
+  "inline_citations": [
+    {
+      "url": "https://x.com/...",
+      "start_index": 10,
+      "end_index": 42,
+      "title": "1"
+    }
+  ],
+  "raw_response": {}
+}
+```
+
+## Environment Variables
+- `XAI_API_KEY` (required)
+- `XAI_MODEL` (default: `grok-4-1-fast`)
+- `XAI_BASE_URL` (default: `https://api.x.ai/v1`)
+- `XAI_TIMEOUT` (default: `30000`)
+
+## Notes
+- `allowed_x_handles` and `excluded_x_handles` are mutually exclusive.
+- Date filters must be `YYYY-MM-DD` and `from_date` must be <= `to_date`.
+- Tool responses are returned as MCP `structuredContent` (with a text fallback for display).
+- Citations are normalized from xAI response annotations when available.

package/bin/x-search-mcp

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/dist/index.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+const DEFAULT_MODEL = "grok-4-1-fast";
+const XSearchInputBaseSchema = z.object({
+    query: z.string().min(1).max(2000).describe("Search query for X"),
+    allowed_x_handles: z
+        .array(z.string().min(1))
+        .max(10)
+        .optional()
+        .describe("Only include posts from these handles"),
+    excluded_x_handles: z
+        .array(z.string().min(1))
+        .max(10)
+        .optional()
+        .describe("Exclude posts from these handles"),
+    from_date: z
+        .string()
+        .optional()
+        .describe("Start date (YYYY-MM-DD)"),
+    to_date: z.string().optional().describe("End date (YYYY-MM-DD)"),
+    enable_image_understanding: z
+        .boolean()
+        .optional()
+        .describe("Enable image understanding"),
+    enable_video_understanding: z
+        .boolean()
+        .optional()
+        .describe("Enable video understanding"),
+    include_raw_response: z
+        .boolean()
+        .optional()
+        .describe("Include raw xAI response for debugging"),
+});
+const XSearchInputSchema = XSearchInputBaseSchema.superRefine((data, ctx) => {
+    if (data.allowed_x_handles && data.excluded_x_handles) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "allowed_x_handles and excluded_x_handles cannot both be set",
+            path: ["allowed_x_handles"],
+        });
+    }
+    if (data.from_date) {
+        const error = validateDateString(data.from_date);
+        if (error) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: error,
+                path: ["from_date"],
+            });
+        }
+    }
+    if (data.to_date) {
+        const error = validateDateString(data.to_date);
+        if (error) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: error,
+                path: ["to_date"],
+            });
+        }
+    }
+    if (data.from_date && data.to_date) {
+        const from = new Date(data.from_date);
+        const to = new Date(data.to_date);
+        if (from > to) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "from_date must be before or equal to to_date",
+                path: ["from_date"],
+            });
+        }
+    }
+});
+const XSearchOutputSchema = z.object({
+    answer: z.string(),
+    citations: z.array(z.string()),
+    inline_citations: z.array(z.object({
+        url: z.string(),
+        start_index: z.number().nullable(),
+        end_index: z.number().nullable(),
+        title: z.string().nullable(),
+    })),
+    raw_response: z.unknown().optional(),
+});
+const RESPONSE_SCHEMA = {
+    name: "x_search_answer",
+    schema: {
+        type: "object",
+        properties: {
+            answer: { type: "string" },
+            citations: { type: "array", items: { type: "string" } },
+        },
+        required: ["answer"],
+    },
+};
+function validateDateString(value) {
+    if (!DATE_REGEX.test(value)) {
+        return "Date must be in YYYY-MM-DD format";
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        return "Invalid date";
+    }
+    const iso = date.toISOString().slice(0, 10);
+    if (iso !== value) {
+        return "Invalid date";
+    }
+    return null;
+}
+function dedupeUrls(urls) {
+    const seen = new Set();
+    const result = [];
+    for (const url of urls) {
+        if (!url)
+            continue;
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        result.push(url);
+    }
+    return result;
+}
+function extractMessage(output) {
+    if (!output)
+        return null;
+    const message = output.find((item) => item?.type === "message");
+    if (!message)
+        return null;
+    const content = message.content?.find((item) => item?.type === "output_text");
+    if (!content)
+        return null;
+    return content;
+}
+function normalizeCitations(annotations, parsedCitations) {
+    const urlCitations = (annotations || [])
+        .filter((a) => a?.type === "url_citation" && a?.url)
+        .map((a) => ({
+        url: a.url,
+        start_index: typeof a.start_index === "number" ? a.start_index : null,
+        end_index: typeof a.end_index === "number" ? a.end_index : null,
+        title: a.title ?? null,
+    }));
+    const urlsFromAnnotations = dedupeUrls(urlCitations.map((c) => c.url));
+    const urlsFromParsed = Array.isArray(parsedCitations)
+        ? parsedCitations.filter((c) => typeof c === "string" && c.startsWith("http"))
+        : [];
+    const citations = urlsFromAnnotations.length > 0 ? urlsFromAnnotations : urlsFromParsed;
+    return {
+        citations,
+        inline_citations: urlCitations,
+    };
+}
+async function fetchJson(url, options, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { ...options, signal: controller.signal });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new Error(`xAI API error ${response.status}: ${text}`);
+        }
+        return JSON.parse(text);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+const server = new McpServer({
+    name: "x-search-mcp",
+    version: "0.1.0",
+});
+server.registerTool("x_search", {
+    title: "X Search",
+    description: "Search X posts using xAI's Responses API x_search tool. Returns a normalized answer and citations.",
+    inputSchema: XSearchInputBaseSchema,
+    outputSchema: XSearchOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+}, async (args) => {
+    try {
+        const parsedArgs = XSearchInputSchema.parse(args);
+        const apiKey = process.env.XAI_API_KEY;
+        if (!apiKey) {
+            throw new Error("XAI_API_KEY is required");
+        }
+        const baseUrl = process.env.XAI_BASE_URL ?? "https://api.x.ai/v1";
+        const model = process.env.XAI_MODEL ?? DEFAULT_MODEL;
+        const timeoutMs = Number.parseInt(process.env.XAI_TIMEOUT ?? "30000", 10);
+        const toolConfig = {
+            type: "x_search",
+        };
+        if (parsedArgs.allowed_x_handles) {
+            toolConfig.allowed_x_handles = parsedArgs.allowed_x_handles;
+        }
+        if (parsedArgs.excluded_x_handles) {
+            toolConfig.excluded_x_handles = parsedArgs.excluded_x_handles;
+        }
+        if (parsedArgs.from_date) {
+            toolConfig.from_date = parsedArgs.from_date;
+        }
+        if (parsedArgs.to_date) {
+            toolConfig.to_date = parsedArgs.to_date;
+        }
+        if (typeof parsedArgs.enable_image_understanding === "boolean") {
+            toolConfig.enable_image_understanding = parsedArgs.enable_image_understanding;
+        }
+        if (typeof parsedArgs.enable_video_understanding === "boolean") {
+            toolConfig.enable_video_understanding = parsedArgs.enable_video_understanding;
+        }
+        const body = {
+            model,
+            input: [
+                {
+                    role: "system",
+                    content: "You answer questions using X search. Return JSON that matches the provided schema. Use citations when possible.",
+                },
+                {
+                    role: "user",
+                    content: parsedArgs.query,
+                },
+            ],
+            tools: [toolConfig],
+            text: {
+                format: {
+                    type: "json_schema",
+                    schema: RESPONSE_SCHEMA,
+                },
+            },
+        };
+        const response = await fetchJson(`${baseUrl}/responses`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify(body),
+        }, timeoutMs);
+        const content = extractMessage(response.output);
+        const rawText = content?.text ?? "";
+        let parsed = { answer: rawText };
+        if (rawText) {
+            try {
+                const parsedJson = JSON.parse(rawText);
+                if (parsedJson && typeof parsedJson === "object") {
+                    parsed = parsedJson;
+                }
+            }
+            catch {
+                // Keep raw text fallback
+            }
+        }
+        const normalizedCitations = normalizeCitations(content?.annotations, parsed.citations);
+        const normalizedResponse = {
+            answer: typeof parsed.answer === "string" && parsed.answer.trim().length > 0
+                ? parsed.answer
+                : rawText,
+            citations: normalizedCitations.citations,
+            inline_citations: normalizedCitations.inline_citations,
+            ...(parsedArgs.include_raw_response ? { raw_response: response } : {}),
+        };
+        return {
+            structuredContent: normalizedResponse,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(normalizedResponse, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        console.error("x_search failed", message);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: message,
+                        status: "failed",
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("x-search-mcp running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "x-search-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for xAI X search via Responses API",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/konarkm/x-search-mcp.git"
+  },
+  "homepage": "https://github.com/konarkm/x-search-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/konarkm/x-search-mcp/issues"
+  },
+  "bin": {
+    "x-search-mcp": "bin/x-search-mcp"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build",
+    "smoke-test": "tsx scripts/smoke-test.ts",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "xai",
+    "x-search",
+    "x"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.12.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}