@j0hanz/code-review-analyst-mcp 1.0.2 → 1.1.0

package/dist/index.js

@@ -4,6 +4,11 @@ import { parseArgs } from 'node:util';
 import { getErrorMessage } from './lib/errors.js';
 import { createServer } from './server.js';
 const SHUTDOWN_SIGNALS = ['SIGINT', 'SIGTERM'];
+function setEnvFromArg(name, value) {
+    if (typeof value === 'string') {
+        process.env[name] = value;
+    }
+}
 function parseCommandLineArgs() {
     const { values } = parseArgs({
         args: process.argv.slice(2),
@@ -18,12 +23,8 @@ function parseCommandLineArgs() {
         },
         strict: false,
     });
-    if (typeof values.model === 'string') {
-        process.env.GEMINI_MODEL = values.model;
-    }
-    if (typeof values['max-diff-chars'] === 'string') {
-        process.env.MAX_DIFF_CHARS = values['max-diff-chars'];
-    }
+    setEnvFromArg('GEMINI_MODEL', values.model);
+    setEnvFromArg('MAX_DIFF_CHARS', values['max-diff-chars']);
 }
 let shuttingDown = false;
 async function shutdown(server) {

package/dist/instructions.md

@@ -67,7 +67,7 @@ These instructions are available as a resource (internal://instructions) or prom
 
 - Purpose: Generate structured review findings, overall risk, and test recommendations from a unified diff.
 - Input: `maxFindings` defaults to 10; `focusAreas` defaults to security/correctness/regressions/performance when omitted.
-- Output: `ok/result/error` envelope; successful payload follows `ReviewDiffResultSchema` and includes `summary`, `overallRisk`, `findings`, and `testsNeeded`.
+- Output: `ok/result/error` envelope; successful payload includes `summary`, `overallRisk`, `findings[]`, and `testsNeeded[]`.
 - Gotcha: Schema allows `diff` up to 400,000 chars, but runtime rejects payloads above `MAX_DIFF_CHARS` (default 120,000) with `E_INPUT_TOO_LARGE`.
 - Side effects: Calls external Gemini API (`openWorldHint: true`); does not mutate local state (`readOnlyHint: true`).
 
@@ -75,7 +75,7 @@ These instructions are available as a resource (internal://instructions) or prom
 
 - Purpose: Produce deployment risk score and rationale for release decisions.
 - Input: `deploymentCriticality` defaults to `medium` when omitted.
-- Output: `ok/result/error` envelope; successful payload includes `score`, `bucket`, and `rationale`.
+- Output: `ok/result/error` envelope; successful payload includes `score`, `bucket`, and `rationale[]`.
 - Gotcha: Uses the same runtime diff budget guard as other tools; oversized inputs fail before model execution.
 - Side effects: External Gemini call only.
 
@@ -83,7 +83,7 @@ These instructions are available as a resource (internal://instructions) or prom
 
 - Purpose: Generate a focused unified diff patch for one selected review finding.
 - Input: `patchStyle` defaults to `balanced`; requires both `findingTitle` and `findingDetails`.
-- Output: `ok/result/error` envelope; successful payload includes `summary`, `patch`, and `validationChecklist`.
+- Output: `ok/result/error` envelope; successful payload includes `summary`, `patch`, and `validationChecklist[]`.
 - Gotcha: Output is model-generated text and must be validated before application.
 - Side effects: External Gemini call only.
 
@@ -104,7 +104,7 @@ These instructions are available as a resource (internal://instructions) or prom
 - API credentials: Require `GEMINI_API_KEY` or `GOOGLE_API_KEY`.
 - Model selection: Uses `GEMINI_MODEL` if set; defaults to `gemini-2.5-flash`.
 - Diff size: Runtime limit defaults to 120,000 chars (`MAX_DIFF_CHARS` env override). Input schema max is 400,000 chars.
-- Timeout/retries: Per-call timeout defaults to 30,000 ms; retry count defaults to 1 with exponential backoff.
+- Timeout/retries: Per-call timeout defaults to 45,000 ms; retry count defaults to 1 with exponential backoff.
 - Output tokens: `maxOutputTokens` defaults to 16,384 to prevent unbounded responses.
 - Safety config: Gemini safety thresholds default to `BLOCK_NONE` for configured harm categories and can be overridden with `GEMINI_HARM_BLOCK_THRESHOLD` (`BLOCK_NONE`, `BLOCK_ONLY_HIGH`, `BLOCK_MEDIUM_AND_ABOVE`, `BLOCK_LOW_AND_ABOVE`).
 - Resource scope: Only `internal://instructions` is registered as a resource; no dynamic resource templates are exposed.
@@ -122,5 +122,3 @@ These instructions are available as a resource (internal://instructions) or prom
 - Gemini timeout message (`Gemini request timed out after ...ms.`): Request exceeded timeout budget. → Reduce prompt/diff size or increase `timeoutMs` in caller.
 - Empty model body (`Gemini returned an empty response body.`): Provider returned no text payload. → Retry and inspect model/service status.
 - JSON parse failure from model output (wrapped by tool error codes): Output was not valid JSON. → Retry with same schema; inspect logs for malformed response text.
-
----

package/dist/lib/diff-budget.js

@@ -2,22 +2,28 @@ import { createErrorToolResponse } from './tool-response.js';
 const DEFAULT_MAX_DIFF_CHARS = 120_000;
 const MAX_DIFF_CHARS_ENV_VAR = 'MAX_DIFF_CHARS';
 const numberFormatter = new Intl.NumberFormat('en-US');
-function formatNumber(value) {
-    return numberFormatter.format(value);
-}
-function getPositiveIntEnv(name) {
-    const parsed = Number.parseInt(process.env[name] ?? '', 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+// Lazy-cached: first call happens after parseCommandLineArgs() sets MAX_DIFF_CHARS.
+let _maxDiffChars;
+function parsePositiveInteger(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return undefined;
+    }
+    return parsed;
 }
 function getMaxDiffChars() {
-    return getPositiveIntEnv(MAX_DIFF_CHARS_ENV_VAR) ?? DEFAULT_MAX_DIFF_CHARS;
+    if (_maxDiffChars !== undefined)
+        return _maxDiffChars;
+    const value = parsePositiveInteger(process.env[MAX_DIFF_CHARS_ENV_VAR] ?? '') ??
+        DEFAULT_MAX_DIFF_CHARS;
+    _maxDiffChars = value;
+    return value;
 }
 export function exceedsDiffBudget(diff) {
     return diff.length > getMaxDiffChars();
 }
 export function getDiffBudgetError(diffLength) {
-    const maxDiffChars = getMaxDiffChars();
-    return `diff exceeds max allowed size (${formatNumber(diffLength)} chars > ${formatNumber(maxDiffChars)} chars)`;
+    return `diff exceeds max allowed size (${numberFormatter.format(diffLength)} chars > ${numberFormatter.format(getMaxDiffChars())} chars)`;
 }
 export function validateDiffBudget(diff) {
     if (!exceedsDiffBudget(diff)) {

package/dist/lib/errors.js

@@ -1,4 +1,7 @@
 import { inspect } from 'node:util';
+function isString(value) {
+    return typeof value === 'string';
+}
 function isErrorWithMessage(error) {
     return (typeof error === 'object' &&
         error !== null &&
@@ -9,7 +12,7 @@ export function getErrorMessage(error) {
     if (isErrorWithMessage(error)) {
         return error.message;
     }
-    if (typeof error === 'string') {
+    if (isString(error)) {
         return error;
     }
     return inspect(error, { depth: 3, breakLength: 120 });

package/dist/lib/gemini-schema.js

@@ -15,6 +15,9 @@ const CONSTRAINT_KEYS = new Set([
     'maxItems',
     'multipleOf',
 ]);
+function isJsonRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
  * Recursively strips value-range constraints (`min*`, `max*`, `multipleOf`)
  * from a JSON Schema object and converts `"type": "integer"` to
@@ -36,11 +39,9 @@ export function stripJsonSchemaConstraints(schema) {
             continue;
         }
         if (Array.isArray(value)) {
-            result[key] = value.map((item) => typeof item === 'object' && item !== null && !Array.isArray(item)
-                ? stripJsonSchemaConstraints(item)
-                : item);
+            result[key] = value.map((item) => isJsonRecord(item) ? stripJsonSchemaConstraints(item) : item);
         }
-        else if (typeof value === 'object' && value !== null) {
+        else if (isJsonRecord(value)) {
             result[key] = stripJsonSchemaConstraints(value);
         }
         else {

package/dist/lib/gemini.js

@@ -3,18 +3,33 @@ import { randomInt, randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import { performance } from 'node:perf_hooks';
 import { setTimeout as sleep } from 'node:timers/promises';
+import { debuglog } from 'node:util';
 import { GoogleGenAI, HarmBlockThreshold, HarmCategory } from '@google/genai';
 import { getErrorMessage } from './errors.js';
+// Lazy-cached: first call happens after parseCommandLineArgs() sets GEMINI_MODEL.
+let _defaultModel;
 function getDefaultModel() {
-    return process.env.GEMINI_MODEL ?? 'gemini-2.5-flash';
+    if (_defaultModel !== undefined)
+        return _defaultModel;
+    const value = process.env.GEMINI_MODEL ?? 'gemini-2.5-flash';
+    _defaultModel = value;
+    return value;
 }
 const DEFAULT_MAX_RETRIES = 1;
-const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_TIMEOUT_MS = 45_000;
 const DEFAULT_MAX_OUTPUT_TOKENS = 16_384;
 const RETRY_DELAY_BASE_MS = 300;
 const RETRY_DELAY_MAX_MS = 5_000;
 const RETRY_JITTER_RATIO = 0.2;
 const DEFAULT_SAFETY_THRESHOLD = HarmBlockThreshold.BLOCK_NONE;
+const RETRYABLE_NUMERIC_CODES = new Set([429, 500, 502, 503, 504]);
+const RETRYABLE_TRANSIENT_CODES = new Set([
+    'RESOURCE_EXHAUSTED',
+    'UNAVAILABLE',
+    'DEADLINE_EXCEEDED',
+    'INTERNAL',
+    'ABORTED',
+]);
 const numberFormatter = new Intl.NumberFormat('en-US');
 function formatNumber(value) {
     return numberFormatter.format(value);
@@ -25,14 +40,32 @@ const SAFETY_THRESHOLD_BY_NAME = {
     BLOCK_MEDIUM_AND_ABOVE: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
     BLOCK_LOW_AND_ABOVE: HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
 };
+function getSafetyThreshold() {
+    const threshold = process.env.GEMINI_HARM_BLOCK_THRESHOLD;
+    if (!threshold) {
+        return DEFAULT_SAFETY_THRESHOLD;
+    }
+    const normalizedThreshold = threshold.trim().toUpperCase();
+    if (normalizedThreshold in SAFETY_THRESHOLD_BY_NAME) {
+        return SAFETY_THRESHOLD_BY_NAME[normalizedThreshold];
+    }
+    return DEFAULT_SAFETY_THRESHOLD;
+}
 let cachedClient;
 export const geminiEvents = new EventEmitter();
+const debug = debuglog('gemini');
 geminiEvents.on('log', (payload) => {
-    console.error(JSON.stringify(payload));
+    debug(JSON.stringify(payload));
 });
 const geminiContext = new AsyncLocalStorage({
     name: 'gemini_request',
+    defaultValue: { requestId: 'unknown', model: 'unknown' },
 });
+// Shared fallback avoids a fresh object allocation per logEvent call when outside a run context.
+const UNKNOWN_CONTEXT = {
+    requestId: 'unknown',
+    model: 'unknown',
+};
 function getApiKey() {
     const apiKey = process.env.GEMINI_API_KEY ?? process.env.GOOGLE_API_KEY;
     if (!apiKey) {
@@ -51,14 +84,22 @@ function nextRequestId() {
     return randomUUID();
 }
 function logEvent(event, details) {
-    const context = geminiContext.getStore();
+    const context = geminiContext.getStore() ?? UNKNOWN_CONTEXT;
     geminiEvents.emit('log', {
         event,
-        requestId: context?.requestId ?? null,
-        model: context?.model ?? null,
+        requestId: context.requestId,
+        model: context.model,
         ...details,
     });
 }
+async function safeCallOnLog(onLog, level, data) {
+    try {
+        await onLog?.(level, data);
+    }
+    catch {
+        // Log callbacks are best-effort; never fail the tool call.
+    }
+}
 function getNestedError(error) {
     if (!error || typeof error !== 'object') {
         return undefined;
@@ -101,19 +142,12 @@ function getTransientErrorCode(error) {
 }
 function shouldRetry(error) {
     const numericCode = getNumericErrorCode(error);
-    if (numericCode === 429 ||
-        numericCode === 500 ||
-        numericCode === 502 ||
-        numericCode === 503 ||
-        numericCode === 504) {
+    if (numericCode !== undefined && RETRYABLE_NUMERIC_CODES.has(numericCode)) {
         return true;
     }
     const transientCode = getTransientErrorCode(error);
-    if (transientCode === 'RESOURCE_EXHAUSTED' ||
-        transientCode === 'UNAVAILABLE' ||
-        transientCode === 'DEADLINE_EXCEEDED' ||
-        transientCode === 'INTERNAL' ||
-        transientCode === 'ABORTED') {
+    if (transientCode !== undefined &&
+        RETRYABLE_TRANSIENT_CODES.has(transientCode)) {
         return true;
     }
     const message = getErrorMessage(error);
@@ -126,17 +160,6 @@ function getRetryDelayMs(attempt) {
     const jitter = randomInt(0, jitterWindow);
     return Math.min(RETRY_DELAY_MAX_MS, boundedDelay + jitter);
 }
-function getSafetyThreshold() {
-    const threshold = process.env.GEMINI_HARM_BLOCK_THRESHOLD;
-    if (!threshold) {
-        return DEFAULT_SAFETY_THRESHOLD;
-    }
-    const normalizedThreshold = threshold.trim().toUpperCase();
-    if (normalizedThreshold in SAFETY_THRESHOLD_BY_NAME) {
-        return SAFETY_THRESHOLD_BY_NAME[normalizedThreshold];
-    }
-    return DEFAULT_SAFETY_THRESHOLD;
-}
 function buildGenerationConfig(request, abortSignal) {
     const safetyThreshold = getSafetyThreshold();
     return {
@@ -144,9 +167,10 @@ function buildGenerationConfig(request, abortSignal) {
         maxOutputTokens: request.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
         responseMimeType: 'application/json',
         responseSchema: request.responseSchema,
+        // Spread undefined instead of {} so no intermediate object is allocated when absent.
         ...(request.systemInstruction
             ? { systemInstruction: request.systemInstruction }
-            : {}),
+            : undefined),
         safetySettings: [
             {
                 category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
@@ -168,15 +192,16 @@ function buildGenerationConfig(request, abortSignal) {
         abortSignal,
     };
 }
+function combineSignals(signal, requestSignal) {
+    return requestSignal ? AbortSignal.any([signal, requestSignal]) : signal;
+}
 async function generateContentWithTimeout(request, model, timeoutMs) {
     const controller = new AbortController();
     const timeout = setTimeout(() => {
         controller.abort();
     }, timeoutMs);
     timeout.unref();
-    const signal = request.signal
-        ? AbortSignal.any([controller.signal, request.signal])
-        : controller.signal;
+    const signal = combineSignals(controller.signal, request.signal);
     try {
         return await getClient().models.generateContent({
             model,
@@ -189,7 +214,7 @@ async function generateContentWithTimeout(request, model, timeoutMs) {
             throw new Error('Gemini request was cancelled.');
         }
         if (controller.signal.aborted) {
-            throw new Error(`Gemini request timed out after ${formatNumber(timeoutMs)}ms.`);
+            throw new Error(`Gemini request timed out after ${formatNumber(timeoutMs)}ms.`, { cause: error });
         }
         throw error;
     }
@@ -201,15 +226,23 @@ export async function generateStructuredJson(request) {
     const model = request.model ?? getDefaultModel();
     const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const maxRetries = request.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const { onLog } = request;
     return geminiContext.run({ requestId: nextRequestId(), model }, async () => {
         let lastError;
         for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
             const startedAt = performance.now();
             try {
                 const response = await generateContentWithTimeout(request, model, timeoutMs);
+                const latencyMs = Math.round(performance.now() - startedAt);
                 logEvent('gemini_call', {
                     attempt,
-                    latencyMs: Math.round(performance.now() - startedAt),
+                    latencyMs,
+                    usageMetadata: response.usageMetadata ?? null,
+                });
+                await safeCallOnLog(onLog, 'info', {
+                    event: 'gemini_call',
+                    attempt,
+                    latencyMs,
                     usageMetadata: response.usageMetadata ?? null,
                 });
                 if (!response.text) {
@@ -236,6 +269,12 @@ export async function generateStructuredJson(request) {
                     delayMs,
                     reason: getErrorMessage(error),
                 });
+                await safeCallOnLog(onLog, 'warning', {
+                    event: 'gemini_retry',
+                    attempt,
+                    delayMs,
+                    reason: getErrorMessage(error),
+                });
                 await sleep(delayMs, undefined, { ref: false });
             }
         }
@@ -243,6 +282,11 @@ export async function generateStructuredJson(request) {
             error: getErrorMessage(lastError),
             attempts: maxRetries + 1,
         });
-        throw new Error(`Gemini request failed after ${maxRetries + 1} attempts: ${getErrorMessage(lastError)}`);
+        await safeCallOnLog(onLog, 'error', {
+            event: 'gemini_failure',
+            error: getErrorMessage(lastError),
+            attempts: maxRetries + 1,
+        });
+        throw new Error(`Gemini request failed after ${maxRetries + 1} attempts: ${getErrorMessage(lastError)}`, { cause: lastError });
     });
 }

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

@@ -13,10 +13,10 @@ export interface StructuredToolTaskConfig<TInput extends object = Record<string,
     title: string;
     /** Short description of the tool's purpose. */
     description: string;
-    /** Zod shape object (e.g. `MySchema.shape`) used as the MCP input schema. */
+    /** Zod schema shape for the tool input. Used by the MCP SDK to strip unknown fields before the handler runs. */
     inputSchema: ZodRawShapeCompat;
-    /** Full Zod schema for runtime input re-validation (rejects unknown fields). */
-    fullInputSchema?: z.ZodType;
+    /** Zod schema for validating the complete tool input, including all expected fields. This is used within the handler to validate the actual input shape after the MCP SDK has stripped unknown fields. */
+    fullInputSchema: z.ZodType<TInput>;
     /** Zod schema for parsing and validating the Gemini structured response. */
     resultSchema: z.ZodType;
     /** Optional Zod schema used specifically for Gemini response validation. */

package/dist/lib/tool-factory.js

@@ -4,10 +4,18 @@ import { getErrorMessage } from './errors.js';
 import { stripJsonSchemaConstraints } from './gemini-schema.js';
 import { generateStructuredJson } from './gemini.js';
 import { createErrorToolResponse, createToolResponse, } from './tool-response.js';
+function createGeminiResponseSchema(config) {
+    const sourceSchema = config.geminiSchema ?? config.resultSchema;
+    return stripJsonSchemaConstraints(z.toJSONSchema(sourceSchema));
+}
+function parseToolInput(input, fullInputSchema) {
+    return fullInputSchema.parse(input);
+}
 export function registerStructuredToolTask(server, config) {
-    const responseSchema = config.geminiSchema
-        ? stripJsonSchemaConstraints(z.toJSONSchema(config.geminiSchema))
-        : stripJsonSchemaConstraints(z.toJSONSchema(config.resultSchema));
+    const responseSchema = createGeminiResponseSchema({
+        geminiSchema: config.geminiSchema,
+        resultSchema: config.resultSchema,
+    });
     server.experimental.tasks.registerToolTask(config.name, {
         title: config.title,
         description: config.description,
@@ -39,21 +47,34 @@ export function registerStructuredToolTask(server, config) {
                     // Progress is best-effort; never fail the tool call.
                 }
             };
+            const updateStatusMessage = async (message) => {
+                try {
+                    await extra.taskStore.updateTaskStatus(task.taskId, 'working', message);
+                }
+                catch {
+                    // statusMessage is best-effort; task may already be terminal.
+                }
+            };
             try {
-                const inputRecord = config.fullInputSchema
-                    ? config.fullInputSchema.parse(input)
-                    : input;
+                const onLog = async (level, data) => {
+                    try {
+                        await server.sendLoggingMessage({
+                            level: level,
+                            logger: 'gemini',
+                            data,
+                        });
+                    }
+                    catch {
+                        // Logging is best-effort; never fail the tool call.
+                    }
+                };
+                const inputRecord = parseToolInput(input, config.fullInputSchema);
                 if (config.validateInput) {
                     const validationError = await config.validateInput(inputRecord);
                     if (validationError) {
                         const validationMessage = validationError.structuredContent.error?.message ??
                             'Input validation failed';
-                        try {
-                            await extra.taskStore.updateTaskStatus(task.taskId, 'working', validationMessage);
-                        }
-                        catch {
-                            // statusMessage is best-effort; task may already be terminal.
-                        }
+                        await updateStatusMessage(validationMessage);
                         await extra.taskStore.storeTaskResult(task.taskId, 'failed', validationError);
                         return { task };
                     }
@@ -66,6 +87,7 @@ export function registerStructuredToolTask(server, config) {
                     prompt,
                     responseSchema,
                     signal: extra.signal,
+                    onLog,
                 });
                 await sendProgress(3, 4);
                 const parsed = config.resultSchema.parse(raw);
@@ -77,12 +99,7 @@ export function registerStructuredToolTask(server, config) {
             }
             catch (error) {
                 const errorMessage = getErrorMessage(error);
-                try {
-                    await extra.taskStore.updateTaskStatus(task.taskId, 'working', errorMessage);
-                }
-                catch {
-                    // statusMessage is best-effort; task may already be terminal.
-                }
+                await updateStatusMessage(errorMessage);
                 await extra.taskStore.storeTaskResult(task.taskId, 'failed', createErrorToolResponse(config.errorCode, errorMessage));
             }
             return { task };

package/dist/lib/tool-response.js

@@ -1,6 +1,12 @@
 function toTextContent(structured) {
     return [{ type: 'text', text: JSON.stringify(structured) }];
 }
+function createErrorStructuredContent(code, message, result) {
+    if (result === undefined) {
+        return { ok: false, error: { code, message } };
+    }
+    return { ok: false, error: { code, message }, result };
+}
 export function createToolResponse(structured) {
     return {
         content: toTextContent(structured),
@@ -8,11 +14,7 @@ export function createToolResponse(structured) {
     };
 }
 export function createErrorToolResponse(code, message, result) {
-    const structured = {
-        ok: false,
-        error: { code, message },
-        ...(result === undefined ? {} : { result }),
-    };
+    const structured = createErrorStructuredContent(code, message, result);
     return {
         content: toTextContent(structured),
         structuredContent: structured,

package/dist/lib/types.d.ts

@@ -1,15 +1,15 @@
 export type JsonObject = Record<string, unknown>;
-interface GeminiStructuredRequestOptions {
+export interface GeminiStructuredRequestOptions {
     model?: string;
     maxRetries?: number;
     timeoutMs?: number;
     temperature?: number;
     maxOutputTokens?: number;
     signal?: AbortSignal;
+    onLog?: (level: string, data: unknown) => Promise<void>;
 }
 export interface GeminiStructuredRequest extends GeminiStructuredRequestOptions {
     systemInstruction?: string;
     prompt: string;
     responseSchema: JsonObject;
 }
-export {};

package/dist/prompts/index.js

@@ -1,9 +1,51 @@
+import { completable } from '@modelcontextprotocol/sdk/server/completable.js';
+import { z } from 'zod';
+const HELP_PROMPT_NAME = 'get-help';
+const HELP_PROMPT_DESCRIPTION = 'Return the server usage instructions.';
+const REVIEW_GUIDE_PROMPT_NAME = 'review-guide';
+const REVIEW_GUIDE_PROMPT_DESCRIPTION = 'Guided workflow instructions for a specific code review tool and focus area.';
+const TOOLS = ['review_diff', 'risk_score', 'suggest_patch'];
+const FOCUS_AREAS = [
+    'security',
+    'correctness',
+    'performance',
+    'regressions',
+    'tests',
+];
+const TOOL_GUIDES = {
+    review_diff: 'Call `review_diff` with `diff` (unified diff text) and `repository` (org/repo). ' +
+        'Optional: `focusAreas` array and `maxFindings` cap. ' +
+        'Returns structured findings, overallRisk, and test recommendations.',
+    risk_score: 'Call `risk_score` with `diff`. Optional: `deploymentCriticality` (low, medium, high). ' +
+        'Returns a 0–100 score, bucket, and rationale for release gating.',
+    suggest_patch: 'First call `review_diff` to get findings. Then call `suggest_patch` with `diff`, ' +
+        '`findingTitle`, and `findingDetails` from one finding. ' +
+        'Optional: `patchStyle` (minimal, balanced, defensive). One finding per call.',
+};
+const FOCUS_AREA_GUIDES = {
+    security: 'Audit for injection vulnerabilities, insecure data handling, broken authentication, ' +
+        'cryptographic failures, and OWASP Top 10 issues.',
+    correctness: 'Check for logic errors, edge case mishandling, incorrect algorithm implementations, ' +
+        'and API contract violations.',
+    performance: 'Identify algorithmic complexity issues, unnecessary allocations, blocking I/O, ' +
+        'and database query inefficiencies.',
+    regressions: 'Look for changes that could break existing behavior, removed guards, altered return types, ' +
+        'or contract changes in public APIs.',
+    tests: 'Assess test coverage gaps, missing edge case tests, flaky test patterns, ' +
+        'and untested error paths.',
+};
+function getToolGuide(tool) {
+    return TOOL_GUIDES[tool] ?? `Use \`${tool}\` to analyze your code changes.`;
+}
+function getFocusAreaGuide(focusArea) {
+    return FOCUS_AREA_GUIDES[focusArea] ?? `Focus on ${focusArea} concerns.`;
+}
 export function registerAllPrompts(server, instructions) {
-    server.registerPrompt('get-help', {
+    server.registerPrompt(HELP_PROMPT_NAME, {
         title: 'Get Help',
         description: 'Return the server usage instructions.',
     }, () => ({
-        description: 'Server usage instructions',
+        description: HELP_PROMPT_DESCRIPTION,
         messages: [
             {
                 role: 'user',
@@ -14,4 +56,30 @@ export function registerAllPrompts(server, instructions) {
             },
         ],
     }));
+    server.registerPrompt(REVIEW_GUIDE_PROMPT_NAME, {
+        title: 'Review Guide',
+        description: REVIEW_GUIDE_PROMPT_DESCRIPTION,
+        argsSchema: {
+            tool: completable(z
+                .string()
+                .describe('Which review tool to use: review_diff, risk_score, or suggest_patch'), (value) => TOOLS.filter((t) => t.startsWith(value))),
+            focusArea: completable(z
+                .string()
+                .describe('Focus area: security, correctness, performance, regressions, or tests'), (value) => FOCUS_AREAS.filter((f) => f.startsWith(value))),
+        },
+    }, ({ tool, focusArea }) => ({
+        description: `Code review guide: ${tool} / ${focusArea}`,
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `# Code Review Guide\n\n` +
+                        `## Tool: \`${tool}\`\n${getToolGuide(tool)}\n\n` +
+                        `## Focus Area: ${focusArea}\n${getFocusAreaGuide(focusArea)}\n\n` +
+                        `> Tip: Run \`get-help\` for full server documentation.`,
+                },
+            },
+        ],
+    }));
 }

package/dist/resources/index.js

@@ -1,8 +1,11 @@
+const RESOURCE_ID = 'server-instructions';
+const RESOURCE_URI = 'internal://instructions';
+const RESOURCE_MIME_TYPE = 'text/markdown';
 export function registerAllResources(server, instructions) {
-    server.registerResource('server-instructions', 'internal://instructions', {
+    server.registerResource(RESOURCE_ID, RESOURCE_URI, {
         title: 'Server Instructions',
         description: 'Guidance for using the MCP tools effectively.',
-        mimeType: 'text/markdown',
+        mimeType: RESOURCE_MIME_TYPE,
         annotations: {
             audience: ['assistant'],
             priority: 0.8,
@@ -11,7 +14,7 @@ export function registerAllResources(server, instructions) {
         contents: [
             {
                 uri: uri.href,
-                mimeType: 'text/markdown',
+                mimeType: RESOURCE_MIME_TYPE,
                 text: instructions,
             },
         ],

package/dist/schemas/inputs.js

@@ -8,32 +8,18 @@ const INPUT_LIMITS = {
     findingTitle: { min: 3, max: 160 },
     findingDetails: { min: 10, max: 3_000 },
 };
+function createBoundedString(min, max, description) {
+    return z.string().min(min).max(max).describe(description);
+}
 function createDiffSchema(description) {
-    return z
-        .string()
-        .min(INPUT_LIMITS.diff.min)
-        .max(INPUT_LIMITS.diff.max)
-        .describe(description);
+    return createBoundedString(INPUT_LIMITS.diff.min, INPUT_LIMITS.diff.max, description);
 }
 export const ReviewDiffInputSchema = z.strictObject({
     diff: createDiffSchema('Unified diff text for one PR or commit.'),
-    repository: z
-        .string()
-        .min(INPUT_LIMITS.repository.min)
-        .max(INPUT_LIMITS.repository.max)
-        .describe('Repository identifier, for example org/repo.'),
-    language: z
-        .string()
-        .min(INPUT_LIMITS.language.min)
-        .max(INPUT_LIMITS.language.max)
-        .optional()
-        .describe('Primary implementation language to bias review depth.'),
+    repository: createBoundedString(INPUT_LIMITS.repository.min, INPUT_LIMITS.repository.max, 'Repository identifier, for example org/repo.'),
+    language: createBoundedString(INPUT_LIMITS.language.min, INPUT_LIMITS.language.max, 'Primary implementation language to bias review depth.').optional(),
     focusAreas: z
-        .array(z
-        .string()
-        .min(INPUT_LIMITS.focusArea.min)
-        .max(INPUT_LIMITS.focusArea.max)
-        .describe('Specific area to inspect, for example security or tests.'))
+        .array(createBoundedString(INPUT_LIMITS.focusArea.min, INPUT_LIMITS.focusArea.max, 'Specific area to inspect, for example security or tests.'))
         .min(1)
         .max(INPUT_LIMITS.focusArea.maxItems)
         .optional()
@@ -55,16 +41,8 @@ export const RiskScoreInputSchema = z.strictObject({
 });
 export const SuggestPatchInputSchema = z.strictObject({
     diff: createDiffSchema('Unified diff text that contains the issue to patch.'),
-    findingTitle: z
-        .string()
-        .min(INPUT_LIMITS.findingTitle.min)
-        .max(INPUT_LIMITS.findingTitle.max)
-        .describe('Short title of the finding that needs a patch.'),
-    findingDetails: z
-        .string()
-        .min(INPUT_LIMITS.findingDetails.min)
-        .max(INPUT_LIMITS.findingDetails.max)
-        .describe('Detailed explanation of the bug or risk.'),
+    findingTitle: createBoundedString(INPUT_LIMITS.findingTitle.min, INPUT_LIMITS.findingTitle.max, 'Short title of the finding that needs a patch.'),
+    findingDetails: createBoundedString(INPUT_LIMITS.findingDetails.min, INPUT_LIMITS.findingDetails.max, 'Detailed explanation of the bug or risk.'),
     patchStyle: z
         .enum(['minimal', 'balanced', 'defensive'])
         .optional()

package/dist/schemas/outputs.js

@@ -22,6 +22,9 @@ const OUTPUT_LIMITS = {
         checklist: { minItems: 1, maxItems: 12, itemMin: 6, itemMax: 300 },
     },
 };
+function createBoundedString(min, max, description) {
+    return z.string().min(min).max(max).describe(description);
+}
 export const DefaultOutputSchema = z.strictObject({
     ok: z.boolean().describe('Whether the tool completed successfully.'),
     result: z.unknown().optional().describe('Successful result payload.'),
@@ -49,28 +52,12 @@ export const ReviewFindingSchema = z.strictObject({
         .max(OUTPUT_LIMITS.reviewFinding.lineMax)
         .nullable()
         .describe('1-based line number when known, otherwise null.'),
-    title: z
-        .string()
-        .min(OUTPUT_LIMITS.reviewFinding.title.min)
-        .max(OUTPUT_LIMITS.reviewFinding.title.max)
-        .describe('Short finding title.'),
-    explanation: z
-        .string()
-        .min(OUTPUT_LIMITS.reviewFinding.text.min)
-        .max(OUTPUT_LIMITS.reviewFinding.text.max)
-        .describe('Why this issue matters.'),
-    recommendation: z
-        .string()
-        .min(OUTPUT_LIMITS.reviewFinding.text.min)
-        .max(OUTPUT_LIMITS.reviewFinding.text.max)
-        .describe('Concrete fix recommendation.'),
+    title: createBoundedString(OUTPUT_LIMITS.reviewFinding.title.min, OUTPUT_LIMITS.reviewFinding.title.max, 'Short finding title.'),
+    explanation: createBoundedString(OUTPUT_LIMITS.reviewFinding.text.min, OUTPUT_LIMITS.reviewFinding.text.max, 'Why this issue matters.'),
+    recommendation: createBoundedString(OUTPUT_LIMITS.reviewFinding.text.min, OUTPUT_LIMITS.reviewFinding.text.max, 'Concrete fix recommendation.'),
 });
 export const ReviewDiffResultSchema = z.strictObject({
-    summary: z
-        .string()
-        .min(OUTPUT_LIMITS.reviewDiffResult.summary.min)
-        .max(OUTPUT_LIMITS.reviewDiffResult.summary.max)
-        .describe('Short review summary.'),
+    summary: createBoundedString(OUTPUT_LIMITS.reviewDiffResult.summary.min, OUTPUT_LIMITS.reviewDiffResult.summary.max, 'Short review summary.'),
     overallRisk: z
         .enum(['low', 'medium', 'high'])
         .describe('Overall risk for merging this diff.'),
@@ -80,11 +67,7 @@ export const ReviewDiffResultSchema = z.strictObject({
         .max(OUTPUT_LIMITS.reviewDiffResult.findingsMax)
         .describe('Ordered list of findings, highest severity first.'),
     testsNeeded: z
-        .array(z
-        .string()
-        .min(OUTPUT_LIMITS.reviewDiffResult.testsNeeded.itemMin)
-        .max(OUTPUT_LIMITS.reviewDiffResult.testsNeeded.itemMax)
-        .describe('Test recommendation to reduce risk.'))
+        .array(createBoundedString(OUTPUT_LIMITS.reviewDiffResult.testsNeeded.itemMin, OUTPUT_LIMITS.reviewDiffResult.testsNeeded.itemMax, 'Test recommendation to reduce risk.'))
         .min(OUTPUT_LIMITS.reviewDiffResult.testsNeeded.minItems)
         .max(OUTPUT_LIMITS.reviewDiffResult.testsNeeded.maxItems)
         .describe('Targeted tests to add before merge.'),
@@ -100,32 +83,16 @@ export const RiskScoreResultSchema = z.strictObject({
         .enum(['low', 'medium', 'high', 'critical'])
         .describe('Risk bucket derived from score and criticality.'),
     rationale: z
-        .array(z
-        .string()
-        .min(OUTPUT_LIMITS.riskScoreResult.rationale.itemMin)
-        .max(OUTPUT_LIMITS.riskScoreResult.rationale.itemMax)
-        .describe('Reason that influenced the final score.'))
+        .array(createBoundedString(OUTPUT_LIMITS.riskScoreResult.rationale.itemMin, OUTPUT_LIMITS.riskScoreResult.rationale.itemMax, 'Reason that influenced the final score.'))
         .min(OUTPUT_LIMITS.riskScoreResult.rationale.minItems)
         .max(OUTPUT_LIMITS.riskScoreResult.rationale.maxItems)
         .describe('Evidence-based explanation for the score.'),
 });
 export const PatchSuggestionResultSchema = z.strictObject({
-    summary: z
-        .string()
-        .min(OUTPUT_LIMITS.patchSuggestionResult.summary.min)
-        .max(OUTPUT_LIMITS.patchSuggestionResult.summary.max)
-        .describe('Short patch strategy summary.'),
-    patch: z
-        .string()
-        .min(OUTPUT_LIMITS.patchSuggestionResult.patch.min)
-        .max(OUTPUT_LIMITS.patchSuggestionResult.patch.max)
-        .describe('Unified diff patch text.'),
+    summary: createBoundedString(OUTPUT_LIMITS.patchSuggestionResult.summary.min, OUTPUT_LIMITS.patchSuggestionResult.summary.max, 'Short patch strategy summary.'),
+    patch: createBoundedString(OUTPUT_LIMITS.patchSuggestionResult.patch.min, OUTPUT_LIMITS.patchSuggestionResult.patch.max, 'Unified diff patch text.'),
     validationChecklist: z
-        .array(z
-        .string()
-        .min(OUTPUT_LIMITS.patchSuggestionResult.checklist.itemMin)
-        .max(OUTPUT_LIMITS.patchSuggestionResult.checklist.itemMax)
-        .describe('Validation step after applying patch.'))
+        .array(createBoundedString(OUTPUT_LIMITS.patchSuggestionResult.checklist.itemMin, OUTPUT_LIMITS.patchSuggestionResult.checklist.itemMax, 'Validation step after applying patch.'))
         .min(OUTPUT_LIMITS.patchSuggestionResult.checklist.minItems)
         .max(OUTPUT_LIMITS.patchSuggestionResult.checklist.maxItems)
         .describe('Post-change validation actions.'),

package/dist/server.js

@@ -8,6 +8,9 @@ import { getErrorMessage } from './lib/errors.js';
 import { registerAllPrompts } from './prompts/index.js';
 import { registerAllResources } from './resources/index.js';
 import { registerAllTools } from './tools/index.js';
+const SERVER_NAME = 'code-review-analyst';
+const INSTRUCTIONS_FILENAME = 'instructions.md';
+const INSTRUCTIONS_FALLBACK = '(Instructions failed to load)';
 function isPackageJsonMetadata(value) {
     return (typeof value === 'object' &&
         value !== null &&
@@ -28,9 +31,6 @@ function parsePackageJson(packageJson, packageJsonPath) {
     }
     return parsed;
 }
-function extractVersion(packageJson, packageJsonPath) {
-    return parsePackageJson(packageJson, packageJsonPath).version;
-}
 function readPackageJson(packageJsonPath) {
     try {
         return readFileSync(packageJsonPath, 'utf8');
@@ -42,31 +42,35 @@ function readPackageJson(packageJsonPath) {
 function loadVersion() {
     const packageJsonPath = findPackageJSON(import.meta.url);
     if (!packageJsonPath) {
-        throw new Error('Unable to locate package.json for code-review-analyst.');
+        throw new Error(`Unable to locate package.json for ${SERVER_NAME}.`);
     }
-    return extractVersion(readPackageJson(packageJsonPath), packageJsonPath);
+    return parsePackageJson(readPackageJson(packageJsonPath), packageJsonPath)
+        .version;
 }
 const SERVER_VERSION = loadVersion();
 function loadInstructions() {
     const currentDir = dirname(fileURLToPath(import.meta.url));
+    const instructionsPath = join(currentDir, INSTRUCTIONS_FILENAME);
     try {
-        return readFileSync(join(currentDir, 'instructions.md'), 'utf8');
+        return readFileSync(instructionsPath, 'utf8');
     }
     catch (error) {
-        process.emitWarning(`Failed to load instructions.md: ${getErrorMessage(error)}`);
-        return '(Instructions failed to load)';
+        process.emitWarning(`Failed to load ${INSTRUCTIONS_FILENAME}: ${getErrorMessage(error)}`);
+        return INSTRUCTIONS_FALLBACK;
     }
 }
 const SERVER_INSTRUCTIONS = loadInstructions();
 const SERVER_TASK_STORE = new InMemoryTaskStore();
 export function createServer() {
     const server = new McpServer({
-        name: 'code-review-analyst',
+        name: SERVER_NAME,
         version: SERVER_VERSION,
     }, {
         instructions: SERVER_INSTRUCTIONS,
         taskStore: SERVER_TASK_STORE,
         capabilities: {
+            logging: {},
+            completions: {},
             tasks: {
                 list: {},
                 cancel: {},

package/dist/tools/review-diff.js

@@ -4,16 +4,17 @@ import { ReviewDiffInputSchema } from '../schemas/inputs.js';
 import { ReviewDiffResultSchema } from '../schemas/outputs.js';
 const DEFAULT_MAX_FINDINGS = 10;
 const DEFAULT_FOCUS_AREAS = 'security, correctness, regressions, performance';
+// Hoisted: avoids array allocation + join on every request.
+const SYSTEM_INSTRUCTION = 'You are a senior staff engineer performing pull request review.\nReturn strict JSON only with no markdown fences.';
+function joinPromptLines(lines) {
+    return lines.join('\n');
+}
 function buildReviewPrompt(input) {
     const focus = input.focusAreas?.length
         ? input.focusAreas.join(', ')
         : DEFAULT_FOCUS_AREAS;
     const maxFindings = input.maxFindings ?? DEFAULT_MAX_FINDINGS;
-    const systemInstruction = [
-        'You are a senior staff engineer performing pull request review.',
-        'Return strict JSON only with no markdown fences.',
-    ].join('\n');
-    const prompt = [
+    const prompt = joinPromptLines([
         `Repository: ${input.repository}`,
         `Primary language: ${input.language ?? 'not specified'}`,
         `Focus areas: ${focus}`,
@@ -23,8 +24,8 @@ function buildReviewPrompt(input) {
         '',
         'Unified diff:',
         input.diff,
-    ].join('\n');
-    return { systemInstruction, prompt };
+    ]);
+    return { systemInstruction: SYSTEM_INSTRUCTION, prompt };
 }
 export function registerReviewDiffTool(server) {
     registerStructuredToolTask(server, {

package/dist/tools/risk-score.js

@@ -3,20 +3,21 @@ import { registerStructuredToolTask, } from '../lib/tool-factory.js';
 import { RiskScoreInputSchema } from '../schemas/inputs.js';
 import { RiskScoreResultSchema } from '../schemas/outputs.js';
 const DEFAULT_DEPLOYMENT_CRITICALITY = 'medium';
+// Hoisted: avoids array allocation + join on every request.
+const SYSTEM_INSTRUCTION = 'You are assessing software deployment risk from a code diff.\nReturn strict JSON only, no markdown fences.';
+function joinPromptLines(lines) {
+    return lines.join('\n');
+}
 function buildRiskPrompt(input) {
-    const systemInstruction = [
-        'You are assessing software deployment risk from a code diff.',
-        'Return strict JSON only, no markdown fences.',
-    ].join('\n');
-    const prompt = [
+    const prompt = joinPromptLines([
         `Deployment criticality: ${input.deploymentCriticality ?? DEFAULT_DEPLOYMENT_CRITICALITY}`,
         'Score guidance: 0 is no risk, 100 is severe risk.',
         'Rationale must be concise, concrete, and evidence-based.',
         '',
         'Unified diff:',
         input.diff,
-    ].join('\n');
-    return { systemInstruction, prompt };
+    ]);
+    return { systemInstruction: SYSTEM_INSTRUCTION, prompt };
 }
 export function registerRiskScoreTool(server) {
     registerStructuredToolTask(server, {

package/dist/tools/suggest-patch.js

@@ -3,12 +3,13 @@ import { registerStructuredToolTask, } from '../lib/tool-factory.js';
 import { SuggestPatchInputSchema } from '../schemas/inputs.js';
 import { PatchSuggestionResultSchema } from '../schemas/outputs.js';
 const DEFAULT_PATCH_STYLE = 'balanced';
+// Hoisted: avoids array allocation + join on every request.
+const SYSTEM_INSTRUCTION = 'You are producing a corrective patch for a code review issue.\nReturn strict JSON only, no markdown fences.';
+function joinPromptLines(lines) {
+    return lines.join('\n');
+}
 function buildPatchPrompt(input) {
-    const systemInstruction = [
-        'You are producing a corrective patch for a code review issue.',
-        'Return strict JSON only, no markdown fences.',
-    ].join('\n');
-    const prompt = [
+    const prompt = joinPromptLines([
         `Patch style: ${input.patchStyle ?? DEFAULT_PATCH_STYLE}`,
         `Finding title: ${input.findingTitle}`,
         `Finding details: ${input.findingDetails}`,
@@ -16,8 +17,8 @@ function buildPatchPrompt(input) {
         '',
         'Original unified diff:',
         input.diff,
-    ].join('\n');
-    return { systemInstruction, prompt };
+    ]);
+    return { systemInstruction: SYSTEM_INSTRUCTION, prompt };
 }
 export function registerSuggestPatchTool(server) {
     registerStructuredToolTask(server, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/code-review-analyst-mcp",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "mcpName": "io.github.j0hanz/code-review-analyst",
   "description": "Gemini-powered MCP server for code review analysis.",
   "type": "module",