@imenam/mcp-organizer 0.0.0-stage → 1.0.2

package/dist/src/mcp/notifications.js

@@ -0,0 +1,54 @@
+import { NotificationsDataSchema } from "../../shared/schemas/agent-tools.schema.js";
+import { writeHandoff } from "./watch-handoff.js";
+/**
+ * Outil `enable_notifications`, exécuté par le mode MCP lui-même : il lit le
+ * jeton, l'espace et l'état du veilleur sur le site, dépose le relais du
+ * veilleur et rend l'appel `Monitor` que l'agent doit faire.
+ */
+/** Durée maximale d'un `Monitor` côté hôte. */
+export const MONITOR_TIMEOUT_MS = 1_800_000;
+const PACKAGE_NAME = "@imenam/mcp-organizer";
+export const ENABLE_NOTIFICATIONS_TOOL = {
+    name: "enable_notifications",
+    description: "Get notified in real time of the requests the members of your space send to the AI, without polling the queue. Returns immediately: it blocks nothing and starts nothing on its own. It hands you the exact Monitor call to make right after — arming that watcher is what actually delivers notifications, and until you do it no request will reach you. Call this once at the start of a session; then keep working, each new pending request interrupts you on its own. The host stops the watcher after 30 minutes at most: re-arm it with the same Monitor call each time it expires.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+};
+/** Commande du veilleur du jeton `tokenId`. */
+export function watchCommand(tokenId) {
+    return `npx -y ${PACKAGE_NAME} --watch ${tokenId}`;
+}
+export async function enableNotifications(client, connection) {
+    const envelope = await client.envelope({ method: "GET", path: "notifications", query: {}, body: undefined });
+    const { token, space, pendingCount, watcher } = client.parseData(NotificationsDataSchema, envelope.data);
+    writeHandoff({ tokenId: token.id, url: connection.url, token: connection.token });
+    const command = watchCommand(token.id);
+    if (watcher.armed) {
+        return [
+            `Notifications are already live for token "${token.name}" on space "${space.name}" (watcher armed since ${watcher.since}).`,
+            "Nothing to do: keep working, new requests will interrupt you on their own.",
+            "Do not arm a second watcher — you would get every request twice.",
+            "Only exception: if the host just told you your watcher expired or stopped, re-arm it",
+            `with the same Monitor call (command \`${command}\`, timeout_ms ${MONITOR_TIMEOUT_MS}).`,
+        ].join("\n");
+    }
+    const lines = [
+        `Notifications enabled for token "${token.name}" on space "${space.name}".`,
+        "",
+        "Last step — call the Monitor tool now, with exactly these arguments:",
+        `  command:     ${command}`,
+        "  description: New requests for the AI in the organizer",
+        `  timeout_ms:  ${MONITOR_TIMEOUT_MS}`,
+        "",
+        "Until that watcher is armed, nothing will reach you: no request will be announced.",
+        "Once it is, keep working normally — each request that becomes pending shows up on its own,",
+        "even while you are idle. One line per request; process it with claim_request.",
+        "",
+        "The host stops every monitor after 30 minutes at most. Each time it tells you this",
+        "watcher expired, call Monitor again right away with the same arguments — do not call",
+        "enable_notifications again. Skip that and notifications stop for good.",
+    ];
+    if (pendingCount > 0) {
+        lines.push("", `${pendingCount} request(s) are already pending. Only requests that become pending AFTER the`, "watcher starts are announced — process the backlog with list_requests.");
+    }
+    return lines.join("\n");
+}

package/dist/src/mcp/start.d.ts

@@ -0,0 +1,14 @@
+import { type SiteConnection } from "./client.js";
+/** Présentation du serveur transmise au client MCP : concepts et déroulé. */
+export declare const INSTRUCTIONS = "mcp-organizer connects you to an organizer site: a multi-user task manager where people organize tasks in a web app and queue requests for the AI. You, the connected agent, process those requests when the user asks you to. The site never calls an LLM: you are the intelligence.\n\nYour token covers exactly one space, with the rights of the user who created the token. Every tool works on that space.\n\nConcepts:\n- A **space** holds tasks and an idea box. A user's **personal space** is private; a **shared space** has one owner and members.\n- A **task** has a title, a markdown description, a status (todo, doing, review, done), a priority (low, medium, high, critical), assignees and tags. Tasks nest on two levels: task > sub-task > sub-sub-task. A task is either standard (with a checklist) or a test (with checkpoints that each tester marks ok, ko, blocked or untested).\n- A **request** is something a member of your space asked the AI: an idea, a remark, a test review, a message or an idea promotion. It is pending, then processing once you claim it (only your token can then act for it), then done (with your reply) or failed (with the reason).\n- A **batch** is the set of actions you perform for one request. Every action is logged with its before and after state and with your token, and users can undo one action or the whole batch.\n- The **scope** of your work is the space of your token: you see and process the requests of all its members, and you never act outside it.\n\nWork loop, when the user asks you to process the queue:\n1. list_requests to see the pending requests of your space.\n2. claim_request on the oldest one: it becomes processing for you and you get its context (text, author, context task, task tree, members, recent ideas). get_context shows the space at any time.\n3. Read what you need with get_task and search_tasks.\n4. Act with create_task, update_task, set_assignees, set_tags, edit_checklist, add_comment, create_idea, update_idea, promote_idea \u2014 always passing the request_id. Each write is one undoable action of the batch.\n5. complete_request with a short reply in the author's language (or fail_request with the reason), then go back to step 1 until no request is pending.\nWhen the queue is empty, tell the user.\n\nNotifications: call enable_notifications once at the start of the session and arm the watcher it hands you with Monitor. Each request that becomes pending in your space then arrives on its own as one line (kind, author, excerpt, request id), even while you are idle: process it with the work loop above, starting with claim_request. The host stops that watcher after 30 minutes at most: each time it tells you the watcher expired, re-arm it at once with the same Monitor call; otherwise notifications stop for good. A line \"notifications stopped\" means the site refused the token: tell the user.\n\nHow to handle each kind of request:\n- **idea**: classify it. If it belongs to an existing task or sub-task, attach it there (sub-task, checklist item or comment). If it is actionable and important enough, create a task (or sub-task) with a fitting priority. Otherwise, put it in the idea box with create_idea. Prefer existing tasks over duplicates.\n- **test_review**: feed the tester's findings back into the existing tasks (status, checklist, comments, priority of the affected tasks), or create a task for each problem that has none.\n- **remark** and **message**: do whatever is useful \u2014 answer, update or create tasks, comment \u2014 and say what you did in the reply.\n- **idea_promotion**: turn the context idea into a well-formed task with promote_idea.\n\nRules: write titles, descriptions and replies in the language of the users; keep the reply short and factual. Errors tell you what to do next; an error about the token (missing, revoked, expired, owner no longer a member) cannot be fixed by retrying: tell the user.";
+/**
+ * Connexion au site d'après `ORGANIZER_URL` et `ORGANIZER_TOKEN` ; une valeur
+ * absente ou invalide, ou une URL http vers une autre machine, est une `ConfigError`.
+ */
+export declare function loadSiteConnection(): SiteConnection;
+/**
+ * Mode MCP (par défaut) : serveur stdio sans base ni logique métier. Il
+ * expose les outils de l'agent et relaie chaque appel à l'API agent du site
+ * désigné par `ORGANIZER_URL`, avec le jeton `ORGANIZER_TOKEN`.
+ */
+export declare function runMcpMode(): Promise<void>;

package/dist/src/mcp/start.js

@@ -0,0 +1,123 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { APP_VERSION } from "../version.js";
+import { createLogger, setupLogging } from "../core/logger.js";
+import { ConfigError } from "../core/errors.js";
+import { OrganizerSiteClient, SiteError } from "./client.js";
+import { AGENT_TOOLS, ToolArgumentError, findAgentTool, toolHttpRequest } from "./tools.js";
+import { ENABLE_NOTIFICATIONS_TOOL, enableNotifications } from "./notifications.js";
+import { removeOwnHandoffs } from "./watch-handoff.js";
+/** Présentation du serveur transmise au client MCP : concepts et déroulé. */
+export const INSTRUCTIONS = `mcp-organizer connects you to an organizer site: a multi-user task manager where people organize tasks in a web app and queue requests for the AI. You, the connected agent, process those requests when the user asks you to. The site never calls an LLM: you are the intelligence.
+
+Your token covers exactly one space, with the rights of the user who created the token. Every tool works on that space.
+
+Concepts:
+- A **space** holds tasks and an idea box. A user's **personal space** is private; a **shared space** has one owner and members.
+- A **task** has a title, a markdown description, a status (todo, doing, review, done), a priority (low, medium, high, critical), assignees and tags. Tasks nest on two levels: task > sub-task > sub-sub-task. A task is either standard (with a checklist) or a test (with checkpoints that each tester marks ok, ko, blocked or untested).
+- A **request** is something a member of your space asked the AI: an idea, a remark, a test review, a message or an idea promotion. It is pending, then processing once you claim it (only your token can then act for it), then done (with your reply) or failed (with the reason).
+- A **batch** is the set of actions you perform for one request. Every action is logged with its before and after state and with your token, and users can undo one action or the whole batch.
+- The **scope** of your work is the space of your token: you see and process the requests of all its members, and you never act outside it.
+
+Work loop, when the user asks you to process the queue:
+1. list_requests to see the pending requests of your space.
+2. claim_request on the oldest one: it becomes processing for you and you get its context (text, author, context task, task tree, members, recent ideas). get_context shows the space at any time.
+3. Read what you need with get_task and search_tasks.
+4. Act with create_task, update_task, set_assignees, set_tags, edit_checklist, add_comment, create_idea, update_idea, promote_idea — always passing the request_id. Each write is one undoable action of the batch.
+5. complete_request with a short reply in the author's language (or fail_request with the reason), then go back to step 1 until no request is pending.
+When the queue is empty, tell the user.
+
+Notifications: call enable_notifications once at the start of the session and arm the watcher it hands you with Monitor. Each request that becomes pending in your space then arrives on its own as one line (kind, author, excerpt, request id), even while you are idle: process it with the work loop above, starting with claim_request. The host stops that watcher after 30 minutes at most: each time it tells you the watcher expired, re-arm it at once with the same Monitor call; otherwise notifications stop for good. A line "notifications stopped" means the site refused the token: tell the user.
+
+How to handle each kind of request:
+- **idea**: classify it. If it belongs to an existing task or sub-task, attach it there (sub-task, checklist item or comment). If it is actionable and important enough, create a task (or sub-task) with a fitting priority. Otherwise, put it in the idea box with create_idea. Prefer existing tasks over duplicates.
+- **test_review**: feed the tester's findings back into the existing tasks (status, checklist, comments, priority of the affected tasks), or create a task for each problem that has none.
+- **remark** and **message**: do whatever is useful — answer, update or create tasks, comment — and say what you did in the reply.
+- **idea_promotion**: turn the context idea into a well-formed task with promote_idea.
+
+Rules: write titles, descriptions and replies in the language of the users; keep the reply short and factual. Errors tell you what to do next; an error about the token (missing, revoked, expired, owner no longer a member) cannot be fixed by retrying: tell the user.`;
+/** Hôtes de la machine locale, seuls admis en http. */
+const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** Variable d'environnement non vide, ou null. */
+function read(name) {
+    const value = process.env[name]?.trim();
+    return value ? value : null;
+}
+/**
+ * Connexion au site d'après `ORGANIZER_URL` et `ORGANIZER_TOKEN` ; une valeur
+ * absente ou invalide, ou une URL http vers une autre machine, est une `ConfigError`.
+ */
+export function loadSiteConnection() {
+    const rawUrl = read("ORGANIZER_URL");
+    const token = read("ORGANIZER_TOKEN");
+    const missing = [rawUrl === null ? "ORGANIZER_URL" : null, token === null ? "ORGANIZER_TOKEN" : null].filter((name) => name !== null);
+    if (missing.length > 0) {
+        throw new ConfigError(`mcp-organizer (MCP mode) needs ${missing.join(" and ")}: ORGANIZER_URL is the public URL of the organizer site, ORGANIZER_TOKEN an agent token created on that site (Paramètres > Agents). Set them in the "env" block of the MCP server declaration, or run: npx -y @imenam/mcp-organizer --claude-setup-mcp --url=<site URL> --token=<agent token>.`);
+    }
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new ConfigError(`ORGANIZER_URL is not an absolute URL (${rawUrl}): expected the public URL of the site, e.g. https://organizer.example.com.`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw new ConfigError(`ORGANIZER_URL must use http or https (${rawUrl}).`);
+    if (url.search || url.hash || url.username || url.password)
+        throw new ConfigError(`ORGANIZER_URL must not contain credentials, a query or a fragment (${rawUrl}).`);
+    if (url.protocol === "http:" && !LOCAL_HOSTNAMES.has(url.hostname)) {
+        throw new ConfigError(`ORGANIZER_URL must use https for a remote site (${url.hostname}): over http the agent token would travel in clear text. http is only accepted for a site on this machine (localhost, 127.0.0.1, ::1). Use the https URL of the site.`);
+    }
+    return { url: url.href.replace(/\/+$/, ""), token: token };
+}
+/**
+ * Mode MCP (par défaut) : serveur stdio sans base ni logique métier. Il
+ * expose les outils de l'agent et relaie chaque appel à l'API agent du site
+ * désigné par `ORGANIZER_URL`, avec le jeton `ORGANIZER_TOKEN`.
+ */
+export async function runMcpMode() {
+    const connection = loadSiteConnection();
+    const logDir = read("MCP_LOG_DIR");
+    if (logDir)
+        setupLogging("mcp-organizer", logDir);
+    const logger = createLogger("mcp");
+    const client = new OrganizerSiteClient(connection);
+    const server = new Server({ name: "mcp-organizer", version: APP_VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...AGENT_TOOLS.map((tool) => tool.definition), ENABLE_NOTIFICATIONS_TOOL] }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === ENABLE_NOTIFICATIONS_TOOL.name) {
+            try {
+                return { content: [{ type: "text", text: await enableNotifications(client, connection) }] };
+            }
+            catch (error) {
+                if (!(error instanceof SiteError))
+                    logger.error(`Tool ${name} failed: ${error?.stack ?? error}`);
+                return errorResult(error?.message ?? String(error));
+            }
+        }
+        const tool = findAgentTool(name);
+        if (!tool)
+            return errorResult(`Unknown tool "${name}". Call tools/list to get the available tools.`);
+        try {
+            const text = await client.call(toolHttpRequest(tool, (args ?? {})));
+            return { content: [{ type: "text", text }] };
+        }
+        catch (error) {
+            if (!(error instanceof SiteError) && !(error instanceof ToolArgumentError))
+                logger.error(`Tool ${name} failed: ${error?.stack ?? error}`);
+            return errorResult(error?.message ?? String(error));
+        }
+    });
+    // Le relais du veilleur porte le jeton : il ne survit pas au mode MCP qui l'a écrit.
+    process.on("exit", removeOwnHandoffs);
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.on(signal, () => process.exit(0));
+    }
+    await server.connect(new StdioServerTransport());
+    logger.info(`MCP server running on stdio (version ${APP_VERSION}, site: ${connection.url})`);
+}
+function errorResult(text) {
+    return { content: [{ type: "text", text: `Error: ${text}` }], isError: true };
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Outils de l'agent : définition (schéma JSON écrit à la main, description
+ * en anglais) et route de l'API agent du site qui l'exécute. Le mode MCP ne
+ * fait que relayer chaque appel à sa route.
+ */
+/** Définition d'un outil telle que la liste `tools/list`. */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+}
+export interface AgentTool {
+    definition: ToolDefinition;
+    method: "GET" | "POST" | "PUT" | "PATCH";
+    /**
+     * Chemin sous `/api/agent/`. `{nom}` y est remplacé par l'argument `nom`,
+     * encodé ; les autres arguments forment la requête d'un GET, le corps JSON sinon.
+     */
+    path: string;
+}
+/** Requête HTTP d'un appel d'outil. */
+export interface ToolHttpRequest {
+    method: AgentTool["method"];
+    /** Chemin sous `/api/agent/`, segments encodés. */
+    path: string;
+    query: Record<string, string>;
+    body: Record<string, unknown> | undefined;
+}
+/** Argument d'appel d'outil inutilisable pour former la requête. */
+export declare class ToolArgumentError extends Error {
+    constructor(message: string);
+}
+export declare const AGENT_TOOLS: readonly AgentTool[];
+/** Outil d'après son nom. */
+export declare function findAgentTool(name: string): AgentTool | undefined;
+/**
+ * Requête HTTP d'un appel d'outil : les arguments nommés dans le chemin y
+ * sont placés (ils sont alors obligatoires et textuels), les autres vont
+ * dans la requête d'un GET ou le corps JSON. Le site valide le reste.
+ */
+export declare function toolHttpRequest(tool: AgentTool, args: Record<string, unknown>): ToolHttpRequest;

package/dist/src/mcp/tools.js

@@ -0,0 +1,348 @@
+import { REQUEST_STATUSES, TASK_PRIORITIES, TASK_STATUSES, TASK_TYPES } from "../../shared/schemas/enums.schema.js";
+import { MAX_TAG_LENGTH, MAX_TASK_TITLE_LENGTH } from "../../shared/schemas/tasks-api.schema.js";
+import { MAX_CHECKLIST_ITEM_LENGTH, MAX_CHECKLIST_OPERATIONS, MAX_COMMENT_LENGTH, MAX_IDEA_LENGTH, MAX_REASON_LENGTH, MAX_REPLY_LENGTH, MAX_REQUEST_LIST_LIMIT, MAX_SEARCH_LIMIT, } from "../../shared/schemas/agent-tools.schema.js";
+/** Argument d'appel d'outil inutilisable pour former la requête. */
+export class ToolArgumentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ToolArgumentError";
+    }
+}
+const REQUEST_ID = {
+    type: "string",
+    description: "Id of the request you claimed with claim_request (status processing). Every write is recorded in its batch and can be undone by the users.",
+};
+const TASK_REF = { type: "string", description: "Task of your space: its key (e.g. ORG-41) or its id." };
+export const AGENT_TOOLS = [
+    {
+        method: "GET",
+        path: "requests",
+        definition: {
+            name: "list_requests",
+            description: "List the requests the members of your space queued for the agent, with author, kind and context task: pending requests oldest first, other statuses most recent first. Call it when the user asks you to process the queue (default: pending), or to review processing, done, failed or cancelled requests.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    status: { type: "string", enum: [...REQUEST_STATUSES, "all"], description: "Status to list. Default: pending." },
+                    limit: { type: "integer", minimum: 1, maximum: MAX_REQUEST_LIST_LIMIT, description: "Maximum number of requests. Default: 20." },
+                },
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "POST",
+        path: "requests/{request_id}/claim",
+        definition: {
+            name: "claim_request",
+            description: "Claim a pending request before working on it: it becomes processing for your token only (no other agent can take it or act for it) and you get its full context — text, author, context task or idea, the task tree of your space with keys, statuses, priorities and assignees, its members and recent ideas. Every write tool then needs this request_id.",
+            inputSchema: {
+                type: "object",
+                properties: { request_id: { type: "string", description: "Id of a pending request, from list_requests." } },
+                required: ["request_id"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "GET",
+        path: "context",
+        definition: {
+            name: "get_context",
+            description: "Show your space: its name and task key prefix, its members (ids and e-mails, for set_assignees), the task tree with statuses, priorities and assignees, and the recent ideas of its idea box.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        },
+    },
+    {
+        method: "GET",
+        path: "tasks/{task}",
+        definition: {
+            name: "get_task",
+            description: "Read one task of your space in detail: fields, parents, assignees, tags, description, checklist items or test checkpoints (with their ids, needed by edit_checklist), sub-tasks, recent comments and attachments. Use it before modifying a task.",
+            inputSchema: { type: "object", properties: { task: TASK_REF }, required: ["task"], additionalProperties: false },
+        },
+    },
+    {
+        method: "GET",
+        path: "tasks",
+        definition: {
+            name: "search_tasks",
+            description: "Search the tasks of your space by words of their title, description or key, optionally filtered by status, priority, type or assignee. Use it to find an existing task to attach an idea to or to update, before creating a duplicate.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Words to look for (case-insensitive, all must match). Omit to list by filters only." },
+                    status: { type: "string", enum: [...TASK_STATUSES] },
+                    priority: { type: "string", enum: [...TASK_PRIORITIES] },
+                    type: { type: "string", enum: [...TASK_TYPES] },
+                    assignee: { type: "string", description: "Member id or e-mail." },
+                    limit: { type: "integer", minimum: 1, maximum: MAX_SEARCH_LIMIT, description: "Maximum number of results. Default: 30." },
+                },
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "POST",
+        path: "tasks",
+        definition: {
+            name: "create_task",
+            description: "Create a task in your space: a top-level task, or a sub-task / sub-sub-task with parent (two levels at most). Use type test for a task whose checkpoints testers verify. Search first with search_tasks to avoid duplicates. It goes at the bottom of its column.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    request_id: REQUEST_ID,
+                    title: { type: "string", maxLength: MAX_TASK_TITLE_LENGTH, description: "Short, actionable title, in the language of the space." },
+                    description: { type: "string", description: "Markdown description." },
+                    type: { type: "string", enum: [...TASK_TYPES], description: "Default: standard." },
+                    priority: { type: "string", enum: [...TASK_PRIORITIES], description: "Default: medium." },
+                    status: { type: "string", enum: [...TASK_STATUSES], description: "Default: todo." },
+                    parent: { type: "string", description: "Parent task key (e.g. ORG-41) or id, to create a sub-task." },
+                },
+                required: ["request_id", "title"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "PATCH",
+        path: "tasks/{task}",
+        definition: {
+            name: "update_task",
+            description: "Change a task of your space: title, description, status, priority, type, parent (move it under another task, or null to make it top-level), position in its column (after_task) and, for a test task, the task it tests (tested_task_id). Only the given fields change. Read the task with get_task first.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    request_id: REQUEST_ID,
+                    task: TASK_REF,
+                    title: { type: "string", maxLength: MAX_TASK_TITLE_LENGTH },
+                    description: { type: "string", description: "New markdown description (replaces the whole description)." },
+                    status: { type: "string", enum: [...TASK_STATUSES] },
+                    priority: { type: "string", enum: [...TASK_PRIORITIES] },
+                    type: { type: "string", enum: [...TASK_TYPES] },
+                    parent: { type: ["string", "null"], description: "New parent task key or id; null makes the task top-level." },
+                    after_task: {
+                        type: ["string", "null"],
+                        description: "Place the task right after this task of its (new) column — same parent and status; null puts it at the top of the column.",
+                    },
+                    tested_task_id: {
+                        type: ["string", "null"],
+                        description: "Test tasks only: the task of your space this test verifies (key or id, not the test itself); null removes the link. A task changed to standard loses it.",
+                    },
+                },
+                required: ["request_id", "task"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "PUT",
+        path: "tasks/{task}/assignees",
+        definition: {
+            name: "set_assignees",
+            description: "Replace the assignees of a task of your space (the testers, for a test task). Pass the full list: members not listed are unassigned, an empty list unassigns everybody. Newly assigned members are notified. Member ids and e-mails are listed by claim_request and get_context.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    request_id: REQUEST_ID,
+                    task: TASK_REF,
+                    assignees: { type: "array", items: { type: "string" }, description: "Member ids or e-mails: the complete new list." },
+                },
+                required: ["request_id", "task", "assignees"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "PUT",
+        path: "tasks/{task}/tags",
+        definition: {
+            name: "set_tags",
+            description: "Replace the tags of a task of your space. Pass the full list; an unknown name creates the tag in the space (names match case-insensitively, so reuse existing tags), an empty list removes all tags.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    request_id: REQUEST_ID,
+                    task: TASK_REF,
+                    tags: { type: "array", items: { type: "string", maxLength: MAX_TAG_LENGTH }, description: "Tag names: the complete new list." },
+                },
+                required: ["request_id", "task", "tags"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "POST",
+        path: "tasks/{task}/checklist",
+        definition: {
+            name: "edit_checklist",
+            description: "Edit the checklist of a standard task (add, rename, check or uncheck, delete items) or the checkpoints of a test task (add, rename, delete; testers record the results themselves). Operations apply in order, all or nothing. Item ids come from get_task.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    request_id: REQUEST_ID,
+                    task: TASK_REF,
+                    operations: {
+                        type: "array",
+                        minItems: 1,
+                        maxItems: MAX_CHECKLIST_OPERATIONS,
+                        items: {
+                            type: "object",
+                            properties: {
+                                action: { type: "string", enum: ["add", "update", "delete"] },
+                                text: { type: "string", maxLength: MAX_CHECKLIST_ITEM_LENGTH, description: "add: text of the new item; update: new text." },
+                                item_id: { type: "string", description: "update / delete: id of the checklist item or checkpoint." },
+                                done: { type: "boolean", description: "update, standard task only: check (true) or uncheck (false) the item." },
+                            },
+                            required: ["action"],
+                            additionalProperties: false,
+                        },
+                    },
+                },
+                required: ["request_id", "task", "operations"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "POST",
+        path: "tasks/{task}/comments",
+        definition: {
+            name: "add_comment",
+            description: "Comment on a task of your space as the agent (shown as written by the agent, in the name of your token's owner). Assignees and previous commenters are notified. Use it to record a remark, a decision or a test finding on the task it concerns.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    request_id: REQUEST_ID,
+                    task: TASK_REF,
+                    body: { type: "string", maxLength: MAX_COMMENT_LENGTH, description: "Comment text, in the language of the space." },
+                },
+                required: ["request_id", "task", "body"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "POST",
+        path: "ideas",
+        definition: {
+            name: "create_idea",
+            description: "Put an idea in the idea box of your space. Use it for an idea that is not urgent or not actionable yet and does not belong to an existing task; rewrite it as one clear sentence.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    request_id: REQUEST_ID,
+                    text: { type: "string", maxLength: MAX_IDEA_LENGTH, description: "The idea, clearly worded, in the language of the space." },
+                },
+                required: ["request_id", "text"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "PATCH",
+        path: "ideas/{idea_id}",
+        definition: {
+            name: "update_idea",
+            description: "Reword an idea of your space's idea box, or archive it (archived true) when it is done, obsolete or merged into a task; archived false brings it back. Idea ids are listed by claim_request and get_context.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    request_id: REQUEST_ID,
+                    idea_id: { type: "string" },
+                    text: { type: "string", maxLength: MAX_IDEA_LENGTH, description: "New wording." },
+                    archived: { type: "boolean" },
+                },
+                required: ["request_id", "idea_id"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "POST",
+        path: "ideas/{idea_id}/promote",
+        definition: {
+            name: "promote_idea",
+            description: "Turn an idea of your space's idea box into a task (todo column): the task is created with the given title, description, type, priority and optional parent, and the idea is marked as promoted to it. Use it for an idea_promotion request, or when an idea in the box has become actionable.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    request_id: REQUEST_ID,
+                    idea_id: { type: "string" },
+                    title: { type: "string", maxLength: MAX_TASK_TITLE_LENGTH, description: "Short, actionable task title." },
+                    description: { type: "string", description: "Markdown description, usually the idea reworded with what to do." },
+                    type: { type: "string", enum: [...TASK_TYPES], description: "Default: standard." },
+                    priority: { type: "string", enum: [...TASK_PRIORITIES], description: "Default: medium." },
+                    parent: { type: "string", description: "Parent task key or id, to create a sub-task." },
+                },
+                required: ["request_id", "idea_id", "title"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "POST",
+        path: "requests/{request_id}/complete",
+        definition: {
+            name: "complete_request",
+            description: "Finish a processing request with your reply to its author: one or two sentences in the author's language saying what you did (tasks created or changed, where the idea went) or answering their message. The reply is shown in the assistant panel and on the Agent page, next to the actions of the batch. Call it last.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    request_id: { type: "string", description: "Id of the request you claimed." },
+                    reply: { type: "string", maxLength: MAX_REPLY_LENGTH, description: "Short report for the author." },
+                },
+                required: ["request_id", "reply"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        method: "POST",
+        path: "requests/{request_id}/fail",
+        definition: {
+            name: "fail_request",
+            description: "Finish a processing request as failed when you cannot do it (unclear request, impossible change, your token's owner can no longer act in the space). Give the reason in the author's language: they see it. Actions already done stay in the batch and can be undone by the users.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    request_id: { type: "string", description: "Id of the request you claimed." },
+                    reason: { type: "string", maxLength: MAX_REASON_LENGTH, description: "Why the request could not be done, and what the author can do." },
+                },
+                required: ["request_id", "reason"],
+                additionalProperties: false,
+            },
+        },
+    },
+];
+/** Outil d'après son nom. */
+export function findAgentTool(name) {
+    return AGENT_TOOLS.find((tool) => tool.definition.name === name);
+}
+/**
+ * Requête HTTP d'un appel d'outil : les arguments nommés dans le chemin y
+ * sont placés (ils sont alors obligatoires et textuels), les autres vont
+ * dans la requête d'un GET ou le corps JSON. Le site valide le reste.
+ */
+export function toolHttpRequest(tool, args) {
+    const rest = { ...args };
+    const path = tool.path.replace(/\{([a-z_]+)\}/g, (_, name) => {
+        const value = rest[name];
+        if (typeof value !== "string" || value.trim() === "") {
+            throw new ToolArgumentError(`Invalid arguments — ${name}: expected a non-empty string. Check the tool's input schema.`);
+        }
+        delete rest[name];
+        return encodeURIComponent(value.trim());
+    });
+    if (tool.method !== "GET")
+        return { method: tool.method, path, query: {}, body: rest };
+    const query = {};
+    for (const [name, value] of Object.entries(rest)) {
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value === "object")
+            throw new ToolArgumentError(`Invalid arguments — ${name}: expected a single value. Check the tool's input schema.`);
+        query[name] = String(value);
+    }
+    return { method: tool.method, path, query, body: undefined };
+}

package/dist/src/mcp/watch-handoff.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Relais entre la session MCP et son veilleur de notifications.
+ *
+ * Le veilleur est lancé par l'agent via l'outil `Monitor` de l'hôte : c'est un
+ * processus du shell de la session, pas un enfant du mode MCP. Il n'hérite donc
+ * pas du bloc `env` du `.mcp.json` et n'a ni URL du site ni jeton. Les passer sur
+ * la ligne de commande les afficherait dans la conversation : ils transitent par
+ * un fichier en 0600, que seul l'identifiant du jeton (pas sa valeur) permet de
+ * retrouver.
+ *
+ * Le fichier est écrit par `enable_notifications`, jamais au démarrage, et retiré
+ * à l'arrêt du mode MCP qui l'a écrit en dernier.
+ */
+export interface Handoff {
+    /** Identifiant du jeton d'agent. */
+    tokenId: string;
+    url: string;
+    /** Valeur du jeton. */
+    token: string;
+    /** Processus du mode MCP qui a écrit le relais. */
+    pid: number;
+    /** Horodatage d'écriture, qui sert à purger les relais abandonnés. */
+    writtenAt: string;
+}
+/** Répertoire des relais : `<ORGANIZER_STATE_DIR>/watch`, ou `~/.mcp-organizer/watch`. */
+export declare function handoffDir(): string;
+/** Fichier du relais d'un jeton, nommé d'après le hachage de son identifiant. */
+export declare function handoffPath(tokenId: string): string;
+export declare function writeHandoff(handoff: Omit<Handoff, "pid" | "writtenAt">): string;
+/** Relais du jeton `tokenId`, ou null s'il n'existe pas ou ne concerne pas ce jeton. */
+export declare function readHandoff(tokenId: string): Handoff | null;
+/** Supprime le relais du jeton s'il a été écrit en dernier par ce processus. */
+export declare function removeHandoff(tokenId: string): void;
+/** Supprime les relais écrits en dernier par ce processus. Synchrone : appelable sur `exit`. */
+export declare function removeOwnHandoffs(): void;