@lkbaba/grok-mcp 1.0.0

package/dist/utils/tool-builder.js

@@ -0,0 +1,187 @@
+/**
+ * Search Tool Builder
+ *
+ * Provides type-safe xAI search tool builder functions with parameter validation
+ */
+import { z } from 'zod';
+// ============================================================================
+// Parameter Validation Schemas
+// ============================================================================
+/**
+ * Web Search tool parameter validation schema
+ */
+const webSearchOptionsSchema = z.object({
+    allowedDomains: z
+        .array(z.string().min(1, 'Domain cannot be empty').regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*\.[a-zA-Z]{2,}$/, 'Invalid domain format, e.g.: github.com, stackoverflow.com'))
+        .max(5, 'Maximum of 5 allowed domains')
+        .optional(),
+    excludedDomains: z
+        .array(z.string().min(1, 'Domain cannot be empty').regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*\.[a-zA-Z]{2,}$/, 'Invalid domain format, e.g.: github.com, stackoverflow.com'))
+        .max(5, 'Maximum of 5 excluded domains')
+        .optional(),
+    enableImageUnderstanding: z.boolean().optional(),
+});
+/**
+ * X Search tool parameter validation schema
+ */
+const xSearchOptionsSchema = z.object({
+    fromDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/, 'Date must be in ISO8601 format (e.g.: 2024-01-01T00:00:00Z)')
+        .optional(),
+    toDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/, 'Date must be in ISO8601 format (e.g.: 2024-01-01T00:00:00Z)')
+        .optional(),
+    allowedXHandles: z
+        .array(z.string().min(1, 'X handle cannot be empty'))
+        .max(10, 'Maximum of 10 allowed X handles')
+        .optional(),
+    excludedXHandles: z
+        .array(z.string().min(1, 'X handle cannot be empty'))
+        .max(10, 'Maximum of 10 excluded X handles')
+        .optional(),
+    enableImageUnderstanding: z.boolean().optional(),
+    enableVideoUnderstanding: z.boolean().optional(),
+});
+// ============================================================================
+// Tool Builder Functions
+// ============================================================================
+/**
+ * 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 function buildWebSearchTool(options) {
+    // Parameter validation
+    if (options) {
+        try {
+            webSearchOptionsSchema.parse(options);
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                const messages = error.errors.map((err) => `  - ${err.path.join('.')}: ${err.message}`);
+                throw new Error(`Web Search tool parameter validation failed:\n${messages.join('\n')}`);
+            }
+            throw error;
+        }
+    }
+    // Build tool object
+    const tool = {
+        type: 'web_search',
+    };
+    // Add optional parameters
+    if (options?.enableImageUnderstanding !== undefined) {
+        tool.enable_image_understanding = options.enableImageUnderstanding;
+    }
+    // Add filters
+    if (options?.allowedDomains || options?.excludedDomains) {
+        tool.filters = {};
+        if (options.allowedDomains) {
+            tool.filters.allowed_domains = options.allowedDomains;
+        }
+        if (options.excludedDomains) {
+            tool.filters.excluded_domains = options.excludedDomains;
+        }
+    }
+    return tool;
+}
+/**
+ * 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 function buildXSearchTool(options) {
+    // Parameter validation
+    if (options) {
+        try {
+            xSearchOptionsSchema.parse(options);
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                const messages = error.errors.map((err) => `  - ${err.path.join('.')}: ${err.message}`);
+                throw new Error(`X Search tool parameter validation failed:\n${messages.join('\n')}`);
+            }
+            throw error;
+        }
+        // Date logic validation
+        if (options.fromDate && options.toDate) {
+            const from = new Date(options.fromDate);
+            const to = new Date(options.toDate);
+            if (from > to) {
+                throw new Error('fromDate cannot be later than toDate');
+            }
+        }
+    }
+    // Build tool object
+    const tool = {
+        type: 'x_search',
+    };
+    // Add optional parameters
+    if (options?.fromDate)
+        tool.from_date = options.fromDate;
+    if (options?.toDate)
+        tool.to_date = options.toDate;
+    if (options?.enableImageUnderstanding !== undefined) {
+        tool.enable_image_understanding = options.enableImageUnderstanding;
+    }
+    if (options?.enableVideoUnderstanding !== undefined) {
+        tool.enable_video_understanding = options.enableVideoUnderstanding;
+    }
+    if (options?.allowedXHandles) {
+        tool.allowed_x_handles = options.allowedXHandles;
+    }
+    if (options?.excludedXHandles) {
+        tool.excluded_x_handles = options.excludedXHandles;
+    }
+    return tool;
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Validate ISO8601 date format
+ *
+ * @param dateString - Date string
+ * @returns Whether the string is valid ISO8601 format
+ */
+export function isValidISO8601(dateString) {
+    const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
+    if (!iso8601Regex.test(dateString)) {
+        return false;
+    }
+    const date = new Date(dateString);
+    return !isNaN(date.getTime());
+}
+/**
+ * Convert date to ISO8601 format
+ *
+ * @param date - Date object
+ * @returns ISO8601 formatted date string
+ */
+export function toISO8601(date) {
+    return date.toISOString();
+}
+//# sourceMappingURL=tool-builder.js.map

package/dist/utils/tool-builder.js.map

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

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@lkbaba/grok-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for xAI Grok with real-time Web + X (Twitter) search and creative brainstorming",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "grok-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "test:integration": "vitest tests/integration"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "grok",
+    "xai",
+    "search",
+    "x-search",
+    "twitter-search",
+    "brainstorm",
+    "ai",
+    "llm",
+    "claude-code",
+    "claude-desktop",
+    "typescript"
+  ],
+  "author": "LKbaba",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LKbaba/Grok-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/LKbaba/Grok-mcp/issues"
+  },
+  "homepage": "https://github.com/LKbaba/Grok-mcp#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "vitest": "^1.0.0",
+    "@vitest/ui": "^1.0.0"
+  }
+}