@j0hanz/code-review-analyst-mcp 1.5.2 → 1.6.0

package/dist/lib/gemini.js

@@ -35,6 +35,8 @@ const DEFAULT_BATCH_MODE = 'off';
 const UNKNOWN_REQUEST_CONTEXT_VALUE = 'unknown';
 const RETRYABLE_NUMERIC_CODES = new Set([429, 500, 502, 503, 504]);
 const DIGITS_ONLY_PATTERN = /^\d+$/;
+const TRUE_ENV_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_ENV_VALUES = new Set(['0', 'false', 'no', 'off']);
 const SLEEP_UNREF_OPTIONS = { ref: false };
 const maxConcurrentCallsConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS', 10);
 const maxConcurrentBatchCallsConfig = createCachedEnvInt('MAX_CONCURRENT_BATCH_CALLS', 2);
@@ -129,16 +131,10 @@ function parseBooleanEnv(value) {
     if (normalized.length === 0) {
         return undefined;
     }
-    if (normalized === '1' ||
-        normalized === 'true' ||
-        normalized === 'yes' ||
-        normalized === 'on') {
+    if (TRUE_ENV_VALUES.has(normalized)) {
         return true;
     }
-    if (normalized === '0' ||
-        normalized === 'false' ||
-        normalized === 'no' ||
-        normalized === 'off') {
+    if (FALSE_ENV_VALUES.has(normalized)) {
         return false;
     }
     return undefined;
@@ -240,7 +236,7 @@ function logEvent(event, details) {
         ...details,
     });
 }
-function asRecord(value) {
+function toRecord(value) {
     if (typeof value !== 'object' || value === null) {
         return undefined;
     }
@@ -262,12 +258,12 @@ async function emitGeminiLog(onLog, level, payload) {
     });
 }
 function getNestedError(error) {
-    const record = asRecord(error);
+    const record = toRecord(error);
     if (!record) {
         return undefined;
     }
     const nested = record.error;
-    const nestedRecord = asRecord(nested);
+    const nestedRecord = toRecord(nested);
     if (!nestedRecord) {
         return record;
     }
@@ -372,6 +368,14 @@ function parseStructuredResponse(responseText) {
     try {
         return JSON.parse(responseText);
     }
+    catch {
+        // fast-path failed; try extracting from markdown block
+    }
+    const jsonMatch = /```(?:json)?\n?([\s\S]*?)(?=\n?```)/u.exec(responseText);
+    const jsonText = jsonMatch?.[1] ?? responseText;
+    try {
+        return JSON.parse(jsonText);
+    }
     catch (error) {
         throw new Error(`Model produced invalid JSON: ${getErrorMessage(error)}`);
     }
@@ -571,88 +575,94 @@ async function waitForBatchConcurrencySlot(limit, requestSignal) {
         activeBatchCalls += 1;
     }, batchSlotWaiters, requestSignal);
 }
-function getBatchState(payload) {
-    const record = asRecord(payload);
-    if (!record) {
-        return undefined;
-    }
-    const directState = toUpperStringCode(record.state);
-    if (directState) {
-        return directState;
-    }
-    const metadata = asRecord(record.metadata);
-    if (!metadata) {
-        return undefined;
-    }
-    return toUpperStringCode(metadata.state);
-}
-function extractBatchResponseText(payload) {
-    const record = asRecord(payload);
-    if (!record) {
-        return undefined;
-    }
-    const inlineResponse = asRecord(record.inlineResponse);
-    const inlineText = typeof inlineResponse?.text === 'string' ? inlineResponse.text : undefined;
-    if (inlineText) {
-        return inlineText;
-    }
-    const response = asRecord(record.response);
-    if (!response) {
-        return undefined;
-    }
-    const responseText = typeof response.text === 'string' ? response.text : undefined;
-    if (responseText) {
+const BatchHelper = {
+    getState(payload) {
+        const record = toRecord(payload);
+        if (!record) {
+            return undefined;
+        }
+        const directState = toUpperStringCode(record.state);
+        if (directState) {
+            return directState;
+        }
+        const metadata = toRecord(record.metadata);
+        if (!metadata) {
+            return undefined;
+        }
+        return toUpperStringCode(metadata.state);
+    },
+    getResponseText(payload) {
+        const record = toRecord(payload);
+        if (!record) {
+            return undefined;
+        }
+        const inlineResponse = toRecord(record.inlineResponse);
+        const inlineText = typeof inlineResponse?.text === 'string'
+            ? inlineResponse.text
+            : undefined;
+        if (inlineText) {
+            return inlineText;
+        }
+        const response = toRecord(record.response);
+        if (!response) {
+            return undefined;
+        }
+        const responseText = typeof response.text === 'string' ? response.text : undefined;
+        if (responseText) {
+            return responseText;
+        }
+        const { inlineResponses } = response;
+        if (!Array.isArray(inlineResponses) || inlineResponses.length === 0) {
+            return undefined;
+        }
+        const firstInline = toRecord(inlineResponses[0]);
+        return typeof firstInline?.text === 'string' ? firstInline.text : undefined;
+    },
+    getErrorDetail(payload) {
+        const record = toRecord(payload);
+        if (!record) {
+            return undefined;
+        }
+        const directError = toRecord(record.error);
+        const directMessage = typeof directError?.message === 'string'
+            ? directError.message
+            : undefined;
+        if (directMessage) {
+            return directMessage;
+        }
+        const metadata = toRecord(record.metadata);
+        const metadataError = toRecord(metadata?.error);
+        const metadataMessage = typeof metadataError?.message === 'string'
+            ? metadataError.message
+            : undefined;
+        if (metadataMessage) {
+            return metadataMessage;
+        }
+        const response = toRecord(record.response);
+        const responseError = toRecord(response?.error);
+        return typeof responseError?.message === 'string'
+            ? responseError.message
+            : undefined;
+    },
+    getSuccessResponseText(polled) {
+        const responseText = this.getResponseText(polled);
+        if (!responseText) {
+            const errorDetail = this.getErrorDetail(polled);
+            throw new Error(errorDetail
+                ? `Gemini batch request succeeded but returned no response text: ${errorDetail}`
+                : 'Gemini batch request succeeded but returned no response text.');
+        }
         return responseText;
-    }
-    const { inlineResponses } = response;
-    if (!Array.isArray(inlineResponses) || inlineResponses.length === 0) {
-        return undefined;
-    }
-    const firstInline = asRecord(inlineResponses[0]);
-    return typeof firstInline?.text === 'string' ? firstInline.text : undefined;
-}
-function extractBatchErrorDetail(payload) {
-    const record = asRecord(payload);
-    if (!record) {
-        return undefined;
-    }
-    const directError = asRecord(record.error);
-    const directMessage = typeof directError?.message === 'string' ? directError.message : undefined;
-    if (directMessage) {
-        return directMessage;
-    }
-    const metadata = asRecord(record.metadata);
-    const metadataError = asRecord(metadata?.error);
-    const metadataMessage = typeof metadataError?.message === 'string'
-        ? metadataError.message
-        : undefined;
-    if (metadataMessage) {
-        return metadataMessage;
-    }
-    const response = asRecord(record.response);
-    const responseError = asRecord(response?.error);
-    return typeof responseError?.message === 'string'
-        ? responseError.message
-        : undefined;
-}
-function getBatchSuccessResponseText(polled) {
-    const responseText = extractBatchResponseText(polled);
-    if (!responseText) {
-        const errorDetail = extractBatchErrorDetail(polled);
-        throw new Error(errorDetail
-            ? `Gemini batch request succeeded but returned no response text: ${errorDetail}`
-            : 'Gemini batch request succeeded but returned no response text.');
-    }
-    return responseText;
-}
-function handleBatchTerminalState(state, payload) {
-    if (state === 'JOB_STATE_FAILED' || state === 'JOB_STATE_CANCELLED') {
-        const errorDetail = extractBatchErrorDetail(payload);
-        throw new Error(errorDetail
-            ? `Gemini batch request ended with state ${state}: ${errorDetail}`
-            : `Gemini batch request ended with state ${state}.`);
-    }
-}
+    },
+    handleTerminalState(state, payload) {
+        if (state === 'JOB_STATE_FAILED' || state === 'JOB_STATE_CANCELLED') {
+            const errorDetail = this.getErrorDetail(payload);
+            throw new Error(errorDetail
+                ? `Gemini batch request ended with state ${state}: ${errorDetail}`
+                : `Gemini batch request ended with state ${state}.`);
+        }
+    },
+};
 async function pollBatchStatusWithRetries(batches, batchName, onLog, requestSignal) {
     const maxPollRetries = 2;
     for (let attempt = 0; attempt <= maxPollRetries; attempt += 1) {
@@ -717,7 +727,7 @@ async function runInlineBatchWithPolling(request, model, onLog) {
             ],
         };
         const createdJob = await batches.create(createPayload);
-        const createdRecord = asRecord(createdJob);
+        const createdRecord = toRecord(createdJob);
         batchName =
             typeof createdRecord?.name === 'string' ? createdRecord.name : undefined;
         if (!batchName) {
@@ -740,13 +750,13 @@ async function runInlineBatchWithPolling(request, model, onLog) {
                 throw new Error(`Gemini batch request timed out after ${formatNumber(timeoutMs)}ms.`);
             }
             const polled = await pollBatchStatusWithRetries(batches, batchName, onLog, request.signal);
-            const state = getBatchState(polled);
+            const state = BatchHelper.getState(polled);
             if (state === 'JOB_STATE_SUCCEEDED') {
-                const responseText = getBatchSuccessResponseText(polled);
+                const responseText = BatchHelper.getSuccessResponseText(polled);
                 completed = true;
                 return parseStructuredResponse(responseText);
             }
-            handleBatchTerminalState(state, polled);
+            BatchHelper.handleTerminalState(state, polled);
             await sleep(pollIntervalMs, undefined, request.signal
                 ? { ...SLEEP_UNREF_OPTIONS, signal: request.signal }
                 : SLEEP_UNREF_OPTIONS);

package/dist/lib/model-config.js

@@ -2,12 +2,10 @@
 export const FLASH_MODEL = 'gemini-3-flash-preview';
 /** High-capability model for deep reasoning, quality inspection, and reliable code generation. */
 export const PRO_MODEL = 'gemini-3-pro-preview';
-/** Default hint for auto-detection. */
-const DEFAULT_DETECT_HINT = 'detect';
 /** Default language hint. */
-export const DEFAULT_LANGUAGE = DEFAULT_DETECT_HINT;
+export const DEFAULT_LANGUAGE = 'detect';
 /** Default test-framework hint. */
-export const DEFAULT_FRAMEWORK = DEFAULT_DETECT_HINT;
+export const DEFAULT_FRAMEWORK = 'detect';
 /** Extended timeout for Pro model calls (ms). */
 export const DEFAULT_TIMEOUT_PRO_MS = 120_000;
 export const MODEL_TIMEOUT_MS = {

package/dist/lib/tool-contracts.d.ts

@@ -29,6 +29,12 @@ export interface ToolContract {
     crossToolFlow: readonly string[];
     constraints?: readonly string[];
 }
+interface StructuredToolRuntimeOptions {
+    thinkingLevel?: NonNullable<ToolContract['thinkingLevel']>;
+    temperature?: NonNullable<ToolContract['temperature']>;
+    deterministicJson?: NonNullable<ToolContract['deterministicJson']>;
+}
+export declare function buildStructuredToolRuntimeOptions(contract: Pick<ToolContract, 'thinkingLevel' | 'temperature' | 'deterministicJson'>): StructuredToolRuntimeOptions;
 export declare const TOOL_CONTRACTS: readonly [{
     readonly name: "generate_diff";
     readonly purpose: "Generate a diff of current changes and cache it server-side. MUST be called before any other tool. Uses git to capture unstaged or staged changes in the current working directory.";
@@ -97,7 +103,7 @@ export declare const TOOL_CONTRACTS: readonly [{
     readonly crossToolFlow: readonly ["Use before deep review to decide whether Pro analysis is needed."];
 }, {
     readonly name: "inspect_code_quality";
-    readonly purpose: "Deep code review with optional full-file context.";
+    readonly purpose: "Deep code review over the cached diff; files are optional supplementary excerpts only.";
     readonly model: "gemini-3-pro-preview";
     readonly timeoutMs: 120000;
     readonly thinkingLevel: "high";
@@ -133,10 +139,10 @@ export declare const TOOL_CONTRACTS: readonly [{
         readonly type: "object[]";
         readonly required: false;
         readonly constraints: "1-20 files, 100K chars/file";
-        readonly description: "Optional full file content context.";
+        readonly description: "Optional short excerpts for supplementary context only; avoid full files — the diff is the primary source.";
     }];
     readonly outputShape: "{summary, overallRisk, findings[], testsNeeded[], contextualInsights[], totalFindings}";
-    readonly gotchas: readonly ["Requires generate_diff to be called first.", "Combined diff + file context is bounded by MAX_CONTEXT_CHARS.", "maxFindings caps output after generation."];
+    readonly gotchas: readonly ["Requires generate_diff to be called first.", "Combined diff + file context is bounded by MAX_CONTEXT_CHARS.", "maxFindings caps output after generation.", "files[] is token-expensive — omit unless the diff lacks critical structural context (e.g. class hierarchy, imports). Never pass full files."];
     readonly crossToolFlow: readonly ["findings[].title -> suggest_search_replace.findingTitle", "findings[].explanation -> suggest_search_replace.findingDetails"];
     readonly constraints: readonly ["Context budget (diff + files) < 500K chars."];
 }, {
@@ -245,3 +251,4 @@ export declare function getToolContracts(): readonly ToolContract[];
 export declare function getToolContract(toolName: string): ToolContract | undefined;
 export declare function requireToolContract(toolName: string): ToolContract;
 export declare function getToolContractNames(): string[];
+export {};

package/dist/lib/tool-contracts.js

@@ -9,6 +9,19 @@ export const INSPECTION_FOCUS_AREAS = [
     'maintainability',
     'concurrency',
 ];
+export function buildStructuredToolRuntimeOptions(contract) {
+    const options = {};
+    if (contract.thinkingLevel !== undefined) {
+        options.thinkingLevel = contract.thinkingLevel;
+    }
+    if (contract.temperature !== undefined) {
+        options.temperature = contract.temperature;
+    }
+    if (contract.deterministicJson !== undefined) {
+        options.deterministicJson = contract.deterministicJson;
+    }
+    return options;
+}
 export const TOOL_CONTRACTS = [
     {
         name: 'generate_diff',
@@ -105,7 +118,7 @@ export const TOOL_CONTRACTS = [
     },
     {
         name: 'inspect_code_quality',
-        purpose: 'Deep code review with optional full-file context.',
+        purpose: 'Deep code review over the cached diff; files are optional supplementary excerpts only.',
         model: PRO_MODEL,
         timeoutMs: DEFAULT_TIMEOUT_PRO_MS,
         thinkingLevel: PRO_THINKING_LEVEL,
@@ -146,7 +159,7 @@ export const TOOL_CONTRACTS = [
                 type: 'object[]',
                 required: false,
                 constraints: '1-20 files, 100K chars/file',
-                description: 'Optional full file content context.',
+                description: 'Optional short excerpts for supplementary context only; avoid full files — the diff is the primary source.',
             },
         ],
         outputShape: '{summary, overallRisk, findings[], testsNeeded[], contextualInsights[], totalFindings}',
@@ -154,6 +167,7 @@ export const TOOL_CONTRACTS = [
             'Requires generate_diff to be called first.',
             'Combined diff + file context is bounded by MAX_CONTEXT_CHARS.',
             'maxFindings caps output after generation.',
+            'files[] is token-expensive — omit unless the diff lacks critical structural context (e.g. class hierarchy, imports). Never pass full files.',
         ],
         crossToolFlow: [
             'findings[].title -> suggest_search_replace.findingTitle',

package/dist/lib/tool-factory.d.ts

@@ -1,3 +1,4 @@
+import type { CreateTaskRequestHandlerExtra } from '@modelcontextprotocol/sdk/experimental/tasks/interfaces.js';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
@@ -34,6 +35,12 @@ interface ProgressExtra {
         params: ProgressNotificationParams;
     }) => Promise<void>;
 }
+export interface ToolAnnotations {
+    readOnlyHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+    destructiveHint?: boolean;
+}
 export interface StructuredToolTaskConfig<TInput extends object = Record<string, unknown>, TResult extends object = Record<string, unknown>, TFinal extends TResult = TResult> {
     /** Tool name registered with the MCP server (e.g. 'analyze_pr_impact'). */
     name: string;
@@ -84,6 +91,8 @@ export interface StructuredToolTaskConfig<TInput extends object = Record<string,
     progressContext?: (input: TInput) => string;
     /** Optional short outcome suffix for the completion progress message (e.g., "3 findings"). */
     formatOutcome?: (result: TFinal) => string;
+    /** Optional MCP annotation overrides for this tool. */
+    annotations?: ToolAnnotations;
     /** Builds the system instruction and user prompt from parsed tool input. */
     buildPrompt: (input: TInput, ctx: ToolExecutionContext) => PromptParts;
 }
@@ -92,5 +101,27 @@ export declare function wrapToolHandler<TInput, TResult extends CallToolResult>(
     toolName: string;
     progressContext?: (input: TInput) => string;
 }, handler: (input: TInput, extra: ProgressExtra) => Promise<TResult> | TResult): (input: TInput, extra: ProgressExtra) => Promise<TResult>;
+interface TaskLike {
+    taskId: string;
+}
+export declare class ToolTaskRunner<TInput extends object, TResult extends object, TFinal extends TResult> {
+    private readonly server;
+    private readonly config;
+    private readonly extra;
+    private readonly task;
+    private diffSlotSnapshot;
+    private hasSnapshot;
+    private readonly responseSchema;
+    private readonly onLog;
+    private readonly reportProgress;
+    private progressContext;
+    constructor(server: McpServer, config: StructuredToolTaskConfig<TInput, TResult, TFinal>, extra: CreateTaskRequestHandlerExtra, task: TaskLike);
+    setDiffSlotSnapshot(diffSlotSnapshot: DiffSlot | undefined): void;
+    private updateStatusMessage;
+    private storeResultSafely;
+    private executeValidation;
+    private executeModelCall;
+    run(input: unknown): Promise<void>;
+}
 export declare function registerStructuredToolTask<TInput extends object, TResult extends object = Record<string, unknown>, TFinal extends TResult = TResult>(server: McpServer, config: StructuredToolTaskConfig<TInput, TResult, TFinal>): void;
 export {};