@j0hanz/code-review-analyst-mcp 1.2.1 → 1.3.0

package/dist/lib/tool-contracts.js

@@ -0,0 +1,302 @@
+import { DEFAULT_TIMEOUT_PRO_MS, FLASH_API_BREAKING_MAX_OUTPUT_TOKENS, FLASH_COMPLEXITY_MAX_OUTPUT_TOKENS, FLASH_MODEL, FLASH_TEST_PLAN_MAX_OUTPUT_TOKENS, FLASH_THINKING_BUDGET, FLASH_TRIAGE_MAX_OUTPUT_TOKENS, PRO_MODEL, PRO_PATCH_MAX_OUTPUT_TOKENS, PRO_REVIEW_MAX_OUTPUT_TOKENS, PRO_THINKING_BUDGET, } from './model-config.js';
+const DEFAULT_TIMEOUT_FLASH_MS = 90_000;
+export const TOOL_CONTRACTS = [
+    {
+        name: 'analyze_pr_impact',
+        purpose: 'Assess severity, categories, breaking changes, and rollback complexity.',
+        model: FLASH_MODEL,
+        timeoutMs: DEFAULT_TIMEOUT_FLASH_MS,
+        maxOutputTokens: FLASH_TRIAGE_MAX_OUTPUT_TOKENS,
+        params: [
+            {
+                name: 'diff',
+                type: 'string',
+                required: true,
+                constraints: '10-120K chars',
+                description: 'Unified diff text.',
+            },
+            {
+                name: 'repository',
+                type: 'string',
+                required: true,
+                constraints: '1-200 chars',
+                description: 'Repository identifier (org/repo).',
+            },
+            {
+                name: 'language',
+                type: 'string',
+                required: false,
+                constraints: '2-32 chars',
+                description: 'Primary language hint.',
+            },
+        ],
+        outputShape: '{severity, categories[], summary, breakingChanges[], affectedAreas[], rollbackComplexity}',
+        gotchas: [
+            'Flash triage tool optimized for speed.',
+            'Diff-only analysis (no full-file context).',
+        ],
+        crossToolFlow: [
+            'severity/categories feed triage and merge-gate decisions.',
+        ],
+    },
+    {
+        name: 'generate_review_summary',
+        purpose: 'Produce PR summary, risk rating, and merge recommendation.',
+        model: FLASH_MODEL,
+        timeoutMs: DEFAULT_TIMEOUT_FLASH_MS,
+        maxOutputTokens: FLASH_TRIAGE_MAX_OUTPUT_TOKENS,
+        params: [
+            {
+                name: 'diff',
+                type: 'string',
+                required: true,
+                constraints: '10-120K chars',
+                description: 'Unified diff text.',
+            },
+            {
+                name: 'repository',
+                type: 'string',
+                required: true,
+                constraints: '1-200 chars',
+                description: 'Repository identifier (org/repo).',
+            },
+            {
+                name: 'language',
+                type: 'string',
+                required: false,
+                constraints: '2-32 chars',
+                description: 'Primary language hint.',
+            },
+        ],
+        outputShape: '{summary, overallRisk, keyChanges[], recommendation, stats{filesChanged, linesAdded, linesRemoved}}',
+        gotchas: [
+            'stats are computed locally from the diff.',
+            'Flash triage tool optimized for speed.',
+        ],
+        crossToolFlow: [
+            'Use before deep review to decide whether Pro analysis is needed.',
+        ],
+    },
+    {
+        name: 'inspect_code_quality',
+        purpose: 'Deep code review with optional full-file context.',
+        model: PRO_MODEL,
+        timeoutMs: DEFAULT_TIMEOUT_PRO_MS,
+        thinkingBudget: PRO_THINKING_BUDGET,
+        maxOutputTokens: PRO_REVIEW_MAX_OUTPUT_TOKENS,
+        params: [
+            {
+                name: 'diff',
+                type: 'string',
+                required: true,
+                constraints: '10-120K chars',
+                description: 'Unified diff text.',
+            },
+            {
+                name: 'repository',
+                type: 'string',
+                required: true,
+                constraints: '1-200 chars',
+                description: 'Repository identifier (org/repo).',
+            },
+            {
+                name: 'language',
+                type: 'string',
+                required: false,
+                constraints: '2-32 chars',
+                description: 'Primary language hint.',
+            },
+            {
+                name: 'focusAreas',
+                type: 'string[]',
+                required: false,
+                constraints: '1-12 items, 2-80 chars each',
+                description: 'Focused inspection categories.',
+            },
+            {
+                name: 'maxFindings',
+                type: 'number',
+                required: false,
+                constraints: '1-25',
+                description: 'Post-generation cap applied to findings.',
+            },
+            {
+                name: 'files',
+                type: 'object[]',
+                required: false,
+                constraints: '1-20 files, 100K chars/file',
+                description: 'Optional full file content context.',
+            },
+        ],
+        outputShape: '{summary, overallRisk, findings[], testsNeeded[], contextualInsights[], totalFindings}',
+        gotchas: [
+            'Combined diff + file context is bounded by MAX_CONTEXT_CHARS.',
+            'maxFindings caps output after generation.',
+        ],
+        crossToolFlow: [
+            'findings[].title -> suggest_search_replace.findingTitle',
+            'findings[].explanation -> suggest_search_replace.findingDetails',
+        ],
+        constraints: ['Context budget (diff + files) < 500K chars.'],
+    },
+    {
+        name: 'suggest_search_replace',
+        purpose: 'Generate verbatim search/replace fix blocks for one finding.',
+        model: PRO_MODEL,
+        timeoutMs: DEFAULT_TIMEOUT_PRO_MS,
+        thinkingBudget: PRO_THINKING_BUDGET,
+        maxOutputTokens: PRO_PATCH_MAX_OUTPUT_TOKENS,
+        params: [
+            {
+                name: 'diff',
+                type: 'string',
+                required: true,
+                constraints: '10-120K chars',
+                description: 'Unified diff containing the target issue.',
+            },
+            {
+                name: 'findingTitle',
+                type: 'string',
+                required: true,
+                constraints: '3-160 chars',
+                description: 'Short finding title.',
+            },
+            {
+                name: 'findingDetails',
+                type: 'string',
+                required: true,
+                constraints: '10-3000 chars',
+                description: 'Detailed finding context.',
+            },
+        ],
+        outputShape: '{summary, blocks[], validationChecklist[]}',
+        gotchas: [
+            'One finding per call to avoid mixed patch intent.',
+            'search must be exact whitespace-preserving match.',
+        ],
+        crossToolFlow: [
+            'Consumes findings from inspect_code_quality for targeted fixes.',
+        ],
+        constraints: ['One finding per call; verbatim search match required.'],
+    },
+    {
+        name: 'generate_test_plan',
+        purpose: 'Generate prioritized test cases and coverage guidance.',
+        model: FLASH_MODEL,
+        timeoutMs: DEFAULT_TIMEOUT_FLASH_MS,
+        thinkingBudget: FLASH_THINKING_BUDGET,
+        maxOutputTokens: FLASH_TEST_PLAN_MAX_OUTPUT_TOKENS,
+        params: [
+            {
+                name: 'diff',
+                type: 'string',
+                required: true,
+                constraints: '10-120K chars',
+                description: 'Unified diff text.',
+            },
+            {
+                name: 'repository',
+                type: 'string',
+                required: true,
+                constraints: '1-200 chars',
+                description: 'Repository identifier (org/repo).',
+            },
+            {
+                name: 'language',
+                type: 'string',
+                required: false,
+                constraints: '2-32 chars',
+                description: 'Primary language hint.',
+            },
+            {
+                name: 'testFramework',
+                type: 'string',
+                required: false,
+                constraints: '1-50 chars',
+                description: 'Framework hint (jest, vitest, pytest, node:test).',
+            },
+            {
+                name: 'maxTestCases',
+                type: 'number',
+                required: false,
+                constraints: '1-30',
+                description: 'Post-generation cap applied to test cases.',
+            },
+        ],
+        outputShape: '{summary, testCases[], coverageSummary}',
+        gotchas: ['maxTestCases caps output after generation.'],
+        crossToolFlow: [
+            'Pair with inspect_code_quality to validate high-risk paths.',
+        ],
+    },
+    {
+        name: 'analyze_time_space_complexity',
+        purpose: 'Analyze Big-O complexity and detect degradations in changed code.',
+        model: FLASH_MODEL,
+        timeoutMs: DEFAULT_TIMEOUT_FLASH_MS,
+        thinkingBudget: FLASH_THINKING_BUDGET,
+        maxOutputTokens: FLASH_COMPLEXITY_MAX_OUTPUT_TOKENS,
+        params: [
+            {
+                name: 'diff',
+                type: 'string',
+                required: true,
+                constraints: '10-120K chars',
+                description: 'Unified diff text.',
+            },
+            {
+                name: 'language',
+                type: 'string',
+                required: false,
+                constraints: '2-32 chars',
+                description: 'Primary language hint.',
+            },
+        ],
+        outputShape: '{timeComplexity, spaceComplexity, explanation, potentialBottlenecks[], isDegradation}',
+        gotchas: ['Analyzes only changed code visible in the diff.'],
+        crossToolFlow: ['Use for algorithmic/performance-sensitive changes.'],
+    },
+    {
+        name: 'detect_api_breaking_changes',
+        purpose: 'Detect breaking API/interface changes in a diff.',
+        model: FLASH_MODEL,
+        timeoutMs: DEFAULT_TIMEOUT_FLASH_MS,
+        maxOutputTokens: FLASH_API_BREAKING_MAX_OUTPUT_TOKENS,
+        params: [
+            {
+                name: 'diff',
+                type: 'string',
+                required: true,
+                constraints: '10-120K chars',
+                description: 'Unified diff text.',
+            },
+            {
+                name: 'language',
+                type: 'string',
+                required: false,
+                constraints: '2-32 chars',
+                description: 'Primary language hint.',
+            },
+        ],
+        outputShape: '{hasBreakingChanges, breakingChanges[]}',
+        gotchas: ['Targets public API contracts over internal refactors.'],
+        crossToolFlow: ['Run before merge for API-surface-sensitive changes.'],
+    },
+];
+const TOOL_CONTRACTS_BY_NAME = new Map(TOOL_CONTRACTS.map((contract) => [contract.name, contract]));
+export function getToolContracts() {
+    return TOOL_CONTRACTS;
+}
+export function getToolContract(toolName) {
+    return TOOL_CONTRACTS_BY_NAME.get(toolName);
+}
+export function requireToolContract(toolName) {
+    const contract = getToolContract(toolName);
+    if (contract) {
+        return contract;
+    }
+    throw new Error(`Unknown tool contract: ${toolName}`);
+}
+export function getToolContractNames() {
+    return TOOL_CONTRACTS.map((contract) => contract.name);
+}

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

@@ -31,8 +31,12 @@ export interface StructuredToolTaskConfig<TInput extends object = Record<string,
     model?: string;
     /** Optional thinking budget in tokens. */
     thinkingBudget?: number;
-    /** Optional timeout in ms for the Gemini call. Defaults to 60,000 ms. Use DEFAULT_TIMEOUT_PRO_MS for Pro model calls. */
+    /** Optional timeout in ms for the Gemini call. Defaults to 90,000 ms. Use DEFAULT_TIMEOUT_PRO_MS for Pro model calls. */
     timeoutMs?: number;
+    /** Optional max output tokens for Gemini. */
+    maxOutputTokens?: number;
+    /** Optional opt-in to Gemini thought output. Defaults to false. */
+    includeThoughts?: boolean;
     /** Optional formatter for human-readable text output. */
     formatOutput?: (result: TFinal) => string;
     /** Optional context text used in progress messages. */

package/dist/lib/tool-factory.js

@@ -12,6 +12,7 @@ const CANCELLED_ERROR_PATTERN = /cancelled|canceled/i;
 const TIMEOUT_ERROR_PATTERN = /timed out|timeout/i;
 const BUDGET_ERROR_PATTERN = /exceeds limit|max allowed size|input too large/i;
 const BUSY_ERROR_PATTERN = /too many concurrent/i;
+const MAX_SCHEMA_RETRIES = 1;
 function createGeminiResponseSchema(config) {
     const sourceSchema = config.geminiSchema ?? config.resultSchema;
     return stripJsonSchemaConstraints(z.toJSONSchema(sourceSchema));
@@ -35,6 +36,12 @@ function createGenerationRequest(config, promptParts, responseSchema, onLog, sig
     if (config.timeoutMs !== undefined) {
         request.timeoutMs = config.timeoutMs;
     }
+    if (config.maxOutputTokens !== undefined) {
+        request.maxOutputTokens = config.maxOutputTokens;
+    }
+    if (config.includeThoughts !== undefined) {
+        request.includeThoughts = config.includeThoughts;
+    }
     if (signal !== undefined) {
         request.signal = signal;
     }
@@ -65,13 +72,7 @@ function classifyErrorMeta(error, message) {
             retryable: false,
         };
     }
-    if (RETRYABLE_UPSTREAM_ERROR_PATTERN.test(message)) {
-        return {
-            kind: 'upstream',
-            retryable: true,
-        };
-    }
-    if (BUSY_ERROR_PATTERN.test(message)) {
+    if (isRetryableUpstreamMessage(message)) {
         return {
             kind: 'upstream',
             retryable: true,
@@ -82,6 +83,10 @@ function classifyErrorMeta(error, message) {
         retryable: false,
     };
 }
+function isRetryableUpstreamMessage(message) {
+    return (RETRYABLE_UPSTREAM_ERROR_PATTERN.test(message) ||
+        BUSY_ERROR_PATTERN.test(message));
+}
 async function sendTaskProgress(extra, payload) {
     const progressToken = extra._meta?.progressToken;
     if (typeof progressToken !== 'string' && typeof progressToken !== 'number') {
@@ -118,11 +123,14 @@ function createProgressReporter(extra) {
         const total = payload.total !== undefined
             ? Math.max(payload.total, current)
             : undefined;
-        await sendTaskProgress(extra, {
-            current,
-            ...(total !== undefined ? { total } : {}),
-            ...(payload.message !== undefined ? { message: payload.message } : {}),
-        });
+        const progressPayload = { current };
+        if (total !== undefined) {
+            progressPayload.total = total;
+        }
+        if (payload.message !== undefined) {
+            progressPayload.message = payload.message;
+        }
+        await sendTaskProgress(extra, progressPayload);
         lastCurrent = current;
         if (total !== undefined && total === current) {
             didSendTerminal = true;
@@ -140,7 +148,7 @@ function normalizeProgressContext(context) {
     return `${compact.slice(0, 77)}...`;
 }
 function formatProgressStep(toolName, context, metadata) {
-    const prefix = metadata === 'start' ? '▸' : '◆';
+    const prefix = metadata === 'starting' ? '▸' : '◦';
     return `${prefix} ${toolName}: ${context} [${metadata}]`;
 }
 function friendlyModelName(model) {
@@ -153,9 +161,23 @@ function friendlyModelName(model) {
     return 'model';
 }
 function formatProgressCompletion(toolName, context, outcome, success = true) {
-    const prefix = success ? '◈' : '‣';
+    const prefix = success ? '◆' : '◇';
     return `${prefix} ${toolName}: ${context} • ${outcome}`;
 }
+async function reportProgressStepUpdate(reportProgress, toolName, context, current, metadata) {
+    await reportProgress({
+        current,
+        total: TASK_PROGRESS_TOTAL,
+        message: formatProgressStep(toolName, context, metadata),
+    });
+}
+async function reportProgressCompletionUpdate(reportProgress, toolName, context, outcome, success = true) {
+    await reportProgress({
+        current: TASK_PROGRESS_TOTAL,
+        total: TASK_PROGRESS_TOTAL,
+        message: formatProgressCompletion(toolName, context, outcome, success),
+    });
+}
 function toLoggingLevel(level) {
     switch (level) {
         case 'debug':
@@ -207,6 +229,7 @@ export function registerStructuredToolTask(server, config) {
         outputSchema: DefaultOutputSchema,
         annotations: {
             readOnlyHint: true,
+            idempotentHint: true,
             openWorldHint: true,
         },
     }, {
@@ -237,52 +260,31 @@ export function registerStructuredToolTask(server, config) {
                     const onLog = createGeminiLogger(server, task.taskId);
                     const inputRecord = parseToolInput(input, config.fullInputSchema);
                     progressContext = normalizeProgressContext(config.progressContext?.(inputRecord));
-                    await reportProgress({
-                        current: 0,
-                        total: TASK_PROGRESS_TOTAL,
-                        message: formatProgressStep(config.name, progressContext, 'starting'),
-                    });
+                    await reportProgressStepUpdate(reportProgress, config.name, progressContext, 0, 'starting');
                     if (config.validateInput) {
                         const validationError = await config.validateInput(inputRecord);
                         if (validationError) {
                             const validationMessage = validationError.structuredContent.error?.message ??
                                 INPUT_VALIDATION_FAILED;
                             await updateStatusMessage(validationMessage);
-                            await reportProgress({
-                                current: TASK_PROGRESS_TOTAL,
-                                total: TASK_PROGRESS_TOTAL,
-                                message: formatProgressCompletion(config.name, progressContext, 'rejected', false),
-                            });
+                            await reportProgressCompletionUpdate(reportProgress, config.name, progressContext, 'rejected', false);
                             await storeResultSafely('completed', validationError);
                             return;
                         }
                     }
-                    await reportProgress({
-                        current: 1,
-                        total: TASK_PROGRESS_TOTAL,
-                        message: formatProgressStep(config.name, progressContext, 'preparing'),
-                    });
+                    await reportProgressStepUpdate(reportProgress, config.name, progressContext, 1, 'preparing');
                     const promptParts = config.buildPrompt(inputRecord);
-                    let { prompt } = promptParts;
+                    const { prompt } = promptParts;
                     const { systemInstruction } = promptParts;
                     const modelLabel = friendlyModelName(config.model);
-                    await reportProgress({
-                        current: 2,
-                        total: TASK_PROGRESS_TOTAL,
-                        message: formatProgressStep(config.name, progressContext, `awaiting ${modelLabel}`),
-                    });
-                    const MAX_SCHEMA_RETRIES = 1;
-                    let raw;
+                    await reportProgressStepUpdate(reportProgress, config.name, progressContext, 2, modelLabel);
                     let parsed;
+                    let retryPrompt = prompt;
                     for (let attempt = 0; attempt <= MAX_SCHEMA_RETRIES; attempt += 1) {
                         try {
-                            raw = await generateStructuredJson(createGenerationRequest(config, { systemInstruction, prompt }, responseSchema, onLog, extra.signal));
+                            const raw = await generateStructuredJson(createGenerationRequest(config, { systemInstruction, prompt: retryPrompt }, responseSchema, onLog, extra.signal));
                             if (attempt === 0) {
-                                await reportProgress({
-                                    current: 3,
-                                    total: TASK_PROGRESS_TOTAL,
-                                    message: formatProgressStep(config.name, progressContext, 'processing response'),
-                                });
+                                await reportProgressStepUpdate(reportProgress, config.name, progressContext, 3, 'processing response');
                             }
                             parsed = config.resultSchema.parse(raw);
                             break;
@@ -297,7 +299,7 @@ export function registerStructuredToolTask(server, config) {
                                 event: 'schema_validation_failed',
                                 details: { attempt, error: errorMessage },
                             });
-                            prompt += `\n\nCRITICAL: The previous response was invalid JSON schema. Error: ${errorMessage}. Please fix and return valid JSON matching the schema.`;
+                            retryPrompt = `${prompt}\n\nCRITICAL: The previous response failed schema validation. Error: ${errorMessage}`;
                         }
                     }
                     if (!parsed) {
@@ -310,11 +312,7 @@ export function registerStructuredToolTask(server, config) {
                         ? config.formatOutput(finalResult)
                         : undefined;
                     const outcome = config.formatOutcome?.(finalResult) ?? 'completed';
-                    await reportProgress({
-                        current: TASK_PROGRESS_TOTAL,
-                        total: TASK_PROGRESS_TOTAL,
-                        message: formatProgressCompletion(config.name, progressContext, outcome),
-                    });
+                    await reportProgressCompletionUpdate(reportProgress, config.name, progressContext, outcome);
                     await storeResultSafely('completed', createToolResponse({
                         ok: true,
                         result: finalResult,
@@ -323,11 +321,7 @@ export function registerStructuredToolTask(server, config) {
                 catch (error) {
                     const errorMessage = getErrorMessage(error);
                     const errorMeta = classifyErrorMeta(error, errorMessage);
-                    await reportProgress({
-                        current: TASK_PROGRESS_TOTAL,
-                        total: TASK_PROGRESS_TOTAL,
-                        message: formatProgressCompletion(config.name, progressContext, 'failed', false),
-                    });
+                    await reportProgressCompletionUpdate(reportProgress, config.name, progressContext, 'failed', false);
                     await updateStatusMessage(errorMessage);
                     await storeResultSafely('failed', createErrorToolResponse(config.errorCode, errorMessage, undefined, errorMeta));
                 }

package/dist/lib/tool-response.js

@@ -1,3 +1,11 @@
+function appendErrorMeta(error, meta) {
+    if (meta?.retryable !== undefined) {
+        error.retryable = meta.retryable;
+    }
+    if (meta?.kind !== undefined) {
+        error.kind = meta.kind;
+    }
+}
 function toTextContent(structured, textContent) {
     const text = textContent ?? JSON.stringify(structured);
     return [{ type: 'text', text }];
@@ -13,12 +21,7 @@ function createErrorStructuredContent(code, message, result, meta) {
         code,
         message,
     };
-    if (meta?.retryable !== undefined) {
-        error.retryable = meta.retryable;
-    }
-    if (meta?.kind !== undefined) {
-        error.kind = meta.kind;
-    }
+    appendErrorMeta(error, meta);
     if (result === undefined) {
         return { ok: false, error };
     }
@@ -29,10 +32,5 @@ export function createToolResponse(structured, textContent) {
 }
 export function createErrorToolResponse(code, message, result, meta) {
     const structured = createErrorStructuredContent(code, message, result, meta);
-    const base = buildToolResponse(structured);
-    return {
-        content: base.content,
-        structuredContent: base.structuredContent,
-        isError: true,
-    };
+    return { ...buildToolResponse(structured), isError: true };
 }

package/dist/lib/types.d.ts

@@ -1,11 +1,12 @@
 export type JsonObject = Record<string, unknown>;
 export type GeminiLogHandler = (level: string, data: unknown) => Promise<void>;
-interface GeminiRequestExecutionOptions {
+export interface GeminiRequestExecutionOptions {
     maxRetries?: number;
     timeoutMs?: number;
     temperature?: number;
     maxOutputTokens?: number;
     thinkingBudget?: number;
+    includeThoughts?: boolean;
     signal?: AbortSignal;
     onLog?: GeminiLogHandler;
 }
@@ -15,6 +16,5 @@ export interface GeminiStructuredRequestOptions extends GeminiRequestExecutionOp
 export interface GeminiStructuredRequest extends GeminiStructuredRequestOptions {
     systemInstruction?: string;
     prompt: string;
-    responseSchema: JsonObject;
+    responseSchema: Readonly<JsonObject>;
 }
-export {};