@imenam/mcp-organizer 1.0.3 → 1.0.7

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

@@ -1,6 +1,6 @@
 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, whatever the command (behind mcp-http-gateway, the gateway relay answers in place of this server and gives its own watcher command). 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, and a line \"[gateway-watch] \u2026 la veille \u00E9choue\" means the gateway watcher keeps failing: tell the user. wait_for_requests is the waiting tool of the watcher: you do not need to call it.\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.";
+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, for a message the previous exchanges of its author, 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, whatever the command (behind mcp-http-gateway, the gateway relay answers in place of this server and gives its own watcher command). 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, and a line \"[gateway-watch] \u2026 la veille \u00E9choue\" means the gateway watcher keeps failing: tell the user. wait_for_requests is the waiting tool of the watcher: you do not need to call it.\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`.

package/dist/src/mcp/start.js

@@ -22,7 +22,7 @@ Concepts:
 
 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.
+2. claim_request on the oldest one: it becomes processing for you and you get its context (text, author, context task, for a message the previous exchanges of its author, 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.

package/dist/src/mcp/tools.js

@@ -35,7 +35,7 @@ export const AGENT_TOOLS = [
         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.",
+            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, for a message the previous exchanges of its author (their requests and your replies), 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." } },

package/dist/src/server/runner.d.ts

@@ -0,0 +1,51 @@
+import type { Logger } from "../core/logger.js";
+import type { Store } from "../core/store.js";
+import type { RunnerStatus } from "../../shared/schemas/admin-api.schema.js";
+/** Consigne de la session. Les `instructions` du serveur MCP organizer décrivent les concepts et la boucle de travail. */
+export declare const SESSION_PROMPT: string;
+export interface RunnerConfig {
+    /** Commande de Claude Code, et ses éventuels arguments fixes. */
+    command: string[];
+    /** URL du site joignable depuis cette machine, en http local. */
+    siteUrl: string;
+    /** Point d'entrée de ce paquet, lancé en mode MCP par la session. */
+    entry: string;
+    /** Dossier de configuration et de connexion de Claude Code. */
+    claudeDir: string;
+    /** Dossier des sessions : configurations MCP éphémères, dossier courant de Claude Code. */
+    workDir: string;
+}
+/** Configuration du runner d'après l'environnement, ou la raison de sa désactivation. */
+export declare function runnerFromEnv(env: NodeJS.ProcessEnv, site: {
+    host: string;
+    port: number;
+    rootDir: string;
+    dataDir: string;
+}): {
+    status: RunnerStatus;
+    config: RunnerConfig | null;
+};
+export declare class SiteRunner {
+    private readonly store;
+    private readonly config;
+    private readonly logger;
+    private readonly queue;
+    private readonly rerun;
+    /** Espaces à traiter une fois même sans autorisation : demande ponctuelle d'un administrateur. */
+    private readonly forced;
+    private running;
+    private child;
+    private readonly unsubscribe;
+    constructor(store: Store, config: RunnerConfig, logger: Logger);
+    /** S'abonne aux demandes et aux autorisations, et planifie les espaces autorisés qui ont déjà des demandes. */
+    start(): void;
+    /** Arrête la session en cours et ne planifie plus rien. */
+    stop(): void;
+    /** Planifie une session pour traiter la file de l'espace une fois, même si le runner n'y est pas autorisé. */
+    runNow(spaceId: string): void;
+    /** Planifie une session pour l'espace ; un espace en cours de session est repris après elle. */
+    schedule(spaceId: string): void;
+    private drain;
+    private runSession;
+    private spawnClaude;
+}

package/dist/src/server/runner.js

@@ -0,0 +1,222 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { issueRunnerToken } from "../core/agent-tokens.js";
+import { upstreamAddress } from "../deploy/templates.js";
+/**
+ * Runner du site : une session Claude Code (`claude -p`) par espace autorisé
+ * qui a des demandes en attente.
+ *
+ * Le site lance lui-même la session, sous son propre compte, quand une
+ * demande passe en attente dans un espace où un administrateur a autorisé le
+ * runner, quand un espace est autorisé alors que des demandes y attendent, et
+ * au démarrage ; un administrateur peut aussi faire traiter la file d'un espace
+ * ponctuellement, qu'il soit autorisé ou non. La session reçoit une configuration MCP qui lui est propre :
+ * le mode MCP de ce paquet, relié au site local par le jeton du runner de
+ * l'espace, dont la valeur est renouvelée avant la session et invalidée après.
+ * Elle n'a accès qu'aux outils organizer : ni shell, ni fichiers, ni autre
+ * serveur MCP. Une seule session tourne à la fois.
+ *
+ * `ORGANIZER_RUNNER_CLAUDE` donne la commande de Claude Code ; sans elle, le
+ * runner est désactivé et le dit. Claude Code garde sa configuration et sa
+ * connexion dans `<données>/claude`.
+ */
+/** Durée maximale d'une session. */
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
+/** Nom du serveur MCP organizer dans la configuration d'une session. */
+const MCP_SERVER_NAME = "organizer";
+/** Outils intégrés de Claude Code refusés à la session : elle n'agit que par les outils organizer. */
+const DISALLOWED_TOOLS = [
+    "Bash",
+    "BashOutput",
+    "KillShell",
+    "Read",
+    "Write",
+    "Edit",
+    "NotebookEdit",
+    "Glob",
+    "Grep",
+    "WebFetch",
+    "WebSearch",
+    "Task",
+    "TodoWrite",
+];
+/** Consigne de la session. Les `instructions` du serveur MCP organizer décrivent les concepts et la boucle de travail. */
+export const SESSION_PROMPT = [
+    "You are the organizer runner: process the pending requests of your organizer space with the organizer tools.",
+    "Call list_requests, then claim and process each pending request with the work loop of the server instructions, until list_requests reports no pending request. Then stop.",
+    "Do not call enable_notifications or wait_for_requests.",
+].join("\n");
+const LOCAL_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "0.0.0.0", "::"]);
+/** Configuration du runner d'après l'environnement, ou la raison de sa désactivation. */
+export function runnerFromEnv(env, site) {
+    const raw = env.ORGANIZER_RUNNER_CLAUDE?.trim();
+    if (!raw) {
+        return {
+            status: { enabled: false, disabledReason: "ORGANIZER_RUNNER_CLAUDE n'est pas défini : indiquez la commande de Claude Code (par exemple /usr/bin/claude) dans le fichier .env du site." },
+            config: null,
+        };
+    }
+    if (!LOCAL_HOSTS.has(site.host)) {
+        return {
+            status: { enabled: false, disabledReason: `HOST (${site.host}) n'est pas une adresse locale : le runner joint le site en http sur cette machine ; écoutez sur 127.0.0.1 derrière nginx.` },
+            config: null,
+        };
+    }
+    return {
+        status: { enabled: true, disabledReason: null },
+        config: {
+            command: raw.split(/\s+/),
+            siteUrl: `http://${upstreamAddress(site.host, site.port)}`,
+            entry: path.join(site.rootDir, "dist", "src", "index.js"),
+            claudeDir: path.join(site.dataDir, "claude"),
+            workDir: path.join(site.dataDir, "runner"),
+        },
+    };
+}
+/** Environnement de la session : le strict nécessaire, sans les secrets du site (SMTP, Groq…). */
+function sessionEnv(config) {
+    const env = { HOME: config.claudeDir, CLAUDE_CONFIG_DIR: config.claudeDir };
+    for (const name of ["PATH", "LANG", "TMPDIR", "TEMP", "TMP", "SystemRoot", "SYSTEMROOT"]) {
+        if (process.env[name] !== undefined)
+            env[name] = process.env[name];
+    }
+    return env;
+}
+export class SiteRunner {
+    store;
+    config;
+    logger;
+    queue = [];
+    rerun = new Set();
+    /** Espaces à traiter une fois même sans autorisation : demande ponctuelle d'un administrateur. */
+    forced = new Set();
+    running = null;
+    child = null;
+    unsubscribe = [];
+    constructor(store, config, logger) {
+        this.store = store;
+        this.config = config;
+        this.logger = logger;
+    }
+    /** S'abonne aux demandes et aux autorisations, et planifie les espaces autorisés qui ont déjà des demandes. */
+    start() {
+        fs.mkdirSync(this.config.claudeDir, { recursive: true, mode: 0o700 });
+        fs.mkdirSync(this.config.workDir, { recursive: true, mode: 0o700 });
+        this.unsubscribe.push(this.store.onPendingRequest((request) => {
+            if (this.store.findSpace(request.targetSpaceId)?.runnerAllowed)
+                this.schedule(request.targetSpaceId);
+        }), this.store.onRunnerAllowed((space) => this.schedule(space.id)));
+        for (const space of this.store.listAllSpaces())
+            if (space.runnerAllowed)
+                this.schedule(space.id);
+        this.logger.info(`Runner enabled: Claude Code sessions with ${this.config.command[0]} (configuration in ${this.config.claudeDir})`);
+    }
+    /** Arrête la session en cours et ne planifie plus rien. */
+    stop() {
+        for (const unsubscribe of this.unsubscribe.splice(0))
+            unsubscribe();
+        this.queue.length = 0;
+        this.child?.kill();
+    }
+    /** Planifie une session pour traiter la file de l'espace une fois, même si le runner n'y est pas autorisé. */
+    runNow(spaceId) {
+        this.forced.add(spaceId);
+        this.schedule(spaceId);
+    }
+    /** Planifie une session pour l'espace ; un espace en cours de session est repris après elle. */
+    schedule(spaceId) {
+        if (this.running === spaceId) {
+            this.rerun.add(spaceId);
+            return;
+        }
+        if (!this.queue.includes(spaceId))
+            this.queue.push(spaceId);
+        void this.drain();
+    }
+    async drain() {
+        if (this.running !== null)
+            return;
+        for (let spaceId = this.queue.shift(); spaceId !== undefined; spaceId = this.queue.shift()) {
+            this.running = spaceId;
+            try {
+                await this.runSession(spaceId);
+            }
+            catch (err) {
+                this.logger.error(`Runner session for space ${spaceId} failed: ${err?.stack ?? err}`);
+            }
+            finally {
+                this.running = null;
+            }
+            if (this.rerun.delete(spaceId) && !this.queue.includes(spaceId))
+                this.queue.push(spaceId);
+        }
+    }
+    async runSession(spaceId) {
+        const space = this.store.findSpace(spaceId);
+        const forced = this.forced.delete(spaceId);
+        if (!space || (!space.runnerAllowed && !forced) || this.store.countPendingRequestsOfSpace(spaceId) === 0)
+            return;
+        const token = issueRunnerToken(this.store, spaceId);
+        const configFile = path.join(this.config.workDir, `session-${randomUUID()}.json`);
+        const mcpConfig = {
+            mcpServers: {
+                [MCP_SERVER_NAME]: { command: process.execPath, args: [this.config.entry], env: { ORGANIZER_URL: this.config.siteUrl, ORGANIZER_TOKEN: token } },
+            },
+        };
+        fs.writeFileSync(configFile, JSON.stringify(mcpConfig), { encoding: "utf-8", mode: 0o600 });
+        try {
+            await this.spawnClaude(space.name, configFile);
+        }
+        finally {
+            fs.rmSync(configFile, { force: true });
+            issueRunnerToken(this.store, spaceId);
+        }
+    }
+    spawnClaude(spaceName, configFile) {
+        const [command, ...fixed] = this.config.command;
+        const args = [
+            ...fixed,
+            "-p",
+            SESSION_PROMPT,
+            "--mcp-config",
+            configFile,
+            "--strict-mcp-config",
+            "--allowedTools",
+            `mcp__${MCP_SERVER_NAME}`,
+            "--disallowedTools",
+            DISALLOWED_TOOLS.join(","),
+        ];
+        const label = `Runner [${spaceName}]`;
+        this.logger.info(`${label}: session started`);
+        return new Promise((resolve) => {
+            const child = spawn(command, args, { cwd: this.config.workDir, env: sessionEnv(this.config), stdio: ["ignore", "pipe", "pipe"] });
+            this.child = child;
+            const forward = (stream) => stream?.on("data", (chunk) => {
+                for (const line of String(chunk).split(/\r?\n/))
+                    if (line.trim())
+                        this.logger.info(`${label}: ${line}`);
+            });
+            forward(child.stdout);
+            forward(child.stderr);
+            const timer = setTimeout(() => {
+                this.logger.warn(`${label}: session still running after ${SESSION_TIMEOUT_MS / 60000} min, stopped`);
+                child.kill();
+            }, SESSION_TIMEOUT_MS);
+            const done = () => {
+                clearTimeout(timer);
+                this.child = null;
+                resolve();
+            };
+            child.once("error", (err) => {
+                this.logger.error(`${label}: cannot start ${command} (${err.message}): check ORGANIZER_RUNNER_CLAUDE`);
+                done();
+            });
+            child.once("exit", (code) => {
+                this.logger.info(`${label}: session ended (exit code ${code})`);
+                done();
+            });
+        });
+    }
+}

package/dist/src/server/start.js

@@ -13,6 +13,7 @@ import { transcriberFromEnv } from "../core/transcription.js";
 import { ConfigError } from "../core/errors.js";
 import { loadSiteConfig } from "./config.js";
 import { createSiteApp } from "./app.js";
+import { SiteRunner, runnerFromEnv } from "./runner.js";
 /**
  * Mode site (`mcp-organizer --server`) : un processus web permanent qui
  * détient la base, sert la GUI et son API, et écoute sur `HOST:PORT`.
@@ -35,6 +36,10 @@ export async function runServerMode(rootDir) {
     const transcriber = transcriberFromEnv();
     if (!transcriber.enabled)
         logger.warn(transcriber.disabledReason);
+    const runner = runnerFromEnv(process.env, { host: config.host, port: config.port, rootDir, dataDir });
+    if (!runner.status.enabled)
+        logger.warn(`Runner disabled: ${runner.status.disabledReason}`);
+    const siteRunner = runner.config ? new SiteRunner(store, runner.config, createLogger("runner")) : null;
     new NotificationMailer(store, { mailer, publicUrl: config.publicUrl, logError: (message) => logger.error(message) }).attach();
     let bootstrap;
     try {
@@ -62,6 +67,7 @@ export async function runServerMode(rootDir) {
             publicUrl: config.publicUrl,
             attachments: new AttachmentStorage(dataDir),
             transcriber,
+            runner: { status: runner.status, runNow: siteRunner ? (spaceId) => siteRunner.runNow(spaceId) : null },
         },
     });
     const server = await new Promise((resolve, reject) => {
@@ -71,12 +77,14 @@ export async function runServerMode(rootDir) {
     logger.info(`mcp-organizer v${APP_VERSION} listening on http://${config.host}:${config.port}, public URL ${config.publicUrl} (data dir: ${dataDir})`);
     if (config.trustProxy)
         logger.info("ORGANIZER_TRUST_PROXY=1: the client address is read from X-Forwarded-For.");
+    siteRunner?.start();
     let shuttingDown = false;
     const shutdown = (signal) => {
         if (shuttingDown)
             return;
         shuttingDown = true;
         logger.info(`${signal} received, shutting down`);
+        siteRunner?.stop();
         server.close(() => {
             store.close();
             process.exit(0);