@pkwadsy/grok-mcp 1.1.0 → 1.2.0

package/README.md

@@ -2,21 +2,17 @@
 
 MCP server that wraps the xAI Grok API. Lets Claude and other AI agents delegate thinking, planning, and real-time search to Grok.
 
-## Setup
+## Quick Start
 
-```bash
-npm install -g @pkwadsy/grok-mcp
-```
-
-Or use directly with npx:
+One-liner to add to Claude Code on any device:
 
 ```bash
-npx @pkwadsy/grok-mcp
+claude mcp add grok -e XAI_API_KEY=your-key -- npx -y @pkwadsy/grok-mcp
 ```
 
 You need an xAI API key from [console.x.ai](https://console.x.ai).
 
-## Configure in Claude Code
+### Alternative: project config
 
 Add to your project's `.mcp.json`:
 
@@ -26,7 +22,7 @@ Add to your project's `.mcp.json`:
     "grok": {
       "type": "stdio",
       "command": "npx",
-      "args": ["@pkwadsy/grok-mcp"],
+      "args": ["-y", "@pkwadsy/grok-mcp"],
       "env": {
         "XAI_API_KEY": "your-xai-api-key"
       }
@@ -44,16 +40,17 @@ Single tool with options for different use cases.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `prompt` | string | yes | The question or task for Grok |
+| `files` | array | no | Files to include in context (path, optional start_line/end_line) |
 | `system_prompt` | string | no | Custom system prompt |
-| `model` | string | no | Model to use (default: `grok-4.20-reasoning`) |
-| `web_search` | boolean | no | Enable real-time web search |
+| `model` | string | no | Model to use (default: `grok-4.20-multi-agent`) |
+| `web_search` | boolean | no | Web search, enabled by default |
 | `x_search` | boolean | no | Enable X/Twitter search |
 
 ### Available Models
 
-- `grok-4.20-reasoning` — flagship reasoning (default)
+- `grok-4.20-multi-agent` — multi-agent mode, great for architecture and planning (default)
+- `grok-4.20-reasoning` — flagship reasoning
 - `grok-4.20-non-reasoning` — fast, no reasoning
-- `grok-4.20-multi-agent` — multi-agent mode, great for architecture and planning
 - `grok-4.1-fast-reasoning` — cheaper reasoning
 - `grok-4.1-fast-non-reasoning` — cheapest, fast
 

package/dist/index.js

@@ -1,8 +1,33 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { readFile } from "node:fs/promises";
+import { globSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { z } from "zod";
+function parseFileArg(arg) {
+    // "path/to/file:10-30" or "path/to/file:10" or "path/to/file" or "src/**/*.ts"
+    const match = arg.match(/^(.+?):(\d+)(?:-(\d+))?$/);
+    let pattern;
+    let startLine;
+    let endLine;
+    if (match) {
+        pattern = match[1];
+        startLine = parseInt(match[2], 10);
+        endLine = match[3] ? parseInt(match[3], 10) : startLine;
+    }
+    else {
+        pattern = arg;
+    }
+    const resolved = resolve(pattern);
+    if (/[*?[\]]/.test(pattern)) {
+        const paths = globSync(pattern).sort();
+        if (paths.length === 0) {
+            return [{ path: pattern }]; // will fail at read time with a clear error
+        }
+        return paths.map((p) => ({ path: resolve(p), startLine, endLine }));
+    }
+    return [{ path: resolved, startLine, endLine }];
+}
 const apiKey = process.env.XAI_API_KEY;
 if (!apiKey) {
     console.error("XAI_API_KEY environment variable is required");
@@ -48,13 +73,9 @@ async function callGrok(options) {
 server.tool("ask_grok", `Ask Grok a question. Grok is great for thinking, planning, architecture, and real-time search via web and X/Twitter. Use web_search for current information from the internet. Use x_search to find and analyze posts on X/Twitter. IMPORTANT: Grok has no context about your conversation or codebase. Always include all relevant context directly in the prompt — file contents, error messages, architecture details, constraints, and goals. The more context you provide, the better Grok's response will be. Do not assume Grok knows anything about the current project. Use the files parameter to automatically include file contents with line numbers — this is preferred over pasting code into the prompt. File paths are resolved relative to the server working directory: ${process.cwd()}`, {
     prompt: z.string().describe("The question or task for Grok. Include all relevant context — constraints, background, and goals — since Grok has no access to your conversation or files. Use the files parameter to attach source code rather than pasting it inline"),
     files: z
-        .array(z.object({
-        path: z.string().describe("Absolute path to the file"),
-        start_line: z.number().optional().describe("First line to include (1-based, inclusive)"),
-        end_line: z.number().optional().describe("Last line to include (1-based, inclusive)"),
-    }))
+        .array(z.string())
         .optional()
-        .describe("Files to read and include in the context sent to Grok. Each file is included with its path and line numbers. Use start_line/end_line to include only a specific range"),
+        .describe('Files to include in context. Compact syntax: "path/to/file" (whole file), "path/to/file:10-30" (lines 10-30), "path/to/file:10" (just line 10), "src/**/*.ts" (glob pattern). Paths resolve relative to server cwd. All files are sent to Grok with line numbers.'),
     system_prompt: z
         .string()
         .optional()
@@ -81,25 +102,46 @@ server.tool("ask_grok", `Ask Grok a question. Grok is great for thinking, planni
     if (files && files.length > 0) {
         const cwd = process.cwd();
         const fileBlocks = [`Working directory: ${cwd}\n`];
-        for (const file of files) {
+        const errors = [];
+        const specs = files.flatMap(parseFileArg);
+        for (const spec of specs) {
             try {
-                const raw = await readFile(file.path, "utf-8");
+                const raw = readFileSync(spec.path, "utf-8");
                 const allLines = raw.split("\n");
-                const start = file.start_line ? file.start_line - 1 : 0;
-                const end = file.end_line ? file.end_line : allLines.length;
+                const totalLines = allLines.length;
+                if (spec.startLine && spec.startLine > totalLines) {
+                    errors.push(`${spec.path}: line ${spec.startLine} is past end of file (${totalLines} lines)`);
+                    continue;
+                }
+                if (spec.endLine && spec.endLine > totalLines) {
+                    errors.push(`${spec.path}: line ${spec.endLine} is past end of file (${totalLines} lines)`);
+                    continue;
+                }
+                if (spec.startLine && spec.endLine && spec.startLine > spec.endLine) {
+                    errors.push(`${spec.path}: start line ${spec.startLine} is after end line ${spec.endLine}`);
+                    continue;
+                }
+                const start = spec.startLine ? spec.startLine - 1 : 0;
+                const end = spec.endLine ? spec.endLine : totalLines;
                 const sliced = allLines.slice(start, end);
                 const numbered = sliced
                     .map((line, i) => `${start + i + 1}\t${line}`)
                     .join("\n");
-                const range = file.start_line || file.end_line
-                    ? `:${file.start_line ?? 1}-${file.end_line ?? allLines.length}`
+                const range = spec.startLine || spec.endLine
+                    ? `:${spec.startLine ?? 1}-${spec.endLine ?? totalLines}`
                     : "";
-                fileBlocks.push(`--- ${file.path}${range} ---\n${numbered}\n---`);
+                fileBlocks.push(`--- ${spec.path}${range} ---\n${numbered}\n---`);
             }
             catch (err) {
-                fileBlocks.push(`--- ${file.path} --- ERROR: ${err instanceof Error ? err.message : String(err)} ---`);
+                errors.push(`${spec.path}: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
+        if (errors.length > 0) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Failed to read ${errors.length} file(s):\n${errors.join("\n")}\n\nFix the paths and try again.` }],
+            };
+        }
         userContent = `${fileBlocks.join("\n\n")}\n\n${prompt}`;
     }
     messages.push({ role: "user", content: userContent });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pkwadsy/grok-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP server that wraps the xAI Grok API — delegate thinking, planning, and search to Grok",
   "type": "module",
   "main": "dist/index.js",