@bussolabs/closeyourit-cli 0.25.1 → 0.27.0

package/dist/lib/mcp/server.d.ts

@@ -0,0 +1,41 @@
+import type { Readable, Writable } from 'node:stream';
+import { type CliApi } from '../api';
+import { type JsonRpcRequest, type JsonRpcResponse } from './protocol';
+import { type McpToolContext } from './tools';
+/**
+ * Il server Model Context Protocol della conoscenza CloseYourIt (CYCL-56).
+ *
+ * Parla la revisione con handshake (`initialize`), quella che i client sanno parlare oggi. Non
+ * espone `server/discover`: un client che sa fare entrambe le ere prova quella nuova, riceve un
+ * errore che non riconosce come moderno e ricade sull'handshake — che è esattamente la strada che
+ * qui funziona.
+ */
+export declare const SERVER_NAME = "closeyourit";
+/**
+ * Le revisioni del protocollo che questo server serve, dalla più recente. Tutte trattano allo
+ * stesso modo un server di soli strumenti: fra loro cambiano cose che qui non esistono
+ * (autorizzazione, elicitation, risorse), quindi la versione richiesta si può confermare com'è.
+ */
+export declare const PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+export declare const DEFAULT_PROTOCOL_VERSION: "2025-11-25";
+/** Lo stato di una connessione: quello che serve agli strumenti più chi si è presentato. */
+export interface McpSession extends McpToolContext {
+    version: string;
+    /** Interrompe le chiamate rimaste in volo quando la finestra di chiusura è scaduta. */
+    abort: AbortController;
+    shutdownGraceMs: number;
+}
+export declare function createSession(opts: {
+    api: CliApi;
+    version: string;
+    cwd?: string;
+    timeoutMs?: number;
+    shutdownGraceMs?: number;
+}): McpSession;
+export declare function handleRequest(request: JsonRpcRequest, session: McpSession): Promise<JsonRpcResponse | undefined>;
+/**
+ * Serve il protocollo su due flussi: un messaggio JSON per riga in ingresso, un messaggio JSON per
+ * riga in uscita e niente altro. La promessa si chiude quando il flusso di ingresso finisce — o
+ * quando uno dei due si rompe, che è il modo in cui un client se ne va.
+ */
+export declare function serveStdio(input: Readable, output: Writable, session: McpSession): Promise<void>;

package/dist/lib/mcp/server.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PROTOCOL_VERSION = exports.PROTOCOL_VERSIONS = exports.SERVER_NAME = void 0;
+exports.createSession = createSession;
+exports.handleRequest = handleRequest;
+exports.serveStdio = serveStdio;
+const api_1 = require("../api");
+const protocol_1 = require("./protocol");
+const tools_1 = require("./tools");
+/**
+ * Il server Model Context Protocol della conoscenza CloseYourIt (CYCL-56).
+ *
+ * Parla la revisione con handshake (`initialize`), quella che i client sanno parlare oggi. Non
+ * espone `server/discover`: un client che sa fare entrambe le ere prova quella nuova, riceve un
+ * errore che non riconosce come moderno e ricade sull'handshake — che è esattamente la strada che
+ * qui funziona.
+ */
+exports.SERVER_NAME = 'closeyourit';
+const SERVER_TITLE = 'CloseYourIt knowledge';
+/**
+ * Le revisioni del protocollo che questo server serve, dalla più recente. Tutte trattano allo
+ * stesso modo un server di soli strumenti: fra loro cambiano cose che qui non esistono
+ * (autorizzazione, elicitation, risorse), quindi la versione richiesta si può confermare com'è.
+ */
+exports.PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+exports.DEFAULT_PROTOCOL_VERSION = exports.PROTOCOL_VERSIONS[0];
+/** Quanto si aspetta `git` per riconoscere il progetto della cartella, quando non lo si dice. */
+const DEFAULT_GIT_TIMEOUT_MS = 5000;
+/**
+ * Quanto si concede alle chiamate ancora in volo quando il canale si chiude, prima di interromperle.
+ *
+ * Chiudere lo standard input È il modo in cui un client MCP chiede al server di uscire, e subito
+ * dopo passa ai segnali. Una risposta che arriva entro questa finestra fa ancora in tempo a uscire;
+ * oltre, chi l'aspettava non c'è più — e restare in attesa terrebbe vivo il sottoprocesso finché
+ * la richiesta non torna, cioè potenzialmente fino al segnale che lo uccide.
+ */
+const DEFAULT_SHUTDOWN_GRACE_MS = 2000;
+/** Quello che il client legge prima di usare gli strumenti: a cosa serve questa conoscenza. */
+const INSTRUCTIONS = [
+    'The CloseYourIt knowledge base of this organization: decisions taken, guides and notes that the code and the git history do not say.',
+    'Search it (kb_search) or ask it (kb_ask) before answering how something is done here; kb_context lists what to know about the project of the current directory.',
+    'New knowledge goes in with kb_propose: it always waits for a person to accept it, so nothing written from here is published on its own.',
+].join(' ');
+function createSession(opts) {
+    const abort = new AbortController();
+    // Sul client, non su ogni chiamata: così l'interruzione arriva anche alle ricerche per nome che
+    // uno strumento si porta dietro, senza che debbano saperne niente.
+    opts.api.signal = abort.signal;
+    return {
+        api: opts.api,
+        version: opts.version,
+        cwd: opts.cwd ?? process.cwd(),
+        timeoutMs: opts.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS,
+        shutdownGraceMs: opts.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS,
+        abort,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Il testo che il modello legge quando uno strumento non è andato a buon fine. Un rifiuto del
+ * server porta il suo codice, come lo porta il terminale: è quello che distingue «non hai accesso»
+ * da «non sei collegato» senza doverlo indovinare.
+ */
+function toolErrorText(error) {
+    if (error instanceof api_1.ApiRequestError)
+        return `${error.code}: ${error.message}`;
+    return String(error.message);
+}
+function initialize(params, session) {
+    const clientInfo = params.clientInfo;
+    const clientName = typeof clientInfo?.name === 'string' ? clientInfo.name.trim() : '';
+    if (clientName !== '')
+        session.clientName = clientName;
+    const requested = params.protocolVersion;
+    const known = typeof requested === 'string' && exports.PROTOCOL_VERSIONS.includes(requested);
+    return {
+        protocolVersion: known ? requested : exports.DEFAULT_PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: exports.SERVER_NAME, title: SERVER_TITLE, version: session.version },
+        instructions: INSTRUCTIONS,
+    };
+}
+async function callTool(id, params, session) {
+    const name = typeof params.name === 'string' ? params.name : '';
+    const tool = (0, tools_1.findTool)(name);
+    // Uno strumento che non esiste è un errore di protocollo: non c'è nessuna chiamata di cui
+    // raccontare l'esito, e il client deve accorgersene come si accorge di un metodo sbagliato.
+    if (!tool) {
+        return (0, protocol_1.rpcFailure)(id, protocol_1.RPC_ERROR.invalidParams, `Unknown tool: ${name}. Call tools/list for the tools this server offers.`);
+    }
+    const args = params.arguments;
+    try {
+        const result = await tool.run(isRecord(args) ? args : {}, session);
+        return (0, protocol_1.rpcResult)(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false });
+    }
+    catch (error) {
+        // Un argomento sbagliato o un rifiuto del server sono l'ESITO dello strumento, non un guasto del
+        // protocollo: così il motivo arriva al modello, che può correggersi da sé invece di fermarsi.
+        return (0, protocol_1.rpcResult)(id, { content: [{ type: 'text', text: toolErrorText(error) }], isError: true });
+    }
+}
+async function handleRequest(request, session) {
+    const { id, method, params } = request;
+    // Una notifica non ha a chi rispondere: qualunque cosa chieda, l'unica replica corretta è nessuna.
+    if (id === undefined)
+        return undefined;
+    switch (method) {
+        case 'initialize': {
+            return (0, protocol_1.rpcResult)(id, initialize(params, session));
+        }
+        case 'ping': {
+            return (0, protocol_1.rpcResult)(id, {});
+        }
+        case 'tools/list': {
+            return (0, protocol_1.rpcResult)(id, { tools: (0, tools_1.toolDefinitions)() });
+        }
+        case 'tools/call': {
+            return callTool(id, params, session);
+        }
+        default: {
+            return (0, protocol_1.rpcFailure)(id, protocol_1.RPC_ERROR.methodNotFound, `Unknown method: ${method}`);
+        }
+    }
+}
+/**
+ * Serve il protocollo su due flussi: un messaggio JSON per riga in ingresso, un messaggio JSON per
+ * riga in uscita e niente altro. La promessa si chiude quando il flusso di ingresso finisce — o
+ * quando uno dei due si rompe, che è il modo in cui un client se ne va.
+ */
+function serveStdio(input, output, session) {
+    return new Promise((resolve) => {
+        const pending = new Set();
+        let buffer = '';
+        let closed = false;
+        // Una sola write per messaggio, a capo compreso: due write potrebbero intrecciarsi con quelle
+        // di una richiesta servita in parallelo e spezzare una riga a metà.
+        //
+        // Se scrivere fallisce non c'è un canale su cui dirlo, e provarci sarebbe peggio: l'errore
+        // uscirebbe da qui, risalirebbe fino al gestore che risponde ai guasti — che scrive anche lui —
+        // e finirebbe come rifiuto senza padrone, cioè un processo morto invece di un server che chiude.
+        const send = (response) => {
+            try {
+                output.write(`${JSON.stringify(response)}\n`);
+            }
+            catch {
+                void finish();
+            }
+        };
+        const drain = async () => {
+            while (pending.size > 0) {
+                // eslint-disable-next-line no-await-in-loop
+                await Promise.all([...pending]);
+            }
+        };
+        // Il timer non deve tenere vivo il processo per conto suo: se non resta altro da aspettare,
+        // uscire subito è la cosa giusta, e il ritardo serve solo finché c'è una chiamata in volo.
+        const grace = () => new Promise((done) => {
+            setTimeout(done, session.shutdownGraceMs).unref();
+        });
+        const finish = async () => {
+            if (closed)
+                return;
+            closed = true;
+            // Chi ha chiuso il canale non aspetta più nessuna risposta: le chiamate in volo hanno la loro
+            // finestra per finire e poi vengono interrotte. Senza interromperle davvero, la connessione
+            // aperta terrebbe vivo l'event loop — e con esso un sottoprocesso che il client ha già
+            // considerato chiuso — a prescindere da quando questa promessa si risolve.
+            await Promise.race([drain(), grace()]);
+            session.abort.abort();
+            await drain();
+            resolve();
+        };
+        const serve = (line) => {
+            const parsed = (0, protocol_1.parseLine)(line);
+            if (parsed.kind === 'ignore')
+                return;
+            if (parsed.kind === 'response') {
+                send(parsed.response);
+                return;
+            }
+            const { request } = parsed;
+            const task = handleRequest(request, session)
+                .then((response) => {
+                if (response)
+                    send(response);
+            })
+                .catch((error) => {
+                // Un guasto qui è nostro, non del client: si dichiara sul canale e il server resta in piedi.
+                if (request.id !== undefined)
+                    send((0, protocol_1.rpcFailure)(request.id, protocol_1.RPC_ERROR.internal, toolErrorText(error)));
+            })
+                .finally(() => {
+                pending.delete(task);
+            });
+            pending.add(task);
+        };
+        input.setEncoding('utf8');
+        input.on('data', (chunk) => {
+            buffer += chunk;
+            let cut = buffer.indexOf('\n');
+            while (cut !== -1) {
+                serve(buffer.slice(0, cut));
+                buffer = buffer.slice(cut + 1);
+                cut = buffer.indexOf('\n');
+            }
+        });
+        input.on('end', () => {
+            // L'ultima riga può arrivare senza a capo: chi chiude subito dopo averla scritta non deve
+            // perdere la richiesta che ha appena fatto.
+            serve(buffer);
+            buffer = '';
+            void finish();
+        });
+        // Un flusso che si rompe non è un guasto da raccontare: il client se n'è andato (stdin chiuso,
+        // uscita interrotta) e al server non resta che chiudere pulito.
+        input.on('error', () => void finish());
+        output.on('error', () => void finish());
+    });
+}

package/dist/lib/mcp/tools.d.ts

@@ -0,0 +1,43 @@
+import type { CliApi } from '../api';
+/**
+ * Gli strumenti che il server MCP offre sulla conoscenza (CYCL-56).
+ *
+ * Ognuno è la chiamata che già fa il comando corrispondente, sullo stesso client HTTP e con lo
+ * stesso token: i limiti di chi si collega restano quelli che ha da riga di comando, senza che
+ * questo strato debba conoscerli. Cinque leggono; il sesto, `kb_propose`, è l'unico che scrive e
+ * manda la pagina in revisione SEMPRE — non c'è argomento che possa pubblicarla.
+ */
+/** Un argomento sbagliato: il modello che l'ha scritto può correggersi e riprovare. */
+export declare class McpToolInputError extends Error {
+    constructor(message: string);
+}
+/** Quello che uno strumento sa del mondo attorno alla chiamata. */
+export interface McpToolContext {
+    api: CliApi;
+    /** Cartella da cui il server è stato lanciato: è lì che `kb_context` cerca il remote git. */
+    cwd: string;
+    /** Quanto aspettare `git` prima di rinunciare a riconoscere il progetto. */
+    timeoutMs: number;
+    /** Nome del client dichiarato nell'handshake, usato per attribuire una proposta di pagina. */
+    clientName?: string;
+}
+/** Suggerimenti che il client mostra prima di invocare: dicono chi legge soltanto e chi scrive. */
+export interface McpToolAnnotations {
+    title: string;
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+export interface McpTool {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: McpToolAnnotations;
+    run(args: Record<string, unknown>, ctx: McpToolContext): Promise<unknown>;
+}
+export declare const MCP_TOOLS: McpTool[];
+export declare function findTool(name: string): McpTool | undefined;
+/** Il catalogo come lo vuole `tools/list`: tutto tranne il codice che esegue la chiamata. */
+export declare function toolDefinitions(): Array<Omit<McpTool, 'run'>>;

package/dist/lib/mcp/tools.js

@@ -0,0 +1,340 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_TOOLS = exports.McpToolInputError = void 0;
+exports.findTool = findTool;
+exports.toolDefinitions = toolDefinitions;
+const error_codes_1 = require("../../errors/error-codes");
+const knowledge_1 = require("../knowledge");
+const knowledge_context_1 = require("../knowledge-context");
+const limits_1 = require("../limits");
+const lookup_1 = require("../lookup");
+/**
+ * Gli strumenti che il server MCP offre sulla conoscenza (CYCL-56).
+ *
+ * Ognuno è la chiamata che già fa il comando corrispondente, sullo stesso client HTTP e con lo
+ * stesso token: i limiti di chi si collega restano quelli che ha da riga di comando, senza che
+ * questo strato debba conoscerli. Cinque leggono; il sesto, `kb_propose`, è l'unico che scrive e
+ * manda la pagina in revisione SEMPRE — non c'è argomento che possa pubblicarla.
+ */
+/** Un argomento sbagliato: il modello che l'ha scritto può correggersi e riprovare. */
+class McpToolInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'McpToolInputError';
+    }
+}
+exports.McpToolInputError = McpToolInputError;
+/** Attribuzione di una proposta quando il client non si è presentato e nessuno l'ha dichiarata. */
+const DEFAULT_AUTHOR_ORIGIN = 'mcp';
+function optionalString(args, key) {
+    const raw = args[key];
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'string')
+        throw new McpToolInputError(`"${key}" must be a string.`);
+    const trimmed = raw.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+function requiredString(args, key) {
+    const value = optionalString(args, key);
+    if (value === undefined)
+        throw new McpToolInputError(`"${key}" is required and cannot be empty.`);
+    return value;
+}
+/**
+ * Un interruttore è acceso solo se vale davvero `true`. Nessun'altra forma conta come sì: uno
+ * strumento che leggesse `"false"` come acceso farebbe l'opposto di quello che gli è stato chiesto.
+ */
+function flag(args, key) {
+    return args[key] === true ? true : undefined;
+}
+function optionalInteger(args, key, min) {
+    const raw = args[key];
+    if (raw === undefined || raw === null)
+        return undefined;
+    const value = typeof raw === 'string' ? Number(raw) : raw;
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw new McpToolInputError(`"${key}" must be a whole number.`);
+    }
+    if (value < min)
+        throw new McpToolInputError(`"${key}" must be at least ${min}.`);
+    return value;
+}
+/** Un campo ripetibile, accettato sia come singolo valore sia come lista (i client fanno entrambi). */
+function stringList(args, key) {
+    const raw = args[key];
+    if (raw === undefined || raw === null)
+        return [];
+    return (0, knowledge_1.cleanList)((Array.isArray(raw) ? raw : [raw]).map((value) => String(value)));
+}
+/** La busta del server così com'è: gli stessi dati che `cyi … --json` stampa sul terminale. */
+function payload(envelope) {
+    return envelope.meta === undefined ? { data: envelope.data } : { data: envelope.data, meta: envelope.meta };
+}
+const PROJECT_PROPERTY = {
+    type: 'string',
+    description: 'Project key (e.g. ACME) or UUID. Only projects your access already includes.',
+};
+const QUESTION_PROPERTY = {
+    type: 'string',
+    description: 'Keep only the related pages relevant to this question.',
+};
+exports.MCP_TOOLS = [
+    {
+        name: 'kb_search',
+        title: 'Search knowledge pages',
+        description: 'Search the CloseYourIt knowledge base (semantic when available, title match otherwise) and return the matching pages. Only pages your access already includes are ever returned.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'What to look for, in plain words.' },
+                project: PROJECT_PROPERTY,
+                kind: {
+                    type: 'array',
+                    items: { type: 'string', enum: [...knowledge_1.KNOWLEDGE_KINDS] },
+                    description: 'Keep only these page kinds.',
+                },
+                status: {
+                    type: 'string',
+                    enum: [...knowledge_1.KNOWLEDGE_STATUSES],
+                    description: 'Review state to search in. Omitted, only accepted pages; "all" also finds proposals waiting for review — use it before proposing a page, to see a duplicate that is not accepted yet.',
+                },
+                page: { type: 'integer', minimum: 1, description: 'Result page (default 1).' },
+                per: { type: 'integer', minimum: 1, description: 'Page size.' },
+                with_related: { type: 'boolean', description: 'Also return the pages each result links to.' },
+            },
+            required: ['query'],
+        },
+        annotations: {
+            title: 'Search knowledge pages',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        async run(args, { api }) {
+            const query = (0, knowledge_1.buildPagesQuery)({
+                kinds: (0, knowledge_1.normalizeKinds)(stringList(args, 'kind')),
+                page: optionalInteger(args, 'page', 1) ?? 1,
+                per: optionalInteger(args, 'per', 1),
+                project: optionalString(args, 'project'),
+                q: requiredString(args, 'query'),
+                related: flag(args, 'with_related'),
+                status: optionalString(args, 'status'),
+            });
+            return payload(await api.get(`/cli/v1/knowledge/pages?${query}`));
+        },
+    },
+    {
+        name: 'kb_ask',
+        title: 'Ask the knowledge base',
+        description: 'Ask a natural-language question; the CloseYourIt AI answers from the knowledge pages you can see and cites the ones it used. Takes a few seconds.',
+        inputSchema: {
+            type: 'object',
+            properties: { question: { type: 'string', description: 'The question, in plain words.' } },
+            required: ['question'],
+        },
+        annotations: {
+            title: 'Ask the knowledge base',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        async run(args, { api }) {
+            return payload(await api.post('/cli/v1/knowledge/ask', { question: requiredString(args, 'question') }));
+        },
+    },
+    {
+        name: 'kb_show',
+        title: 'Read a knowledge page',
+        description: 'Read one knowledge page in full: metadata, markdown body and technical section, optionally with the pages to read next.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Knowledge page id, as returned by kb_search or kb_context.' },
+                related: { type: 'boolean', description: 'Also list the pages to read next.' },
+                question: QUESTION_PROPERTY,
+            },
+            required: ['id'],
+        },
+        annotations: {
+            title: 'Read a knowledge page',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        async run(args, { api }) {
+            const id = requiredString(args, 'id');
+            const query = new URLSearchParams();
+            const question = optionalString(args, 'question');
+            if (question)
+                query.set('question', question);
+            else if (flag(args, 'related'))
+                query.set('related', '1');
+            const suffix = query.toString() === '' ? '' : `?${query.toString()}`;
+            return payload(await api.get(`/cli/v1/knowledge/pages/${encodeURIComponent(id)}${suffix}`));
+        },
+    },
+    {
+        name: 'kb_related',
+        title: 'Pages to read next',
+        description: 'List the pages to read next: the ones this page links to (and that link to it), plus close matches by meaning.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Knowledge page id.' },
+                question: QUESTION_PROPERTY,
+                links_only: { type: 'boolean', description: 'Only pages linked with [[wiki links]], no close matches.' },
+            },
+            required: ['id'],
+        },
+        annotations: {
+            title: 'Pages to read next',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        async run(args, { api }) {
+            const id = requiredString(args, 'id');
+            const query = new URLSearchParams();
+            const question = optionalString(args, 'question');
+            if (question)
+                query.set('question', question);
+            if (flag(args, 'links_only'))
+                query.set('links_only', '1');
+            const suffix = query.toString() === '' ? '' : `?${query.toString()}`;
+            return payload(await api.get(`/cli/v1/knowledge/pages/${encodeURIComponent(id)}/related${suffix}`));
+        },
+    },
+    {
+        name: 'kb_context',
+        title: 'Knowledge context of this project',
+        description: 'The short list of pages whoever starts working on this project should already know. Without a project it is recognised from the git remote of the directory the server was started in; outside a project the list is simply empty.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: PROJECT_PROPERTY,
+                limit: { type: 'integer', minimum: 1, description: 'How many pages at most (default 10).' },
+            },
+        },
+        annotations: {
+            title: 'Knowledge context of this project',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        async run(args, { api, cwd, timeoutMs }) {
+            const limit = optionalInteger(args, 'limit', 1) ?? 10;
+            const project = optionalString(args, 'project') ?? (await (0, knowledge_context_1.projectFromGitRemote)(api, cwd, timeoutMs));
+            // Fuori da un progetto non c'è niente da sapere: uno stato normale, non un guasto (CYCL-55).
+            if (project === undefined)
+                return { data: { project: null, pages: [] } };
+            const answer = await (0, knowledge_context_1.fetchKnowledgeContext)(api, project, limit);
+            // Il tetto vale sulla risposta, non solo sulla richiesta: nulla garantisce che la rotta del
+            // contesto onori `per`, e chi ha chiesto cinque pagine non deve riceverne dieci.
+            return payload({ ...answer, data: (0, knowledge_1.capContextPages)(answer.data, limit) });
+        },
+    },
+    {
+        name: 'kb_propose',
+        title: 'Propose a knowledge page',
+        description: 'Propose a new knowledge page. It ALWAYS enters the review queue and waits for a person to accept it: it stays out of search, answers and related panels until then, and nothing this tool receives can publish it directly.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: `Page title (max ${limits_1.LENGTH_LIMITS.title} characters).` },
+                body: { type: 'string', description: `Page body in markdown (max ${limits_1.LENGTH_LIMITS.pageBody} characters).` },
+                project: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Project keys or UUIDs the page belongs to. At least one project or group is required.',
+                },
+                group: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Group names or UUIDs the page belongs to.',
+                },
+                tag: { type: 'array', items: { type: 'string' }, description: 'Tags for the page.' },
+                kind: { type: 'string', enum: [...knowledge_1.KNOWLEDGE_KINDS], description: 'Page kind (default note).' },
+                tech_spec: {
+                    type: 'string',
+                    description: `Technical section, kept separate from the body (max ${limits_1.LENGTH_LIMITS.techSpec} characters).`,
+                },
+                review_note: {
+                    type: 'string',
+                    description: `One line for the reviewer on why the page is worth keeping (max ${limits_1.LENGTH_LIMITS.reviewNote} characters).`,
+                },
+                author_origin: {
+                    type: 'string',
+                    description: 'Name of the assistant or skill that wrote the text; defaults to the connected client.',
+                },
+            },
+            required: ['title', 'body'],
+        },
+        annotations: {
+            title: 'Propose a knowledge page',
+            readOnlyHint: false,
+            // Nulla viene sovrascritto o pubblicato: la proposta si aggiunge alla coda di revisione.
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        async run(args, { api, clientName }) {
+            const title = requiredString(args, 'title');
+            const body = requiredString(args, 'body');
+            const techSpec = optionalString(args, 'tech_spec');
+            const reviewNote = optionalString(args, 'review_note');
+            const tooLong = (0, limits_1.tooLongMessage)([
+                { flag: 'title', value: title, max: limits_1.LENGTH_LIMITS.title },
+                { flag: 'body', value: body, max: limits_1.LENGTH_LIMITS.pageBody },
+                { flag: 'tech_spec', value: techSpec, max: limits_1.LENGTH_LIMITS.techSpec },
+                { flag: 'review_note', value: reviewNote, max: limits_1.LENGTH_LIMITS.reviewNote },
+            ]);
+            if (tooLong)
+                throw new McpToolInputError(tooLong);
+            const [primary, ...extraProjects] = stringList(args, 'project');
+            const groupRefs = stringList(args, 'group');
+            // Una pagina senza scope il server la creerebbe a livello di organizzazione, cioè visibile
+            // soltanto a chi ha accesso pieno — invisibile a chi l'ha appena proposta.
+            if (primary === undefined && groupRefs.length === 0) {
+                throw new McpToolInputError('Name at least one "project" or "group": a knowledge page has to belong somewhere.');
+            }
+            const projectIds = await Promise.all(extraProjects.map((ref) => (0, lookup_1.resolveProjectId)(api, ref)));
+            const groupIds = await Promise.all(groupRefs.map((ref) => (0, lookup_1.resolveNamedId)(api, '/cli/v1/groups', ref, error_codes_1.ErrorCodes.Group.notFound, 'Group')));
+            const tags = stringList(args, 'tag');
+            const res = await api.post('/cli/v1/knowledge/pages', {
+                ...(primary !== undefined && { project: primary }),
+                ...(projectIds.length > 0 && { project_ids: projectIds }),
+                ...(groupIds.length > 0 && { group_ids: groupIds }),
+                ...(tags.length > 0 && { tags }),
+                title,
+                kind: optionalString(args, 'kind') ?? 'note',
+                body,
+                tech_spec: techSpec,
+                // Scritto qui e mai letto dagli argomenti: è la garanzia che la revisione umana non si
+                // possa saltare da questo lato, qualunque cosa chieda chi invoca lo strumento.
+                in_review: true,
+                review_note: reviewNote,
+                author_origin: optionalString(args, 'author_origin') ?? clientName ?? DEFAULT_AUTHOR_ORIGIN,
+            });
+            return payload(res);
+        },
+    },
+];
+function findTool(name) {
+    return exports.MCP_TOOLS.find((tool) => tool.name === name);
+}
+/** Il catalogo come lo vuole `tools/list`: tutto tranne il codice che esegue la chiamata. */
+function toolDefinitions() {
+    return exports.MCP_TOOLS.map(({ name, title, description, inputSchema, annotations }) => ({
+        name,
+        title,
+        description,
+        inputSchema,
+        annotations,
+    }));
+}