consult-llm-mcp 1.0.0 → 1.0.2

package/README.md

@@ -22,8 +22,6 @@ npm install -g .
 
 ## Configuration
 
-Set the following environment variables:
-
 - `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)
@@ -32,17 +30,75 @@ Set the following environment variables:
 
 ## Usage with Claude Code
 
+### Installation
+
 Add the MCP server to Claude Code:
 
 ```bash
-claude mcp add consult-llm -- consult-llm-mcp
+claude mcp add consult-llm -- npx -y consult-llm-mcp
 ```
 
 Or for global availability:
 
 ```bash
-claude mcp add --scope user consult-llm -- consult-llm-mcp
+claude mcp add --scope user consult-llm -- npx -y consult-llm-mcp
+```
+
+### Example workflows
+
+<details>
+<summary>Explain the problem, and tell CC to consult a smarter LLM</summary>
+
 ```
+  <Some long explanation of the issue here>
+
+  Consult LLM for assistance, use gemini
+
+⏺ I see the issue! The problem is that the frontend is trying to use the hint
+  for "isn't" but the server generated a hint for "isn't it" (the full phrase).
+  This is a mismatch between how the frontend segments text and how the server
+  generates hints.
+
+  Let me consult the LLM to get assistance on this segmentation mismatch issue.
+
+⏺ Write(hint-segmentation-issue.md)
+  ⎿  Wrote 53 lines to hint-segmentation-issue.md
+     # Hint Segmentation Mismatch Issue
+     ## Problem Description
+     There's a mismatch between how the frontend segments text for clickable
+     words and how the backend generates hints. This causes hint unlocking to
+     fail when the segments don't match exactly.
+     ## Example Case
+     **Original Text**: "Hello! Nice weather, isn't it?"
+     … +43 lines (ctrl+r to expand)
+
+⏺ consult-llm:consult_llm (MCP)(model: "gemini-2.5-pro", files: ["/project/hint
+                                -segmentation-issue.md","/project/web/src/compo
+                                nents/HintsText.tsx","/project/web/src/utils/hi
+                                nts.ts","/project/server/src/routes/public/hint
+                                s.ts","/project/server/src/llm/hints.ts"])
+  ⎿ An excellent analysis of the problem. The root cause has been correctly
+    identified: a race condition within the `handleConfirmGenerateHints`
+    function in `HintsText.tsx`. The component state updates in the background
+    after `await generateHints()`, but the function continues executing with a
+    stale `activeSegment` variable, causing it to request a hint for a smaller
+    text segment ( e.g., "isn't") instead of the full, newly-available hint
+    phrase (e.g., "isn't it").
+    … +607 lines (ctrl+r to expand)
+
+⏺ Perfect! The LLM identified the core issue - there's a race condition in
+  handleConfirmGenerateHints where the function uses stale state after async
+  operations. The solution is to re-target the hint key after generation to
+  find the correct matching hint.
+
+  Let me implement this solution:
+
+⏺ Update Todos
+  ⎿  ☐ Fix hint segmentation mismatch by implementing smarter hint key
+       targeting in handleConfirmGenerateHints
+```
+
+</details>
 
 ## MCP Tool: consult_llm
 
@@ -131,16 +187,3 @@ Tool call:
 }
 ```
 ````
-
-## Development
-
-```bash
-# Run in development mode
-npm run dev
-
-# Build TypeScript
-npm run build
-
-# Format code
-npm run format
-```

package/dist/logger.d.ts

@@ -2,3 +2,4 @@ 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 logServerStart(version: string): void;

package/dist/logger.js

@@ -28,3 +28,6 @@ export function logPrompt(model, prompt) {
 export function logResponse(model, response, costInfo) {
     logToFile(`RESPONSE (model: ${model}):\n${response}\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

@@ -3,15 +3,21 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { config } from './config.js';
-import { ConsultLlmArgs, toolSchema } from './schema.js';
+import { ConsultLlmArgs, toolSchema, } from './schema.js';
 import { processFiles } from './file.js';
 import { generateGitDiff } from './git.js';
 import { buildPrompt } from './prompt-builder.js';
 import { queryLlm } from './llm-query.js';
-import { logToolCall, logPrompt, logResponse } from './logger.js';
+import { logToolCall, logPrompt, logResponse, logServerStart, } from './logger.js';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+const SERVER_VERSION = packageJson.version;
 const server = new Server({
     name: 'consult_llm',
-    version: '1.0.0',
+    version: SERVER_VERSION,
 }, {
     capabilities: {
         tools: {},
@@ -61,6 +67,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     throw new Error(`Unknown tool: ${request.params.name}`);
 });
 async function main() {
+    logServerStart(SERVER_VERSION);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/schema.d.ts

@@ -20,7 +20,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.";
+    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 inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -29,7 +29,7 @@ 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.";
+                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 model: {
                 readonly type: "string";

package/dist/schema.js

@@ -19,14 +19,18 @@ 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. Write your problem description in a markdown file and pass relevant code files as context. 
+
+Be specific about what you want: code implementation, code review, bug analysis, architecture advice, etc.`,
     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.',
+                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.`,
             },
             model: {
                 type: 'string',

package/package.json

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