consult-llm-mcp 1.0.2 → 1.0.4

package/README.md

@@ -1,32 +1,25 @@
 # Consult LLM MCP
 
-An MCP (Model Context Protocol) server that allows you to consult more powerful
-AI models with your code and questions.
+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.
 
 ## Features
 
 - Query powerful AI models (o3, Gemini 2.5 Pro, DeepSeek Reasoner) with file
   context
-- Automatic prompt construction from markdown and code files
+- Direct prompt support for simple questions or automatic prompt construction
+  from markdown and code files
 - Git diff to feed code changes
 - Usage tracking with cost estimation
 - Comprehensive logging
 
-## Installation
-
-```bash
-npm install
-npm run build
-npm install -g .
-```
-
 ## Configuration
 
 - `OPENAI_API_KEY` - Your OpenAI API key (required for o3)
 - `GEMINI_API_KEY` - Your Google AI API key (required for Gemini models)
 - `DEEPSEEK_API_KEY` - Your DeepSeek API key (required for DeepSeek models)
-- `CONSULT_LLM_DEFAULT_MODEL` - Override the default model (optional, defaults
-  to 'o3')
+- `CONSULT_LLM_DEFAULT_MODEL` - Override the default model (optional)
+  - Options: `o3` (default), `gemini-2.5-pro`, `deepseek-reasoner`
 
 ## Usage with Claude Code
 
@@ -46,6 +39,8 @@ claude mcp add --scope user consult-llm -- npx -y consult-llm-mcp
 
 ### Example workflows
 
+Click to expand.
+
 <details>
 <summary>Explain the problem, and tell CC to consult a smarter LLM</summary>
 
@@ -107,11 +102,16 @@ models complex questions.
 
 ### Parameters
 
-- **files** (required): Array of file paths to process
+- **files** (optional): 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
 
+- **prompt** (optional): Direct prompt text for simple questions
+
+  - Alternative to using markdown files
+  - Either `files` or `prompt` must be provided
+
 - **model** (optional): LLM model to use
 
   - Options: `o3` (default), `gemini-2.5-pro`, `deepseek-reasoner`
@@ -124,6 +124,8 @@ models complex questions.
 
 ### Example Usage
 
+**With files:**
+
 ```json
 {
   "files": ["src/auth.ts", "src/middleware.ts", "review.md"],
@@ -135,6 +137,16 @@ models complex questions.
 }
 ```
 
+**With direct prompt:**
+
+```json
+{
+  "prompt": "Analyze the performance implications of using async/await vs Promise.then() in Node.js",
+  "files": ["src/database.ts"],
+  "model": "gemini-2.5-pro"
+}
+```
+
 ## Supported Models
 
 - **o3**: OpenAI's reasoning model ($2/$8 per million tokens)
@@ -150,40 +162,63 @@ All prompts and responses are logged to `~/.consult-llm-mcp/logs/mcp.log` with:
 - Full prompts and responses
 - Token usage and cost estimates
 
-## CLAUDE.md example
+<details>
+<summary>Example</summary>
+
+```
+[2025-06-22T20:16:04.673Z] TOOL CALL: consult_llm
+Arguments: {
+  "files": [
+    "refactor-analysis.md",
+    "src/main.ts",
+    "src/schema.ts",
+    "src/config.ts",
+    "src/llm.ts",
+    "src/llm-cost.ts"
+  ],
+  "model": "deepseek-reasoner"
+}
+================================================================================
+[2025-06-22T20:16:04.675Z] PROMPT (model: deepseek-reasoner):
+## Relevant Files
 
-To help Claude Code understand when and how to use this tool, you can add the
-following to your project's `CLAUDE.md` file:
+### File: src/main.ts
 
-````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.
+Please provide specific suggestions for refactoring with example code structure
+where helpful.
+================================================================================
+[2025-06-22T20:19:20.632Z] RESPONSE (model: deepseek-reasoner):
+Based on the analysis, here are the key refactoring suggestions to improve
+separation of concerns and maintainability:
 
-Use Gemini 2.5 Pro.
+...
 
-### Example
+This refactoring maintains all existing functionality while significantly
+improving maintainability and separation of concerns. The new structure makes
+it easier to add features like new LLM providers, additional context sources,
+or alternative prompt formats.
 
-```bash
-echo "<very detailed plan or question to be reviewed by the smart LLM>" > task.md
+Tokens: 3440 input, 5880 output | Cost: $0.014769 (input: $0.001892, output: $0.012877)
 ```
 
-Tool call:
+</details>
 
-```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.md example
+
+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
+## consult-llm-mcp
+
+Use the `consult_llm` MCP tool to ask a more powerful AI for help with complex
+problems. Include files to git_diff when asking feedback for changes.
+
+Use Gemini 2.5 Pro.
 ```
-````
+
+Claude Code seems to know pretty well when to use this MCP even without this
+instruction however.

package/dist/llm-query.js

@@ -1,10 +1,30 @@
 import { getClientForModel } from './llm.js';
 import { calculateCost } from './llm-cost.js';
+const SYSTEM_PROMPT = `You are an expert software engineering consultant being asked to analyze complex problems that require deep technical insight. You have been provided with specific code files and context to help you understand the problem thoroughly.
+
+Your role is to:
+- Provide detailed technical analysis of the problem
+- Suggest specific, actionable solutions with code examples where helpful
+- Consider architectural implications and best practices
+- Identify potential edge cases or risks
+- Explain your reasoning clearly
+
+When reviewing code changes (git diffs), focus on:
+- Correctness and potential bugs
+- Performance implications
+- Security considerations
+- Maintainability and code quality
+- Integration with existing codebase patterns
+
+Provide concrete, implementable recommendations rather than general advice. Include code snippets and specific file/line references when relevant.`;
 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/llm.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
 import { type SupportedChatModel as SupportedChatModelType } from './schema.js';
-export declare function getClientForModel(model: SupportedChatModelType | string): {
+export declare function getClientForModel(model: SupportedChatModelType): {
     client: OpenAI;
 };

package/dist/llm.js

@@ -4,6 +4,9 @@ const clients = {};
 export function getClientForModel(model) {
     if (model.startsWith('gpt-') || model === 'o3') {
         if (!clients.openai) {
+            if (!config.openaiApiKey) {
+                throw new Error('OPENAI_API_KEY environment variable is required for OpenAI models');
+            }
             clients.openai = new OpenAI({
                 apiKey: config.openaiApiKey,
             });
@@ -12,6 +15,9 @@ export function getClientForModel(model) {
     }
     else if (model.startsWith('gemini-')) {
         if (!clients.gemini) {
+            if (!config.geminiApiKey) {
+                throw new Error('GEMINI_API_KEY environment variable is required for Gemini models');
+            }
             clients.gemini = new OpenAI({
                 apiKey: config.geminiApiKey,
                 baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai/',
@@ -21,6 +27,9 @@ export function getClientForModel(model) {
     }
     else if (model.startsWith('deepseek-')) {
         if (!clients.deepseek) {
+            if (!config.deepseekApiKey) {
+                throw new Error('DEEPSEEK_API_KEY environment variable is required for DeepSeek models');
+            }
             clients.deepseek = new OpenAI({
                 apiKey: config.deepseekApiKey,
                 baseURL: 'https://api.deepseek.com',

package/dist/main.js

@@ -36,17 +36,17 @@ async function handleConsultLlm(args) {
             .join(', ');
         throw new Error(`Invalid request parameters: ${errors}`);
     }
-    const { files, git_diff } = parseResult.data;
+    const { files, prompt: directPrompt, 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)
+    const { markdownFiles, otherFiles } = files ? processFiles(files) : { markdownFiles: [], otherFiles: [] };
     // 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);
+    const prompt = buildPrompt(directPrompt, markdownFiles, otherFiles, gitDiffOutput);
     logPrompt(model, prompt);
     // Query LLM
     const { response, costInfo } = await queryLlm(prompt, model);

package/dist/prompt-builder.d.ts

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

package/dist/prompt-builder.js

@@ -1,4 +1,4 @@
-export function buildPrompt(markdownFiles, otherFiles, gitDiffOutput) {
+export function buildPrompt(directPrompt, markdownFiles, otherFiles, gitDiffOutput) {
     const promptParts = [];
     if (gitDiffOutput?.trim()) {
         promptParts.push('## Git Diff\n```diff', gitDiffOutput, '```\n');
@@ -12,6 +12,9 @@ export function buildPrompt(markdownFiles, otherFiles, gitDiffOutput) {
             promptParts.push('```\n');
         }
     }
+    if (directPrompt) {
+        promptParts.push(directPrompt);
+    }
     if (markdownFiles.length > 0) {
         promptParts.push(...markdownFiles);
     }

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.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodEnum<{
         o3: "o3";
         "gemini-2.5-pro": "gemini-2.5-pro";
@@ -31,6 +32,10 @@ export declare const toolSchema: {
                 };
                 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 prompt: {
+                readonly type: "string";
+                readonly description: "Direct prompt text for simple questions. Alternative to using markdown files.";
+            };
             readonly model: {
                 readonly type: "string";
                 readonly enum: readonly ["o3", "gemini-2.5-pro", "deepseek-reasoner"];
@@ -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 [];
     };
 };

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().optional(),
     model: SupportedChatModel.optional(),
     git_diff: z
         .object({
@@ -16,7 +18,8 @@ export const ConsultLlmArgs = z.object({
         base_ref: z.string().optional().default('HEAD'),
     })
         .optional(),
-});
+})
+    .refine((data) => data.files || data.prompt, 'Either files or prompt must be provided');
 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. 
@@ -32,6 +35,10 @@ Be specific about what you want: code implementation, code review, bug analysis,
 
 In the markdown file(s), be clear about what you want the LLM to do: implement code, review code, explain concepts, analyze bugs, etc.`,
             },
+            prompt: {
+                type: 'string',
+                description: 'Direct prompt text for simple questions. Alternative to using markdown files.',
+            },
             model: {
                 type: 'string',
                 enum: ['o3', 'gemini-2.5-pro', 'deepseek-reasoner'],
@@ -60,6 +67,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: [],
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "consult-llm-mcp",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "MCP server for consulting powerful AI models",
   "type": "module",
   "main": "dist/main.js",