mcp-phase-gate 2.0.1 → 2.2.0

package/build/schemas.js

@@ -1,105 +1,181 @@
 // Los argumentos de cada tool, declarados una sola vez con zod.
 //
 // Antes cada tool leía sus argumentos con String(args?.x), que no valida nada: sin task_name,
-// String(undefined) creaba la tarea "undefined/" y la dejaba activa. Ahora todo pasa por aquí
-// antes de usarse, y el error nombra el campo.
+// String(undefined) creaba la tarea "undefined/" y la dejaba activa. Desde la Etapa 0 todo pasa
+// por aquí antes de usarse, y el error nombra el campo.
 //
-// Se exportan shapes (los campos sueltos) y no z.object(...): es lo que recibe registerTool
-// del SDK, al que se pasarán tal cual en la migración a McpServer (Etapa 2).
+// Se exportan shapes (los campos sueltos) y no z.object(...): es lo que recibe registerTool del
+// SDK. El SDK genera con ellos el JSON Schema que ve el cliente —por eso cada campo lleva aquí su
+// descripción— y valida cada llamada antes del callback.
+//
+// Los mensajes de error van en cada campo, en español, porque el SDK los entrega tal cual detrás
+// de su prefijo en inglés ("Input validation error: Invalid arguments for tool …"). Sin ellos
+// llegaría el texto genérico de zod ("expected string, received undefined"), que no le dice al
+// modelo cómo corregir la llamada.
 //
 // Los opcionales son .nullish() y null cuenta como ausente: algunos clientes con modelos en
 // modo estricto mandan null en todo campo opcional. Un número en texto (phase: "3") no se
 // convierte: se rechaza con un mensaje que dice qué se espera. Es raro, el modelo lo corrige
-// al primer intento, y convertirlo complicaría el JSON Schema que se generará desde aquí.
+// al primer intento, y convertirlo complicaría el JSON Schema que se genera desde aquí.
 import { z } from "zod";
+// Lo que se espera de cada tipo, dicho como se le diría al modelo para que corrija la llamada.
+// El único número es `phase`, de ahí el ejemplo.
+const TIPOS = {
+    string: "un texto",
+    number: "un número, por ejemplo 3",
+    int: "un número entero, por ejemplo 3",
+    boolean: "true o false",
+    object: "un objeto",
+};
+// El mensaje de un campo. null también es "falta": en un opcional se tolera antes de llegar aquí,
+// en un obligatorio es lo mismo que no venir.
+function mensaje(campo) {
+    const nombre = `\`${campo}\``;
+    return (issue) => {
+        if (issue.input === undefined || issue.input === null)
+            return `Falta ${nombre}.`;
+        if (issue.code === "invalid_type")
+            return `${nombre} debe ser ${TIPOS[issue.expected] ?? issue.expected}.`;
+        // El único máximo que puede saltar es el del entero seguro de `phase`.
+        if (issue.code === "too_big")
+            return `${nombre} es demasiado grande.`;
+        return `${nombre} no es válido.`;
+    };
+}
+function texto(campo) {
+    return z.string({ error: mensaje(campo) });
+}
+// `recortar` quita los espacios ANTES de exigir el mínimo: "   " cuenta como que falta.
+function obligatorio(campo, opciones = {}) {
+    const base = opciones.recortar ? texto(campo).trim() : texto(campo);
+    return base.min(1, `Falta \`${campo}\`.`);
+}
+function booleano(campo) {
+    return z.boolean({ error: mensaje(campo) });
+}
+// ─── Descripciones ──────────────────────────────────────────────────────────
+// Son estáticas: no nombran proyectos ni fases concretas. Antes se armaban al arrancar con la
+// lista de proyectos y de fases, y se quedaban viejas en cuanto alguien creaba una carpeta con el
+// cliente abierto, porque la lista de tools no se vuelve a pedir. Lo que cambia vive ahora en los
+// recursos phase-gate://estado y phase-gate://fases, que sí avisan cuando cambian.
+const PROYECTO = "Proyecto: el nombre de una carpeta de proyecto de la Documentación Central. Si no existe, la " +
+    "tool te devuelve los que hay. También los listan `list_tasks`, `get_orchestrator_status` y el recurso " +
+    "`phase-gate://estado`.";
+const FASE = "Número de fase. Con los prompts de fábrica son 1 a 5; `get_orchestrator_status` y el recurso " +
+    "`phase-gate://fases` listan las disponibles con su título y documento.";
+const TAREA = "Nombre de la carpeta de la tarea.";
+const ARCHIVO = "Nombre (o ruta relativa) del archivo dentro de la carpeta de la tarea (ej. '01 - Análisis Técnico.md').";
+// ─── Shapes ─────────────────────────────────────────────────────────────────
 export const startTaskShape = {
-    project: z.string().trim().min(1, "Falta `project`."),
-    task_name: z.string().min(1, "Falta `task_name`."),
-    initial_context: z.string().min(1, "Falta `initial_context`."),
-    crear_proyecto: z.boolean().nullish(),
+    project: obligatorio("project", { recortar: true }).describe(PROYECTO),
+    task_name: obligatorio("task_name").describe("Nombre de la tarea (creará una carpeta con este nombre)."),
+    initial_context: obligatorio("initial_context").describe("El contexto, correo o requerimiento inicial completo."),
+    crear_proyecto: booleano("crear_proyecto")
+        .nullish()
+        .describe("Solo para ESTRENAR un proyecto que todavía no existe. Déjalo sin poner salvo que el usuario te haya " +
+        "dicho explícitamente que quiere crear un proyecto nuevo: sirve para que un nombre mal escrito no cree " +
+        "una carpeta suelta en la Documentación."),
 };
 export const getPhasePromptShape = {
-    phase: z.number().int(),
-    project: z.string().nullish(),
-    task_name: z.string().nullish(),
+    phase: z.number({ error: mensaje("phase") }).int({ error: mensaje("phase") }).describe(FASE),
+    project: texto("project")
+        .nullish()
+        .describe(`${PROYECTO} Pásalo siempre que lo sepas —lo sabes por el repositorio que tienes abierto— para que se ` +
+        "pueda comprobar que no te saltas una fase. La tarea se toma de la activa de ese proyecto."),
+    task_name: texto("task_name")
+        .nullish()
+        .describe("Solo si quieres comprobar contra una tarea distinta de la activa del proyecto. Normalmente se omite."),
 };
 export const getActiveTaskShape = {
-    project: z.string().nullish(),
+    project: texto("project")
+        .nullish()
+        .describe(`${PROYECTO} Si lo omites, se devuelve la tarea activa de cada proyecto.`),
 };
 export const listTasksShape = {
-    project: z.string().nullish(),
+    project: texto("project").nullish().describe(`${PROYECTO} Si lo omites, se listan todos.`),
 };
 export const switchTaskShape = {
-    project: z.string().trim().min(1, "Falta `project`."),
-    task_name: z.string().min(1, "Falta `task_name`."),
+    project: obligatorio("project", { recortar: true }).describe(PROYECTO),
+    task_name: obligatorio("task_name").describe("Nombre de la carpeta de la tarea a activar. Si no existe, la tool te devuelve las que sí."),
 };
 // Los cuatro son opcionales por separado: qué combinación vale lo decide resolveDocPath.
 export const readCentralDocShape = {
-    project: z.string().nullish(),
-    task_name: z.string().nullish(),
-    file_name: z.string().nullish(),
-    file_path: z.string().nullish(),
+    project: texto("project").nullish().describe(`${PROYECTO} Úsalo junto con task_name y file_name.`),
+    task_name: texto("task_name").nullish().describe(TAREA),
+    file_name: texto("file_name").nullish().describe(ARCHIVO),
+    file_path: texto("file_path")
+        .nullish()
+        .describe("ALTERNATIVA: ruta relativa dentro de la Documentación Central (ej. " +
+        "'PROYECTO-A/Proyectos/tarea/01 - Análisis Técnico.md'). Solo si no usas project+task_name."),
 };
 export const writeCentralDocShape = {
     ...readCentralDocShape,
-    content: z.string(),
+    file_path: texto("file_path")
+        .nullish()
+        .describe("ALTERNATIVA: ruta relativa dentro de la Documentación Central, que tiene que caer dentro de la carpeta " +
+        "de una tarea que ya existe (ej. 'PROYECTO-A/Proyectos/tarea/01 - Análisis Técnico.md'). Los archivos " +
+        "del proyecto no se escriben con esta tool. Solo si no usas project+task_name."),
+    content: texto("content").describe("Contenido a escribir."),
+    force: booleano("force")
+        .nullish()
+        .describe("Permite reescribir un documento congelado o el contexto inicial. Solo se usa si tu cliente no puede " +
+        "pedirle la confirmación al usuario directamente. Nunca lo pongas sin que el usuario lo haya confirmado en el chat."),
 };
 export const readCrossRepoShape = {
-    repo_name: z.string().min(1, "Falta `repo_name`."),
-    file_path: z.string().min(1, "Falta `file_path`."),
+    repo_name: obligatorio("repo_name").describe("Nombre del repositorio (ej. 'repo-a', 'repo-b')."),
+    file_path: obligatorio("file_path").describe("Ruta relativa del archivo dentro del repositorio (ej. 'src/main.ts')."),
 };
-const SHAPES = {
-    start_task: startTaskShape,
-    get_phase_prompt: getPhasePromptShape,
-    get_active_task: getActiveTaskShape,
-    list_tasks: listTasksShape,
-    switch_task: switchTaskShape,
-    read_central_doc: readCentralDocShape,
-    write_central_doc: writeCentralDocShape,
-    read_cross_repo: readCrossRepoShape,
+// get_orchestrator_status no recibe nada.
+export const getOrchestratorStatusShape = {};
+// ─── Salida de get_orchestrator_status ──────────────────────────────────────
+// El objeto Diagnostico de diagnostico.ts, campo por campo. Con un outputSchema el cliente recibe
+// además `structuredContent`, y el SDK comprueba antes de enviarlo que cuadra con este shape:
+// si diagnostico.ts cambia y esto no, la tool falla en los tests en vez de mentir al cliente.
+const estadoRuta = z.object({ ruta: z.string().optional(), existe: z.boolean(), error: z.string().optional() });
+export const diagnosticoShape = {
+    paquete: z.object({
+        version: z.string(),
+        ruta: z.string(),
+        via: z.enum(["npx", "global", "dependencia", "clon"]),
+    }),
+    node: z.object({ version: z.string(), plataforma: z.string() }),
+    variables: z.array(z.object({
+        logica: z.enum(["DOCS_PATH", "REPOS_PATH", "TASKS_SUBDIR", "PROMPTS_PATH", "STATE_PATH", "ELICITATION"]),
+        valor: z.string().optional(),
+        usada: z.string().nullable(),
+        fuente: z.enum(["entorno", ".env", "sin definir"]),
+        discrepancia: z.string().nullable(),
+    })),
+    rutas: z.object({ docs: estadoRuta, repos: estadoRuta }),
+    estado: z.object({ archivo: z.string(), existe: z.boolean(), punteros: z.number().int() }),
+    capas: z.array(z.object({ ruta: z.string(), etiqueta: z.enum(["fábrica", "propia"]), existe: z.boolean() })),
+    reglasGlobales: z.object({ archivo: z.string().nullable(), capa: z.string().nullable(), faltan: z.array(z.string()) }),
+    fases: z.array(z.object({
+        numero: z.number().int(),
+        titulo: z.string(),
+        archivo: z.string(),
+        capa: z.string(),
+        documento: z.string().optional(),
+        recibos: z.string().optional(),
+        comando: z.string().nullable(),
+    })),
+    proyectos: z.array(z.object({
+        nombre: z.string(),
+        tareas: z.number().int(),
+        activa: z
+            .object({ tarea: z.string(), origen: z.enum(["puntero", "deducida"]), fase: z.string() })
+            .nullable(),
+    })),
+    cliente: z
+        .object({
+        nombre: z.string(),
+        version: z.string(),
+        capacidades: z.object({ elicitation: z.boolean(), roots: z.boolean() }),
+    })
+        .optional(),
+    hallazgos: z.array(z.object({ severidad: z.enum(["error", "aviso", "info"]), codigo: z.string(), texto: z.string() })),
 };
-// Lo que se espera de cada tipo, dicho como se le diría al modelo para que corrija la llamada.
-// El único número es `phase`, de ahí el ejemplo.
-const TIPOS = {
-    string: "un texto",
-    number: "un número, por ejemplo 3",
-    int: "un número entero, por ejemplo 3",
-    boolean: "true o false",
-    object: "un objeto",
-};
-function describirProblema(issue, recibidos) {
-    const campo = issue.path.map(String).join(".");
-    if (!campo)
-        return "los argumentos tienen que ser un objeto.";
-    const nombre = `\`${campo}\``;
-    // null también es "falta": en un opcional se tolera, en un obligatorio es lo mismo que no venir.
-    if (issue.code === "invalid_type") {
-        return recibidos[campo] == null
-            ? `Falta ${nombre}.`
-            : `${nombre} debe ser ${TIPOS[issue.expected] ?? issue.expected}.`;
-    }
-    // Los mínimos llevan su mensaje en español en el propio shape ("Falta `task_name`.").
-    if (issue.code === "too_small")
-        return issue.message;
-    // Los máximos no: el único que puede saltar es el del entero seguro de `phase`.
-    if (issue.code === "too_big")
-        return `${nombre} es demasiado grande.`;
-    return `${nombre}: ${issue.message}.`;
-}
-export function validarLlamada(tool, args) {
-    if (!Object.hasOwn(SHAPES, tool)) {
-        throw new Error(`Unknown tool: ${tool}`);
-    }
-    const resultado = z.object(SHAPES[tool]).safeParse(args ?? {});
-    if (!resultado.success) {
-        const recibidos = (args && typeof args === "object" ? args : {});
-        const problemas = resultado.error.issues.map((issue) => describirProblema(issue, recibidos));
-        throw new Error(`Argumentos no válidos. ${problemas.join(" ")}`);
-    }
-    // null cuenta como ausente: se quita aquí, una vez, para que ninguna tool tenga que
-    // distinguir entre un campo que no vino y uno que vino vacío.
-    const sinNulos = Object.fromEntries(Object.entries(resultado.data).filter(([, valor]) => valor !== null));
-    // El cast es seguro: los datos los acaba de producir el shape de esta misma tool.
-    return { tool, args: sinNulos };
+export function sinNulos(args) {
+    return Object.fromEntries(Object.entries(args).filter(([, valor]) => valor !== null));
 }
 //# sourceMappingURL=schemas.js.map

package/build/servidor.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function crearServidor(): McpServer;
+//# sourceMappingURL=servidor.d.ts.map

package/build/servidor.js

@@ -0,0 +1,372 @@
+// El servidor MCP: registra las tools y las conecta con la lógica de los demás módulos.
+// Aquí no se calcula nada — las rutas viven en paths.ts, las fases en phases.ts y las tareas en
+// tasks.ts. Este archivo solo traduce entre el protocolo y esas funciones.
+//
+// crearServidor no conecta ningún transporte: lo hace index.ts con stdio, y los tests con un
+// transporte en memoria. Así el servidor entero se puede probar sin lanzar un proceso.
+//
+// Cada tool se registra con su shape de schemas.ts: el SDK valida los argumentos antes del
+// callback y convierte en `isError` tanto un fallo de validación como un Error lanzado aquí. Por
+// eso los callbacks lanzan Error con el mensaje para el modelo, y no arman respuestas de error.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as fs from "fs";
+import * as path from "path";
+import { DOCS, SERVER_NAME, SERVER_VERSION, requireBasePath, stateFile } from "./config.js";
+import { diagnosticar, formatearDiagnostico } from "./diagnostico.js";
+import { pedirConfirmacion } from "./confirmacion.js";
+import { conectarLog, log } from "./log.js";
+import { describeProjects, discoverProjects, estaDentroReal, findProjectFolder, leerTextoAcotado, requireProjectFolder, resolveDocPath, resolveRepoPath, taskFolderPath, ubicarEnTarea, validarNombreVisible, validarSegmento, } from "./paths.js";
+import { discoverPhases, loadPhasePrompt, nombreContextoInicial } from "./phases.js";
+import { asegurarCapacidadDePrompts, sincronizarPrompts, vigilarCapas } from "./prompts-mcp.js";
+import { registrarRecursos } from "./recursos.js";
+import { diagnosticoShape, getActiveTaskShape, getOrchestratorStatusShape, getPhasePromptShape, listTasksShape, readCentralDocShape, readCrossRepoShape, sinNulos, startTaskShape, switchTaskShape, writeCentralDocShape, } from "./schemas.js";
+import { avisoDeCompuerta, avisoDePendientes, bloqueDeRecibos, describeEstado, guardarPuntero, listarTareas, motivoDeProteccion, tareaActiva, tareaDelPrompt, } from "./tasks.js";
+function responder(texto) {
+    return { content: [{ type: "text", text: texto }] };
+}
+function siCancelada(extra) {
+    if (extra.signal.aborted)
+        throw new Error("El cliente canceló la llamada antes de escribir. No se escribió nada.");
+}
+function lineaDeTarea(estado, phases) {
+    return `- ${estado.taskName} — ${describeEstado(estado, phases)}`;
+}
+// Las anotaciones dicen al cliente qué hace cada tool, para que decida si pide permiso. Los
+// valores por defecto del protocolo son pesimistas (destructiva y de mundo abierto), así que todas
+// declaran los cuatro valores. openWorldHint es false en todas: ninguna sale de las carpetas
+// configuradas.
+function anotaciones(title, readOnlyHint, destructiveHint, idempotentHint) {
+    return { title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint: false };
+}
+export function crearServidor() {
+    const mcp = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { logging: {} } });
+    conectarLog(mcp);
+    registrarTools(mcp);
+    registrarRecursos(mcp);
+    // Los /fN se registran ya, antes de conectar, y se vuelven a sincronizar tras cada tool y
+    // cuando cambia una capa de prompts.
+    sincronizarPrompts(mcp);
+    asegurarCapacidadDePrompts(mcp);
+    const dejarDeVigilar = vigilarCapas(mcp);
+    const alCerrar = mcp.server.onclose;
+    mcp.server.onclose = () => {
+        dejarDeVigilar();
+        alCerrar?.();
+    };
+    return mcp;
+}
+function registrarTools(mcp) {
+    // Tras cada llamada a una tool se sincronizan los prompts /fN. Leer las carpetas de prompts
+    // cuesta milisegundos, y es lo único que garantiza que una fase nueva aparezca en OneDrive,
+    // donde fs.watch no avisa.
+    const sincronizandoTras = (callback) => async (...args) => {
+        try {
+            return await callback(...args);
+        }
+        finally {
+            sincronizarPrompts(mcp);
+        }
+    };
+    // start_task no es destructiva (se niega a pisar una tarea) ni idempotente (la segunda llamada falla).
+    mcp.registerTool("start_task", {
+        title: "Iniciar tarea",
+        description: "Inicia una tarea NUEVA creando su carpeta en la Documentación Central y guardando el contexto inicial. " +
+            "Para volver a una tarea que ya existe usa 'switch_task': start_task reescribiría su contexto inicial.",
+        inputSchema: startTaskShape,
+        annotations: anotaciones("Iniciar tarea", false, false, false),
+    }, sincronizandoTras(async (entrada, extra) => {
+        const args = sinNulos(entrada);
+        const proj = args.project; // el schema ya le quitó los espacios
+        const taskName = args.task_name;
+        // Estrenar proyecto tiene que ser deliberado: sin esta puerta, un nombre mal escrito
+        // creaba una carpeta suelta en la Documentación y nadie se enteraba hasta buscarla.
+        let carpetaProyecto = findProjectFolder(proj);
+        let estrenado = false;
+        if (!carpetaProyecto) {
+            if (args.crear_proyecto !== true) {
+                throw new Error(`No existe el proyecto "${proj}". Los proyectos disponibles son: ${describeProjects()}. ` +
+                    `Si el usuario te confirmó que quiere estrenar el proyecto "${proj.toUpperCase()}", ` +
+                    `vuelve a llamar a start_task con crear_proyecto: true.`);
+            }
+            // El nombre se vuelve carpeta tal cual: "../evil" la creaba fuera de la Documentación.
+            validarSegmento(proj, "project");
+            validarNombreVisible(proj, "project");
+            carpetaProyecto = proj.toUpperCase();
+            estrenado = true;
+        }
+        validarNombreVisible(taskName, "task_name");
+        const carpetaTarea = taskFolderPath(carpetaProyecto, taskName);
+        const contextoInicial = path.join(carpetaTarea, nombreContextoInicial());
+        const docsBase = requireBasePath(DOCS);
+        if (!estaDentroReal(docsBase, carpetaTarea)) {
+            throw new Error(`Acceso denegado: la carpeta de la tarea queda fuera de ${docsBase}.`);
+        }
+        // Estrenar un proyecto se le confirma a la persona si el cliente puede preguntarle. Sin
+        // crear_proyecto no se pregunta nada: ofrecer "¿lo creo?" ante un nombre desconocido
+        // invitaría a aceptar un typo con un clic.
+        if (estrenado) {
+            const { estado, nota } = await pedirConfirmacion(mcp, extra, {
+                mensaje: `¿Estrenar el proyecto «${carpetaProyecto}»? Se creará la carpeta \`${path.join(docsBase, carpetaProyecto)}\`.`,
+                etiqueta: `Crear el proyecto ${carpetaProyecto}`,
+            });
+            if (estado === "rechazada") {
+                throw new Error(`El usuario no confirmó el proyecto nuevo. No se creó nada.${nota ? ` ${nota}` : ""}`);
+            }
+        }
+        // start_task escribe el contexto inicial sin preguntar, así que llamarlo sobre una tarea
+        // que ya existe borraba el requerimiento original — el único documento que no se puede
+        // regenerar leyendo el código. Retomar una tarea es switch_task, que no toca archivos.
+        if (fs.existsSync(contextoInicial)) {
+            throw new Error(`La tarea "${taskName}" ya existe en ${carpetaProyecto} y start_task reescribiría su ` +
+                `contexto inicial. Si quieres retomarla, usa switch_task. Si de verdad quieres ` +
+                `empezar de cero, borra o renombra la carpeta primero: ${carpetaTarea}`);
+        }
+        siCancelada(extra);
+        if (!fs.existsSync(carpetaTarea)) {
+            fs.mkdirSync(carpetaTarea, { recursive: true });
+        }
+        fs.writeFileSync(contextoInicial, args.initial_context, "utf-8");
+        // Queda como activa de SU proyecto. Otra ventana trabajando en otro proyecto conserva
+        // la suya: los punteros son independientes.
+        guardarPuntero(carpetaProyecto, taskName);
+        // Cambia la tarea activa, y con ella qué documentos se listan como recursos.
+        mcp.sendResourceListChanged();
+        const aviso = estrenado ? `\nProyecto "${carpetaProyecto}" estrenado.` : "";
+        return responder(`Tarea '${taskName}' inicializada correctamente. Archivo guardado en: ${contextoInicial}\n` +
+            `Tarea activa de ${carpetaProyecto}: ${taskName}.${aviso}`);
+    }));
+    mcp.registerTool("get_phase_prompt", {
+        title: "Prompt de fase",
+        description: "Obtiene el prompt maestro de comportamiento de una fase. Comprueba además que no te estés saltando una " +
+            "fase: si faltan documentos anteriores, el prompt llega con un aviso al principio.",
+        inputSchema: getPhasePromptShape,
+        annotations: anotaciones("Prompt de fase", true, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        // Que sea un entero ya lo garantiza el schema; si la fase no existe, lo dice loadPhasePrompt.
+        const { phase, project, task_name } = sinNulos(entrada);
+        const prompt = loadPhasePrompt(phase);
+        // La compuerta avisa, no bloquea: el prompt se entrega siempre. Si comprobarla fallara
+        // por lo que sea, entregarlo igual es mejor que dejar al usuario sin fase por un aviso.
+        // Lo mismo con la lista de recibos: es una ayuda, no una condición.
+        let aviso = null;
+        let pendientes = null;
+        let recibos = null;
+        try {
+            const phases = discoverPhases();
+            const opciones = { ...(project ? { project } : {}), ...(task_name ? { taskName: task_name } : {}) };
+            aviso = avisoDeCompuerta(phase, phases, opciones);
+            const estado = tareaDelPrompt(phases, opciones);
+            if (estado && estado !== "ambigua") {
+                pendientes = avisoDePendientes(phase, estado, phases);
+                recibos = bloqueDeRecibos(phase, estado, phases);
+            }
+        }
+        catch (error) {
+            log("warning", `No se pudo comprobar la compuerta: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Lo que el modelo tiene que leer antes de nada va delante: el salto de fase y los pendientes.
+        return responder([aviso, pendientes, prompt, recibos].filter(Boolean).join("\n\n"));
+    }));
+    mcp.registerTool("get_active_task", {
+        title: "Tarea activa",
+        description: "Devuelve la tarea activa y en qué fase va, deducida de los documentos que ya tiene. Úsalo al iniciar un " +
+            "chat nuevo o si perdiste el contexto. Sin 'project' devuelve la activa de CADA proyecto.",
+        inputSchema: getActiveTaskShape,
+        annotations: anotaciones("Tarea activa", true, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        const phases = discoverPhases();
+        const pedido = sinNulos(entrada).project ?? "";
+        // Con proyecto: la suya. Sin proyecto: la de cada uno. Antes había un único puntero
+        // global y responder "la activa" a secas obligaba a adivinar cuál de dos ventanas
+        // preguntaba; listar todas es la respuesta honesta cuando no se sabe.
+        const proyectos = pedido ? [requireProjectFolder(pedido)] : [...discoverProjects().values()].sort();
+        if (proyectos.length === 0) {
+            return responder("No hay ningún proyecto en la Documentación Central todavía.");
+        }
+        const bloques = [];
+        for (const carpetaProyecto of proyectos) {
+            const activa = tareaActiva(carpetaProyecto, phases);
+            if (!activa) {
+                bloques.push(`${carpetaProyecto}: sin tareas todavía.`);
+                continue;
+            }
+            const nota = activa.origen === "deducida"
+                ? " (deducida por ser la más reciente: no había puntero guardado, confírmalo antes de escribir)"
+                : "";
+            bloques.push(`${carpetaProyecto}: ${activa.estado.taskName}${nota}\n` +
+                `  Fase: ${describeEstado(activa.estado, phases)}\n` +
+                `  Carpeta: ${activa.estado.folderPath}`);
+        }
+        return responder(`${bloques.join("\n\n")}\n\nPunteros guardados en: ${stateFile()}`);
+    }));
+    mcp.registerTool("list_tasks", {
+        title: "Listar tareas",
+        description: "Lista las tareas que existen y la fase en la que va cada una. Úsalo para retomar una tarea vieja o para " +
+            "saber qué hay pendiente.",
+        inputSchema: listTasksShape,
+        annotations: anotaciones("Listar tareas", true, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        const phases = discoverPhases();
+        const pedido = sinNulos(entrada).project ?? "";
+        const proyectos = pedido ? [requireProjectFolder(pedido)] : [...discoverProjects().values()].sort();
+        const bloques = [];
+        for (const carpetaProyecto of proyectos) {
+            const tareas = listarTareas(carpetaProyecto, phases);
+            const activa = tareaActiva(carpetaProyecto, phases);
+            if (tareas.length === 0) {
+                bloques.push(`${carpetaProyecto}: sin tareas.`);
+                continue;
+            }
+            const lineas = tareas.map((tarea) => {
+                const marca = tarea.taskName === activa?.estado.taskName ? " [activa]" : "";
+                return `${lineaDeTarea(tarea, phases)}${marca}`;
+            });
+            bloques.push(`${carpetaProyecto} (${tareas.length}), de la más reciente a la más antigua:\n${lineas.join("\n")}`);
+        }
+        return responder(bloques.join("\n\n") || "No hay proyectos todavía.");
+    }));
+    // Escribe el puntero, así que no es de solo lectura; pero repetirla da el mismo estado.
+    mcp.registerTool("switch_task", {
+        title: "Cambiar de tarea activa",
+        description: "Cambia cuál es la tarea activa de un proyecto, sin tocar ningún archivo. Es la forma correcta de " +
+            "retomar una tarea que ya existe.",
+        inputSchema: switchTaskShape,
+        annotations: anotaciones("Cambiar de tarea activa", false, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        const args = sinNulos(entrada);
+        const phases = discoverPhases();
+        const carpetaProyecto = requireProjectFolder(args.project);
+        const taskName = args.task_name;
+        const tareas = listarTareas(carpetaProyecto, phases);
+        const encontrada = tareas.find((tarea) => tarea.taskName === taskName);
+        if (!encontrada) {
+            const disponibles = tareas.length ? tareas.map((tarea) => `"${tarea.taskName}"`).join(", ") : "(ninguna)";
+            throw new Error(`No existe la tarea "${taskName}" en ${carpetaProyecto}. Las que hay son: ${disponibles}. ` +
+                `Si es una tarea nueva, créala con start_task.`);
+        }
+        guardarPuntero(carpetaProyecto, taskName);
+        mcp.sendResourceListChanged();
+        return responder(`Tarea activa de ${carpetaProyecto}: ${taskName}.\nFase: ${describeEstado(encontrada, phases)}\n` +
+            `Carpeta: ${encontrada.folderPath}`);
+    }));
+    mcp.registerTool("read_central_doc", {
+        title: "Leer documento",
+        description: "Lee un archivo de la Documentación Central. RECOMENDADO: pasa 'project' + 'task_name' + 'file_name' y el " +
+            "servidor arma la ruta correcta automáticamente (<PROYECTO>/<subcarpeta de tareas>/<tarea>/<archivo>). " +
+            "Alternativamente puedes pasar 'file_path' relativo a la Documentación Central.",
+        inputSchema: readCentralDocShape,
+        annotations: anotaciones("Leer documento", true, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        const docsBase = requireBasePath(DOCS);
+        const fullPath = resolveDocPath(sinNulos(entrada));
+        if (!estaDentroReal(docsBase, fullPath)) {
+            throw new Error(`Acceso denegado: la ruta queda fuera de ${docsBase}.`);
+        }
+        return responder(leerTextoAcotado(fullPath));
+    }));
+    // La única destructiva: puede sobrescribir un documento. Repetirla con el mismo contenido deja
+    // el mismo archivo, así que es idempotente.
+    mcp.registerTool("write_central_doc", {
+        title: "Escribir documento",
+        description: "Escribe o sobrescribe un archivo en la Documentación Central. RECOMENDADO: pasa 'project' + 'task_name' + " +
+            "'file_name' y el servidor arma la ruta correcta automáticamente " +
+            "(<PROYECTO>/<subcarpeta de tareas>/<tarea>/<archivo>). Alternativamente puedes pasar 'file_path' relativo " +
+            "a la Documentación Central.",
+        inputSchema: writeCentralDocShape,
+        annotations: anotaciones("Escribir documento", false, true, true),
+    }, sincronizandoTras(async (entrada, extra) => {
+        const args = sinNulos(entrada);
+        const docsBase = requireBasePath(DOCS);
+        const fullPath = resolveDocPath(args);
+        if (!estaDentroReal(docsBase, fullPath)) {
+            throw new Error(`Acceso denegado: la ruta queda fuera de ${docsBase}.`);
+        }
+        // Antes del mkdir: con una tarea mal escrita, el mkdir recursivo creaba su carpeta.
+        const ubicacion = ubicarEnTarea(fullPath);
+        if (!ubicacion) {
+            throw new Error("write_central_doc solo escribe dentro de la carpeta de una tarea que ya existe " +
+                "(<DOCS>/<PROYECTO>/<subcarpeta de tareas>/<tarea>/). Los archivos del proyecto, como " +
+                "phase-gate.json, no se escriben con esta tool. Para una tarea nueva, usa start_task.");
+        }
+        const motivo = motivoDeProteccion(ubicacion.carpetaTarea, ubicacion.relativo, discoverPhases(), nombreContextoInicial());
+        const existia = fs.existsSync(fullPath);
+        // Un documento protegido se le pregunta a la persona si el cliente puede mostrarle la
+        // pregunta; entonces force no basta, porque lo pone el modelo. Solo sin elicitation decide
+        // force, como antes.
+        let sufijo = "";
+        if (motivo) {
+            const archivo = ubicacion.relativo;
+            const { estado, nota } = await pedirConfirmacion(mcp, extra, {
+                mensaje: `\`${archivo}\` de la tarea «${ubicacion.taskName}» está protegido: ${motivo.replace(/\.$/, "")}. ` +
+                    (existia ? "¿Reescribirlo?" : "¿Crearlo?"),
+                etiqueta: `${existia ? "Reescribir" : "Crear"} ${archivo}`,
+            });
+            const conNota = nota ? ` ${nota}` : "";
+            if (estado === "rechazada") {
+                const accion = existia ? "la reescritura" : "la escritura";
+                throw new Error(`El usuario no confirmó ${accion} de \`${archivo}\`. No se escribió nada.${conNota}`);
+            }
+            if (estado === "no-disponible" && args.force !== true) {
+                throw new Error(`${motivo} Si de verdad hay que reescribirlo, pídele al usuario confirmación explícita ` +
+                    `y vuelve a llamar con force: true.${conNota}`);
+            }
+            // force también crea el contexto inicial cuando falta: no se dice "sobrescrito" si no lo era.
+            sufijo =
+                estado === "confirmada"
+                    ? existia
+                        ? " (reescrito con confirmación del usuario)"
+                        : " (creado con confirmación del usuario)"
+                    : existia
+                        ? " (sobrescrito con force)"
+                        : " (creado con force)";
+            if (nota)
+                sufijo += `\n${nota}`;
+        }
+        // Si el cliente canceló la llamada mientras se esperaba algo (una confirmación), ya no
+        // escucha la respuesta: escribir ahora dejaría un archivo que el modelo cree que no existe.
+        siCancelada(extra);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, args.content, "utf-8");
+        // Un archivo nuevo puede ser un documento o un recibo que se lista como recurso. Reescribir
+        // uno que ya existía no cambia la lista.
+        if (!existia)
+            mcp.sendResourceListChanged();
+        return responder(`Archivo escrito exitosamente en ${fullPath}${sufijo}`);
+    }));
+    // La misma radiografía que `npx mcp-phase-gate doctor`, más lo que solo se sabe desde dentro de
+    // una sesión: qué cliente está conectado y qué capacidades anunció.
+    mcp.registerTool("get_orchestrator_status", {
+        title: "Estado de la instalación",
+        description: "Radiografía de la instalación: versión y ruta del paquete, variables y de dónde salió cada una, qué " +
+            "archivo de prompt gana en cada fase, proyectos y tarea activa, y avisos. Úsala cuando algo no se " +
+            "comporte como esperas.",
+        inputSchema: getOrchestratorStatusShape,
+        outputSchema: diagnosticoShape,
+        annotations: anotaciones("Estado de la instalación", true, false, true),
+    }, sincronizandoTras(async () => {
+        const version = mcp.server.getClientVersion();
+        const capacidades = mcp.server.getClientCapabilities();
+        const cliente = version
+            ? {
+                nombre: version.name,
+                version: version.version,
+                capacidades: { elicitation: Boolean(capacidades?.elicitation?.form), roots: Boolean(capacidades?.roots) },
+            }
+            : undefined;
+        const diagnostico = diagnosticar(cliente ? { cliente } : {});
+        return {
+            content: [{ type: "text", text: formatearDiagnostico(diagnostico, "markdown") }],
+            structuredContent: diagnostico,
+        };
+    }));
+    mcp.registerTool("read_cross_repo", {
+        title: "Leer archivo de repositorio",
+        description: "Lee archivos de otros repositorios locales, dentro de la carpeta configurada en PHASE_GATE_REPOS_PATH.",
+        inputSchema: readCrossRepoShape,
+        annotations: anotaciones("Leer archivo de repositorio", true, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        const args = sinNulos(entrada);
+        return responder(leerTextoAcotado(resolveRepoPath(args.repo_name, args.file_path)));
+    }));
+}
+//# sourceMappingURL=servidor.js.map