@imenam/mcp-feature-analyzer 1.0.1 → 1.0.3

package/dist/src/core/agent-repo.d.ts

@@ -0,0 +1,4 @@
+import { type RepoAccess } from "./git.js";
+import { type Run } from "./gateway-exec.js";
+/** Accès au dépôt `repoPath` de la machine de l'agent, par les commandes que `run` y fait exécuter. */
+export declare function agentRepo(repoPath: string, run: Run): RepoAccess;

package/dist/src/core/agent-repo.js

@@ -0,0 +1,172 @@
+/**
+ * Accès au dépôt placé sur la machine de l'agent, quand ce serveur tourne derrière
+ * mcp-http-gateway : chaque commande est exécutée par le relais agent (voir
+ * gateway-exec.ts), dans `repoPath`, et sa sortie revient dans le rappel de l'outil.
+ *
+ * - git lit le dépôt ; `node` lit les fichiers de la copie de travail.
+ * - La sortie d'une commande est limitée à 1 Mio par le relais : le diff est demandé
+ *   fichier par fichier, et un contenu tronqué est rendu `null`.
+ * - Les commandes d'une même demande sont groupées par paquets de STEPS_PER_ROUND, pour
+ *   borner la taille de chaque rappel.
+ */
+import path from "path";
+import { toPosixPath } from "./diff-parser.js";
+import { GitError } from "./errors.js";
+import { DIFF_ARGS, assertRefShape } from "./git.js";
+import { RELAY_MAX_OUTPUT_BYTES, isTruncated } from "./gateway-exec.js";
+/** Nombre maximal de commandes par demande d'exécution. */
+const STEPS_PER_ROUND = 25;
+/** Variable d'environnement qui porte le chemin du fichier à lire. */
+const FILE_ENV = "FEATURE_ANALYZER_FILE";
+/** Écrit sur stdout le contenu du fichier FILE_ENV, ou la cible POSIX d'un lien symbolique. */
+const READ_FILE_SCRIPT = [
+    'const fs = require("fs");',
+    `const file = process.env.${FILE_ENV};`,
+    "process.stdout.write(fs.lstatSync(file).isSymbolicLink()",
+    '  ? fs.readlinkSync(file).split(String.fromCharCode(92)).join("/")',
+    "  : fs.readFileSync(file));",
+].join("\n");
+const MIB = `${RELAY_MAX_OUTPUT_BYTES / (1024 * 1024)} MiB`;
+function detail(result) {
+    return (result.error ?? (result.stderr.trim() || result.stdout.trim())) || "no output";
+}
+/** Accès au dépôt `repoPath` de la machine de l'agent, par les commandes que `run` y fait exécuter. */
+export function agentRepo(repoPath, run) {
+    function gitStep(args) {
+        return {
+            command: "git",
+            args: ["-c", "core.quotepath=false", ...args],
+            cwd: repoPath,
+            env: { GIT_LITERAL_PATHSPECS: "1", GIT_TERMINAL_PROMPT: "0" },
+        };
+    }
+    function readFileStep(filePath) {
+        return {
+            command: "node",
+            args: ["--input-type=commonjs", "-e", READ_FILE_SCRIPT],
+            cwd: repoPath,
+            env: { [FILE_ENV]: filePath },
+        };
+    }
+    /** Échec de lancement d'une commande : dossier absent ou exécutable introuvable. */
+    function launchError(step, result) {
+        return new GitError(`Could not run ${step.command} in "${repoPath}" on the agent's machine (${result.error}). ` +
+            `Check that repo_path exists on that machine and that ${step.command} is on its PATH.`);
+    }
+    /** Exécute une seule commande et rend son résultat ; un échec de lancement lève une erreur. */
+    async function runOne(step) {
+        const [result] = await run([step]);
+        if (!result)
+            throw new GitError(`The agent relay returned no result for ${step.command} ${step.args.join(" ")}.`);
+        if (result.error !== undefined)
+            throw launchError(step, result);
+        return result;
+    }
+    /** Exécute une commande git qui doit réussir, avec une sortie complète. */
+    async function runGit(args) {
+        const result = await runOne(gitStep(args));
+        if (result.code !== 0)
+            throw new GitError(`git ${args.join(" ")} failed in ${repoPath} on the agent's machine: ${detail(result)}`);
+        if (isTruncated(result.stdout)) {
+            throw new GitError(`The output of git ${args.join(" ")} exceeds ${MIB}, the output limit of the agent relay.`);
+        }
+        return result.stdout;
+    }
+    /**
+     * Exécute une commande par élément, par paquets. Le relais s'arrête à la première
+     * commande en échec : `onFailure` rend l'erreur à lever pour cet élément.
+     */
+    async function runEach(items, toStep, onFailure) {
+        const all = [];
+        for (let start = 0; start < items.length; start += STEPS_PER_ROUND) {
+            const chunk = items.slice(start, start + STEPS_PER_ROUND);
+            const steps = chunk.map(toStep);
+            const results = await run(steps);
+            chunk.forEach((item, index) => {
+                const result = results[index];
+                if (!result)
+                    throw new GitError(`The agent relay returned no result for ${steps[index].command} ${steps[index].args.join(" ")}.`);
+                if (result.error !== undefined)
+                    throw launchError(steps[index], result);
+                if (result.code !== 0)
+                    throw onFailure(item, result);
+                all.push(result);
+            });
+        }
+        return all;
+    }
+    /** Contenu rendu par le relais, ou null s'il a été tronqué. */
+    function contentOf(result) {
+        return isTruncated(result.stdout) ? null : Buffer.from(result.stdout, "utf-8");
+    }
+    return {
+        async assertRepoRoot() {
+            if (!path.posix.isAbsolute(repoPath) && !path.win32.isAbsolute(repoPath)) {
+                throw new GitError(`repo_path must be an absolute path on the agent's machine, got "${repoPath}".`);
+            }
+            const args = ["rev-parse", "--show-toplevel", "--show-cdup"];
+            const result = await runOne(gitStep(args));
+            if (result.code !== 0) {
+                if (/not a git repository/i.test(result.stderr)) {
+                    throw new GitError(`repo_path "${repoPath}" is not inside a git repository.`);
+                }
+                throw new GitError(`git ${args.join(" ")} failed in ${repoPath} on the agent's machine: ${detail(result)}`);
+            }
+            const [topLevel, cdup] = result.stdout.split("\n");
+            if (cdup.trim() !== "") {
+                throw new GitError(`repo_path "${repoPath}" is not the root of its git repository. Use the repository root: ${topLevel.trim()}`);
+            }
+        },
+        async resolveCommit(ref, role) {
+            assertRefShape(ref, role);
+            const result = await runOne(gitStep(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]));
+            if (result.code !== 0) {
+                throw new GitError(`Unknown ${role} ref "${ref}" in ${repoPath}. Use a branch name, a tag or a commit sha that exists in this repository.`);
+            }
+            return result.stdout.trim();
+        },
+        async diff(range) {
+            const listing = await runGit([
+                "diff",
+                "--no-color",
+                "--no-ext-diff",
+                "--no-relative",
+                "--find-renames",
+                "--name-status",
+                "-z",
+                ...range,
+                "--",
+            ]);
+            const tokens = listing.split("\0");
+            const files = [];
+            for (let index = 0; index < tokens.length && tokens[index] !== "";) {
+                const pathCount = /^[RC]/.test(tokens[index]) ? 2 : 1;
+                files.push(tokens.slice(index + 1, index + 1 + pathCount));
+                index += 1 + pathCount;
+            }
+            const results = await runEach(files, (paths) => gitStep([...DIFF_ARGS, ...range, "--", ...paths]), (paths, result) => new GitError(`git diff of "${paths.join('" -> "')}" failed on the agent's machine: ${detail(result)}`));
+            return results
+                .map((result, index) => {
+                if (isTruncated(result.stdout)) {
+                    throw new GitError(`The diff of "${files[index].at(-1)}" exceeds ${MIB}, the output limit of the agent relay: this change cannot be analysed through the gateway.`);
+                }
+                return result.stdout;
+            })
+                .join("");
+        },
+        async readCommitFiles(commit, paths) {
+            const results = await runEach(paths, (filePath) => gitStep(["cat-file", "blob", `${commit}:${filePath}`]), (filePath) => new GitError(`"${filePath}" is in the diff but is not a file of commit ${commit} (submodule or unreadable entry).`));
+            return new Map(paths.map((filePath, index) => [filePath, contentOf(results[index])]));
+        },
+        async untrackedFiles() {
+            return (await runGit(["ls-files", "--others", "--exclude-standard", "-z"]))
+                .split("\0")
+                .filter((entry) => entry !== "")
+                .map(toPosixPath);
+        },
+        async readWorkingFiles(paths) {
+            const results = await runEach(paths, readFileStep, (filePath, result) => new GitError(`Could not read "${filePath}" in ${repoPath} on the agent's machine: ${detail(result)}`));
+            return new Map(paths.map((filePath, index) => [filePath, contentOf(results[index])]));
+        },
+    };
+}

package/dist/src/core/gateway-exec.d.ts

@@ -0,0 +1,27 @@
+import type { ToolResult } from "../tools/types.js";
+export declare const EXEC_ARG = "_gateway_exec";
+export declare const EXEC_META = "gateway/exec";
+export declare const EXEC_VERSION = 1;
+/** Taille maximale de la sortie d'une étape conservée par le relais agent. */
+export declare const RELAY_MAX_OUTPUT_BYTES: number;
+export interface ExecStep {
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+}
+export interface StepResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    error?: string;
+}
+export type Run = (steps: ExecStep[]) => Promise<StepResult[]>;
+/** Vrai si le relais agent a tronqué cette sortie. */
+export declare function isTruncated(output: string): boolean;
+/**
+ * Point d'entrée d'un outil qui s'exécute sur la machine de l'agent. Au premier appel,
+ * démarre `tool` ; aux rappels du relais agent, reprend la fonction là où elle attend.
+ * `exec` est la valeur de l'argument `_gateway_exec` de l'appel.
+ */
+export declare function handleAgentExec(exec: unknown, tool: (run: Run) => Promise<ToolResult>): Promise<ToolResult>;

package/dist/src/core/gateway-exec.js

@@ -0,0 +1,115 @@
+/**
+ * Exécution de commandes sur la machine de l'agent, par le relais agent de
+ * mcp-http-gateway (`mcp-http-gateway --mcp`).
+ *
+ * Convention, entre le relais agent et un MCP placé derrière le gateway :
+ *
+ * - Quand la route de ce MCP figure dans sa liste blanche (GATEWAY_EXEC_ROUTES), le
+ *   relais agent ajoute à chaque appel d'outil l'argument réservé `_gateway_exec` :
+ *   `{ version, cwd, gatewayToken }`. `cwd` est son dossier de lancement.
+ * - Le MCP peut répondre par une demande d'exécution au lieu d'un résultat final :
+ *   `_meta["gateway/exec"] = { id, steps }`. Chaque étape est `{ command, args, cwd, env }`,
+ *   lancée sans shell ; `cwd` est résolu par rapport au dossier de lancement du relais.
+ * - Le relais agent exécute les étapes dans l'ordre et s'arrête à la première qui
+ *   échoue. Il rappelle alors le même outil avec
+ *   `_gateway_exec.continuation = { id, results }`, un résultat par étape exécutée.
+ *   La sortie standard de chaque étape est tronquée au-delà de 1 Mio.
+ *
+ * Un outil s'écrit comme une fonction asynchrone qui appelle `run(steps)` : chaque
+ * appel suspend la fonction jusqu'au rappel du relais agent qui porte les résultats.
+ */
+import { randomUUID } from "crypto";
+export const EXEC_ARG = "_gateway_exec";
+export const EXEC_META = "gateway/exec";
+export const EXEC_VERSION = 1;
+/** Taille maximale de la sortie d'une étape conservée par le relais agent. */
+export const RELAY_MAX_OUTPUT_BYTES = 1024 * 1024;
+/** Mention ajoutée par le relais agent à la fin d'une sortie tronquée. */
+const TRUNCATION_MARK = /\n\[sortie tronquée à \d+ octets\]$/;
+/** Délai laissé au relais agent pour rendre les résultats d'une demande. */
+const CONTINUATION_TTL_MS = 30 * 60 * 1000;
+/** Vrai si le relais agent a tronqué cette sortie. */
+export function isTruncated(output) {
+    return TRUNCATION_MARK.test(output);
+}
+const flows = new Map();
+function nextEvent(flow) {
+    return new Promise((resolve) => {
+        flow.emit = resolve;
+    });
+}
+function toToolResult(flow, event) {
+    if (event.kind === "done") {
+        flows.delete(flow.id);
+        return event.result;
+    }
+    if (event.kind === "failed") {
+        flows.delete(flow.id);
+        throw event.error;
+    }
+    flow.steps = event.steps;
+    flow.timer = setTimeout(() => {
+        flows.delete(flow.id);
+        flow.abort?.(new Error("Timed out waiting for the agent relay to return the command results."));
+    }, CONTINUATION_TTL_MS);
+    flow.timer.unref();
+    return {
+        content: [{ type: "text", text: "Command execution request for the agent's machine, to be handled by the agent relay." }],
+        _meta: { [EXEC_META]: { id: flow.id, steps: event.steps } },
+    };
+}
+function assertAnnounced(raw) {
+    if (!raw || typeof raw !== "object") {
+        const route = process.env.MCP_SERVER_ROUTE?.trim() || "the route of this MCP";
+        throw new Error("This tool runs git on the agent's machine, through the agent relay (mcp-http-gateway --mcp), " +
+            `and the relay did not offer command execution: add ${route} to GATEWAY_EXEC_ROUTES in the "env" block ` +
+            "of the relay configuration, with a version of mcp-http-gateway that supports it.");
+    }
+    if (raw.version !== EXEC_VERSION) {
+        throw new Error(`Unsupported agent relay execution version: ${raw.version} (expected ${EXEC_VERSION}).`);
+    }
+}
+function parseResults(raw, steps) {
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > steps.length) {
+        throw new Error("Invalid command results from the agent relay: one result is expected per step run.");
+    }
+    return raw.map((r) => ({
+        code: typeof r?.code === "number" ? r.code : null,
+        stdout: typeof r?.stdout === "string" ? r.stdout : "",
+        stderr: typeof r?.stderr === "string" ? r.stderr : "",
+        ...(typeof r?.error === "string" ? { error: r.error } : {}),
+    }));
+}
+/**
+ * Point d'entrée d'un outil qui s'exécute sur la machine de l'agent. Au premier appel,
+ * démarre `tool` ; aux rappels du relais agent, reprend la fonction là où elle attend.
+ * `exec` est la valeur de l'argument `_gateway_exec` de l'appel.
+ */
+export async function handleAgentExec(exec, tool) {
+    assertAnnounced(exec);
+    const continuation = exec.continuation;
+    if (continuation) {
+        const flow = flows.get(continuation.id);
+        if (!flow || !flow.resume || !flow.steps) {
+            throw new Error("Unknown or expired execution continuation (the MCP server may have restarted): call the tool again.");
+        }
+        const results = parseResults(continuation.results, flow.steps);
+        clearTimeout(flow.timer);
+        const resume = flow.resume;
+        flow.resume = undefined;
+        flow.abort = undefined;
+        const event = nextEvent(flow);
+        resume(results);
+        return toToolResult(flow, await event);
+    }
+    const flow = { id: randomUUID(), emit: () => { } };
+    flows.set(flow.id, flow);
+    const event = nextEvent(flow);
+    const run = (steps) => new Promise((resolve, reject) => {
+        flow.resume = resolve;
+        flow.abort = reject;
+        flow.emit({ kind: "exec", steps });
+    });
+    tool(run).then((result) => flow.emit({ kind: "done", result }), (error) => flow.emit({ kind: "failed", error }));
+    return toToolResult(flow, await event);
+}

package/dist/src/core/git.d.ts

@@ -26,10 +26,35 @@ export interface ComputedSnapshot {
     diff: FileDiff[];
 }
 /**
- * Calcule le snapshot d'une analyse avec git.
+ * Accès au dépôt sur la machine qui le porte : git et copie de travail.
+ * Un contenu `null` dépasse ce que l'accès sait transférer.
+ */
+export interface RepoAccess {
+    /** Vérifie que le chemin du dépôt désigne la racine d'un dépôt git. */
+    assertRepoRoot(): Promise<void>;
+    /** Résout une ref en sha de commit ; erreur explicite si elle est inconnue. */
+    resolveCommit(ref: string, role: string): Promise<string>;
+    /** Sortie de `git diff` (DIFF_ARGS) pour `range`, par ex. `["<base>...<head>"]` ou `["HEAD"]`. */
+    diff(range: string[]): Promise<string>;
+    /** Contenu des fichiers `paths` dans le commit `commit`. */
+    readCommitFiles(commit: string, paths: string[]): Promise<Map<string, Buffer | null>>;
+    /** Fichiers non suivis et non ignorés, chemins POSIX relatifs au dépôt. */
+    untrackedFiles(): Promise<string[]>;
+    /** Contenu des fichiers `paths` de la copie de travail ; un lien symbolique donne sa cible. */
+    readWorkingFiles(paths: string[]): Promise<Map<string, Buffer | null>>;
+}
+export declare const DIFF_ARGS: string[];
+/** Vrai si le contenu contient un octet nul dans ses 8000 premiers octets (même règle que git). */
+export declare function looksBinary(content: Buffer): boolean;
+/** Accès direct au dépôt, sur la machine de ce serveur. */
+export declare function localRepo(repoPath: string): RepoAccess;
+/** Vérifie une ref fournie par l'agent avant de la passer à git. */
+export declare function assertRefShape(ref: string, role: string): void;
+/**
+ * Calcule le snapshot d'une analyse avec git, par `repo` (accès local par défaut).
  * - `branch` : diff `base...head` (head vaut `HEAD` par défaut), contenu lu dans le commit de tête ;
  * - `working_tree` : diff de HEAD vers la copie de travail, index compris, fichiers non suivis
  *   présentés comme ajoutés, contenu lu sur disque.
  * Les fichiers sont triés par chemin ; `reviewed` vaut false partout.
  */
-export declare function computeSnapshot(request: SnapshotRequest): Promise<ComputedSnapshot>;
+export declare function computeSnapshot(request: SnapshotRequest, repo?: RepoAccess): Promise<ComputedSnapshot>;

package/dist/src/core/git.js

@@ -57,9 +57,7 @@ async function assertRepoRoot(repoPath) {
 }
 /** Résout une ref en sha de commit ; erreur explicite si elle est inconnue. */
 async function resolveCommit(repoPath, ref, role) {
-    if (ref.startsWith("-")) {
-        throw new GitError(`Invalid ${role} ref "${ref}": a ref cannot start with "-".`);
-    }
+    assertRefShape(ref, role);
     try {
         return (await runGit(repoPath, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], "utf-8")).trim();
     }
@@ -67,7 +65,7 @@ async function resolveCommit(repoPath, ref, role) {
         throw new GitError(`Unknown ${role} ref "${ref}" in ${repoPath}. Use a branch name, a tag or a commit sha that exists in this repository.`);
     }
 }
-const DIFF_ARGS = [
+export const DIFF_ARGS = [
     "-c",
     "diff.noprefix=false",
     "-c",
@@ -82,7 +80,7 @@ const DIFF_ARGS = [
     "--dst-prefix=b/",
 ];
 /** Vrai si le contenu contient un octet nul dans ses 8000 premiers octets (même règle que git). */
-function looksBinary(content) {
+export function looksBinary(content) {
     return content.subarray(0, 8000).includes(0);
 }
 /** Hunk unique d'un fichier ajouté, toutes lignes en ajout. */
@@ -108,9 +106,9 @@ function readWorkingFile(repoPath, filePath) {
         return Buffer.from(toPosixPath(fs.readlinkSync(absolute)), "utf-8");
     return fs.readFileSync(absolute);
 }
-/** Texte conservé dans le snapshot, ou null quand le contenu dépasse MAX_SNAPSHOT_FILE_BYTES. */
+/** Texte conservé dans le snapshot, ou null quand le contenu est absent ou dépasse MAX_SNAPSHOT_FILE_BYTES. */
 function snapshotText(content) {
-    if (content.length > MAX_SNAPSHOT_FILE_BYTES)
+    if (content == null || content.length > MAX_SNAPSHOT_FILE_BYTES)
         return null;
     return content.toString("utf-8");
 }
@@ -172,33 +170,49 @@ async function readCommitFiles(repoPath, commit, paths) {
     });
     return contents;
 }
-async function branchSnapshot(repoPath, base, head) {
-    const baseCommit = await resolveCommit(repoPath, base, "base");
-    const headCommit = await resolveCommit(repoPath, head, "head");
-    const output = await runGit(repoPath, [...DIFF_ARGS, `${baseCommit}...${headCommit}`, "--"], "utf-8");
+/** Accès direct au dépôt, sur la machine de ce serveur. */
+export function localRepo(repoPath) {
+    return {
+        assertRepoRoot: () => assertRepoRoot(repoPath),
+        resolveCommit: (ref, role) => resolveCommit(repoPath, ref, role),
+        diff: (range) => runGit(repoPath, [...DIFF_ARGS, ...range, "--"], "utf-8"),
+        readCommitFiles: (commit, paths) => readCommitFiles(repoPath, commit, paths),
+        untrackedFiles: async () => (await runGit(repoPath, ["ls-files", "--others", "--exclude-standard", "-z"], "utf-8"))
+            .split("\0")
+            .filter((entry) => entry !== "")
+            .map(toPosixPath),
+        readWorkingFiles: async (paths) => new Map(paths.map((filePath) => [filePath, readWorkingFile(repoPath, filePath)])),
+    };
+}
+/** Vérifie une ref fournie par l'agent avant de la passer à git. */
+export function assertRefShape(ref, role) {
+    if (ref.startsWith("-")) {
+        throw new GitError(`Invalid ${role} ref "${ref}": a ref cannot start with "-".`);
+    }
+}
+async function branchSnapshot(repo, base, head) {
+    const baseCommit = await repo.resolveCommit(base, "base");
+    const headCommit = await repo.resolveCommit(head, "head");
+    const output = await repo.diff([`${baseCommit}...${headCommit}`]);
     const parsedFiles = parseUnifiedDiff(output);
     const withContent = parsedFiles.filter((parsed) => parsed.status !== "deleted" && !parsed.binary).map((parsed) => parsed.path);
-    const contents = await readCommitFiles(repoPath, headCommit, withContent);
-    const results = parsedFiles.map((parsed) => {
-        const content = contents.get(parsed.path);
-        return toEntry(parsed, content === undefined ? null : snapshotText(content));
-    });
+    const contents = await repo.readCommitFiles(headCommit, withContent);
+    const results = parsedFiles.map((parsed) => toEntry(parsed, snapshotText(contents.get(parsed.path))));
     return { baseCommit, headCommit, results };
 }
-async function workingTreeSnapshot(repoPath) {
-    const baseCommit = await resolveCommit(repoPath, "HEAD", "base");
-    const output = await runGit(repoPath, [...DIFF_ARGS, "HEAD", "--"], "utf-8");
-    const results = [];
-    for (const parsed of parseUnifiedDiff(output)) {
-        const content = parsed.status !== "deleted" && !parsed.binary ? snapshotText(readWorkingFile(repoPath, parsed.path)) : null;
-        results.push(toEntry(parsed, content));
-    }
-    const untracked = (await runGit(repoPath, ["ls-files", "--others", "--exclude-standard", "-z"], "utf-8"))
-        .split("\0")
-        .filter((entry) => entry !== "")
-        .map(toPosixPath);
+async function workingTreeSnapshot(repo) {
+    const baseCommit = await repo.resolveCommit("HEAD", "base");
+    const parsedFiles = parseUnifiedDiff(await repo.diff(["HEAD"]));
+    const withContent = parsedFiles.filter((parsed) => parsed.status !== "deleted" && !parsed.binary).map((parsed) => parsed.path);
+    const contents = await repo.readWorkingFiles(withContent);
+    const results = parsedFiles.map((parsed) => toEntry(parsed, snapshotText(contents.get(parsed.path))));
+    const untracked = await repo.untrackedFiles();
+    const untrackedContents = await repo.readWorkingFiles(untracked);
     for (const filePath of untracked) {
-        const raw = readWorkingFile(repoPath, filePath);
+        const raw = untrackedContents.get(filePath);
+        if (raw == null) {
+            throw new GitError(`The untracked file "${filePath}" is too large to be transferred from the repository's machine. Add it to .gitignore or remove it, then try again.`);
+        }
         const binary = looksBinary(raw);
         const content = binary ? null : snapshotText(raw);
         const lines = binary ? [] : splitLines(raw.toString("utf-8"));
@@ -208,15 +222,15 @@ async function workingTreeSnapshot(repoPath) {
     return { baseCommit, headCommit: null, results };
 }
 /**
- * Calcule le snapshot d'une analyse avec git.
+ * Calcule le snapshot d'une analyse avec git, par `repo` (accès local par défaut).
  * - `branch` : diff `base...head` (head vaut `HEAD` par défaut), contenu lu dans le commit de tête ;
  * - `working_tree` : diff de HEAD vers la copie de travail, index compris, fichiers non suivis
  *   présentés comme ajoutés, contenu lu sur disque.
  * Les fichiers sont triés par chemin ; `reviewed` vaut false partout.
  */
-export async function computeSnapshot(request) {
+export async function computeSnapshot(request, repo = localRepo(request.repoPath)) {
     const { repoPath, mode } = request;
-    await assertRepoRoot(repoPath);
+    await repo.assertRepoRoot();
     let base;
     let head;
     let computed;
@@ -226,7 +240,7 @@ export async function computeSnapshot(request) {
             throw new GitError(`"base" is required in branch mode: give the ref the feature branched from.`);
         base = requestedBase;
         head = request.head?.trim() || DEFAULT_HEAD_REF;
-        computed = await branchSnapshot(repoPath, base, head);
+        computed = await branchSnapshot(repo, base, head);
     }
     else if (mode === "working_tree") {
         if (request.head != null && request.head.trim() !== "") {
@@ -237,7 +251,7 @@ export async function computeSnapshot(request) {
         }
         base = "HEAD";
         head = null;
-        computed = await workingTreeSnapshot(repoPath);
+        computed = await workingTreeSnapshot(repo);
     }
     else {
         throw new GitError(`Unknown mode "${String(mode)}": use "branch" or "working_tree".`);

package/dist/src/core/role.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Rôle du serveur, fixé par la variable MCP_FEATURE_ANALYZER_ROLE.
+ *
+ * - `standalone` (défaut) : le serveur tourne sur la machine qui porte les dépôts et y
+ *   exécute git lui-même.
+ * - `remote` : le serveur tourne derrière mcp-http-gateway, sur une autre machine ; git
+ *   et la lecture des fichiers s'exécutent sur la machine de l'agent, par le relais agent
+ *   (`mcp-http-gateway --mcp`, route listée dans GATEWAY_EXEC_ROUTES).
+ */
+export type Role = "standalone" | "remote";
+export declare function resolveRole(): Role;

package/dist/src/core/role.js

@@ -0,0 +1,9 @@
+const ROLES = ["standalone", "remote"];
+export function resolveRole() {
+    const raw = process.env.MCP_FEATURE_ANALYZER_ROLE?.trim();
+    if (!raw)
+        return "standalone";
+    if (ROLES.includes(raw))
+        return raw;
+    throw new Error(`MCP_FEATURE_ANALYZER_ROLE="${raw}" is invalid (expected: ${ROLES.join(" | ")}).`);
+}

package/dist/src/index.js

@@ -12,7 +12,10 @@ import { resolveDataDir } from "./core/data-dir.js";
 import { resolveLogDir } from "./core/log-dir.js";
 import { AnalysisStore } from "./core/analysis-store.js";
 import { AnalysisError, NotFoundError, RevisionConflictError } from "./core/errors.js";
-import { DEFAULT_HEAD_REF } from "./core/git.js";
+import { DEFAULT_HEAD_REF, localRepo } from "./core/git.js";
+import { agentRepo } from "./core/agent-repo.js";
+import { EXEC_ARG, handleAgentExec } from "./core/gateway-exec.js";
+import { resolveRole } from "./core/role.js";
 import { addNote, deleteNote, setFileReviewed, setFindingStatus, submitReview } from "./core/review-actions.js";
 import { GUI_REQUEST_TYPES, IPCMessageSchema } from "../shared/schemas/ipc.schema.js";
 import { AddNoteRequestSchema, AnalysisRequestSchema, DeleteNoteRequestSchema, SetFileReviewedRequestSchema, SetFindingStatusRequestSchema, SubmitReviewRequestSchema, } from "../shared/schemas/api.schema.js";
@@ -66,6 +69,15 @@ function getConfig() {
     return { proxyUrl: process.env.PROXY_URL, appPort: process.env.APP_PORT, version: APP_VERSION };
 }
 getConfig();
+let role;
+try {
+    role = resolveRole();
+}
+catch (err) {
+    logger.error(err.message);
+    console.error(err.message);
+    process.exit(1);
+}
 const dataDir = resolveDataDir(rootDir);
 const store = new AnalysisStore(dataDir);
 /** Présentation du serveur transmise au client MCP : concepts, déroulé et règles. */
@@ -334,7 +346,12 @@ const TOOLS = [
         inputSchema: {
             type: "object",
             properties: {
-                repo_path: { type: "string", description: "Absolute path of the root of the git repository." },
+                repo_path: {
+                    type: "string",
+                    description: role === "remote"
+                        ? "Absolute path of the root of the git repository on your machine: git runs there, through the agent relay of mcp-http-gateway."
+                        : "Absolute path of the root of the git repository.",
+                },
                 project: { type: "string", description: PROJECT_DOC },
                 title: { type: "string", description: "Short title of the feature, e.g. \"OAuth token refresh\"." },
                 mode: {
@@ -592,9 +609,20 @@ function afterMutation({ result, analysisId }) {
     notifyAnalysisChanged(analysisId);
     return { ...result, content: [{ type: "text", text: result.content[0].text + guiHint(analysisId) }] };
 }
+/**
+ * Donne à `fn` l'accès aux dépôts du rôle : git local en `standalone` ; en `remote`,
+ * commandes exécutées sur la machine de l'agent par le relais, qui annonce cette
+ * possibilité dans l'argument `exec`.
+ */
+function withRepoAccess(exec, fn) {
+    if (role === "standalone")
+        return fn(localRepo);
+    return handleAgentExec(exec, (run) => fn((repoPath) => agentRepo(repoPath, run)));
+}
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
-    const params = (args ?? {});
+    // L'argument réservé du relais agent accompagne tous les appels d'une route listée dans GATEWAY_EXEC_ROUTES.
+    const { [EXEC_ARG]: exec, ...params } = (args ?? {});
     try {
         switch (name) {
             case "list_analyses":
@@ -605,11 +633,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return getDiff(store, params);
             case "get_review_feedback":
                 return getReviewFeedback(store, params);
-            case "create_analysis": {
-                const mutation = await createAnalysis(store, params);
-                notifyAnalysesListChanged();
-                return afterMutation(mutation);
-            }
+            case "create_analysis":
+                return await withRepoAccess(exec, async (repoFor) => {
+                    const mutation = await createAnalysis(store, params, repoFor);
+                    notifyAnalysesListChanged();
+                    return afterMutation(mutation);
+                });
             case "update_analysis":
                 return afterMutation(updateAnalysis(store, params));
             case "add_findings":
@@ -623,7 +652,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "delete_diagram":
                 return afterMutation(deleteDiagram(store, params));
             case "refresh_analysis":
-                return afterMutation(await refreshAnalysis(store, params));
+                return await withRepoAccess(exec, async (repoFor) => afterMutation(await refreshAnalysis(store, params, repoFor)));
             case "delete_analysis": {
                 const { result, analysisId } = deleteAnalysis(store, params);
                 notifyAnalysisChanged(analysisId);
@@ -643,7 +672,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    logger.info(`MCP Server connected and running on stdio (data dir: ${dataDir})`);
+    logger.info(`MCP Server connected and running on stdio (role: ${role}, data dir: ${dataDir})`);
     launchGUI();
 }
 main().catch((err) => {

package/dist/src/tools/create-analysis.d.ts

@@ -1,4 +1,5 @@
 import type { AnalysisStore } from "../core/analysis-store.js";
+import { type RepoAccess } from "../core/git.js";
 import { type Args, type MutationResult } from "./types.js";
-/** Calcule et fige le diff du dépôt, puis crée l'analyse. */
-export declare function createAnalysis(store: AnalysisStore, args: Args): Promise<MutationResult>;
+/** Calcule et fige le diff du dépôt, lu par `repoFor(repo_path)` (git local par défaut), puis crée l'analyse. */
+export declare function createAnalysis(store: AnalysisStore, args: Args, repoFor?: (repoPath: string) => RepoAccess): Promise<MutationResult>;