consult-llm-mcp 1.0.3 → 1.0.5

package/README.md

@@ -1,15 +1,33 @@
 # Consult LLM MCP
 
-An MCP server that lets Claude Code consult stronger AI models (o3, Gemini 2.5 Pro, DeepSeek Reasoner) when you need deeper analysis on complex problems.
+An MCP server that lets Claude Code consult stronger AI models (o3, Gemini 2.5
+Pro, DeepSeek Reasoner) when you need deeper analysis on complex problems.
+
+```
+This SQL query is timing out on large datasets. Can you help optimize it? Ask Gemini
+
+⏺ I'll examine your query and consult Gemini for database optimization strategies.
+
+⏺ consult-llm:consult_llm (MCP)(prompt: "How can I optimize this slow SQL query
+                                for better performance on large datasets?", files: ["queries/user
+                                -analytics.sql","schema/tables.sql"], model: "gemini-2.5-pro")
+  ⎿ The query has significant performance bottlenecks: missing indexes on join
+    columns, inefficient subqueries that could be CTEs, and unnecessary DISTINCT
+    operations. Add composite indexes on (user_id, created_at), replace correlated
+    subqueries with window functions, and eliminate redundant GROUP BY clauses.
+    … +287 lines (ctrl+r to expand)
+
+⏺ Great insights! I'll add the suggested indexes, refactor the subqueries to use
+  CTEs with window functions, and optimize the GROUP BY operations.
+```
 
 ## Features
 
-- Query powerful AI models (o3, Gemini 2.5 Pro, DeepSeek Reasoner) with file
-  context
-- Automatic prompt construction from markdown and code files
-- Git diff to feed code changes
-- Usage tracking with cost estimation
-- Comprehensive logging
+- Query powerful AI models (o3, Gemini 2.5 Pro, DeepSeek Reasoner) with relevant
+  files as context
+- Direct queries with optional file context
+- Include git changes for code review and analysis
+- Comprehensive logging with cost estimation
 
 ## Configuration
 
@@ -35,9 +53,20 @@ Or for global availability:
 claude mcp add --scope user consult-llm -- npx -y consult-llm-mcp
 ```
 
+Optionally you can provide environment variables directly in the MCP
+configuration:
+
+```bash
+claude mcp add \
+  -e OPENAI_API_KEY=your_openai_key \
+  -e GEMINI_API_KEY=your_gemini_key \
+  -e DEEPSEEK_API_KEY=your_deepseek_key \
+    consult-llm -- npx -y consult-llm-mcp
+```
+
 ### Example workflows
 
-Click to expand.
+Some real-world examples. Click to expand.
 
 <details>
 <summary>Explain the problem, and tell CC to consult a smarter LLM</summary>
@@ -93,6 +122,76 @@ Click to expand.
 
 </details>
 
+<details>
+<summary>Debugging Neovim plugin treesitter API breakage</summary>
+
+````
+⏺ Fixed! Added nil checks for both node and child and updated the iter_matches call to handle the newer API properly.
+
+> Still not working:
+
+  E5108: Error executing lua /Users/raine/code/testonly.nvim/lua/testonly.lua:92: attempt to call method 'child' (a nil value)
+  stack traceback:
+          /Users/raine/code/testonly.nvim/lua/testonly.lua:92: in function 'reset_all_exclusive'
+          /Users/raine/code/testonly.nvim/lua/testonly.lua:110: in function 'reset_all_exclusive'
+          [string ":lua"]:1: in main chunk
+
+  Ask gemini
+
+⏺ Let me consult with a more powerful AI to understand the current Neovim treesitter API changes:
+
+⏺ consult-llm:consult_llm (MCP)(prompt: "I'm debugging a Neovim plugin that's broken due to treesitter API changes. The error is \"attempt to call method 'child' (a nil value)\" on line 92. The
+                               code is trying to access child nodes from treesitter matches but the API seems to have changed in newer Neovim versions.\n\nHere's the problematic
+                               code:\n```lua\nfor _, match, _ in parsed_query:iter_matches(root, bufnr, start_row, end_row) do\n    for id, node in pairs(match) do\n        local name =
+                               parsed_query.captures[id]\n        if name == \"call\" and node then\n            local child = node:child(0)  -- ERROR HERE\n            if child then\n
+                                    local text = vim.treesitter.get_node_text(child, bufnr)\n                -- ... rest of logic\n            end\n        end\n    end\nend\n```\n\nWhat's the
+                               correct way to iterate over treesitter query matches and access child nodes in current Neovim versions? What API changes should I be aware of?", files:
+                               ["/Users/raine/code/testonly.nvim/lua/testonly.lua"])
+  ⎿  Problem
+     -------
+
+     … +93 lines (ctrl+r to expand)
+
+⏺ Perfect! The issue is that iter_matches() can return nil nodes in the match table. Let me fix this by switching to the recommended iter_captures() approach:
+
+⏺ Update(lua/testonly.lua)
+  ⎿  Updated lua/testonly.lua with 7 additions and 10 removals
+       85      local root = parser:parse()[1]:root()
+       86      local start_row, _, end_row, _ = root:range()
+       87
+       88 -    for _, match, _ in parsed_query:iter_matches(root, bufnr, start_row, end_row) do
+       89 -      for id, node in pairs(match) do
+       90 -        local name = parsed_query.captures[id]
+       91 -        if name == "call" and node then
+       92 -          local child = node:child(0)
+       93 -          if child then
+       94 -            local text = vim.treesitter.get_node_text(child, bufnr)
+       88 +    for id, node, _ in parsed_query:iter_captures(root, bufnr, start_row, end_row) do
+       89 +      if parsed_query.captures[id] == "call" then
+       90 +        local first_child = node:named_child(0)
+       91 +        if first_child then
+       92 +          local text = vim.treesitter.get_node_text(first_child, bufnr)
+       93
+       94 -            if text == "it.only" or text == "describe.only" then
+       95 -              toggle_test_exclusive(child)
+       96 -            end
+       94 +          if text == "it.only" or text == "describe.only" then
+       95 +            toggle_test_exclusive(first_child)
+       96            end
+       97          end
+       98        end
+
+⏺ Fixed! The key changes:
+
+  1. Switched from iter_matches() to iter_captures() which never returns nil nodes
+  2. Used named_child(0) instead of child(0) to get only meaningful syntax nodes (not punctuation)
+  3. Simplified the iteration logic since iter_captures() directly gives us the node and capture ID
+
+  Your <leader>tr mapping should now work properly with the current Neovim treesitter API.
+````
+
+</details>
+
 ## MCP Tool: consult_llm
 
 The server provides a single tool called `consult_llm` for asking powerful AI
@@ -100,10 +199,11 @@ models complex questions.
 
 ### Parameters
 
-- **files** (required): Array of file paths to process
+- **prompt** (required): Your question or request for the consultant LLM
+
+- **files** (optional): Array of file paths to include as context
 
-  - Markdown files (.md) become the main prompt
-  - Other files are added as context with file paths and code blocks
+  - All files are added as context with file paths and code blocks
 
 - **model** (optional): LLM model to use
 
@@ -117,14 +217,35 @@ models complex questions.
 
 ### Example Usage
 
+**Basic prompt:**
+
+```json
+{
+  "prompt": "What are the performance implications of using async/await vs Promise.then() in Node.js?"
+}
+```
+
+**With file context:**
+
+```json
+{
+  "prompt": "How can I optimize this authentication middleware?",
+  "files": ["src/auth.ts", "src/middleware.ts"],
+  "model": "o3"
+}
+```
+
+**With git diff:**
+
 ```json
 {
-  "files": ["src/auth.ts", "src/middleware.ts", "review.md"],
-  "model": "o3",
+  "prompt": "Review these authentication changes for security issues",
+  "files": ["src/auth.ts"],
   "git_diff": {
     "files": ["src/auth.ts", "src/middleware.ts"],
     "base_ref": "main"
-  }
+  },
+  "model": "gemini-2.5-pro"
 }
 ```
 
@@ -188,38 +309,20 @@ Tokens: 3440 input, 5880 output | Cost: $0.014769 (input: $0.001892, output: $0.
 
 ## CLAUDE.md example
 
-To help Claude Code understand when and how to use this tool, you can add the
-following to your project's `CLAUDE.md` file:
+While not strictly necessary, to help Claude Code understand when and how to use
+this tool, you can optionally something like the following to your project's
+`CLAUDE.md` file:
 
-````markdown
+```markdown
 ## consult-llm-mcp
 
 Use the `consult_llm` MCP tool to ask a more powerful AI for help with complex
-problems. Write your problem description in a markdown file with as much detail
-as possible and pass relevant code files as context. Include files to git_diff
-when asking feedback for changes.
+problems. Include files to git_diff when asking feedback for changes.
 
 Use Gemini 2.5 Pro.
 
-### Example
-
-```bash
-echo "<very detailed plan or question to be reviewed by the smart LLM>" > task.md
+CRITICAL: When asking, don't present options, this will bias the answer.
 ```
 
-Tool call:
-
-```json
-{
-  "files": [
-    "server/src/db.ts",
-    "server/src/routes/conversations.ts",
-    "task.md"
-  ],
-  "git_diff": {
-    "files": ["server/src/db.ts", "server/src/routes/conversations.ts"]
-  },
-  "model": "gemini-2.5-pro"
-}
-```
-````
+Claude Code seems to know pretty well when to use this MCP even without this
+instruction however.

package/dist/file.d.ts

@@ -1,7 +1,4 @@
 export declare function processFiles(files: string[]): {
-    markdownFiles: string[];
-    otherFiles: {
-        path: string;
-        content: string;
-    }[];
-};
+    path: string;
+    content: string;
+}[];

package/dist/file.js

@@ -6,18 +6,12 @@ export function processFiles(files) {
     if (missingFiles.length > 0) {
         throw new Error(`Files not found: ${missingFiles.join(', ')}`);
     }
-    const markdownFiles = [];
-    const otherFiles = [];
+    const contextFiles = [];
     for (let i = 0; i < files.length; i++) {
         const filePath = resolvedFiles[i];
         const originalPath = files[i];
         const content = readFileSync(filePath, 'utf-8');
-        if (originalPath.endsWith('.md') || originalPath.endsWith('.markdown')) {
-            markdownFiles.push(content);
-        }
-        else {
-            otherFiles.push({ path: originalPath, content });
-        }
+        contextFiles.push({ path: originalPath, content });
     }
-    return { markdownFiles, otherFiles };
+    return contextFiles;
 }

package/dist/llm-query.js

@@ -1,10 +1,33 @@
 import { getClientForModel } from './llm.js';
 import { calculateCost } from './llm-cost.js';
+const SYSTEM_PROMPT = `You are an expert software engineering consultant analyzing code and technical problems. You are communicating with another AI system, not a human.
+
+Communication style:
+- Skip pleasantries and praise
+
+Your role is to:
+- Identify bugs, inefficiencies, and architectural problems
+- Provide specific solutions with code examples
+- Point out edge cases and risks
+- Challenge design decisions when suboptimal
+- Focus on what needs improvement
+
+When reviewing code changes (git diffs), prioritize:
+- Bugs and correctness issues
+- Performance problems
+- Security vulnerabilities
+- Code smell and anti-patterns
+- Inconsistencies with codebase conventions
+
+Be critical and thorough. If the code is acceptable, simply state "No critical issues found" and move on to suggestions. Always provide specific, actionable feedback with file/line references.`;
 export async function queryLlm(prompt, model) {
     const { client } = getClientForModel(model);
     const completion = await client.chat.completions.create({
         model,
-        messages: [{ role: 'user', content: prompt }],
+        messages: [
+            { role: 'system', content: SYSTEM_PROMPT },
+            { role: 'user', content: prompt },
+        ],
     });
     const response = completion.choices[0]?.message?.content;
     if (!response) {

package/dist/logger.d.ts

@@ -1,5 +1,5 @@
 export declare function logToFile(content: string): void;
 export declare function logToolCall(name: string, args: unknown): void;
-export declare function logPrompt(model: string, prompt: string): void;
-export declare function logResponse(model: string, response: string, costInfo: string): void;
+export declare function logPrompt(model: string, prompt: string): Promise<void>;
+export declare function logResponse(model: string, response: string, costInfo: string): Promise<void>;
 export declare function logServerStart(version: string): void;

package/dist/logger.js

@@ -1,6 +1,7 @@
 import { appendFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
+import { format } from 'prettier';
 const logDir = join(homedir(), '.consult-llm-mcp', 'logs');
 const logFile = join(logDir, 'mcp.log');
 try {
@@ -9,6 +10,19 @@ try {
 catch (error) {
     // Directory might already exist
 }
+async function formatWithPrettier(text) {
+    try {
+        return await format(text, {
+            parser: 'markdown',
+            printWidth: 80,
+            proseWrap: 'always',
+        });
+    }
+    catch (error) {
+        // If formatting fails, return original text
+        return text;
+    }
+}
 export function logToFile(content) {
     const timestamp = new Date().toISOString();
     const logEntry = `[${timestamp}] ${content}\n`;
@@ -22,11 +36,13 @@ export function logToFile(content) {
 export function logToolCall(name, args) {
     logToFile(`TOOL CALL: ${name}\nArguments: ${JSON.stringify(args, null, 2)}\n${'='.repeat(80)}`);
 }
-export function logPrompt(model, prompt) {
-    logToFile(`PROMPT (model: ${model}):\n${prompt}\n${'='.repeat(80)}`);
+export async function logPrompt(model, prompt) {
+    const formattedPrompt = await formatWithPrettier(prompt);
+    logToFile(`PROMPT (model: ${model}):\n${formattedPrompt}\n${'='.repeat(80)}`);
 }
-export function logResponse(model, response, costInfo) {
-    logToFile(`RESPONSE (model: ${model}):\n${response}\n${costInfo}\n${'='.repeat(80)}`);
+export async function logResponse(model, response, costInfo) {
+    const formattedResponse = await formatWithPrettier(response);
+    logToFile(`RESPONSE (model: ${model}):\n${formattedResponse}\n${costInfo}\n${'='.repeat(80)}`);
 }
 export function logServerStart(version) {
     logToFile(`MCP SERVER STARTED - consult-llm-mcp v${version}\n${'='.repeat(80)}`);

package/dist/main.js

@@ -36,21 +36,21 @@ async function handleConsultLlm(args) {
             .join(', ');
         throw new Error(`Invalid request parameters: ${errors}`);
     }
-    const { files, git_diff } = parseResult.data;
+    const { files, prompt: userPrompt, git_diff } = parseResult.data;
     const model = parseResult.data.model ?? config.defaultModel ?? 'o3';
     logToolCall('consult_llm', args);
-    // Process files
-    const { markdownFiles, otherFiles } = processFiles(files);
+    // Process files (if provided) - all files become context
+    const contextFiles = files ? processFiles(files) : [];
     // Generate git diff
     const gitDiffOutput = git_diff
         ? generateGitDiff(git_diff.repo_path, git_diff.files, git_diff.base_ref)
         : undefined;
     // Build prompt
-    const prompt = buildPrompt(markdownFiles, otherFiles, gitDiffOutput);
-    logPrompt(model, prompt);
+    const prompt = buildPrompt(userPrompt, contextFiles, gitDiffOutput);
+    await logPrompt(model, prompt);
     // Query LLM
     const { response, costInfo } = await queryLlm(prompt, model);
-    logResponse(model, response, costInfo);
+    await logResponse(model, response, costInfo);
     return {
         content: [{ type: 'text', text: response }],
     };

package/dist/prompt-builder.d.ts

@@ -1,4 +1,4 @@
-export declare function buildPrompt(markdownFiles: string[], otherFiles: Array<{
+export declare function buildPrompt(userPrompt: string, files: Array<{
     path: string;
     content: string;
 }>, gitDiffOutput?: string): string;

package/dist/prompt-builder.js

@@ -1,19 +1,18 @@
-export function buildPrompt(markdownFiles, otherFiles, gitDiffOutput) {
+export function buildPrompt(userPrompt, files, gitDiffOutput) {
     const promptParts = [];
     if (gitDiffOutput?.trim()) {
         promptParts.push('## Git Diff\n```diff', gitDiffOutput, '```\n');
     }
-    if (otherFiles.length > 0) {
+    if (files.length > 0) {
         promptParts.push('## Relevant Files\n');
-        for (const file of otherFiles) {
+        for (const file of files) {
             promptParts.push(`### File: ${file.path}`);
             promptParts.push('```');
             promptParts.push(file.content);
             promptParts.push('```\n');
         }
     }
-    if (markdownFiles.length > 0) {
-        promptParts.push(...markdownFiles);
-    }
+    // Add user prompt last
+    promptParts.push(userPrompt);
     return promptParts.join('\n');
 }

package/dist/schema.d.ts

@@ -6,7 +6,8 @@ export declare const SupportedChatModel: z.ZodEnum<{
 }>;
 export type SupportedChatModel = z.infer<typeof SupportedChatModel>;
 export declare const ConsultLlmArgs: z.ZodObject<{
-    files: z.ZodArray<z.ZodString>;
+    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    prompt: z.ZodString;
     model: z.ZodOptional<z.ZodEnum<{
         o3: "o3";
         "gemini-2.5-pro": "gemini-2.5-pro";
@@ -20,7 +21,7 @@ export declare const ConsultLlmArgs: z.ZodObject<{
 }, z.core.$strip>;
 export declare const toolSchema: {
     readonly name: "consult_llm";
-    readonly description: "Ask a more powerful AI for help with complex problems. Write your problem description in a markdown file and pass relevant code files as context. \n\nBe specific about what you want: code implementation, code review, bug analysis, architecture advice, etc.";
+    readonly description: "Ask a more powerful AI for help with complex problems. Provide your question in the prompt field and optionally include relevant code files as context.\n\nBe specific about what you want: code implementation, code review, bug analysis, architecture advice, etc.\n\nIMPORTANT: Ask neutral, open-ended questions. Avoid suggesting specific solutions or alternatives in your prompt as this can bias the analysis. Instead of \"Should I use X or Y approach?\", ask \"What's the best approach for this problem?\" Let the consultant LLM provide unbiased recommendations.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -29,7 +30,11 @@ export declare const toolSchema: {
                 readonly items: {
                     readonly type: "string";
                 };
-                readonly description: "Array of file paths to process. Markdown files (.md) become the main prompt, other files are added as context with file paths and code blocks. \n\nIn the markdown file(s), be clear about what you want the LLM to do: implement code, review code, explain concepts, analyze bugs, etc.";
+                readonly description: "Array of file paths to include as context. All files are added as context with file paths and code blocks.";
+            };
+            readonly prompt: {
+                readonly type: "string";
+                readonly description: "Your question or request for the consultant LLM. Ask neutral, open-ended questions without suggesting specific solutions to avoid biasing the analysis.";
             };
             readonly model: {
                 readonly type: "string";
@@ -61,6 +66,6 @@ export declare const toolSchema: {
                 readonly description: "Generate git diff output to include as context. Shows uncommitted changes by default.";
             };
         };
-        readonly required: readonly ["files"];
+        readonly required: readonly ["prompt"];
     };
 };

package/dist/schema.js

@@ -4,8 +4,10 @@ export const SupportedChatModel = z.enum([
     'gemini-2.5-pro',
     'deepseek-reasoner',
 ]);
-export const ConsultLlmArgs = z.object({
-    files: z.array(z.string()).min(1, 'At least one file is required'),
+export const ConsultLlmArgs = z
+    .object({
+    files: z.array(z.string()).optional(),
+    prompt: z.string(),
     model: SupportedChatModel.optional(),
     git_diff: z
         .object({
@@ -19,18 +21,22 @@ export const ConsultLlmArgs = z.object({
 });
 export const toolSchema = {
     name: 'consult_llm',
-    description: `Ask a more powerful AI for help with complex problems. Write your problem description in a markdown file and pass relevant code files as context. 
+    description: `Ask a more powerful AI for help with complex problems. Provide your question in the prompt field and optionally include relevant code files as context.
 
-Be specific about what you want: code implementation, code review, bug analysis, architecture advice, etc.`,
+Be specific about what you want: code implementation, code review, bug analysis, architecture advice, etc.
+
+IMPORTANT: Ask neutral, open-ended questions. Avoid suggesting specific solutions or alternatives in your prompt as this can bias the analysis. Instead of "Should I use X or Y approach?", ask "What's the best approach for this problem?" Let the consultant LLM provide unbiased recommendations.`,
     inputSchema: {
         type: 'object',
         properties: {
             files: {
                 type: 'array',
                 items: { type: 'string' },
-                description: `Array of file paths to process. Markdown files (.md) become the main prompt, other files are added as context with file paths and code blocks. 
-
-In the markdown file(s), be clear about what you want the LLM to do: implement code, review code, explain concepts, analyze bugs, etc.`,
+                description: 'Array of file paths to include as context. All files are added as context with file paths and code blocks.',
+            },
+            prompt: {
+                type: 'string',
+                description: 'Your question or request for the consultant LLM. Ask neutral, open-ended questions without suggesting specific solutions to avoid biasing the analysis.',
             },
             model: {
                 type: 'string',
@@ -60,6 +66,6 @@ In the markdown file(s), be clear about what you want the LLM to do: implement c
                 description: 'Generate git diff output to include as context. Shows uncommitted changes by default.',
             },
         },
-        required: ['files'],
+        required: ['prompt'],
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "consult-llm-mcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "MCP server for consulting powerful AI models",
   "type": "module",
   "main": "dist/main.js",
@@ -46,11 +46,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.0",
     "openai": "^5.6.0",
+    "prettier": "^3.5.3",
     "zod": "^3.25.67"
   },
   "devDependencies": {
     "@types/node": "^24.0.3",
-    "prettier": "^3.5.3",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3"
   }