pr-checkmate 3.2.3 → 4.0.0

package/dist/esm/mcp/tools.js

@@ -0,0 +1,626 @@
+/**
+ * The tools and resources the MCP server offers.
+ *
+ * Two jobs, matching the two moments an agent can act on a standard:
+ *
+ * - **before writing** — `get_rules` says what this repository's gate enforces, so
+ *   the code comes out right the first time;
+ * - **after writing** — `check_changes` and `scan_secrets` run the same checks CI
+ *   will run, so the agent fixes findings in its own loop instead of in a review.
+ *
+ * All of it is read-only. Nothing here writes a file, posts a comment, or stages
+ * anything.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadProjectConfig } from '../config/loader.js';
+import { DEFAULT_MAX_KB } from '../core/checks/git/large-files.js';
+import { DEFAULT_MAX_FILES, DEFAULT_MAX_LINES } from '../core/checks/pr/pr-size-check.js';
+import { COMMAND_TO_CHECK } from '../core/commands.js';
+import { buildContext } from '../core/context.js';
+import { REGISTRY } from '../core/registry.js';
+import { findOwnPackageRoot } from '../utils/own-deps.js';
+import { packageVersion } from '../utils/package-version.js';
+import { explainConfig, formatSuggestion, suggestConfig, writeConfig } from './config-tools.js';
+import { checkDependency, formatDependency } from './dependency.js';
+import { fingerprintChanges, resolveRepoRoot, review, REVIEW_SCOPES, } from './review.js';
+import { allowedTools, readMcpSettings } from './settings.js';
+/** The checks that look for credentials and risky additions — what `scan_secrets` runs. */
+const SECRET_CHECKS = ['Security Scan', 'Diff Security', 'Sensitive Files'];
+/** Findings longer than this are cut: an agent's context is the scarce resource here. */
+const MAX_DETAIL_CHARS = 3000;
+/** Locations listed per check in the text; the structured result carries them all. */
+const MAX_LOCATIONS_SHOWN = 10;
+const RULES_URI = 'pr-checkmate://rules';
+const INSTRUCTIONS = [
+    'pr-checkmate runs the same quality and security gate that CI applies to pull requests.',
+    'Before writing code in a repository, read the rules (get_rules or the pr-checkmate://rules resource).',
+    'While working, and before committing, call check_changes and fix every failed (❌) finding.',
+    'When you believe the work is done, call verify once — it runs the slow checks too — and fix what it reports before telling the user the work is finished.',
+    'Style findings (formatting, autofixable lint) are not worth fixing by hand: call apply_fixes, which rewrites only the files you changed.',
+    'To set pr-checkmate up for a repository, call suggest_config, show the user what it proposes, and only then call write_config; use explain_config to answer questions about a setting.',
+    'Before adding any package, call check_dependency: it catches names that do not exist, versions with known advisories and look-alike names.',
+    'Call scan_secrets before committing anything that touches configuration, environment files or credentials.',
+    'All tools are read-only.',
+].join(' ');
+/** Calls are queued: checks share process-wide state (cwd, tool lookup paths) and git. */
+let queue = Promise.resolve();
+function serialized(job) {
+    const run = queue.then(job, job);
+    queue = run.catch(() => undefined);
+    return run;
+}
+/** Run `job` with `dir` as the process working directory, restoring it afterwards. */
+async function inDirectory(dir, job) {
+    const previous = process.cwd();
+    process.chdir(dir);
+    try {
+        return await job();
+    }
+    finally {
+        process.chdir(previous);
+    }
+}
+/**
+ * The repository a call refers to. A globally installed server is started once and
+ * used from many projects, so each call may name its own directory; without one it
+ * is wherever the client launched us, which for Claude Code and most editors is the
+ * project the session is in.
+ */
+async function repoFor(args) {
+    const requested = typeof args.cwd === 'string' && args.cwd ? path.resolve(args.cwd) : process.cwd();
+    if (!fs.existsSync(requested) || !fs.statSync(requested).isDirectory()) {
+        throw new Error(`"${requested}" is not a directory`);
+    }
+    const root = await resolveRepoRoot(requested);
+    if (!root)
+        throw new Error(`"${requested}" is not inside a git repository`);
+    return root;
+}
+function clip(text) {
+    return text.length > MAX_DETAIL_CHARS
+        ? `${text.slice(0, MAX_DETAIL_CHARS)}… [${text.length - MAX_DETAIL_CHARS} more characters cut]`
+        : text;
+}
+const ICON = {
+    pass: '✅',
+    warn: '⚠️',
+    fail: '❌',
+    skip: '⏭️',
+};
+/**
+ * Render a report for a model: findings first, nothing for what passed.
+ *
+ * A passing check is the expected case and carries no information the agent can
+ * act on, so only the count survives. Skips stay because one of them can mean "the
+ * tooling never arrived" — a hole in coverage the agent should be able to see.
+ */
+export function formatReport(report, meta) {
+    const { passed, warned, failed, skipped } = report.summary;
+    const files = meta.changedFiles === undefined ? '' : `, ${meta.changedFiles} changed file(s)`;
+    const verdict = report.ok ? 'PASSED' : 'FAILED';
+    const lines = [
+        `pr-checkmate ${verdict} — ${failed} failed, ${warned} warned, ${passed} passed, ${skipped} skipped (scope: ${meta.scope}${files})`,
+    ];
+    if (meta.note)
+        lines.push(`Note: ${meta.note}`);
+    const shown = report.results.filter(r => r.status !== 'pass');
+    for (const r of shown) {
+        lines.push(`${ICON[r.status]} ${r.name}${r.details ? ` — ${clip(r.details)}` : ''}`);
+        // Where, when the check knows. Capped: a hundred identical lines teach the agent
+        // nothing the first ten did not.
+        const where = r.findings ?? [];
+        for (const f of where.slice(0, MAX_LOCATIONS_SHOWN)) {
+            lines.push(`   ${f.file}${f.line ? `:${f.line}` : ''}  ${f.rule}${f.snippet ? ` — ${f.snippet}` : ''}`);
+        }
+        if (where.length > MAX_LOCATIONS_SHOWN) {
+            lines.push(`   … and ${where.length - MAX_LOCATIONS_SHOWN} more`);
+        }
+    }
+    // `advice` lets a caller that is not a tool call (the commit hook) say its own
+    // closing line, or none: "call this tool again" means nothing to a hook.
+    const advice = meta.advice ?? 'Fix the ❌ findings, then call this tool again to confirm.';
+    if (meta.changedFiles === 0)
+        lines.push('Nothing to review: the working tree matches HEAD.');
+    else if (!report.ok) {
+        if (advice)
+            lines.push(advice);
+    }
+    else if (warned > 0)
+        lines.push('Warnings are advisory and do not block the pull request.');
+    return {
+        text: lines.join('\n'),
+        structured: {
+            ok: report.ok,
+            scope: meta.scope,
+            summary: report.summary,
+            ...(meta.changedFiles !== undefined && { changedFiles: meta.changedFiles }),
+            findings: shown.map(r => ({
+                check: r.name,
+                status: r.status,
+                ...(r.details && { details: clip(r.details) }),
+                ...(r.findings && r.findings.length > 0 && { locations: r.findings }),
+            })),
+        },
+    };
+}
+/** The CLI spelling of a check, so the rules can say "run `pr-checkmate lint`". */
+function commandFor(checkName) {
+    return Object.entries(COMMAND_TO_CHECK).find(([, name]) => name === checkName)?.[0];
+}
+/**
+ * The numeric limits that, once crossed, produce a finding — read from the live
+ * config so the agent can size its change before writing it instead of learning the
+ * ceiling from a failure. Only enabled checks are listed: a limit nobody enforces is
+ * not a rule.
+ */
+function describeLimits(config) {
+    const c = config;
+    const on = (key) => c[key] && c[key]?.enabled !== false ? c[key] : undefined;
+    const lines = [];
+    // The built-in default fills in when the repository sets nothing: the limit
+    // applies either way, and an agent should not have to guess it.
+    const size = c.prSize;
+    if (size?.enabled !== false) {
+        lines.push(`- A pull request: at most ${size?.maxFiles ?? DEFAULT_MAX_FILES} files and ${size?.maxLines ?? DEFAULT_MAX_LINES} changed lines.`);
+    }
+    const large = c.largeFiles;
+    if (large?.enabled !== false) {
+        lines.push(`- A committed file: at most ${large?.maxSizeKb ?? DEFAULT_MAX_KB} KB.`);
+    }
+    const dup = on('duplicate');
+    if (dup)
+        lines.push(`- Copy-pasted code: ${dup.minLines}+ identical lines (${dup.minTokens}+ tokens) is reported as a duplicate.`);
+    const body = on('prBody');
+    if (body) {
+        lines.push(`- Pull request description: at least ${body.minLength} characters${body.requireTicket ? ' and a ticket reference' : ''}.`);
+    }
+    if (on('todoFixme')?.requireTicket)
+        lines.push('- A TODO/FIXME needs a ticket reference.');
+    return lines;
+}
+/**
+ * The ESLint rules the gate runs, as the repository will actually see them: the
+ * bundled defaults with the repository's own `eslint.rules` merged over them, the
+ * same order the real config applies. Only `error` is listed — a warning does not
+ * fail the build, and a hundred of them would bury the ones that do.
+ */
+function describeLintRules(config) {
+    let defaults = {};
+    const root = findOwnPackageRoot();
+    try {
+        if (root) {
+            defaults = JSON.parse(fs.readFileSync(path.join(root, 'eslint-default-rules.json'), 'utf-8'));
+        }
+    }
+    catch {
+        // Without the defaults file only the repository's own rules can be listed.
+    }
+    // The real config reads `eslint.rules`; the typed interface still names it `lint`.
+    const own = config.eslint?.rules;
+    const merged = { ...defaults, ...(own ?? config.lint?.rules ?? {}) };
+    const level = (setting) => {
+        const head = Array.isArray(setting) ? setting[0] : setting;
+        return head === 2 ? 'error' : head === 1 ? 'warn' : head === 0 ? 'off' : String(head);
+    };
+    const failing = Object.entries(merged)
+        .filter(([, setting]) => level(setting) === 'error')
+        .map(([rule]) => `\`${rule}\``);
+    return failing.length > 0 ? [failing.join(', ')] : [];
+}
+/**
+ * Describe what this repository's gate enforces, in the order an agent needs it.
+ *
+ * Built from the live registry and the repository's own `pr-checkmate.json`, so it
+ * cannot drift from what CI will do — a hand-written rules file would, the first
+ * time someone promoted a check to a gate.
+ */
+async function describeRules(cwd) {
+    return inDirectory(cwd, async () => {
+        const config = loadProjectConfig(cwd);
+        // `full` skips every git call: applicability depends on languages and config,
+        // not on what is in the diff.
+        const ctx = await buildContext({ cwd, config, full: true, reporter: 'none' });
+        const severity = config.severity ?? {};
+        const gate = [];
+        const advisory = [];
+        for (const check of REGISTRY) {
+            if (severity[check.name] === 'off' || !(await check.applies(ctx)))
+                continue;
+            const blocking = severity[check.name] === 'error' ||
+                (check.phase === 'blocking' && severity[check.name] !== 'warn');
+            const cmd = commandFor(check.name);
+            const entry = `- ${check.name}${cmd ? ` (\`pr-checkmate ${cmd}\`)` : ''}`;
+            (blocking ? gate : advisory).push(entry);
+        }
+        const out = [
+            `# pr-checkmate rules for ${path.basename(cwd)}`,
+            '',
+            `Languages detected: ${ctx.languages.join(', ') || 'none'}`,
+            '',
+            '## Blocking — a finding here fails the pull request',
+            ...(gate.length > 0 ? gate : ['- none']),
+            '',
+            '## Advisory — reported, never blocks',
+            ...(advisory.length > 0 ? advisory : ['- none']),
+        ];
+        if (config.customRules?.length) {
+            out.push('', '## Project rules (matched against added lines)');
+            for (const rule of config.customRules) {
+                out.push(`- ${rule.name} [${rule.severity ?? 'warn'}]${rule.message ? `: ${rule.message}` : ''}`);
+            }
+        }
+        if (config.bannedImports?.length) {
+            out.push('', '## Banned imports and dependencies');
+            for (const banned of config.bannedImports) {
+                out.push(`- ${banned.name} [${banned.severity ?? 'error'}]${banned.message ? `: ${banned.message}` : ''}`);
+            }
+        }
+        const limits = describeLimits(config);
+        if (limits.length > 0)
+            out.push('', '## Limits to stay inside', ...limits);
+        const lint = describeLintRules(config);
+        if (lint.length > 0)
+            out.push('', '## Lint rules that fail the build', ...lint);
+        out.push('', '## Workflow', '1. Write code that follows the rules above.', '2. Call `check_changes` as you work; fix every ❌ and call it again.', '3. Call `scan_secrets` before committing configuration, environment or credential files, and `check_dependency` before adding any package.', '4. Call `verify` once when the work is done — it adds the slow checks (typecheck, dependency audit) — before telling the user it is finished.');
+        return out.join('\n');
+    });
+}
+const CWD_PROPERTY = {
+    cwd: {
+        type: 'string',
+        description: 'Directory inside the repository to review. Defaults to the directory the server was started in.',
+    },
+};
+const getRules = {
+    name: 'get_rules',
+    description: "Describe the quality and security rules this repository's gate enforces: which checks block a pull request, which only warn, and the project's own custom rules and banned imports. Read it before writing code so the first draft already conforms.",
+    inputSchema: { type: 'object', properties: { ...CWD_PROPERTY }, additionalProperties: false },
+    async run(args) {
+        const cwd = await repoFor(args);
+        return serialized(async () => ({ text: await describeRules(cwd) }));
+    },
+};
+const checkChanges = {
+    name: 'check_changes',
+    description: "Run the repository's pull-request gate on the code you have changed — uncommitted files included, nothing needs to be staged — and return the findings. " +
+        'Call it after finishing a change and before committing; fix every failed finding and call it again. ' +
+        'Fast checks only by default; pass deep: true for typecheck, dependency audit and the other slow ones.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            scope: {
+                type: 'string',
+                enum: [...REVIEW_SCOPES],
+                description: '"worktree" (default): all uncommitted changes. "staged": what git commit would record. "branch": commits since the default branch. "full": every tracked file.',
+            },
+            deep: {
+                type: 'boolean',
+                description: 'Also run heavy and network checks. Slower; use before opening a pull request.',
+            },
+            checks: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Run only these checks, by command name (e.g. "lint", "security") or display name (e.g. "ESLint").',
+            },
+            ...CWD_PROPERTY,
+        },
+        additionalProperties: false,
+    },
+    async run(args) {
+        const scope = args.scope ?? 'worktree';
+        if (!REVIEW_SCOPES.includes(scope)) {
+            return {
+                text: `Unknown scope "${String(scope)}". Use one of: ${REVIEW_SCOPES.join(', ')}.`,
+                isError: true,
+            };
+        }
+        const requested = Array.isArray(args.checks) ? args.checks.map(String) : [];
+        const known = new Set(REGISTRY.map(c => c.name));
+        const only = requested.map(name => COMMAND_TO_CHECK[name] ?? name);
+        const unknown = requested.filter((_, i) => !known.has(only[i]));
+        // A misspelt name must never shrink the run to nothing and report green — the
+        // same rule the CLI applies, for the same reason.
+        if (unknown.length > 0) {
+            return {
+                text: `Unknown check(s): ${unknown.join(', ')}. Valid command names: ${Object.keys(COMMAND_TO_CHECK).join(', ')}.`,
+                isError: true,
+            };
+        }
+        const cwd = await repoFor(args);
+        const outcome = await serialized(() => inDirectory(cwd, () => review({ cwd, scope: scope, only, deep: args.deep === true })));
+        return formatReport(outcome.report, outcome);
+    },
+};
+const scanSecrets = {
+    name: 'scan_secrets',
+    description: 'Scan the code you have changed for committed credentials, tokens, private keys and risky additions. Run it before committing configuration, environment or credential files, and whenever a value looks like a secret.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            scope: {
+                type: 'string',
+                enum: [...REVIEW_SCOPES],
+                description: 'Same meaning as in check_changes. Defaults to "worktree".',
+            },
+            ...CWD_PROPERTY,
+        },
+        additionalProperties: false,
+    },
+    async run(args) {
+        const scope = args.scope ?? 'worktree';
+        if (!REVIEW_SCOPES.includes(scope)) {
+            return {
+                text: `Unknown scope "${String(scope)}". Use one of: ${REVIEW_SCOPES.join(', ')}.`,
+                isError: true,
+            };
+        }
+        const cwd = await repoFor(args);
+        const outcome = await serialized(() => inDirectory(cwd, () => review({ cwd, scope: scope, only: [...SECRET_CHECKS] })));
+        return formatReport(outcome.report, outcome);
+    },
+};
+const verify = {
+    name: 'verify',
+    description: 'The final gate. Runs every check the pull-request gate runs, the slow ones included (typecheck, dependency audit, spellcheck, dead code), on the code you have changed. ' +
+        'Call it once when you believe the work is done and before you tell the user it is finished. ' +
+        'check_changes is the quick loop while you work; a clean verify is the closest you can get to knowing CI will agree.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            scope: {
+                type: 'string',
+                enum: [...REVIEW_SCOPES],
+                description: 'Same meaning as in check_changes. Defaults to "worktree".',
+            },
+            ...CWD_PROPERTY,
+        },
+        additionalProperties: false,
+    },
+    async run(args) {
+        const scope = args.scope ?? 'worktree';
+        if (!REVIEW_SCOPES.includes(scope)) {
+            return {
+                text: `Unknown scope "${String(scope)}". Use one of: ${REVIEW_SCOPES.join(', ')}.`,
+                isError: true,
+            };
+        }
+        const cwd = await repoFor(args);
+        const outcome = await serialized(() => inDirectory(cwd, () => review({ cwd, scope: scope, deep: true })));
+        return formatReport(outcome.report, outcome);
+    },
+};
+/** The only checks that can rewrite code safely: formatting and lint autofixes. */
+const FIXERS = ['Prettier', 'ESLint'];
+const applyFixes = {
+    name: 'apply_fixes',
+    writes: true,
+    description: 'Apply the safe automatic fixes — Prettier formatting and ESLint --fix — to the files you have changed, and nothing else. ' +
+        'Use it instead of spending effort fixing style findings by hand. It rewrites files in place, reports exactly which ones it changed, and then re-checks, so what is left is what needs a human decision. ' +
+        'It touches only files in your current changes; it never reformats the rest of the repository.',
+    inputSchema: { type: 'object', properties: { ...CWD_PROPERTY }, additionalProperties: false },
+    async run(args) {
+        const cwd = await repoFor(args);
+        return serialized(() => inDirectory(cwd, async () => {
+            const before = await fingerprintChanges(cwd);
+            if (before.size === 0)
+                return { text: 'Nothing to fix: the working tree matches HEAD.' };
+            await review({ cwd, scope: 'worktree', only: [...FIXERS], write: true });
+            const after = await fingerprintChanges(cwd);
+            const changed = [...after]
+                .filter(([file, hash]) => before.get(file) !== hash)
+                .map(([file]) => file);
+            // Re-check read-only: a fixer reporting success says nothing about what it could not fix.
+            const left = await review({ cwd, scope: 'worktree', only: [...FIXERS] });
+            const remaining = formatReport(left.report, left);
+            const head = changed.length > 0
+                ? `Rewrote ${changed.length} file(s):\n${changed.map(f => `  ${f}`).join('\n')}`
+                : 'No file needed fixing.';
+            return {
+                text: `${head}\n\nAfter the fixes:\n${remaining.text}`,
+                structured: { changedFiles: changed, ...(remaining.structured ?? {}) },
+            };
+        }));
+    },
+};
+const suggestConfigTool = {
+    name: 'suggest_config',
+    description: 'Set pr-checkmate up for THIS repository. Detects its languages, runs the fast checks across the whole repository as a baseline, and proposes a pr-checkmate.json: ' +
+        'checks that already fail are proposed as warnings so existing debt does not block every pull request, generated directories are excluded, and everything else keeps its defaults. ' +
+        'It writes nothing: show the proposal to the user, then call write_config if they agree. May take a while on a large repository.',
+    inputSchema: { type: 'object', properties: { ...CWD_PROPERTY }, additionalProperties: false },
+    async run(args) {
+        const cwd = await repoFor(args);
+        return formatSuggestion(await serialized(() => inDirectory(cwd, () => suggestConfig(cwd))));
+    },
+};
+const writeConfigTool = {
+    name: 'write_config',
+    writes: true,
+    description: "Write settings into the repository's pr-checkmate.json. " +
+        'The config is validated first (unknown keys, misspelt check names and bad values are refused with a suggestion), ' +
+        'then merged over what is already there: a value the user has already set is never replaced unless overwrite is true, ' +
+        'and the call lists what it kept. ' +
+        'Call it only after the user has seen and agreed to the settings.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            config: {
+                type: 'object',
+                description: 'The settings to add, e.g. {"severity": {"ESLint": "warn"}, "prSize": {"maxFiles": 80}}.',
+            },
+            overwrite: {
+                type: 'boolean',
+                description: 'Replace values that are already set. Only when the user asked to change them.',
+            },
+            ...CWD_PROPERTY,
+        },
+        required: ['config'],
+        additionalProperties: false,
+    },
+    async run(args) {
+        const cwd = await repoFor(args);
+        return writeConfig(cwd, args.config, args.overwrite === true);
+    },
+};
+const explainConfigTool = {
+    name: 'explain_config',
+    description: 'Explain a pr-checkmate.json setting from the schema that ships with this version: what it does, its default, its allowed values and its sub-keys. Call it with no key to list every top-level setting. Use it to answer "how do I make X stricter / turn Y off" before changing anything.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            key: {
+                type: 'string',
+                description: 'A setting, with dots for nested ones: "prSize" or "prSize.maxLines". Omit to list all.',
+            },
+        },
+        additionalProperties: false,
+    },
+    async run(args) {
+        return explainConfig(typeof args.key === 'string' && args.key ? args.key : undefined);
+    },
+};
+const dependencyTool = {
+    name: 'check_dependency',
+    network: true,
+    description: 'Before adding a package, ask whether it should be added.' +
+        'Reports whether it exists (models invent plausible names that attackers then publish), whether the version exists, known advisories, how new and how used it is, install-time scripts, deprecation, and whether the name imitates a popular package. ' +
+        'Only the package name and version are sent to the public registry and advisory database; ' +
+        'nothing from the repository leaves the machine. ' +
+        'A verdict of unknown means a lookup failed, never that the package is safe.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Package name exactly as it would be installed, e.g. "left-pad" or "@scope/pkg".',
+            },
+            version: {
+                type: 'string',
+                description: 'Exact version you intend to add. Omit to check the latest.',
+            },
+            ecosystem: { type: 'string', enum: ['npm', 'pypi'], description: 'Defaults to npm.' },
+        },
+        required: ['name'],
+        additionalProperties: false,
+    },
+    async run(args) {
+        if (typeof args.name !== 'string' || !args.name) {
+            return { text: 'check_dependency needs a package name.', isError: true };
+        }
+        if (args.ecosystem !== undefined && args.ecosystem !== 'npm' && args.ecosystem !== 'pypi') {
+            return { text: 'ecosystem must be "npm" or "pypi".', isError: true };
+        }
+        const report = await checkDependency(args.name, {
+            version: typeof args.version === 'string' ? args.version : undefined,
+            ecosystem: args.ecosystem,
+        });
+        return { text: formatDependency(report), structured: { ...report } };
+    },
+};
+const rulesResource = {
+    uri: RULES_URI,
+    name: 'Repository rules',
+    description: "What this repository's pull-request gate enforces, from its live configuration.",
+    mimeType: 'text/markdown',
+    async read() {
+        const cwd = await repoFor({});
+        return serialized(() => describeRules(cwd));
+    },
+};
+const PROMPTS = [
+    {
+        name: 'prepare_pr',
+        description: 'Get the current work ready for a pull request: fix style, run the full gate, report what is left.',
+        render: () => [
+            'Get my current changes ready for a pull request using the pr-checkmate tools.',
+            '1. Call apply_fixes to clear formatting and autofixable lint.',
+            '2. Call verify. It runs every check, including the slow ones.',
+            '3. Fix each failed (❌) finding in the code. Do not silence a rule, edit pr-checkmate.json, or skip a hook to make it pass.',
+            '4. Call verify again until nothing fails.',
+            '5. Tell me what is left: warnings I should know about, and anything you could not fix and why.',
+            'Do not commit unless I ask.',
+        ].join('\n'),
+    },
+    {
+        name: 'fix_findings',
+        description: 'Work through everything the gate reports, security problems first.',
+        render: () => [
+            'Call check_changes with deep: true and fix what it reports, in this order:',
+            '1. Security Scan and Diff Security: a leaked secret must be removed from the code and I must be told to rotate it.',
+            '2. Every other failed (❌) check.',
+            '3. Warnings, only where the fix is small and obvious.',
+            'After each group call check_changes again. Fix the cause in the code; never silence the rule. If a finding is a false positive, say so and ask me before ignoring it.',
+        ].join('\n'),
+    },
+    {
+        name: 'explain_finding',
+        description: 'Explain a finding or rule in plain terms and show how to fix it.',
+        arguments: [
+            {
+                name: 'finding',
+                description: 'The finding or check name, as the report shows it.',
+                required: true,
+            },
+        ],
+        render: ({ finding }) => `Explain this pr-checkmate finding: "${finding}". Say what it protects against, why it matters in this repository, and the smallest change that fixes it. Use explain_config if it is a configurable setting. Do not change any file unless I ask.`,
+    },
+    {
+        name: 'setup_pr_checkmate',
+        description: 'Configure pr-checkmate for this repository: propose settings, then write them once approved.',
+        render: () => [
+            'Set up pr-checkmate for this repository.',
+            '1. Call suggest_config and show me what it found and what it proposes, in plain language.',
+            '2. Wait for my answer. Do not write anything before I agree.',
+            '3. Call write_config with the settings I approved. Use explain_config if I ask what a setting does.',
+            '4. Call check_changes with scope "full" and tell me how many checks are red, so I know where we start.',
+            'Explain that checks proposed as warnings should be promoted back to errors one by one as they go clean.',
+        ].join('\n'),
+    },
+];
+const ALL_TOOLS = [
+    getRules,
+    checkChanges,
+    applyFixes,
+    scanSecrets,
+    dependencyTool,
+    suggestConfigTool,
+    writeConfigTool,
+    explainConfigTool,
+    verify,
+];
+const DISABLED_INSTRUCTIONS = 'pr-checkmate is turned off for this project (pr-checkmate.json, "mcp": { "enabled": false }). It has no tools here; do not look for them.';
+/** What the model is told on connect, with a note for any tool the project took away. */
+function instructionsFor(settings, offered) {
+    if (!settings.enabled)
+        return DISABLED_INSTRUCTIONS;
+    const hidden = ALL_TOOLS.filter(t => !offered.includes(t)).map(t => t.name);
+    return hidden.length === 0
+        ? INSTRUCTIONS
+        : `${INSTRUCTIONS}\nThis project does not offer: ${hidden.join(', ')}. Skip any step above that needs one of them.`;
+}
+/**
+ * The server definition `serve` hands to the protocol layer.
+ *
+ * What it offers is decided per access, from the project's `mcp` settings, so a
+ * change to `pr-checkmate.json` takes effect on the agent's next request.
+ */
+export function createServerDefinition(cwd = process.cwd()) {
+    return {
+        name: 'pr-checkmate',
+        version: packageVersion(),
+        get instructions() {
+            const settings = readMcpSettings(cwd);
+            return instructionsFor(settings, allowedTools(ALL_TOOLS, settings));
+        },
+        get tools() {
+            return allowedTools(ALL_TOOLS, readMcpSettings(cwd));
+        },
+        get resources() {
+            return readMcpSettings(cwd).enabled ? [rulesResource] : [];
+        },
+        get prompts() {
+            return readMcpSettings(cwd).enabled ? PROMPTS : [];
+        },
+    };
+}

package/dist/esm/utils/execa.d.ts

@@ -13,6 +13,13 @@
  * dragging the subprocess toolchain into consumers that never spawn a process.
  */
 import type { Options, Result } from 'execa';
+/**
+ * Keep children that would inherit our streams off them, and stop them sharing
+ * stdin. `stderr` (the MCP server) keeps their output as the server's log;
+ * `discard` (the commit hook) drops it, because a hook's stderr is read by the
+ * model and tool banners are not what it needs to hear. No other command is affected.
+ */
+export declare function isolateInheritedStdio(output?: 'stderr' | 'discard'): void;
 /**
  * Run a command via execa, loading the module lazily on first call.
  *