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

package/dist/prompts/index.js

@@ -1,18 +1,13 @@
 import { completable } from '@modelcontextprotocol/sdk/server/completable.js';
 import { z } from 'zod';
+import { getToolContract, getToolContractNames, } from '../lib/tool-contracts.js';
 const HELP_PROMPT_NAME = 'get-help';
 const HELP_PROMPT_TITLE = 'Get Help';
-const HELP_PROMPT_DESCRIPTION = 'Return the server usage instructions.';
+const HELP_PROMPT_DESCRIPTION = 'Server instructions.';
 const REVIEW_GUIDE_PROMPT_NAME = 'review-guide';
 const REVIEW_GUIDE_PROMPT_TITLE = 'Review Guide';
-const REVIEW_GUIDE_PROMPT_DESCRIPTION = 'Guided workflow instructions for a specific code review tool and focus area.';
-const TOOLS = [
-    'analyze_pr_impact',
-    'generate_review_summary',
-    'inspect_code_quality',
-    'suggest_search_replace',
-    'generate_test_plan',
-];
+const REVIEW_GUIDE_PROMPT_DESCRIPTION = 'Workflow guide for tool/focus area.';
+const TOOLS = getToolContractNames();
 const FOCUS_AREAS = [
     'security',
     'correctness',
@@ -20,26 +15,14 @@ const FOCUS_AREAS = [
     'regressions',
     'tests',
 ];
-const TOOL_GUIDES = {
-    analyze_pr_impact: 'Call `analyze_pr_impact` with `diff` and `repository`. ' +
-        'Get severity rating and categorization.',
-    generate_review_summary: 'Call `generate_review_summary` for a concise digest and merge recommendation.',
-    inspect_code_quality: 'Call `inspect_code_quality` for deep review with optional file context. ' +
-        'Uses thinking model for complex reasoning.',
-    suggest_search_replace: 'Call `suggest_search_replace` to generate verbatim search/replace fixes.',
-    generate_test_plan: 'Call `generate_test_plan` to create a verification strategy.',
-};
+const TOOL_DESCRIPTION_TEXT = 'Select tool for review guide.';
+const FOCUS_DESCRIPTION_TEXT = 'Select focus area.';
 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.',
+    security: 'Focus: Injection, auth, crypto, OWASP.',
+    correctness: 'Focus: Logic, edge cases, algorithms, contracts.',
+    performance: 'Focus: Complexity, allocations, I/O, queries.',
+    regressions: 'Focus: Behavior changes, guards, types, breaks.',
+    tests: 'Focus: Coverage, edge cases, flakes, error paths.',
 };
 function completeByPrefix(values, prefix) {
     const matches = [];
@@ -55,15 +38,23 @@ function getGuide(guides, value, fallback) {
     return guide ?? fallback(value);
 }
 function getToolGuide(tool) {
-    return getGuide(TOOL_GUIDES, tool, (toolName) => `Use \`${toolName}\` to analyze your code changes.`);
+    const contract = getToolContract(tool);
+    if (!contract) {
+        return `Use \`${tool}\` to analyze your code changes.`;
+    }
+    const { thinkingBudget } = contract;
+    const modelLine = thinkingBudget !== undefined
+        ? `Model: ${contract.model} (thinking budget ${thinkingBudget}, output cap ${contract.maxOutputTokens}).`
+        : `Model: ${contract.model} (output cap ${contract.maxOutputTokens}).`;
+    return `Tool: ${contract.name}\n${modelLine}\nOutput: ${contract.outputShape}\nUse: ${contract.purpose}`;
 }
 function getFocusAreaGuide(focusArea) {
     return getGuide(FOCUS_AREA_GUIDES, focusArea, (area) => `Focus on ${area} concerns.`);
 }
-export function registerAllPrompts(server, instructions) {
+function registerHelpPrompt(server, instructions) {
     server.registerPrompt(HELP_PROMPT_NAME, {
         title: HELP_PROMPT_TITLE,
-        description: 'Return the server usage instructions.',
+        description: HELP_PROMPT_DESCRIPTION,
     }, () => ({
         description: HELP_PROMPT_DESCRIPTION,
         messages: [
@@ -76,16 +67,30 @@ export function registerAllPrompts(server, instructions) {
             },
         ],
     }));
+}
+function buildReviewGuideText(tool, focusArea) {
+    return (`# Code Review Guide\n\n` +
+        `## Tool: \`${tool}\`\n${getToolGuide(tool)}\n\n` +
+        `## Focus Area: ${focusArea}\n${getFocusAreaGuide(focusArea)}\n\n` +
+        `## Example: Finding → Patch\n\n` +
+        `Given a finding from \`inspect_code_quality\`:\n` +
+        `- **title:** "Uncaught promise rejection in retry loop"\n` +
+        `- **details:** "The catch block swallows errors without logging."\n\n` +
+        `Call \`suggest_search_replace\` with those values. It returns:\n` +
+        '```\n' +
+        `blocks[0].search: "  } catch {\\n  }"\n` +
+        `blocks[0].replace: "  } catch (err) {\\n    logger.error(err);\\n  }"\n` +
+        '```\n\n' +
+        `Validate that \`blocks[].search\` matches file content verbatim before applying.\n\n` +
+        `> Tip: Run \`get-help\` for full server documentation.`);
+}
+function registerReviewGuidePrompt(server) {
     server.registerPrompt(REVIEW_GUIDE_PROMPT_NAME, {
         title: REVIEW_GUIDE_PROMPT_TITLE,
         description: REVIEW_GUIDE_PROMPT_DESCRIPTION,
         argsSchema: {
-            tool: completable(z
-                .string()
-                .describe('Which review tool to use: analyze_pr_impact, generate_review_summary, etc.'), (value) => completeByPrefix(TOOLS, value)),
-            focusArea: completable(z
-                .string()
-                .describe('Focus area: security, correctness, performance, regressions, or tests'), (value) => completeByPrefix(FOCUS_AREAS, value)),
+            tool: completable(z.string().describe(TOOL_DESCRIPTION_TEXT), (value) => completeByPrefix(TOOLS, value)),
+            focusArea: completable(z.string().describe(FOCUS_DESCRIPTION_TEXT), (value) => completeByPrefix(FOCUS_AREAS, value)),
         },
     }, ({ tool, focusArea }) => ({
         description: `Code review guide: ${tool} / ${focusArea}`,
@@ -94,12 +99,13 @@ export function registerAllPrompts(server, instructions) {
                 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.`,
+                    text: buildReviewGuideText(tool, focusArea),
                 },
             },
         ],
     }));
 }
+export function registerAllPrompts(server, instructions) {
+    registerHelpPrompt(server, instructions);
+    registerReviewGuidePrompt(server);
+}

package/dist/resources/index.d.ts

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

package/dist/resources/index.js

@@ -1,23 +1,104 @@
-const RESOURCE_ID = 'server-instructions';
-const RESOURCE_URI = 'internal://instructions';
+import { ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { DIFF_RESOURCE_URI, getDiff } from '../lib/diff-store.js';
+import { buildServerConfig } from './server-config.js';
+import { buildToolCatalog } from './tool-catalog.js';
+import { getToolInfo, getToolInfoNames } from './tool-info.js';
+import { buildWorkflowGuide } from './workflows.js';
 const RESOURCE_MIME_TYPE = 'text/markdown';
-const RESOURCE_METADATA = {
-    title: 'Server Instructions',
-    description: 'Guidance for using the MCP tools effectively.',
-    mimeType: RESOURCE_MIME_TYPE,
-    annotations: {
-        audience: ['assistant'],
+const RESOURCE_AUDIENCE = ['assistant'];
+function createMarkdownContent(uri, text) {
+    return { uri: uri.href, mimeType: RESOURCE_MIME_TYPE, text };
+}
+const STATIC_RESOURCES = [
+    {
+        id: 'server-instructions',
+        uri: 'internal://instructions',
+        title: 'Server Instructions',
+        description: 'Complete server usage instructions.',
         priority: 0.8,
+        content: () => '', // placeholder — resolved at registration time
+    },
+    {
+        id: 'tool-catalog',
+        uri: 'internal://tool-catalog',
+        title: 'Tool Catalog',
+        description: 'Tool reference: models, params, outputs, data flow.',
+        priority: 1.0,
+        content: buildToolCatalog,
+    },
+    {
+        id: 'workflows',
+        uri: 'internal://workflows',
+        title: 'Workflow Reference',
+        description: 'Recommended workflows and tool sequences.',
+        priority: 0.9,
+        content: buildWorkflowGuide,
+    },
+    {
+        id: 'server-config',
+        uri: 'internal://server-config',
+        title: 'Server Configuration',
+        description: 'Runtime configuration and limits.',
+        priority: 0.7,
+        content: buildServerConfig,
     },
-};
+];
+function registerStaticResource(server, def, contentOverride) {
+    const content = contentOverride ?? def.content();
+    server.registerResource(def.id, def.uri, {
+        title: def.title,
+        description: def.description,
+        mimeType: RESOURCE_MIME_TYPE,
+        annotations: {
+            audience: RESOURCE_AUDIENCE,
+            priority: def.priority,
+        },
+    }, (uri) => ({ contents: [createMarkdownContent(uri, content)] }));
+}
+function registerToolInfoResources(server) {
+    const toolNames = getToolInfoNames();
+    server.registerResource('tool-info', new ResourceTemplate('internal://tool-info/{toolName}', {
+        list: undefined,
+        complete: {
+            toolName: (value) => toolNames.filter((name) => name.startsWith(value)),
+        },
+    }), {
+        title: 'Tool Info',
+        description: 'Per-tool reference: model, params, output, gotchas.',
+        mimeType: RESOURCE_MIME_TYPE,
+        annotations: {
+            audience: RESOURCE_AUDIENCE,
+            priority: 0.6,
+        },
+    }, (uri, { toolName }) => {
+        const name = typeof toolName === 'string' ? toolName : '';
+        const info = getToolInfo(name);
+        const text = info ?? `Unknown tool: ${name}`;
+        return { contents: [createMarkdownContent(uri, text)] };
+    });
+}
+function registerDiffResource(server) {
+    server.registerResource('diff-current', new ResourceTemplate(DIFF_RESOURCE_URI, { list: undefined }), {
+        title: 'Current Diff',
+        description: 'The most recently generated diff, cached by generate_diff. Read by all review tools automatically.',
+        mimeType: 'text/x-patch',
+        annotations: {
+            audience: ['assistant'],
+            priority: 1.0,
+        },
+    }, (uri) => {
+        const slot = getDiff();
+        const text = slot
+            ? `# Diff — ${slot.mode} — ${slot.generatedAt}\n# ${slot.stats.files} file(s), +${slot.stats.added} -${slot.stats.deleted}\n\n${slot.diff}`
+            : '# No diff cached. Call generate_diff first.';
+        return { contents: [{ uri: uri.href, mimeType: 'text/x-patch', text }] };
+    });
+}
 export function registerAllResources(server, instructions) {
-    server.registerResource(RESOURCE_ID, RESOURCE_URI, RESOURCE_METADATA, (uri) => ({
-        contents: [
-            {
-                uri: uri.href,
-                mimeType: RESOURCE_MIME_TYPE,
-                text: instructions,
-            },
-        ],
-    }));
+    for (const def of STATIC_RESOURCES) {
+        const override = def.id === 'server-instructions' ? instructions : undefined;
+        registerStaticResource(server, def, override);
+    }
+    registerToolInfoResources(server);
+    registerDiffResource(server);
 }

package/dist/resources/instructions.d.ts

@@ -0,0 +1 @@
+export declare function buildServerInstructions(): string;

package/dist/resources/instructions.js

@@ -0,0 +1,69 @@
+import { getToolContracts } from '../lib/tool-contracts.js';
+import { getSharedConstraints } from './tool-info.js';
+const PROMPT_LIST = [
+    '- `get-help`: Returns these server instructions.',
+    '- `review-guide`: Workflow guide for a selected tool and focus area.',
+];
+const RESOURCE_LIST = [
+    '- `internal://instructions`: This document.',
+    '- `internal://tool-catalog`: Tool matrix and cross-tool data flow.',
+    '- `internal://workflows`: Recommended multi-step tool workflows.',
+    '- `internal://server-config`: Runtime limits and model configuration.',
+    '- `internal://tool-info/{toolName}`: Per-tool contract details.',
+    '- `diff://current`: Cached diff from the most recent generate_diff run.',
+];
+function formatParameterLine(parameter) {
+    const required = parameter.required ? 'required' : 'optional';
+    return `- \`${parameter.name}\` (${parameter.type}, ${required}; ${parameter.constraints})`;
+}
+function formatToolSection(contract) {
+    const parameterLines = contract.params.map((parameter) => formatParameterLine(parameter));
+    if (contract.model === 'none') {
+        // Synchronous built-in tool (no Gemini call)
+        return `### \`${contract.name}\`
+- Purpose: ${contract.purpose}
+- Model: \`none\` (synchronous built-in)
+- Parameters:
+${parameterLines.join('\n')}
+- Output shape: \`${contract.outputShape}\``;
+    }
+    const thinkingLine = contract.thinkingBudget === undefined
+        ? '- Thinking budget: disabled'
+        : `- Thinking budget: ${contract.thinkingBudget}`;
+    return `### \`${contract.name}\`
+- Purpose: ${contract.purpose}
+- Model: \`${contract.model}\`
+- Timeout: ${Math.round(contract.timeoutMs / 1_000)}s
+${thinkingLine}
+- Max output tokens: ${contract.maxOutputTokens}
+- Parameters:
+${parameterLines.join('\n')}
+- Output shape: \`${contract.outputShape}\``;
+}
+export function buildServerInstructions() {
+    const contracts = getToolContracts();
+    const toolNames = contracts
+        .map((contract) => `\`${contract.name}\``)
+        .join(', ');
+    const toolSections = contracts.map((contract) => formatToolSection(contract));
+    const constraintLines = getSharedConstraints().map((constraint) => `- ${constraint}`);
+    return `# CODE REVIEW ANALYST MCP INSTRUCTIONS
+
+## CORE CAPABILITY
+- Domain: Gemini-powered code review analysis over unified diffs.
+- Tools: ${toolNames}
+- Transport: stdio with task lifecycle support.
+
+## PROMPTS
+${PROMPT_LIST.join('\n')}
+
+## RESOURCES
+${RESOURCE_LIST.join('\n')}
+
+## TOOL CONTRACTS
+${toolSections.join('\n\n')}
+
+## SHARED CONSTRAINTS
+${constraintLines.join('\n')}
+`;
+}

package/dist/resources/server-config.d.ts

@@ -0,0 +1 @@
+export declare function buildServerConfig(): string;

package/dist/resources/server-config.js

@@ -0,0 +1,71 @@
+import { createCachedEnvInt } from '../lib/env-config.js';
+import { FLASH_MODEL } from '../lib/model-config.js';
+import { getToolContracts } from '../lib/tool-contracts.js';
+const DEFAULT_MAX_DIFF_CHARS = 120_000;
+const DEFAULT_MAX_CONTEXT_CHARS = 500_000;
+const DEFAULT_MAX_CONCURRENT_CALLS = 10;
+const DEFAULT_CONCURRENT_WAIT_MS = 2_000;
+const DEFAULT_SAFETY_THRESHOLD = 'BLOCK_NONE';
+const GEMINI_HARM_BLOCK_THRESHOLD_ENV_VAR = 'GEMINI_HARM_BLOCK_THRESHOLD';
+const GEMINI_MODEL_ENV_VAR = 'GEMINI_MODEL';
+const diffCharsConfig = createCachedEnvInt('MAX_DIFF_CHARS', DEFAULT_MAX_DIFF_CHARS);
+const contextCharsConfig = createCachedEnvInt('MAX_CONTEXT_CHARS', DEFAULT_MAX_CONTEXT_CHARS);
+const concurrentCallsConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS', DEFAULT_MAX_CONCURRENT_CALLS);
+const concurrentWaitConfig = createCachedEnvInt('MAX_CONCURRENT_CALLS_WAIT_MS', DEFAULT_CONCURRENT_WAIT_MS);
+function getModelOverride() {
+    return process.env[GEMINI_MODEL_ENV_VAR] ?? FLASH_MODEL;
+}
+function getSafetyThreshold() {
+    return (process.env[GEMINI_HARM_BLOCK_THRESHOLD_ENV_VAR] ?? DEFAULT_SAFETY_THRESHOLD);
+}
+function formatNumber(value) {
+    return new Intl.NumberFormat('en-US').format(value);
+}
+function formatTimeout(ms) {
+    return `${Math.round(ms / 1_000)}s`;
+}
+function formatThinkingBudget(budget) {
+    return budget !== undefined ? formatNumber(budget) : '—';
+}
+export function buildServerConfig() {
+    const maxDiffChars = diffCharsConfig.get();
+    const maxContextChars = contextCharsConfig.get();
+    const maxConcurrent = concurrentCallsConfig.get();
+    const concurrentWaitMs = concurrentWaitConfig.get();
+    const defaultModel = getModelOverride();
+    const safetyThreshold = getSafetyThreshold();
+    const toolRows = getToolContracts()
+        .filter((contract) => contract.model !== 'none')
+        .map((contract) => {
+        return `| \`${contract.name}\` | \`${contract.model}\` | ${formatThinkingBudget(contract.thinkingBudget)} | ${formatTimeout(contract.timeoutMs)} | ${formatNumber(contract.maxOutputTokens)} |`;
+    })
+        .join('\n');
+    return `# Server Configuration
+
+## Input Limits
+
+| Limit | Value | Env |
+|-------|-------|-----|
+| Diff limit | ${formatNumber(maxDiffChars)} chars | \`MAX_DIFF_CHARS\` |
+| Context limit (inspect) | ${formatNumber(maxContextChars)} chars | \`MAX_CONTEXT_CHARS\` |
+| Concurrency limit | ${maxConcurrent} | \`MAX_CONCURRENT_CALLS\` |
+| Wait timeout | ${formatNumber(concurrentWaitMs)}ms | \`MAX_CONCURRENT_CALLS_WAIT_MS\` |
+
+## Model Assignments
+
+Default model: \`${defaultModel}\` (override with \`GEMINI_MODEL\`)
+
+| Tool | Model | Thinking Budget | Timeout | Max Output Tokens |
+|------|-------|----------------|---------|-------------------|
+${toolRows}
+
+## Safety
+
+- Harm block threshold: \`${safetyThreshold}\`
+- Override with \`GEMINI_HARM_BLOCK_THRESHOLD\` (BLOCK_NONE, BLOCK_ONLY_HIGH, BLOCK_MEDIUM_AND_ABOVE, BLOCK_LOW_AND_ABOVE)
+
+## API Keys
+
+- Set \`GEMINI_API_KEY\` or \`GOOGLE_API_KEY\` environment variable (required)
+`;
+}

package/dist/resources/tool-catalog.d.ts

@@ -0,0 +1 @@
+export declare function buildToolCatalog(): string;

package/dist/resources/tool-catalog.js

@@ -0,0 +1,39 @@
+import { buildCoreContextPack } from './tool-info.js';
+const TOOL_CATALOG_CONTENT = `# Tool Catalog Details
+
+## Optional Parameters
+
+- \`language\`: Primary language hint (auto-detects). All tools except \`suggest_search_replace\`.
+- \`focusAreas\`: Focus tags (security, performance, etc.). \`inspect_code_quality\` only.
+- \`maxFindings\`: Output cap (1–25). \`inspect_code_quality\` only.
+- \`files\`: File context (max 20 files, 100K chars/file). \`inspect_code_quality\` only.
+- \`testFramework\`: Framework hint. \`generate_test_plan\` only.
+- \`maxTestCases\`: Output cap (1–30). \`generate_test_plan\` only.
+
+## Cross-Tool Data Flow
+
+\`\`\`
+analyze_pr_impact ──→ severity/categories ──→ triage decision
+                                              │
+generate_review_summary ──→ overallRisk ──────┤
+                                              ▼
+                                    inspect_code_quality
+                                              │
+                                    findings[].title ──→ suggest_search_replace.findingTitle
+                                    findings[].explanation ──→ suggest_search_replace.findingDetails
+                                              │
+                                    diff ─────┴──→ generate_test_plan
+\`\`\`
+
+## When to Use Each Tool
+
+- **Triage**: \`analyze_pr_impact\`, \`generate_review_summary\` (Flash).
+- **Inspection**: \`inspect_code_quality\` (Pro).
+- **Fixes**: \`suggest_search_replace\` (one finding/call).
+- **Tests**: \`generate_test_plan\`.
+- **Complexity**: \`analyze_time_space_complexity\`.
+- **Breaking API**: \`detect_api_breaking_changes\`.
+`;
+export function buildToolCatalog() {
+    return `${buildCoreContextPack()}\n\n${TOOL_CATALOG_CONTENT}`;
+}

package/dist/resources/tool-info.d.ts

@@ -0,0 +1,5 @@
+export declare function buildCoreContextPack(): string;
+export declare function getSharedConstraints(): readonly string[];
+export declare function getToolInfoNames(): string[];
+export declare function getToolInfo(toolName: string): string | undefined;
+export declare function getToolPurpose(toolName: string): string | undefined;

package/dist/resources/tool-info.js

@@ -0,0 +1,122 @@
+import { getToolContract, getToolContracts } from '../lib/tool-contracts.js';
+const GLOBAL_CONSTRAINTS = [
+    'Diff budget: <= 120K chars.',
+    'Structured output: tools return both `structuredContent` and JSON text `content`.',
+];
+const numberFormatter = new Intl.NumberFormat('en-US');
+function formatNumber(value) {
+    return numberFormatter.format(value);
+}
+function formatTimeout(timeoutMs) {
+    return `${Math.round(timeoutMs / 1_000)}s`;
+}
+function formatThinkingBudget(thinkingBudget) {
+    return thinkingBudget === undefined ? '-' : formatNumber(thinkingBudget);
+}
+function formatOutputTokens(maxOutputTokens) {
+    return formatNumber(maxOutputTokens);
+}
+function formatParameterRow(entry) {
+    return `| ${entry.name} | ${entry.type} | ${entry.required ? 'Yes' : 'No'} | ${entry.constraints} | ${entry.description} |`;
+}
+function toToolInfoEntry(contract) {
+    const parameterRows = [
+        '| Param | Type | Required | Constraints | Description |',
+        '|-------|------|----------|-------------|-------------|',
+        ...contract.params.map((parameter) => formatParameterRow(parameter)),
+    ];
+    return {
+        name: contract.name,
+        purpose: contract.purpose,
+        model: contract.model,
+        thinkingBudget: formatThinkingBudget(contract.thinkingBudget),
+        timeout: formatTimeout(contract.timeoutMs),
+        maxOutputTokens: formatOutputTokens(contract.maxOutputTokens),
+        params: parameterRows.join('\n'),
+        outputShape: `\`${contract.outputShape}\``,
+        gotchas: contract.gotchas,
+        crossToolFlow: contract.crossToolFlow,
+        ...(contract.constraints
+            ? { constraints: contract.constraints }
+            : undefined),
+    };
+}
+const TOOL_INFO_ENTRIES = Object.fromEntries(getToolContracts().map((contract) => [
+    contract.name,
+    toToolInfoEntry(contract),
+]));
+const TOOL_NAMES = Object.keys(TOOL_INFO_ENTRIES).sort((a, b) => a.localeCompare(b));
+function collectToolConstraints(entries) {
+    const constraints = new Set();
+    for (const [toolName, entry] of Object.entries(entries)) {
+        for (const constraint of entry.constraints ?? []) {
+            constraints.add(`\`${toolName}\`: ${constraint}`);
+        }
+    }
+    return Array.from(constraints).sort((a, b) => a.localeCompare(b));
+}
+function formatToolInfo(entry) {
+    return `# ${entry.name}
+
+## Purpose
+${entry.purpose}
+
+## Model
+\`${entry.model}\` (thinking budget: ${entry.thinkingBudget}, timeout: ${entry.timeout}, max output tokens: ${entry.maxOutputTokens})
+
+## Parameters
+${entry.params}
+
+## Output Shape
+${entry.outputShape}
+
+## Gotchas
+${entry.gotchas.map((g) => `- ${g}`).join('\n')}
+
+## Cross-Tool Flow
+${entry.crossToolFlow.map((f) => `- ${f}`).join('\n')}
+`;
+}
+function formatCompactToolRow(entry) {
+    return `| \`${entry.name}\` | ${entry.model} | ${entry.timeout} | ${entry.maxOutputTokens} | ${entry.purpose} |`;
+}
+export function buildCoreContextPack() {
+    const rows = TOOL_NAMES.flatMap((toolName) => {
+        const entry = TOOL_INFO_ENTRIES[toolName];
+        return entry ? [formatCompactToolRow(entry)] : [];
+    });
+    return `# Core Context Pack
+
+## Server Essentials
+- Domain: Gemini-powered MCP server for diff-based code review.
+- Surface: 7 review tools + internal resources + guided prompts.
+- Transport: stdio with task lifecycle support.
+
+## Tool Matrix
+| Tool | Model | Timeout | Max Output Tokens | Purpose |
+|------|-------|---------|-------------------|---------|
+${rows.join('\n')}
+
+## Shared Constraints
+${getSharedConstraints()
+        .map((constraint) => `- ${constraint}`)
+        .join('\n')}
+`;
+}
+export function getSharedConstraints() {
+    const toolConstraints = collectToolConstraints(TOOL_INFO_ENTRIES);
+    return [...GLOBAL_CONSTRAINTS, ...toolConstraints];
+}
+export function getToolInfoNames() {
+    return TOOL_NAMES;
+}
+export function getToolInfo(toolName) {
+    const entry = TOOL_INFO_ENTRIES[toolName];
+    if (!entry) {
+        return undefined;
+    }
+    return formatToolInfo(entry);
+}
+export function getToolPurpose(toolName) {
+    return getToolContract(toolName)?.purpose;
+}

package/dist/resources/workflows.d.ts

@@ -0,0 +1 @@
+export declare function buildWorkflowGuide(): string;

package/dist/resources/workflows.js

@@ -0,0 +1,72 @@
+import { getToolContracts } from '../lib/tool-contracts.js';
+import { getSharedConstraints } from './tool-info.js';
+function buildWorkflowToolReference() {
+    const contracts = getToolContracts();
+    return contracts
+        .map((c) => `### \`${c.name}\`\n- **Purpose:** ${c.purpose}\n- **Model:** ${c.model}\n- **Output:** \`${c.outputShape}\``)
+        .join('\n\n');
+}
+export function buildWorkflowGuide() {
+    return `# Workflow Reference
+
+## A: Full PR Review
+
+1. \`generate_review_summary\` → \`{overallRisk, keyChanges[], recommendation, stats}\`
+2. \`inspect_code_quality\` → \`{findings[], overallRisk, contextualInsights[]}\`
+3. For each finding: \`suggest_search_replace\` → \`{blocks[]}\`
+
+> One finding per \`suggest_search_replace\` call.
+
+## B: Impact Assessment
+
+1. \`analyze_pr_impact\` → \`{severity, categories[], breakingChanges[], rollbackComplexity}\`
+2. \`generate_review_summary\` → complementary merge recommendation
+
+> Use when categorization (breaking, api) or rollback assessment needed.
+
+## C: Remediation Loop
+
+1. \`inspect_code_quality\` → \`{findings[]}\`
+2. Pick one finding. \`suggest_search_replace\` → \`{blocks[]}\`
+3. Validate \`blocks[].search\` matches file content verbatim.
+
+> Never batch findings.
+
+## D: Test Coverage
+
+1. \`generate_test_plan\` → \`{testCases[], coverageSummary}\`
+2. Review by priority: \`must_have\` → \`should_have\` → \`nice_to_have\`
+
+> Combine with \`inspect_code_quality\`.
+
+## E: Complexity & Breaking Changes
+
+1. \`analyze_time_space_complexity\` → \`{timeComplexity, spaceComplexity, isDegradation}\`
+2. \`detect_api_breaking_changes\` → \`{hasBreakingChanges, breakingChanges[]}\`
+
+> Use for algorithm or API changes. Diff-only input.
+
+## Shared Constraints
+${getSharedConstraints()
+        .map((constraint) => `- ${constraint}`)
+        .join('\n')}
+
+## Tool Reference
+
+${buildWorkflowToolReference()}
+
+## Output Shape Reference
+
+### Finding
+\`{severity, file, line, title, explanation, recommendation}\`
+
+### Search/Replace Block
+\`{file, search, replace, explanation}\`
+
+### Test Case
+\`{name, type, file, description, pseudoCode, priority}\`
+
+### Breaking Change
+\`{element, natureOfChange, consumerImpact, suggestedMitigation}\`
+`;
+}