askgrokmcp 1.3.0 → 1.4.0

package/README.md

@@ -1,8 +1,14 @@
 # Grok MCP Server
 
+[![npm version](https://img.shields.io/npm/v/askgrokmcp)](https://www.npmjs.com/package/askgrokmcp)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that brings xAI's Grok API into [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as native tools.
 
-Ask Grok questions, generate images with Aurora, and explore available models — directly from your terminal.
+Ask Grok questions, generate images with Aurora, run multi-round consensus analysis, and explore available models — directly from your terminal.
+
+---
 
 ## Tools
 
@@ -11,12 +17,31 @@ Ask Grok questions, generate images with Aurora, and explore available models
 | `ask_grok` | Send a prompt to Grok with optional system prompt and sampling parameters |
 | `generate_image` | Generate images using Grok's Aurora model and save them locally |
 | `list_models` | List all xAI models available to your account |
+| `grok_consensus` | Run a full Consensus Validation Protocol (CVP) for deep, multi-round analysis |
+
+## Built-in Protocols
+
+### Consensus Validation Protocol (CVP)
+
+The `grok_consensus` tool implements a structured, multi-round analysis protocol. Instead of a single prompt-and-response, it runs 3-10 iterative rounds where Grok progressively deepens its analysis — challenging its own assumptions, evaluating evidence strength, and synthesizing a balanced conclusion.
+
+```
+> Run CVP on whether large language models can reason
+> Ask Grok to validate the claim that sleep deprivation affects decision-making — use 5 rounds
+> Consensus check with Grok on the future of nuclear energy
+```
+
+The entire protocol executes server-side in a single tool call. Each round builds on the full conversation history for genuine iterative refinement.
+
+**Default:** 3 rounds | **Max:** 10 rounds | [Full protocol documentation](protocols/consensus-validation.md)
+
+---
 
 ## Prerequisites
 
 - **Node.js** >= 18
 - **Claude Code** CLI installed
-- **xAI API key** -- get one at [console.x.ai](https://console.x.ai)
+- **xAI API key** — get one at [console.x.ai](https://console.x.ai)
 
 ## Setup
 
@@ -50,7 +75,7 @@ Replace `/path/to/askgrokmcp` with the actual path where you cloned the reposito
 
 ---
 
-Replace `your_api_key_here` with your xAI API key in either option. That's it -- the tools are now available in Claude Code.
+Replace `your_api_key_here` with your xAI API key in either option. That's it — the tools are now available in Claude Code.
 
 ## Usage
 
@@ -94,6 +119,13 @@ Once registered, you can use the tools naturally in Claude Code:
 
 When generating multiple images, files are automatically numbered (e.g., `logo-1.png`, `logo-2.png`, ...).
 
+### Run a consensus analysis
+
+```
+> run CVP on the effectiveness of carbon capture technology
+> ask grok to validate whether quantum computers will break RSA by 2030 — use 5 rounds
+```
+
 ### List available models
 
 ```
@@ -169,10 +201,9 @@ claude mcp add grok \
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `XAI_API_KEY` | *(required)* | Your xAI API key |
-| `GROK_CHAT_MODEL` | `grok-3-fast` | Default model for `ask_grok` |
+| `GROK_CHAT_MODEL` | `grok-3-fast` | Default model for `ask_grok` and `grok_consensus` |
 | `GROK_IMAGE_MODEL` | `grok-2-image` | Default model for `generate_image` |
 | `SAFE_WRITE_BASE_DIR` | `process.cwd()` | Base directory for image writes |
-| `MAX_PROMPT_LENGTH` | `128000` | Maximum prompt length in characters (fail-fast guard) |
 | `XAI_REQUEST_TIMEOUT_MS` | `30000` | Timeout per xAI API request in milliseconds |
 | `XAI_MAX_RETRIES` | `2` | Number of retries for transient errors (429/5xx/network/timeout) |
 | `XAI_RETRY_BASE_DELAY_MS` | `500` | Base delay for exponential retry backoff |
@@ -198,6 +229,17 @@ export LOG_REQUEST_PAYLOADS=true
 
 > **Important:** Logs are written to stderr (not stdout) so MCP protocol communication remains safe.
 
+## Project Structure
+
+```
+askgrokmcp/
+  grok-mcp.mjs          Server entry point, config, HTTP client
+  src/tools.js           Tool definitions and handler implementations
+  protocols/             Protocol documentation
+    consensus-validation.md
+  grok-mcp.test.mjs     Test suite
+```
+
 ## How it works
 
 This server implements the MCP protocol over stdio. When Claude Code starts, it launches the server as a subprocess and communicates with it via JSON-RPC over stdin/stdout. The server translates MCP tool calls into xAI API requests and returns the results.
@@ -208,6 +250,22 @@ flowchart LR
     B -- HTTPS --> C[xAI API]
 ```
 
+For the `grok_consensus` tool, the server manages a multi-round conversation loop with Grok internally, returning the complete analysis in a single response:
+
+```mermaid
+sequenceDiagram
+    participant C as Claude Code
+    participant S as grok-mcp
+    participant G as xAI API
+
+    C->>S: grok_consensus(topic, rounds)
+    loop Each round
+        S->>G: chat/completions (with full history)
+        G-->>S: Round analysis
+    end
+    S-->>C: Structured CVP results
+```
+
 ## License
 
 [MIT](LICENSE)

package/grok-mcp.mjs

@@ -4,11 +4,12 @@
  * Grok MCP Server
  *
  * A Model Context Protocol (MCP) server that exposes xAI's Grok API
- * as tools for AI assistants like Claude Code. Provides three capabilities:
+ * as tools for AI assistants like Claude Code. Provides four capabilities:
  *
- * - ask_grok:      Send prompts to Grok and receive text responses.
- * - generate_image: Generate images using Grok's Aurora model and save them locally.
- * - list_models:   List all models available to your xAI account.
+ * - ask_grok:        Send prompts to Grok and receive text responses.
+ * - generate_image:  Generate images using Grok's Aurora model and save them locally.
+ * - list_models:     List all models available to your xAI account.
+ * - grok_consensus:  Run a full Consensus Validation Protocol (CVP) with Grok.
  *
  * Model selection (highest priority wins):
  *   1. Per-call `model` argument
@@ -28,6 +29,7 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
+import { getToolDefinitions, createToolHandlers } from "./src/tools.js";
 
 // -- Configuration -----------------------------------------------------------
 
@@ -43,7 +45,7 @@ const FALLBACK_IMAGE_MODEL = "grok-2-image";
 
 /**
  * Active defaults. Env vars take top priority; otherwise resolved at startup
- * by probing the xAI /models endpoint (frontier → fallback).
+ * by probing the xAI /models endpoint (frontier -> fallback).
  */
 let CHAT_MODEL  = process.env.GROK_CHAT_MODEL  ?? FRONTIER_CHAT_MODEL;
 let IMAGE_MODEL = process.env.GROK_IMAGE_MODEL ?? FRONTIER_IMAGE_MODEL;
@@ -55,7 +57,7 @@ const MAX_RETRIES           = parseNonNegativeIntEnv("XAI_MAX_RETRIES",
 const RETRY_BASE_DELAY_MS   = parsePositiveIntEnv("XAI_RETRY_BASE_DELAY_MS",   500);
 const LOG_REQUESTS          = parseBooleanEnv("LOG_REQUESTS",          false);
 const LOG_REQUEST_PAYLOADS  = parseBooleanEnv("LOG_REQUEST_PAYLOADS",  false);
-const SERVER_VERSION        = "1.3.0";
+const SERVER_VERSION        = "1.4.0";
 
 const SAFE_WRITE_BASE_DIR = process.env.SAFE_WRITE_BASE_DIR;
 if (SAFE_WRITE_BASE_DIR && !isAbsolute(SAFE_WRITE_BASE_DIR)) {
@@ -71,128 +73,25 @@ if (!API_KEY && !__testing) {
   process.exit(1);
 }
 
-// -- Tool definitions --------------------------------------------------------
-
-const tools = [
-  {
-    name: "ask_grok",
-    description:
-      "Ask Grok a question and get a response. " +
-      `Default model: ${CHAT_MODEL}. ` +
-      "Supports system prompts and sampling parameters (temperature, max_tokens, top_p). " +
-      "Run list_models to see all available model options.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        prompt: {
-          type: "string",
-          description: "The question or prompt to send to Grok",
-        },
-        system_prompt: {
-          type: "string",
-          description:
-            "Optional system prompt to set Grok's behavior and persona for this request.",
-        },
-        model: {
-          type: "string",
-          description:
-            `Chat model to use for this request. Defaults to "${CHAT_MODEL}". ` +
-            "Use list_models to see available chat models.",
-        },
-        temperature: {
-          type: "number",
-          description:
-            "Sampling temperature (0-2). Lower values make output more deterministic. Default: model-dependent.",
-        },
-        max_tokens: {
-          type: "number",
-          description:
-            "Maximum number of tokens to generate in the response.",
-        },
-        top_p: {
-          type: "number",
-          description:
-            "Nucleus sampling: only consider tokens with cumulative probability up to this value (0-1).",
-        },
-      },
-      required: ["prompt"],
-    },
-  },
-  {
-    name: "generate_image",
-    description:
-      "Generate an image using Grok's Aurora image model and save it to a local file. " +
-      `Default model: ${IMAGE_MODEL}. ` +
-      "Use the optional 'model' parameter to use a different image model.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        prompt: {
-          type: "string",
-          description: "Text description of the image to generate",
-        },
-        file_path: {
-          type: "string",
-          description:
-            "Path where the image file should be saved. Relative paths resolve from cwd; " +
-            "absolute paths must be within SAFE_WRITE_BASE_DIR (or cwd if unset). Example: images/output.png",
-        },
-        n: {
-          type: "number",
-          description: "Number of image variations to generate (1-10, default 1)",
-        },
-        model: {
-          type: "string",
-          description:
-            `Image model to use for this request. Defaults to "${IMAGE_MODEL}". ` +
-            "Use list_models to see available image models.",
-        },
-      },
-      required: ["prompt", "file_path"],
-    },
-  },
-  {
-    name: "list_models",
-    description:
-      "List all xAI models available to your account, including their IDs and capabilities. " +
-      "Use this to discover which models you can pass to ask_grok or generate_image. " +
-      "You can also filter by type: 'chat' for language models or 'image' for image generation.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        filter: {
-          type: "string",
-          enum: ["all", "chat", "image"],
-          description:
-            "Filter models by capability. " +
-            "'chat' returns language/reasoning models, " +
-            "'image' returns image generation models, " +
-            "'all' returns everything (default).",
-        },
-      },
-      required: [],
-    },
-  },
-];
+// -- Shared mutable config ---------------------------------------------------
+// Handlers hold a reference to this object so they always see resolved values.
+
+const config = {
+  get chatModel()  { return CHAT_MODEL; },
+  get imageModel() { return IMAGE_MODEL; },
+  maxPromptLength:    MAX_PROMPT_LENGTH,
+  maxImageVariations: MAX_IMAGE_VARIATIONS,
+};
 
 // -- Helpers -----------------------------------------------------------------
 
 /**
  * Writes data to a file, enforcing that the destination is inside the
  * allowed base directory. Creates parent directories as needed.
- *
- * Base dir precedence:
- *   1. SAFE_WRITE_BASE_DIR env var (must be an absolute path)
- *   2. process.cwd() as the default fallback
- *
- * @param {string} dest - Resolved absolute destination path.
- * @param {Buffer|string} data - File contents to write.
- * @throws {Error} If dest resolves outside the allowed base.
  */
 async function safeWrite(dest, data) {
   const rel = relative(WRITE_BASE_DIR, dest);
 
-  // Starts with ".." → outside base; isAbsolute guards cross-drive (Windows)
   if (rel.startsWith("..") || isAbsolute(rel)) {
     throw new Error(
       `Path "${dest}" is outside the allowed write directory "${WRITE_BASE_DIR}". ` +
@@ -206,11 +105,6 @@ async function safeWrite(dest, data) {
 
 /**
  * Makes an authenticated POST request to the xAI API with retries.
- *
- * @param {string} endpoint - API path relative to the base URL (e.g. "/chat/completions").
- * @param {object} body     - JSON-serializable request body.
- * @returns {Promise<object>} Parsed JSON response.
- * @throws {Error} On non-2xx responses after retries.
  */
 async function xaiPost(endpoint, body) {
   return xaiRequest("POST", endpoint, body);
@@ -218,10 +112,6 @@ async function xaiPost(endpoint, body) {
 
 /**
  * Makes an authenticated GET request to the xAI API.
- *
- * @param {string} endpoint - API path relative to the base URL (e.g. "/models").
- * @returns {Promise<object>} Parsed JSON response.
- * @throws {Error} On non-2xx responses.
  */
 async function xaiGet(endpoint) {
   return xaiRequest("GET", endpoint, null);
@@ -229,11 +119,6 @@ async function xaiGet(endpoint) {
 
 /**
  * Core HTTP request handler for the xAI API with retry logic.
- *
- * @param {"GET"|"POST"} method - HTTP method.
- * @param {string} endpoint     - API path relative to the base URL.
- * @param {object|null} body    - JSON body (POST only; null for GET).
- * @returns {Promise<object>} Parsed JSON response.
  */
 async function xaiRequest(method, endpoint, body) {
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
@@ -343,11 +228,6 @@ async function xaiRequest(method, endpoint, body) {
 
 /**
  * Downloads a remote URL and returns its contents as a Buffer.
- * Uses the same timeout and retry strategy as xaiRequest().
- *
- * @param {string} url - The URL to download.
- * @returns {Promise<Buffer>} The downloaded file contents.
- * @throws {Error} On non-2xx responses after retries.
  */
 async function downloadBuffer(url) {
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
@@ -390,14 +270,6 @@ async function downloadBuffer(url) {
 
 /**
  * Builds a numbered file path for multi-image generation.
- * For a single image, returns the path unchanged.
- * For multiple images, inserts an index before the extension:
- *   /tmp/cat.png -> /tmp/cat-1.png, /tmp/cat-2.png, ...
- *
- * @param {string} basePath - The original file path.
- * @param {number} index    - Zero-based image index.
- * @param {number} total    - Total number of images being saved.
- * @returns {string} The resolved, possibly indexed, file path.
  */
 function buildFilePath(basePath, index, total) {
   const dest = resolve(basePath);
@@ -410,183 +282,17 @@ function buildFilePath(basePath, index, total) {
   return `${dest}-${index + 1}`;
 }
 
-// -- Tool handlers -----------------------------------------------------------
-
-/**
- * Sends a prompt to Grok's chat completion endpoint and returns the response.
- * Honors the optional per-call `model` argument.
- */
-async function handleAskGrok(args) {
-  if (!args || typeof args.prompt !== "string" || !args.prompt.trim()) {
-    throw new Error("Invalid arguments: 'prompt' must be a non-empty string");
-  }
-  if (args.prompt.length > MAX_PROMPT_LENGTH) {
-    throw new Error(
-      `Prompt too long: ${args.prompt.length} chars exceeds the ${MAX_PROMPT_LENGTH} char limit`,
-    );
-  }
-
-  const model = (typeof args.model === "string" && args.model.trim())
-    ? args.model.trim()
-    : CHAT_MODEL;
-
-  const messages = [];
-  if (typeof args.system_prompt === "string" && args.system_prompt.trim()) {
-    messages.push({ role: "system", content: args.system_prompt });
-  }
-  messages.push({ role: "user", content: args.prompt });
-
-  const requestBody = { model, messages };
-  if (typeof args.temperature === "number") requestBody.temperature = args.temperature;
-  if (typeof args.max_tokens === "number")  requestBody.max_tokens  = args.max_tokens;
-  if (typeof args.top_p === "number")       requestBody.top_p       = args.top_p;
-
-  const data = await xaiPost("/chat/completions", requestBody);
-
-  const messageContent = data?.choices?.[0]?.message?.content;
-  const text =
-    typeof messageContent === "string"
-      ? messageContent
-      : messageContent != null
-        ? JSON.stringify(messageContent)
-        : "No response";
-  return { content: [{ type: "text", text }] };
-}
-
-/**
- * Generates images via Grok's Aurora model, downloads them, and saves to disk.
- * Honors the optional per-call `model` argument.
- */
-async function handleGenerateImage(args) {
-  if (!args || typeof args.prompt !== "string" || !args.prompt.trim()) {
-    throw new Error("Invalid arguments: 'prompt' must be a non-empty string");
-  }
-  if (args.prompt.length > MAX_PROMPT_LENGTH) {
-    throw new Error(
-      `Prompt too long: ${args.prompt.length} chars exceeds the ${MAX_PROMPT_LENGTH} char limit`,
-    );
-  }
-  if (typeof args.file_path !== "string" || !args.file_path.trim()) {
-    throw new Error("Invalid arguments: 'file_path' must be a non-empty string");
-  }
-  if (args.n != null && (!Number.isInteger(args.n) || args.n < 1)) {
-    throw new Error("Invalid arguments: 'n' must be a positive integer");
-  }
-
-  const n = Math.min(Math.max(args.n ?? 1, 1), MAX_IMAGE_VARIATIONS);
-  const model = (typeof args.model === "string" && args.model.trim())
-    ? args.model.trim()
-    : IMAGE_MODEL;
-
-  const data = await xaiPost("/images/generations", {
-    model,
-    prompt: args.prompt,
-    n,
-  });
-
-  const images = Array.isArray(data?.data) ? data.data : [];
-  if (images.length === 0) {
-    throw new Error("xAI API did not return any images");
-  }
-
-  const saved = [];
-  for (let i = 0; i < images.length; i++) {
-    const imageUrl = images[i]?.url;
-    if (typeof imageUrl !== "string" || !imageUrl) {
-      throw new Error(`xAI API returned an invalid image URL at index ${i}`);
-    }
-
-    const buffer = await downloadBuffer(imageUrl);
-    const dest = buildFilePath(args.file_path, i, images.length);
-    await safeWrite(dest, buffer);
-    saved.push(dest);
-  }
-
-  return {
-    content: [
-      {
-        type: "text",
-        text: `Generated and saved ${saved.length} image(s):\n${saved.join("\n")}`,
-      },
-    ],
-  };
-}
-
-/**
- * Fetches available models from the xAI API and formats them for display.
- * Supports optional filtering by capability (chat or image).
- */
-async function handleListModels(args) {
-  const filter = args?.filter ?? "all";
-  if (!["all", "chat", "image"].includes(filter)) {
-    throw new Error("Invalid arguments: 'filter' must be 'all', 'chat', or 'image'");
-  }
-
-  const data = await xaiGet("/models");
-  const models = Array.isArray(data?.data) ? data.data : [];
-
-  if (models.length === 0) {
-    return { content: [{ type: "text", text: "No models returned by the xAI API." }] };
-  }
+// -- Tool handlers (created from src/tools.js) -------------------------------
 
-  // xAI model IDs contain hints about their capability:
-  // image generation models have "image" or "imagine" in the ID.
-  const isImageModel = (id) =>
-    /image|imagine|aurora/i.test(id);
-
-  const filtered = models.filter((m) => {
-    if (filter === "all") return true;
-    const isImg = isImageModel(m.id ?? "");
-    return filter === "image" ? isImg : !isImg;
-  });
-
-  if (filtered.length === 0) {
-    return {
-      content: [{
-        type: "text",
-        text: `No ${filter} models found. Try filter: "all" to see everything.`,
-      }],
-    };
-  }
-
-  // Sort: alphabetically, images last
-  filtered.sort((a, b) => {
-    const aImg = isImageModel(a.id ?? "");
-    const bImg = isImageModel(b.id ?? "");
-    if (aImg !== bImg) return aImg ? 1 : -1;
-    return (a.id ?? "").localeCompare(b.id ?? "");
-  });
-
-  const lines = [
-    `${filtered.length} model(s) available${filter !== "all" ? ` (filter: ${filter})` : ""}:`,
-    "",
-  ];
-
-  for (const m of filtered) {
-    const id = m.id ?? "unknown";
-    const type = isImageModel(id) ? "image" : "chat";
-    const isDefaultChat  = id === CHAT_MODEL;
-    const isDefaultImage = id === IMAGE_MODEL;
-    const defaultTag = isDefaultChat
-      ? " ← current default (chat)"
-      : isDefaultImage
-        ? " ← current default (image)"
-        : "";
-    lines.push(`  ${id}  [${type}]${defaultTag}`);
-  }
-
-  lines.push("");
-  lines.push(`To change the default: set GROK_CHAT_MODEL or GROK_IMAGE_MODEL env vars.`);
-  lines.push(`To use once: pass model="<id>" to ask_grok or generate_image.`);
-
-  return { content: [{ type: "text", text: lines.join("\n") }] };
-}
-
-const toolHandlers = {
-  ask_grok:       handleAskGrok,
-  generate_image: handleGenerateImage,
-  list_models:    handleListModels,
-};
+const toolHandlers = createToolHandlers({
+  xaiPost,
+  xaiGet,
+  safeWrite,
+  buildFilePath,
+  downloadBuffer,
+  resolve,
+  config,
+});
 
 // -- Model resolution --------------------------------------------------------
 
@@ -600,7 +306,6 @@ async function resolveDefaults() {
   const chatFromEnv  = !!process.env.GROK_CHAT_MODEL;
   const imageFromEnv = !!process.env.GROK_IMAGE_MODEL;
 
-  // Nothing to resolve if both were explicitly set.
   if (chatFromEnv && imageFromEnv) return;
 
   let availableIds;
@@ -609,7 +314,6 @@ async function resolveDefaults() {
     const models = Array.isArray(data?.data) ? data.data : [];
     availableIds = new Set(models.map((m) => m.id));
   } catch {
-    // If the models endpoint is unreachable, fall back to safe defaults.
     logEvent("resolve_defaults", { status: "models_fetch_failed", action: "using_fallbacks" });
     if (!chatFromEnv)  CHAT_MODEL  = FALLBACK_CHAT_MODEL;
     if (!imageFromEnv) IMAGE_MODEL = FALLBACK_IMAGE_MODEL;
@@ -661,7 +365,9 @@ if (!__testing) {
     { capabilities: { tools: {} } },
   );
 
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: getToolDefinitions({ chatModel: CHAT_MODEL, imageModel: IMAGE_MODEL }),
+  }));
 
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name } = request.params;
@@ -717,14 +423,20 @@ if (!__testing) {
 export {
   safeWrite,
   buildFilePath,
-  handleAskGrok,
-  handleGenerateImage,
-  handleListModels,
   toolHandlers,
   WRITE_BASE_DIR,
   MAX_PROMPT_LENGTH,
 };
 
+// Re-export individual handlers for backwards-compatible test access.
+const { ask_grok, generate_image, list_models, grok_consensus } = toolHandlers;
+export {
+  ask_grok    as handleAskGrok,
+  generate_image as handleGenerateImage,
+  list_models    as handleListModels,
+  grok_consensus as handleGrokConsensus,
+};
+
 // -- Utility functions -------------------------------------------------------
 
 function parseBooleanEnv(name, defaultValue) {
@@ -773,7 +485,6 @@ function isNetworkError(error) {
 }
 
 function backoffDelay(attempt) {
-  // Exponential backoff: base, 2×base, 4×base, …
   return RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
 }
 
@@ -790,6 +501,9 @@ function summarizeArguments(args) {
   if (typeof summary.prompt === "string") {
     summary.prompt = `[redacted:${summary.prompt.length} chars]`;
   }
+  if (typeof summary.topic === "string") {
+    summary.topic = `[redacted:${summary.topic.length} chars]`;
+  }
   return summary;
 }
 
@@ -799,6 +513,5 @@ function logEvent(event, fields) {
     event,
     ...fields,
   };
-  // MCP uses stdout for protocol; logs must go to stderr.
   console.error(JSON.stringify(payload));
 }

package/grok-mcp.test.mjs

@@ -13,6 +13,7 @@ const {
   handleAskGrok,
   handleGenerateImage,
   handleListModels,
+  handleGrokConsensus,
   toolHandlers,
   WRITE_BASE_DIR,
   MAX_PROMPT_LENGTH,
@@ -179,6 +180,42 @@ describe("handleListModels input validation", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// handleGrokConsensus — input validation
+// ---------------------------------------------------------------------------
+
+describe("handleGrokConsensus input validation", () => {
+  it("rejects missing topic", async () => {
+    await assert.rejects(() => handleGrokConsensus({}), {
+      message: /topic.*must be a non-empty string/,
+    });
+  });
+
+  it("rejects empty topic", async () => {
+    await assert.rejects(() => handleGrokConsensus({ topic: "   " }), {
+      message: /topic.*must be a non-empty string/,
+    });
+  });
+
+  it("rejects invalid rounds value", async () => {
+    await assert.rejects(() => handleGrokConsensus({ topic: "test", rounds: 0 }), {
+      message: /rounds.*must be an integer/,
+    });
+  });
+
+  it("rejects rounds exceeding maximum", async () => {
+    await assert.rejects(() => handleGrokConsensus({ topic: "test", rounds: 11 }), {
+      message: /rounds.*must be an integer/,
+    });
+  });
+
+  it("rejects non-integer rounds", async () => {
+    await assert.rejects(() => handleGrokConsensus({ topic: "test", rounds: 2.5 }), {
+      message: /rounds.*must be an integer/,
+    });
+  });
+});
+
 // ---------------------------------------------------------------------------
 // toolHandlers — routing
 // ---------------------------------------------------------------------------
@@ -196,8 +233,12 @@ describe("toolHandlers", () => {
     assert.equal(typeof toolHandlers.list_models, "function");
   });
 
-  it("has exactly 3 handlers", () => {
-    assert.equal(Object.keys(toolHandlers).length, 3);
+  it("maps grok_consensus to a function", () => {
+    assert.equal(typeof toolHandlers.grok_consensus, "function");
+  });
+
+  it("has exactly 4 handlers", () => {
+    assert.equal(Object.keys(toolHandlers).length, 4);
   });
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askgrokmcp",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "MCP server that exposes xAI's Grok API as tools for Claude Code",
   "license": "MIT",
   "author": "Marcelo Ceccon",

package/protocols/consensus-validation.md

@@ -0,0 +1,105 @@
+# Consensus Validation Protocol (CVP) v1.4
+
+A structured, multi-round analysis protocol powered by the `grok_consensus` MCP tool. CVP enables Claude to leverage Grok as an independent analytical counterpart for deep, iterative reasoning on any topic.
+
+## Overview
+
+The Consensus Validation Protocol runs multiple rounds of progressively deeper analysis through Grok's language model. Each round builds on the full conversation history, ensuring coherent, non-repetitive refinement. The heavy lifting is performed server-side by the `grok_consensus` tool for efficiency — Claude only needs to make a single tool call.
+
+## Activation Triggers
+
+This protocol activates when the user says any of the following (or close variants):
+
+- **"Ask Grok"** — followed by a topic or claim
+- **"Ask Grok to validate..."**
+- **"Run CVP on..."**
+- **"Consensus check with Grok"**
+- **"Validate this with Grok"**
+
+### Examples
+
+```
+Ask Grok to validate whether intermittent fasting improves longevity
+Run CVP on the claim that remote work reduces productivity
+Consensus check with Grok on quantum computing timelines
+Run CVP on climate change mitigation strategies for 5 rounds
+```
+
+## How It Works
+
+### 1. Claude calls `grok_consensus` once
+
+When a CVP trigger is detected, Claude invokes the `grok_consensus` tool with:
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `topic` | string | Yes | The topic, claim, or question to analyze |
+| `rounds` | number | No | Number of rounds (default: 3, max: 10) |
+
+### 2. The tool runs the protocol server-side
+
+The `grok_consensus` tool internally executes the full multi-round protocol:
+
+- **Round 1 — Initial Analysis:** Grok provides a comprehensive, objective analysis of the topic covering key claims, evidence, uncertainties, and misconceptions.
+- **Round 2 — Counterarguments:** Grok challenges its own analysis, identifying the strongest counterarguments and alternative viewpoints.
+- **Round 3 — Evidence Assessment:** Grok evaluates the strength of evidence on all sides, distinguishing well-established facts from contested claims.
+- **Round 4 — Synthesis:** Grok integrates all rounds into a balanced conclusion with confidence levels.
+- **Round 5+ — Refinement:** Additional rounds deepen the analysis with new perspectives and edge cases.
+
+Conversation history is maintained properly across rounds — each round sees the full prior context, enabling genuine iterative refinement rather than redundant restating.
+
+### 3. Claude receives structured results
+
+The tool returns a structured Markdown report with all round-by-round analysis, which Claude can then summarize, quote, or present directly to the user.
+
+## Custom Round Count
+
+Users can request a specific number of rounds:
+
+```
+Run CVP on AI safety concerns for 7 rounds
+Ask Grok to validate this claim — use 5 rounds
+```
+
+- **Default:** 3 rounds (good balance of depth and speed)
+- **Minimum:** 1 round (quick single-pass analysis)
+- **Maximum:** 10 rounds (exhaustive deep-dive)
+
+Higher round counts yield more thorough analysis at the cost of additional latency, since each round is a separate API call to Grok.
+
+## Output Format
+
+The tool returns results in this structure:
+
+```markdown
+## Consensus Validation Protocol — Results
+
+| Field | Value |
+|-------|-------|
+| **Topic** | {topic} |
+| **Rounds completed** | {n} |
+| **Model** | {model} |
+
+### Round 1
+{Initial analysis content}
+
+### Round 2
+{Counterarguments and critique}
+
+### Round 3
+{Evidence assessment and final synthesis}
+```
+
+## Design Principles
+
+- **Concise and factual.** Each round advances the analysis — no filler or repetition.
+- **Collaborative tone.** Grok acts as an analytical partner, not an adversary.
+- **Evidence-based.** Claims are grounded in reasoning and evidence, with uncertainty explicitly acknowledged.
+- **Server-side efficiency.** The entire loop runs within a single MCP tool call, minimizing round-trips between Claude and the server.
+
+## Version History
+
+| Version | Changes |
+|---------|---------|
+| 1.4 | Protocol moved server-side into `grok_consensus` tool. Single tool call replaces client-side loop. |
+| 1.3 | Initial CVP as a Claude Code skill with client-side loop management. |

package/src/tools.js

@@ -0,0 +1,468 @@
+/**
+ * Tool definitions and handlers for the Grok MCP Server.
+ *
+ * This module owns all MCP tool schemas and their implementation.
+ * The main server module provides the HTTP client and configuration.
+ */
+
+// -- Consensus Validation Protocol -------------------------------------------
+
+const CVP_SYSTEM_PROMPT =
+  "You are participating in a Consensus Validation Protocol (CVP). " +
+  "Your role is to provide rigorous, evidence-based analysis through multiple rounds " +
+  "of iterative refinement. Be thorough but concise. Avoid repetition — each round " +
+  "must meaningfully advance the analysis. Stay objective and acknowledge uncertainty.";
+
+/**
+ * Returns the user prompt for a given CVP round.
+ *
+ * @param {string} topic  - The topic under analysis.
+ * @param {number} round  - Current round (1-based).
+ * @param {number} total  - Total number of rounds.
+ * @returns {string}
+ */
+function cvpRoundPrompt(topic, round, total) {
+  if (round === 1) {
+    return (
+      `Round ${round}/${total} — Initial Analysis\n\n` +
+      `Analyze the following topic thoroughly and objectively. Identify the key claims, ` +
+      `supporting evidence, areas of genuine uncertainty, and any common misconceptions.\n\n` +
+      `Topic: ${topic}`
+    );
+  }
+  if (round === total) {
+    return (
+      `Round ${round}/${total} — Final Synthesis\n\n` +
+      `Synthesize your full multi-round analysis into a coherent, balanced conclusion. ` +
+      `Clearly state: (1) points of strong consensus, (2) remaining uncertainties, and ` +
+      `(3) your confidence level for each major conclusion. Be definitive where the evidence supports it.`
+    );
+  }
+
+  // Intermediate rounds cycle through deepening strategies
+  const strategies = [
+    `Round ${round}/${total} — Counterarguments & Critique\n\n` +
+      `Critically examine your previous analysis. What are the strongest counterarguments? ` +
+      `Where might you be wrong or overconfident? What evidence supports alternative viewpoints?`,
+    `Round ${round}/${total} — Evidence Assessment\n\n` +
+      `Assess the quality and strength of evidence on all sides. Distinguish between what is ` +
+      `well-established, what is probable, and what remains genuinely uncertain or contested.`,
+    `Round ${round}/${total} — Perspectives & Edge Cases\n\n` +
+      `Consider perspectives you have not yet explored. What would domain experts disagree on? ` +
+      `Are there edge cases, regional differences, or temporal factors that affect the analysis?`,
+  ];
+  return strategies[(round - 2) % strategies.length];
+}
+
+/**
+ * Formats the final CVP output as structured Markdown.
+ */
+function formatConsensusResult(topic, rounds, roundResults, model) {
+  const lines = [
+    `## Consensus Validation Protocol — Results`,
+    ``,
+    `| Field | Value |`,
+    `|-------|-------|`,
+    `| **Topic** | ${topic} |`,
+    `| **Rounds completed** | ${rounds} |`,
+    `| **Model** | ${model} |`,
+    ``,
+  ];
+
+  for (const r of roundResults) {
+    lines.push(`### Round ${r.round}`);
+    lines.push(``);
+    lines.push(r.content);
+    lines.push(``);
+  }
+
+  return lines.join("\n");
+}
+
+// -- Tool definitions --------------------------------------------------------
+
+/**
+ * Returns the MCP tool schema array. Called on each ListTools request
+ * so descriptions always reflect the current resolved model names.
+ *
+ * @param {{ chatModel: string, imageModel: string }} config
+ * @returns {Array<object>}
+ */
+export function getToolDefinitions({ chatModel, imageModel }) {
+  return [
+    {
+      name: "ask_grok",
+      description:
+        "Ask Grok a question and get a response. " +
+        `Default model: ${chatModel}. ` +
+        "Supports system prompts and sampling parameters (temperature, max_tokens, top_p). " +
+        "Run list_models to see all available model options.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          prompt: {
+            type: "string",
+            description: "The question or prompt to send to Grok",
+          },
+          system_prompt: {
+            type: "string",
+            description:
+              "Optional system prompt to set Grok's behavior and persona for this request.",
+          },
+          model: {
+            type: "string",
+            description:
+              `Chat model to use for this request. Defaults to "${chatModel}". ` +
+              "Use list_models to see available chat models.",
+          },
+          temperature: {
+            type: "number",
+            description:
+              "Sampling temperature (0-2). Lower values make output more deterministic. Default: model-dependent.",
+          },
+          max_tokens: {
+            type: "number",
+            description:
+              "Maximum number of tokens to generate in the response.",
+          },
+          top_p: {
+            type: "number",
+            description:
+              "Nucleus sampling: only consider tokens with cumulative probability up to this value (0-1).",
+          },
+        },
+        required: ["prompt"],
+      },
+    },
+    {
+      name: "generate_image",
+      description:
+        "Generate an image using Grok's Aurora image model and save it to a local file. " +
+        `Default model: ${imageModel}. ` +
+        "Use the optional 'model' parameter to use a different image model.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          prompt: {
+            type: "string",
+            description: "Text description of the image to generate",
+          },
+          file_path: {
+            type: "string",
+            description:
+              "Path where the image file should be saved. Relative paths resolve from cwd; " +
+              "absolute paths must be within SAFE_WRITE_BASE_DIR (or cwd if unset). Example: images/output.png",
+          },
+          n: {
+            type: "number",
+            description: "Number of image variations to generate (1-10, default 1)",
+          },
+          model: {
+            type: "string",
+            description:
+              `Image model to use for this request. Defaults to "${imageModel}". ` +
+              "Use list_models to see available image models.",
+          },
+        },
+        required: ["prompt", "file_path"],
+      },
+    },
+    {
+      name: "list_models",
+      description:
+        "List all xAI models available to your account, including their IDs and capabilities. " +
+        "Use this to discover which models you can pass to ask_grok or generate_image. " +
+        "You can also filter by type: 'chat' for language models or 'image' for image generation.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          filter: {
+            type: "string",
+            enum: ["all", "chat", "image"],
+            description:
+              "Filter models by capability. " +
+              "'chat' returns language/reasoning models, " +
+              "'image' returns image generation models, " +
+              "'all' returns everything (default).",
+          },
+        },
+        required: [],
+      },
+    },
+    {
+      name: "grok_consensus",
+      description:
+        "Runs a full iterative Consensus Validation Protocol (CVP) between Claude and Grok. " +
+        "Returns a structured final summary. Default 3-5 rounds. " +
+        "Supports custom round count via the 'rounds' argument.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          topic: {
+            type: "string",
+            description:
+              "The topic, claim, or question to analyze through the consensus protocol.",
+          },
+          rounds: {
+            type: "number",
+            description:
+              "Number of analysis rounds to run. Omit for the default (3 rounds). " +
+              "Higher values (up to 10) yield deeper analysis at the cost of latency.",
+          },
+        },
+        required: ["topic"],
+      },
+    },
+  ];
+}
+
+// -- Tool handlers -----------------------------------------------------------
+
+/**
+ * Creates tool handler functions bound to the provided server context.
+ *
+ * @param {object} ctx
+ * @param {Function} ctx.xaiPost  - Authenticated POST to xAI API.
+ * @param {Function} ctx.xaiGet   - Authenticated GET from xAI API.
+ * @param {Function} ctx.safeWrite - Safe file writer.
+ * @param {Function} ctx.buildFilePath - Multi-image path builder.
+ * @param {Function} ctx.downloadBuffer - URL downloader.
+ * @param {Function} ctx.resolve - path.resolve.
+ * @param {object}   ctx.config  - Mutable config object with chatModel, imageModel, etc.
+ * @returns {Record<string, Function>}
+ */
+export function createToolHandlers(ctx) {
+  const {
+    xaiPost,
+    xaiGet,
+    safeWrite,
+    buildFilePath,
+    downloadBuffer,
+    resolve,
+    config,
+  } = ctx;
+
+  // -- ask_grok --------------------------------------------------------------
+
+  async function handleAskGrok(args) {
+    if (!args || typeof args.prompt !== "string" || !args.prompt.trim()) {
+      throw new Error("Invalid arguments: 'prompt' must be a non-empty string");
+    }
+    if (args.prompt.length > config.maxPromptLength) {
+      throw new Error(
+        `Prompt too long: ${args.prompt.length} chars exceeds the ${config.maxPromptLength} char limit`,
+      );
+    }
+
+    const model =
+      typeof args.model === "string" && args.model.trim()
+        ? args.model.trim()
+        : config.chatModel;
+
+    const messages = [];
+    if (typeof args.system_prompt === "string" && args.system_prompt.trim()) {
+      messages.push({ role: "system", content: args.system_prompt });
+    }
+    messages.push({ role: "user", content: args.prompt });
+
+    const requestBody = { model, messages };
+    if (typeof args.temperature === "number") requestBody.temperature = args.temperature;
+    if (typeof args.max_tokens === "number") requestBody.max_tokens = args.max_tokens;
+    if (typeof args.top_p === "number") requestBody.top_p = args.top_p;
+
+    const data = await xaiPost("/chat/completions", requestBody);
+
+    const messageContent = data?.choices?.[0]?.message?.content;
+    const text =
+      typeof messageContent === "string"
+        ? messageContent
+        : messageContent != null
+          ? JSON.stringify(messageContent)
+          : "No response";
+    return { content: [{ type: "text", text }] };
+  }
+
+  // -- generate_image --------------------------------------------------------
+
+  async function handleGenerateImage(args) {
+    if (!args || typeof args.prompt !== "string" || !args.prompt.trim()) {
+      throw new Error("Invalid arguments: 'prompt' must be a non-empty string");
+    }
+    if (args.prompt.length > config.maxPromptLength) {
+      throw new Error(
+        `Prompt too long: ${args.prompt.length} chars exceeds the ${config.maxPromptLength} char limit`,
+      );
+    }
+    if (typeof args.file_path !== "string" || !args.file_path.trim()) {
+      throw new Error("Invalid arguments: 'file_path' must be a non-empty string");
+    }
+    if (args.n != null && (!Number.isInteger(args.n) || args.n < 1)) {
+      throw new Error("Invalid arguments: 'n' must be a positive integer");
+    }
+
+    const n = Math.min(Math.max(args.n ?? 1, 1), config.maxImageVariations);
+    const model =
+      typeof args.model === "string" && args.model.trim()
+        ? args.model.trim()
+        : config.imageModel;
+
+    const data = await xaiPost("/images/generations", {
+      model,
+      prompt: args.prompt,
+      n,
+    });
+
+    const images = Array.isArray(data?.data) ? data.data : [];
+    if (images.length === 0) {
+      throw new Error("xAI API did not return any images");
+    }
+
+    const saved = [];
+    for (let i = 0; i < images.length; i++) {
+      const imageUrl = images[i]?.url;
+      if (typeof imageUrl !== "string" || !imageUrl) {
+        throw new Error(`xAI API returned an invalid image URL at index ${i}`);
+      }
+
+      const buffer = await downloadBuffer(imageUrl);
+      const dest = buildFilePath(args.file_path, i, images.length);
+      await safeWrite(dest, buffer);
+      saved.push(dest);
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Generated and saved ${saved.length} image(s):\n${saved.join("\n")}`,
+        },
+      ],
+    };
+  }
+
+  // -- list_models -----------------------------------------------------------
+
+  async function handleListModels(args) {
+    const filter = args?.filter ?? "all";
+    if (!["all", "chat", "image"].includes(filter)) {
+      throw new Error("Invalid arguments: 'filter' must be 'all', 'chat', or 'image'");
+    }
+
+    const data = await xaiGet("/models");
+    const models = Array.isArray(data?.data) ? data.data : [];
+
+    if (models.length === 0) {
+      return { content: [{ type: "text", text: "No models returned by the xAI API." }] };
+    }
+
+    const isImageModel = (id) => /image|imagine|aurora/i.test(id);
+
+    const filtered = models.filter((m) => {
+      if (filter === "all") return true;
+      const isImg = isImageModel(m.id ?? "");
+      return filter === "image" ? isImg : !isImg;
+    });
+
+    if (filtered.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No ${filter} models found. Try filter: "all" to see everything.`,
+          },
+        ],
+      };
+    }
+
+    filtered.sort((a, b) => {
+      const aImg = isImageModel(a.id ?? "");
+      const bImg = isImageModel(b.id ?? "");
+      if (aImg !== bImg) return aImg ? 1 : -1;
+      return (a.id ?? "").localeCompare(b.id ?? "");
+    });
+
+    const lines = [
+      `${filtered.length} model(s) available${filter !== "all" ? ` (filter: ${filter})` : ""}:`,
+      "",
+    ];
+
+    for (const m of filtered) {
+      const id = m.id ?? "unknown";
+      const type = isImageModel(id) ? "image" : "chat";
+      const isDefaultChat = id === config.chatModel;
+      const isDefaultImage = id === config.imageModel;
+      const defaultTag = isDefaultChat
+        ? " <- current default (chat)"
+        : isDefaultImage
+          ? " <- current default (image)"
+          : "";
+      lines.push(`  ${id}  [${type}]${defaultTag}`);
+    }
+
+    lines.push("");
+    lines.push(`To change the default: set GROK_CHAT_MODEL or GROK_IMAGE_MODEL env vars.`);
+    lines.push(`To use once: pass model="<id>" to ask_grok or generate_image.`);
+
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+
+  // -- grok_consensus --------------------------------------------------------
+
+  const CVP_DEFAULT_ROUNDS = 3;
+  const CVP_MAX_ROUNDS = 10;
+
+  async function handleGrokConsensus(args) {
+    if (!args || typeof args.topic !== "string" || !args.topic.trim()) {
+      throw new Error("Invalid arguments: 'topic' must be a non-empty string");
+    }
+    if (args.topic.length > config.maxPromptLength) {
+      throw new Error(
+        `Topic too long: ${args.topic.length} chars exceeds the ${config.maxPromptLength} char limit`,
+      );
+    }
+    if (
+      args.rounds != null &&
+      (!Number.isInteger(args.rounds) || args.rounds < 1 || args.rounds > CVP_MAX_ROUNDS)
+    ) {
+      throw new Error(
+        `Invalid arguments: 'rounds' must be an integer between 1 and ${CVP_MAX_ROUNDS}`,
+      );
+    }
+
+    const topic = args.topic.trim();
+    const numRounds = args.rounds ?? CVP_DEFAULT_ROUNDS;
+    const model = config.chatModel;
+
+    // Build conversation incrementally — Grok sees the full history each round.
+    const messages = [{ role: "system", content: CVP_SYSTEM_PROMPT }];
+
+    const roundResults = [];
+
+    for (let round = 1; round <= numRounds; round++) {
+      const userPrompt = cvpRoundPrompt(topic, round, numRounds);
+      messages.push({ role: "user", content: userPrompt });
+
+      const data = await xaiPost("/chat/completions", {
+        model,
+        messages,
+        temperature: 0.7,
+      });
+
+      const content = data?.choices?.[0]?.message?.content ?? "No response";
+      messages.push({ role: "assistant", content });
+      roundResults.push({ round, content });
+    }
+
+    const text = formatConsensusResult(topic, numRounds, roundResults, model);
+    return { content: [{ type: "text", text }] };
+  }
+
+  // -- Handler map -----------------------------------------------------------
+
+  return {
+    ask_grok: handleAskGrok,
+    generate_image: handleGenerateImage,
+    list_models: handleListModels,
+    grok_consensus: handleGrokConsensus,
+  };
+}