@j0hanz/code-review-analyst-mcp 0.1.0

package/dist/lib/gemini.js

@@ -0,0 +1,248 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+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 { GoogleGenAI, HarmBlockThreshold, HarmCategory } from '@google/genai';
+import { getErrorMessage } from './errors.js';
+function getDefaultModel() {
+    return process.env.GEMINI_MODEL ?? 'gemini-2.5-flash';
+}
+const DEFAULT_MAX_RETRIES = 1;
+const DEFAULT_TIMEOUT_MS = 15_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 numberFormatter = new Intl.NumberFormat('en-US');
+function formatNumber(value) {
+    return numberFormatter.format(value);
+}
+const SAFETY_THRESHOLD_BY_NAME = {
+    BLOCK_NONE: HarmBlockThreshold.BLOCK_NONE,
+    BLOCK_ONLY_HIGH: HarmBlockThreshold.BLOCK_ONLY_HIGH,
+    BLOCK_MEDIUM_AND_ABOVE: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
+    BLOCK_LOW_AND_ABOVE: HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
+};
+let cachedClient;
+export const geminiEvents = new EventEmitter();
+geminiEvents.on('log', (payload) => {
+    console.error(JSON.stringify(payload));
+});
+const geminiContext = new AsyncLocalStorage({
+    name: 'gemini_request',
+});
+function getApiKey() {
+    const apiKey = process.env.GEMINI_API_KEY ?? process.env.GOOGLE_API_KEY;
+    if (!apiKey) {
+        throw new Error('Missing GEMINI_API_KEY or GOOGLE_API_KEY.');
+    }
+    return apiKey;
+}
+function getClient() {
+    cachedClient ??= new GoogleGenAI({ apiKey: getApiKey() });
+    return cachedClient;
+}
+export function setClientForTesting(client) {
+    cachedClient = client;
+}
+function nextRequestId() {
+    return randomUUID();
+}
+function logEvent(event, details) {
+    const context = geminiContext.getStore();
+    geminiEvents.emit('log', {
+        event,
+        requestId: context?.requestId ?? null,
+        model: context?.model ?? null,
+        ...details,
+    });
+}
+function getNestedError(error) {
+    if (!error || typeof error !== 'object') {
+        return undefined;
+    }
+    const record = error;
+    const nested = record.error;
+    if (!nested || typeof nested !== 'object') {
+        return record;
+    }
+    return nested;
+}
+function getNumericErrorCode(error) {
+    const record = getNestedError(error);
+    if (!record) {
+        return undefined;
+    }
+    const candidates = [record.status, record.statusCode, record.code];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+            return candidate;
+        }
+        if (typeof candidate === 'string' && /^\d+$/.test(candidate)) {
+            return Number.parseInt(candidate, 10);
+        }
+    }
+    return undefined;
+}
+function getTransientErrorCode(error) {
+    const record = getNestedError(error);
+    if (!record) {
+        return undefined;
+    }
+    const candidates = [record.code, record.status, record.statusText];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate.trim().length > 0) {
+            return candidate.trim().toUpperCase();
+        }
+    }
+    return undefined;
+}
+function shouldRetry(error) {
+    const numericCode = getNumericErrorCode(error);
+    if (numericCode === 429 ||
+        numericCode === 500 ||
+        numericCode === 502 ||
+        numericCode === 503 ||
+        numericCode === 504) {
+        return true;
+    }
+    const transientCode = getTransientErrorCode(error);
+    if (transientCode === 'RESOURCE_EXHAUSTED' ||
+        transientCode === 'UNAVAILABLE' ||
+        transientCode === 'DEADLINE_EXCEEDED' ||
+        transientCode === 'INTERNAL' ||
+        transientCode === 'ABORTED') {
+        return true;
+    }
+    const message = getErrorMessage(error);
+    return /(429|500|502|503|504|rate limit|unavailable|timeout|invalid json)/i.test(message);
+}
+function getRetryDelayMs(attempt) {
+    const exponentialDelay = RETRY_DELAY_BASE_MS * 2 ** attempt;
+    const boundedDelay = Math.min(RETRY_DELAY_MAX_MS, exponentialDelay);
+    const jitterWindow = Math.max(1, Math.floor(boundedDelay * RETRY_JITTER_RATIO));
+    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 {
+        temperature: request.temperature ?? 0.2,
+        maxOutputTokens: request.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
+        responseMimeType: 'application/json',
+        responseSchema: request.responseSchema,
+        ...(request.systemInstruction
+            ? { systemInstruction: request.systemInstruction }
+            : {}),
+        safetySettings: [
+            {
+                category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
+                threshold: safetyThreshold,
+            },
+            {
+                category: HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+                threshold: safetyThreshold,
+            },
+            {
+                category: HarmCategory.HARM_CATEGORY_HARASSMENT,
+                threshold: safetyThreshold,
+            },
+            {
+                category: HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
+                threshold: safetyThreshold,
+            },
+        ],
+        abortSignal,
+    };
+}
+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;
+    try {
+        return await getClient().models.generateContent({
+            model,
+            contents: request.prompt,
+            config: buildGenerationConfig(request, signal),
+        });
+    }
+    catch (error) {
+        if (request.signal?.aborted) {
+            throw new Error('Gemini request was cancelled.');
+        }
+        if (controller.signal.aborted) {
+            throw new Error(`Gemini request timed out after ${formatNumber(timeoutMs)}ms.`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function generateStructuredJson(request) {
+    const model = request.model ?? getDefaultModel();
+    const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxRetries = request.maxRetries ?? DEFAULT_MAX_RETRIES;
+    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);
+                logEvent('gemini_call', {
+                    attempt,
+                    latencyMs: Math.round(performance.now() - startedAt),
+                    usageMetadata: response.usageMetadata ?? null,
+                });
+                if (!response.text) {
+                    throw new Error('Gemini returned an empty response body.');
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(response.text);
+                }
+                catch (error) {
+                    throw new Error(`Model produced invalid JSON: ${getErrorMessage(error)}`);
+                }
+                return parsed;
+            }
+            catch (error) {
+                lastError = error;
+                const retryable = shouldRetry(error);
+                if (attempt >= maxRetries || !retryable) {
+                    break;
+                }
+                const delayMs = getRetryDelayMs(attempt);
+                logEvent('gemini_retry', {
+                    attempt,
+                    delayMs,
+                    reason: getErrorMessage(error),
+                });
+                await sleep(delayMs, undefined, { ref: false });
+            }
+        }
+        logEvent('gemini_failure', {
+            error: getErrorMessage(lastError),
+            attempts: maxRetries + 1,
+        });
+        throw new Error(`Gemini request failed after ${maxRetries + 1} attempts: ${getErrorMessage(lastError)}`);
+    });
+}

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

@@ -0,0 +1,31 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { z } from 'zod';
+import { createErrorToolResponse } from './tool-response.js';
+export interface PromptParts {
+    systemInstruction: string;
+    prompt: string;
+}
+export interface StructuredToolTaskConfig<TInput extends object = Record<string, unknown>> {
+    /** Tool name registered with the MCP server (e.g. 'review_diff'). */
+    name: string;
+    /** Human-readable title shown to clients. */
+    title: string;
+    /** Short description of the tool's purpose. */
+    description: string;
+    /** Zod shape object (e.g. `MySchema.shape`) used as the MCP input schema. */
+    inputSchema: ZodRawShapeCompat;
+    /** Full Zod schema for runtime input re-validation (rejects unknown fields). */
+    fullInputSchema?: z.ZodType;
+    /** Zod schema for parsing and validating the Gemini structured response. */
+    resultSchema: z.ZodType;
+    /** Optional Zod schema used specifically for Gemini response validation. */
+    geminiSchema?: z.ZodType;
+    /** Stable error code returned on failure (e.g. 'E_REVIEW_DIFF'). */
+    errorCode: string;
+    /** Optional validation hook for input parameters. */
+    validateInput?: (input: TInput) => Promise<ReturnType<typeof createErrorToolResponse> | undefined> | ReturnType<typeof createErrorToolResponse> | undefined;
+    /** Builds the system instruction and user prompt from parsed tool input. */
+    buildPrompt: (input: TInput) => PromptParts;
+}
+export declare function registerStructuredToolTask<TInput extends object>(server: McpServer, config: StructuredToolTaskConfig<TInput>): void;

package/dist/lib/tool-factory.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { DefaultOutputSchema } from '../schemas/outputs.js';
+import { getErrorMessage } from './errors.js';
+import { stripJsonSchemaConstraints } from './gemini-schema.js';
+import { generateStructuredJson } from './gemini.js';
+import { createErrorToolResponse, createToolResponse, } from './tool-response.js';
+export function registerStructuredToolTask(server, config) {
+    const responseSchema = config.geminiSchema
+        ? z.toJSONSchema(config.geminiSchema)
+        : stripJsonSchemaConstraints(z.toJSONSchema(config.resultSchema));
+    server.experimental.tasks.registerToolTask(config.name, {
+        title: config.title,
+        description: config.description,
+        inputSchema: config.inputSchema,
+        outputSchema: DefaultOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+        execution: {
+            taskSupport: 'optional',
+        },
+    }, {
+        createTask: async (input, extra) => {
+            const task = await extra.taskStore.createTask({
+                ttl: extra.taskRequestedTtl ?? null,
+            });
+            const progressToken = extra._meta?.progressToken;
+            const sendProgress = async (progress, total) => {
+                if (progressToken == null)
+                    return;
+                try {
+                    await extra.sendNotification({
+                        method: 'notifications/progress',
+                        params: { progressToken, progress, total },
+                    });
+                }
+                catch {
+                    // Progress is best-effort; never fail the tool call.
+                }
+            };
+            try {
+                const inputRecord = config.fullInputSchema
+                    ? config.fullInputSchema.parse(input)
+                    : input;
+                if (config.validateInput) {
+                    const validationError = await config.validateInput(inputRecord);
+                    if (validationError) {
+                        await extra.taskStore.storeTaskResult(task.taskId, 'failed', validationError);
+                        return { task };
+                    }
+                }
+                await sendProgress(1, 4);
+                const { systemInstruction, prompt } = config.buildPrompt(inputRecord);
+                await sendProgress(2, 4);
+                const raw = await generateStructuredJson({
+                    systemInstruction,
+                    prompt,
+                    responseSchema,
+                    signal: extra.signal,
+                });
+                await sendProgress(3, 4);
+                const parsed = config.resultSchema.parse(raw);
+                await extra.taskStore.storeTaskResult(task.taskId, 'completed', createToolResponse({
+                    ok: true,
+                    result: parsed,
+                }));
+                await sendProgress(4, 4);
+            }
+            catch (error) {
+                await extra.taskStore.storeTaskResult(task.taskId, 'failed', createErrorToolResponse(config.errorCode, getErrorMessage(error)));
+            }
+            return { task };
+        },
+        getTask: async (_input, extra) => {
+            return await extra.taskStore.getTask(extra.taskId);
+        },
+        getTaskResult: async (_input, extra) => {
+            return (await extra.taskStore.getTaskResult(extra.taskId));
+        },
+    });
+}

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

@@ -0,0 +1,25 @@
+interface ToolError {
+    code: string;
+    message: string;
+}
+interface ToolTextContent {
+    type: 'text';
+    text: string;
+}
+interface ToolStructuredContent {
+    [key: string]: unknown;
+    ok: boolean;
+    result?: unknown;
+    error?: ToolError;
+}
+interface ToolResponse<TStructuredContent extends ToolStructuredContent> {
+    [key: string]: unknown;
+    content: ToolTextContent[];
+    structuredContent: TStructuredContent;
+}
+interface ErrorToolResponse extends ToolResponse<ToolStructuredContent> {
+    isError: true;
+}
+export declare function createToolResponse<TStructuredContent extends ToolStructuredContent>(structured: TStructuredContent): ToolResponse<TStructuredContent>;
+export declare function createErrorToolResponse(code: string, message: string, result?: unknown): ErrorToolResponse;
+export {};

package/dist/lib/tool-response.js

@@ -0,0 +1,21 @@
+function toTextContent(structured) {
+    return [{ type: 'text', text: JSON.stringify(structured) }];
+}
+export function createToolResponse(structured) {
+    return {
+        content: toTextContent(structured),
+        structuredContent: structured,
+    };
+}
+export function createErrorToolResponse(code, message, result) {
+    const structured = {
+        ok: false,
+        error: { code, message },
+        ...(result === undefined ? {} : { result }),
+    };
+    return {
+        content: toTextContent(structured),
+        structuredContent: structured,
+        isError: true,
+    };
+}

package/dist/lib/types.d.ts

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

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/prompts/index.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAllPrompts(server: McpServer, instructions: string): void;

package/dist/prompts/index.js

@@ -0,0 +1,17 @@
+export function registerAllPrompts(server, instructions) {
+    server.registerPrompt('get-help', {
+        title: 'Get Help',
+        description: 'Return the server usage instructions.',
+    }, () => ({
+        description: 'Server usage instructions',
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: instructions,
+                },
+            },
+        ],
+    }));
+}

package/dist/resources/index.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAllResources(server: McpServer, instructions: string): void;

package/dist/resources/index.js

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

package/dist/schemas/inputs.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export declare const ReviewDiffInputSchema: z.ZodObject<{
+    diff: z.ZodString;
+    repository: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+    focusAreas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maxFindings: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const RiskScoreInputSchema: z.ZodObject<{
+    diff: z.ZodString;
+    deploymentCriticality: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+}, z.core.$strict>;
+export declare const SuggestPatchInputSchema: z.ZodObject<{
+    diff: z.ZodString;
+    findingTitle: z.ZodString;
+    findingDetails: z.ZodString;
+    patchStyle: z.ZodOptional<z.ZodEnum<{
+        minimal: "minimal";
+        balanced: "balanced";
+        defensive: "defensive";
+    }>>;
+}, z.core.$strict>;

package/dist/schemas/inputs.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+const INPUT_LIMITS = {
+    diff: { min: 10, max: 400_000 },
+    repository: { min: 1, max: 200 },
+    language: { min: 2, max: 32 },
+    focusArea: { min: 2, max: 80, maxItems: 12 },
+    maxFindings: { min: 1, max: 25 },
+    findingTitle: { min: 3, max: 160 },
+    findingDetails: { min: 10, max: 3_000 },
+};
+function createDiffSchema(description) {
+    return z
+        .string()
+        .min(INPUT_LIMITS.diff.min)
+        .max(INPUT_LIMITS.diff.max)
+        .describe(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.'),
+    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.'))
+        .min(1)
+        .max(INPUT_LIMITS.focusArea.maxItems)
+        .optional()
+        .describe('Optional list of priorities for this review pass.'),
+    maxFindings: z
+        .number()
+        .int()
+        .min(INPUT_LIMITS.maxFindings.min)
+        .max(INPUT_LIMITS.maxFindings.max)
+        .optional()
+        .describe('Maximum number of findings to return.'),
+});
+export const RiskScoreInputSchema = z.strictObject({
+    diff: createDiffSchema('Unified diff text to analyze for release risk.'),
+    deploymentCriticality: z
+        .enum(['low', 'medium', 'high'])
+        .optional()
+        .describe('How sensitive the target system is to regressions.'),
+});
+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.'),
+    patchStyle: z
+        .enum(['minimal', 'balanced', 'defensive'])
+        .optional()
+        .describe('How broad the patch should be.'),
+});

package/dist/schemas/outputs.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+export declare const DefaultOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const ReviewFindingSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>;
+    file: z.ZodString;
+    line: z.ZodNullable<z.ZodNumber>;
+    title: z.ZodString;
+    explanation: z.ZodString;
+    recommendation: z.ZodString;
+}, z.core.$strict>;
+export declare const ReviewDiffResultSchema: z.ZodObject<{
+    summary: z.ZodString;
+    overallRisk: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    findings: z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            critical: "critical";
+        }>;
+        file: z.ZodString;
+        line: z.ZodNullable<z.ZodNumber>;
+        title: z.ZodString;
+        explanation: z.ZodString;
+        recommendation: z.ZodString;
+    }, z.core.$strict>>;
+    testsNeeded: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const RiskScoreResultSchema: z.ZodObject<{
+    score: z.ZodNumber;
+    bucket: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>;
+    rationale: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const PatchSuggestionResultSchema: z.ZodObject<{
+    summary: z.ZodString;
+    patch: z.ZodString;
+    validationChecklist: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;