@lkbaba/grok-mcp 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Grok-MCP TypeScript Type Definitions
+ *
+ * Defines all types for xAI API, MCP tools, and project configuration
+ */
+/**
+ * xAI Responses API request type
+ */
+export interface XAIResponsesRequest {
+    /** Model name, e.g. "grok-4.20-beta" */
+    model: string;
+    /** Conversation messages array */
+    messages: Array<{
+        role: 'system' | 'user' | 'assistant';
+        content: string;
+    }>;
+    /** Streaming response toggle */
+    stream: boolean;
+    /** Temperature (0-2), controls randomness */
+    temperature?: number;
+    /** Server-side tool configuration */
+    server_side_tools?: Array<XAIWebSearchTool | XAIXSearchTool>;
+}
+/**
+ * Web Search tool configuration
+ */
+export interface XAIWebSearchTool {
+    type: 'web_search';
+    /** Enable image understanding */
+    enable_image_understanding?: boolean;
+    /** Filter configuration */
+    filters?: {
+        /** Only search specified domains (max 5) */
+        allowed_domains?: string[];
+        /** Exclude specified domains (max 5) */
+        excluded_domains?: string[];
+    };
+}
+/**
+ * X Search tool configuration
+ */
+export interface XAIXSearchTool {
+    type: 'x_search';
+    /** Start date (ISO8601 format) */
+    from_date?: string;
+    /** End date (ISO8601 format) */
+    to_date?: string;
+    /** Enable image understanding */
+    enable_image_understanding?: boolean;
+    /** Enable video understanding */
+    enable_video_understanding?: boolean;
+    /** Only search specified users (max 10) */
+    allowed_x_handles?: string[];
+    /** Exclude specified users (max 10) */
+    excluded_x_handles?: string[];
+}
+/**
+ * xAI Responses API response type
+ */
+export interface XAIResponsesResponse {
+    /** Output array, may contain search call records and messages */
+    output: Array<{
+        type: string;
+        role?: 'assistant';
+        content?: Array<{
+            type: 'output_text';
+            text: string;
+            /** Text annotations (contains citation info) */
+            annotations?: Array<{
+                type: string;
+                url?: string;
+                title?: string;
+                start_index: number;
+                end_index: number;
+            }>;
+        }>;
+        /** Search call action info */
+        action?: {
+            type: string;
+            query?: string;
+        };
+        status?: string;
+    }>;
+    /** Token usage statistics */
+    usage: XAIUsage;
+}
+/**
+ * Token usage statistics type
+ */
+export interface XAIUsage {
+    /** Input tokens */
+    input_tokens: number;
+    /** Input tokens details */
+    input_tokens_details?: {
+        cached_tokens?: number;
+    };
+    /** Output tokens */
+    output_tokens: number;
+    /** Output tokens details */
+    output_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+    /** Total tokens */
+    total_tokens: number;
+    /** Cost (unit: ticks, 1 tick = 0.0000000001 USD) */
+    cost_in_usd_ticks: number;
+    /** Server-side tool usage details (may be absent when no search tools used) */
+    server_side_tool_usage_details?: {
+        web_search_calls?: number;
+        x_search_calls?: number;
+        code_interpreter_calls?: number;
+        file_search_calls?: number;
+        mcp_calls?: number;
+        document_search_calls?: number;
+    };
+}
+/**
+ * grok_agent_search tool input parameters
+ */
+export interface GrokAgentSearchInput {
+    /** Search query */
+    query: string;
+    /** Search type */
+    search_type?: 'web' | 'x' | 'mixed';
+    /** Model to use */
+    model?: string;
+    /** Output format */
+    output_format?: 'text' | 'json';
+    /** Web Search config (when search_type is 'web' or 'mixed') */
+    web_search_config?: {
+        enable_image_understanding?: boolean;
+        allowed_domains?: string[];
+        excluded_domains?: string[];
+    };
+    /** X Search config (when search_type is 'x' or 'mixed') */
+    x_search_config?: {
+        from_date?: string;
+        to_date?: string;
+        enable_image_understanding?: boolean;
+        enable_video_understanding?: boolean;
+        allowed_x_handles?: string[];
+        excluded_x_handles?: string[];
+    };
+}
+/**
+ * grok_agent_search tool output result
+ */
+export interface GrokAgentSearchOutput {
+    /** Search result content */
+    content: string;
+    /** Cited URL list */
+    citations: string[];
+    /** Token usage statistics */
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        reasoning_tokens: number;
+        cached_tokens: number;
+        total_tokens: number;
+        web_search_calls: number;
+        x_search_calls: number;
+    };
+}
+/**
+ * grok_brainstorm tool input parameters
+ */
+export interface GrokBrainstormInput {
+    /** Brainstorm topic */
+    topic: string;
+    /** Context information (optional) */
+    context?: string;
+    /** Project file paths, read as context */
+    context_files?: string[];
+    /** Number of ideas to generate, 1-10 */
+    count?: number;
+    /** Brainstorm style */
+    style?: 'innovative' | 'practical' | 'radical' | 'balanced';
+    /** Model to use */
+    model?: string;
+    /** Output format */
+    output_format?: 'text' | 'json';
+}
+/**
+ * grok_brainstorm tool output result
+ */
+export interface GrokBrainstormOutput {
+    /** Generated content */
+    content: string;
+    /** Token usage statistics */
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        reasoning_tokens: number;
+        total_tokens: number;
+    };
+}
+/**
+ * Grok-MCP project configuration type
+ */
+export interface GrokMCPConfig {
+    /** xAI API key */
+    apiKey: string;
+    /** API base URL */
+    baseURL: string;
+    /** Default model */
+    model: string;
+    /** Debug mode */
+    debug?: boolean;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/types/index.js

@@ -0,0 +1,7 @@
+/**
+ * Grok-MCP TypeScript Type Definitions
+ *
+ * Defines all types for xAI API, MCP tools, and project configuration
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/utils/grok-client.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Grok API Client
+ *
+ * Uses native fetch to call xAI Responses API
+ * Native fetch (undici) automatically reads HTTPS_PROXY env var, no extra proxy config needed
+ */
+import type { XAIResponsesRequest, XAIResponsesResponse } from '../types/index.js';
+/**
+ * Call xAI Responses API
+ *
+ * @param request - API request parameters
+ * @returns API response
+ */
+export declare function createResponse(request: Omit<XAIResponsesRequest, 'stream'>): Promise<XAIResponsesResponse>;
+/**
+ * Extract text content from response
+ *
+ * @param response - API response
+ * @returns Text content
+ */
+export declare function extractContent(response: XAIResponsesResponse): string;
+/**
+ * Extract citation URLs from text
+ *
+ * xAI citation format: [[1]](https://example.com)
+ *
+ * @param text - Text containing citations
+ * @returns Deduplicated citation URL array
+ */
+export declare function extractCitations(text: string): string[];
+/**
+ * Extract token usage statistics
+ *
+ * @param response - API response
+ * @returns Token usage statistics object
+ */
+export declare function extractUsage(response: XAIResponsesResponse): {
+    input_tokens: number;
+    output_tokens: number;
+    reasoning_tokens: number;
+    cached_tokens: number;
+    total_tokens: number;
+    web_search_calls: number;
+    x_search_calls: number;
+};
+/**
+ * Calculate API call cost
+ *
+ * @param response - API response
+ * @returns Cost in USD
+ */
+export declare function calculateCost(response: XAIResponsesResponse): number;
+//# sourceMappingURL=grok-client.d.ts.map

package/dist/utils/grok-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grok-client.d.ts","sourceRoot":"","sources":["../../src/utils/grok-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EAGrB,MAAM,mBAAmB,CAAC;AAO3B;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAC,GAC3C,OAAO,CAAC,oBAAoB,CAAC,CA2E/B;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAarE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAWvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,oBAAoB;;;;;;;;EAY1D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAKpE"}

package/dist/utils/grok-client.js

@@ -0,0 +1,147 @@
+/**
+ * Grok API Client
+ *
+ * Uses native fetch to call xAI Responses API
+ * Native fetch (undici) automatically reads HTTPS_PROXY env var, no extra proxy config needed
+ */
+import { xaiConfig, debugMode } from '../config/index.js';
+// ============================================================================
+// Core API Methods
+// ============================================================================
+/**
+ * Call xAI Responses API
+ *
+ * @param request - API request parameters
+ * @returns API response
+ */
+export async function createResponse(request) {
+    const url = `${xaiConfig.baseURL}/responses`;
+    const body = {
+        model: request.model,
+        input: request.messages,
+        stream: false,
+    };
+    if (request.temperature !== undefined) {
+        body.temperature = request.temperature;
+    }
+    if (request.server_side_tools) {
+        body.tools = request.server_side_tools;
+    }
+    if (debugMode) {
+        console.error('[Grok Client] Sending request:', JSON.stringify(body, null, 2));
+    }
+    // Retry logic: up to 3 attempts
+    let lastError = null;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), xaiConfig.timeout);
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${xaiConfig.apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!res.ok) {
+                const errorText = await res.text();
+                throw new Error(`API request failed (${res.status}): ${errorText}`);
+            }
+            const response = await res.json();
+            if (debugMode) {
+                console.error('[Grok Client] Received response:', JSON.stringify(response, null, 2));
+            }
+            return response;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // If timeout or network error, wait and retry
+            if (attempt < 2 && (lastError.name === 'AbortError' ||
+                lastError.message.includes('fetch failed') ||
+                lastError.message.includes('ECONNRESET'))) {
+                const delay = Math.pow(2, attempt) * 1000; // Exponential backoff: 1s, 2s
+                if (debugMode) {
+                    console.error(`[Grok Client] Retry attempt ${attempt + 1}, waiting ${delay}ms...`);
+                }
+                await new Promise(resolve => setTimeout(resolve, delay));
+                continue;
+            }
+            break;
+        }
+    }
+    console.error('[Grok Client] API call failed:', lastError);
+    throw lastError;
+}
+// ============================================================================
+// Helper Methods
+// ============================================================================
+/**
+ * Extract text content from response
+ *
+ * @param response - API response
+ * @returns Text content
+ */
+export function extractContent(response) {
+    // Output array may contain web_search_call, x_search_call, etc. — find the message type
+    const messageOutput = response.output?.find(item => item.type === 'message');
+    if (!messageOutput) {
+        throw new Error('Invalid response structure: missing message type output');
+    }
+    const content = messageOutput.content?.[0];
+    if (!content || content.type !== 'output_text') {
+        throw new Error('Invalid response structure: missing output_text type content');
+    }
+    return content.text;
+}
+/**
+ * Extract citation URLs from text
+ *
+ * xAI citation format: [[1]](https://example.com)
+ *
+ * @param text - Text containing citations
+ * @returns Deduplicated citation URL array
+ */
+export function extractCitations(text) {
+    const citationRegex = /\[\[(\d+)\]\]\((https?:\/\/[^\)]+)\)/g;
+    const citations = [];
+    let match;
+    while ((match = citationRegex.exec(text)) !== null) {
+        citations.push(match[2]); // Extract URL
+    }
+    // Deduplicate and return
+    return [...new Set(citations)];
+}
+/**
+ * Extract token usage statistics
+ *
+ * @param response - API response
+ * @returns Token usage statistics object
+ */
+export function extractUsage(response) {
+    const usage = response.usage;
+    return {
+        input_tokens: usage.input_tokens,
+        output_tokens: usage.output_tokens,
+        reasoning_tokens: usage.output_tokens_details?.reasoning_tokens || 0,
+        cached_tokens: usage.input_tokens_details?.cached_tokens || 0,
+        total_tokens: usage.total_tokens,
+        web_search_calls: usage.server_side_tool_usage_details?.web_search_calls || 0,
+        x_search_calls: usage.server_side_tool_usage_details?.x_search_calls || 0,
+    };
+}
+/**
+ * Calculate API call cost
+ *
+ * @param response - API response
+ * @returns Cost in USD
+ */
+export function calculateCost(response) {
+    const costInTicks = response.usage.cost_in_usd_ticks;
+    // 1 tick = 0.0000000001 USD
+    // i.e. 10,000,000,000 ticks = 1 USD
+    return costInTicks / 10_000_000_000;
+}
+//# sourceMappingURL=grok-client.js.map

package/dist/utils/grok-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grok-client.js","sourceRoot":"","sources":["../../src/utils/grok-client.ts"],"names":[],"mappings":"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"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Logger Module
+ *
+ * Provides a unified logging interface with different log levels
+ */
+/**
+ * Log levels
+ */
+export declare enum LogLevel {
+    DEBUG = "DEBUG",
+    INFO = "INFO",
+    WARN = "WARN",
+    ERROR = "ERROR"
+}
+/**
+ * Logger
+ */
+export declare const logger: {
+    /**
+     * Debug log (only outputs in DEBUG mode)
+     */
+    debug: (message: string, meta?: any) => void;
+    /**
+     * Info log
+     */
+    info: (message: string, meta?: any) => void;
+    /**
+     * Warning log
+     */
+    warn: (message: string, meta?: any) => void;
+    /**
+     * Error log
+     */
+    error: (message: string, error?: Error | any) => void;
+};
+/**
+ * Performance monitor
+ */
+export declare class PerformanceMonitor {
+    private startTime;
+    private label;
+    constructor(label: string);
+    /**
+     * End monitoring and log duration
+     */
+    end(meta?: any): number;
+}
+/**
+ * Create a performance monitor instance
+ */
+export declare function startPerformanceMonitor(label: string): PerformanceMonitor;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,oBAAY,QAAQ;IAClB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,IAAI,SAAS;IACb,KAAK,UAAU;CAChB;AASD;;GAEG;AACH,eAAO,MAAM,MAAM;IACjB;;OAEG;qBACc,MAAM,SAAS,GAAG;IASnC;;OAEG;oBACa,MAAM,SAAS,GAAG;IAOlC;;OAEG;oBACa,MAAM,SAAS,GAAG;IAOlC;;OAEG;qBACc,MAAM,UAAU,KAAK,GAAG,GAAG;CAU7C,CAAC;AAEF;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAS;gBAEV,KAAK,EAAE,MAAM;IAMzB;;OAEG;IACH,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,MAAM;CAKxB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAEzE"}

package/dist/utils/logger.js

@@ -0,0 +1,97 @@
+/**
+ * Logger Module
+ *
+ * Provides a unified logging interface with different log levels
+ */
+import { debugMode } from '../config/index.js';
+/**
+ * Log levels
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["DEBUG"] = "DEBUG";
+    LogLevel["INFO"] = "INFO";
+    LogLevel["WARN"] = "WARN";
+    LogLevel["ERROR"] = "ERROR";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Format timestamp
+ */
+function getTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * Logger
+ */
+export const logger = {
+    /**
+     * Debug log (only outputs in DEBUG mode)
+     */
+    debug: (message, meta) => {
+        if (debugMode) {
+            console.error(`[${LogLevel.DEBUG}] ${getTimestamp()} - ${message}`);
+            if (meta) {
+                console.error(JSON.stringify(meta, null, 2));
+            }
+        }
+    },
+    /**
+     * Info log
+     */
+    info: (message, meta) => {
+        console.error(`[${LogLevel.INFO}] ${getTimestamp()} - ${message}`);
+        if (meta) {
+            console.error(JSON.stringify(meta, null, 2));
+        }
+    },
+    /**
+     * Warning log
+     */
+    warn: (message, meta) => {
+        console.error(`[${LogLevel.WARN}] ${getTimestamp()} - ${message}`);
+        if (meta) {
+            console.error(JSON.stringify(meta, null, 2));
+        }
+    },
+    /**
+     * Error log
+     */
+    error: (message, error) => {
+        console.error(`[${LogLevel.ERROR}] ${getTimestamp()} - ${message}`);
+        if (error) {
+            if (error instanceof Error) {
+                console.error(error.stack || error.message);
+            }
+            else {
+                console.error(JSON.stringify(error, null, 2));
+            }
+        }
+    },
+};
+/**
+ * Performance monitor
+ */
+export class PerformanceMonitor {
+    startTime;
+    label;
+    constructor(label) {
+        this.label = label;
+        this.startTime = Date.now();
+        logger.debug(`[Perf] ${label} started`);
+    }
+    /**
+     * End monitoring and log duration
+     */
+    end(meta) {
+        const duration = Date.now() - this.startTime;
+        logger.debug(`[Perf] ${this.label} completed, duration: ${duration}ms`, meta);
+        return duration;
+    }
+}
+/**
+ * Create a performance monitor instance
+ */
+export function startPerformanceMonitor(label) {
+    return new PerformanceMonitor(label);
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/tool-builder.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Search Tool Builder
+ *
+ * Provides type-safe xAI search tool builder functions with parameter validation
+ */
+import type { XAIWebSearchTool, XAIXSearchTool } from '../types/index.js';
+/**
+ * Build Web Search tool configuration
+ *
+ * @param options - Web Search configuration options
+ * @returns Web Search tool object
+ * @throws If parameter validation fails
+ *
+ * @example
+ * ```typescript
+ * const tool = buildWebSearchTool({
+ *   allowedDomains: ['https://example.com'],
+ *   enableImageUnderstanding: true
+ * });
+ * ```
+ */
+export declare function buildWebSearchTool(options?: {
+    allowedDomains?: string[];
+    excludedDomains?: string[];
+    enableImageUnderstanding?: boolean;
+}): XAIWebSearchTool;
+/**
+ * Build X Search tool configuration
+ *
+ * @param options - X Search configuration options
+ * @returns X Search tool object
+ * @throws If parameter validation fails
+ *
+ * @example
+ * ```typescript
+ * const tool = buildXSearchTool({
+ *   fromDate: '2024-01-01T00:00:00Z',
+ *   toDate: '2024-12-31T23:59:59Z',
+ *   allowedXHandles: ['elonmusk', 'OpenAI'],
+ *   enableVideoUnderstanding: true
+ * });
+ * ```
+ */
+export declare function buildXSearchTool(options?: {
+    fromDate?: string;
+    toDate?: string;
+    allowedXHandles?: string[];
+    excludedXHandles?: string[];
+    enableImageUnderstanding?: boolean;
+    enableVideoUnderstanding?: boolean;
+}): XAIXSearchTool;
+/**
+ * Validate ISO8601 date format
+ *
+ * @param dateString - Date string
+ * @returns Whether the string is valid ISO8601 format
+ */
+export declare function isValidISO8601(dateString: string): boolean;
+/**
+ * Convert date to ISO8601 format
+ *
+ * @param date - Date object
+ * @returns ISO8601 formatted date string
+ */
+export declare function toISO8601(date: Date): string;
+//# sourceMappingURL=tool-builder.d.ts.map

package/dist/utils/tool-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-builder.d.ts","sourceRoot":"","sources":["../../src/utils/tool-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AA6D1E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE;IAC3C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC,GAAG,gBAAgB,CAwCnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC,GAAG,cAAc,CA+CjB;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAQ1D;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE5C"}