metheus-governance-mcp-cli 0.2.49 → 0.2.51

package/README.md

@@ -24,21 +24,19 @@ Install creates a local Telegram settings template here:
 
 - `~/.metheus/telegram.env`
 
-This file is for local bot secrets only.
+This file is for the local Telegram bot secret only.
 
 - Store locally:
   - `TELEGRAM_BOT_TOKEN`
 - Server-side Metheus stores project Telegram destination metadata separately:
   - `chat_id`
   - label / active state
+- Do not put project `chat_id` in the local Telegram env file.
 
 Example template:
 
 ```env
 TELEGRAM_BOT_TOKEN=
-TELEGRAM_DEFAULT_CHAT_ID=
-TELEGRAM_ALLOWED_CHAT_IDS=
-TELEGRAM_DEFAULT_PARSE_MODE=
 ```
 
 ## One command bootstrap (recommended)
@@ -75,7 +73,7 @@ metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctx
 
 - `~/.metheus/telegram.env`
 
-Fill only the bot token locally. Project Telegram `chat_id` destinations should be managed on the Metheus server.
+Fill only the bot token locally. Project Telegram `chat_id` destinations should be managed on the Metheus server as project Telegram destinations, not as local env values and not inside Chat Hooks.
 
 Gemini CLI note:
 - `gemini mcp` commands require Gemini auth to be configured first (`GEMINI_API_KEY` or `~/.gemini/settings.json` auth).
@@ -107,13 +105,19 @@ metheus-governance-mcp-cli doctor --project-id <project_uuid> --base-url https:/
 
 Checks:
 - auth token status (+ auto refresh attempt)
-- local Telegram env template presence
+- local Telegram env token presence
 - codex/claude/gemini/antigravity/cursor registration state
 - gateway `tools/list` reachability
 - `project.summary` access
 - ctxpack auto sync status
 - smoke calls: `workitem.list`, `evidence.list`, `decision.list`
 
+Direct bot posting:
+- `me.send-bot-message` uses the local `TELEGRAM_BOT_TOKEN` from `~/.metheus/telegram.env`
+- it does not use a server-stored bot token
+- the destination `chat_id` is resolved from the current project's saved Chat Destinations on the Metheus server
+- if multiple active Telegram destinations exist for the project, pass `destination_id` or `destination_label`
+
 ## Use in MCP
 
 `setup` auto-registers this server for `codex`, `claude`, `gemini`, `antigravity`, and `cursor` when those CLIs are available.

package/cli.mjs

@@ -487,15 +487,10 @@ function telegramEnvTemplate() {
   return [
     "# Metheus local Telegram bot settings",
     "# Keep this file on your machine only. Do not commit it.",
-    "# Server-side project Telegram destinations store chat_id metadata separately.",
+    "# Store only the Telegram bot token locally.",
+    "# Project chat_id must be managed on the Metheus server as a project Telegram destination.",
     "",
     "TELEGRAM_BOT_TOKEN=",
-    "# Optional local default for quick tests. Project chat_id is normally resolved from Metheus server.",
-    "TELEGRAM_DEFAULT_CHAT_ID=",
-    "# Optional CSV allowlist to avoid accidental sends to the wrong chats.",
-    "TELEGRAM_ALLOWED_CHAT_IDS=",
-    "# Optional parse mode: Markdown, MarkdownV2, HTML",
-    "TELEGRAM_DEFAULT_PARSE_MODE=",
     "",
   ].join("\n");
 }
@@ -514,6 +509,66 @@ function ensureTelegramEnvTemplate() {
   }
 }
 
+function parseSimpleEnvText(rawText) {
+  const out = {};
+  const lines = String(rawText || "").split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = String(rawLine || "").trim();
+    if (!line || line.startsWith("#")) continue;
+    const eqIndex = line.indexOf("=");
+    if (eqIndex <= 0) continue;
+    const key = String(line.slice(0, eqIndex) || "").trim();
+    if (!key) continue;
+    let value = String(line.slice(eqIndex + 1) || "").trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"'))
+      || (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+function loadTelegramEnvConfig() {
+  const ensured = ensureTelegramEnvTemplate();
+  const filePath = ensured.filePath;
+  if (ensured.error) {
+    return {
+      ok: false,
+      filePath,
+      error: ensured.error,
+      token: "",
+    };
+  }
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = parseSimpleEnvText(raw);
+    const token = String(parsed.TELEGRAM_BOT_TOKEN || "").trim();
+    if (!token) {
+      return {
+        ok: false,
+        filePath,
+        error: `TELEGRAM_BOT_TOKEN is missing in ${filePath}`,
+        token: "",
+      };
+    }
+    return {
+      ok: true,
+      filePath,
+      token,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      filePath,
+      error: String(err?.message || err),
+      token: "",
+    };
+  }
+}
+
 function resolveWorkspaceDir(rawPath) {
   const input = String(rawPath || "").trim();
   if (input) {
@@ -2145,16 +2200,28 @@ async function runDoctor(flags) {
   });
   const rows = [];
 
-  const telegramEnv = ensureTelegramEnvTemplate();
-  if (telegramEnv.error) {
-    addDoctorCheck(rows, "warn", "local telegram env", `unavailable (${telegramEnv.error})`);
+  const telegramEnv = loadTelegramEnvConfig();
+  if (!telegramEnv.ok) {
+    addDoctorCheck(rows, "warn", "local telegram env", `${telegramEnv.error} (${telegramEnv.filePath})`);
   } else {
-    addDoctorCheck(
-      rows,
-      telegramEnv.created ? "warn" : "ok",
-      "local telegram env",
-      `${telegramEnv.created ? "created template" : "ready"} (${telegramEnv.filePath})`,
-    );
+    addDoctorCheck(rows, "ok", "local telegram env", `token configured (${telegramEnv.filePath})`);
+    try {
+      const me = safeObject(
+        await getJSONWithoutAuth(`https://api.telegram.org/bot${telegramEnv.token}/getMe`, timeoutSeconds),
+      );
+      if (Boolean(me.ok) && safeObject(me.result).id) {
+        addDoctorCheck(
+          rows,
+          "ok",
+          "local telegram bot",
+          `reachable as @${String(safeObject(me.result).username || "").trim() || "-"}`,
+        );
+      } else {
+        addDoctorCheck(rows, "warn", "local telegram bot", "getMe returned an unexpected payload");
+      }
+    } catch (err) {
+      addDoctorCheck(rows, "warn", "local telegram bot", String(err?.message || err));
+    }
   }
 
   const resolved = await resolveAccessTokenForCommand(context.baseURL, timeoutSeconds);
@@ -2571,6 +2638,92 @@ function getJSONWithAuth(urlText, timeoutSeconds, token) {
   });
 }
 
+function getJSONWithoutAuth(urlText, timeoutSeconds) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlText);
+    const transport = url.protocol === "http:" ? http : https;
+    const req = transport.request(
+      {
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || (url.protocol === "http:" ? 80 : 443),
+        path: `${url.pathname}${url.search}`,
+        method: "GET",
+        headers: {
+          accept: "application/json",
+        },
+        timeout: Math.max(3, timeoutSeconds) * 1000,
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        res.on("end", () => {
+          const text = Buffer.concat(chunks).toString("utf8");
+          const statusCode = Number(res.statusCode || 0);
+          if (statusCode >= 200 && statusCode < 300) {
+            try {
+              resolve(JSON.parse(text));
+            } catch {
+              reject(new Error("invalid json response"));
+            }
+            return;
+          }
+          const err = new Error(text.trim() || `http ${statusCode}`);
+          err.statusCode = statusCode;
+          err.responseBody = text;
+          reject(err);
+        });
+      },
+    );
+    req.on("timeout", () => {
+      req.destroy(new Error("http timeout"));
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+function postJSONWithoutAuth(urlText, timeoutSeconds, payload, extraHeaders = {}) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlText);
+    const body = Buffer.from(JSON.stringify(payload));
+    const transport = url.protocol === "http:" ? http : https;
+    const req = transport.request(
+      {
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || (url.protocol === "http:" ? 80 : 443),
+        path: `${url.pathname}${url.search}`,
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json",
+          "content-length": String(body.length),
+          ...extraHeaders,
+        },
+        timeout: Math.max(3, timeoutSeconds) * 1000,
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        res.on("end", () => {
+          const text = Buffer.concat(chunks).toString("utf8");
+          resolve({
+            statusCode: Number(res.statusCode || 0),
+            bodyText: text,
+          });
+        });
+      },
+    );
+    req.on("timeout", () => {
+      req.destroy(new Error("http timeout"));
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
 function safeObject(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return {};
   return value;
@@ -3797,7 +3950,9 @@ function appendLocalToolToToolsList(responseObj) {
   const tools = ensureArray(result.tools);
   const localSpecs = buildLocalToolSpecs();
   const localNames = new Set(localSpecs.map((spec) => spec.name));
-  const filtered = tools.filter((tool) => !localNames.has(String(tool?.name || "").trim()));
+  const filtered = patchServerToolSpecsForLocalRouting(
+    tools.filter((tool) => !localNames.has(String(tool?.name || "").trim())),
+  );
   result.tools = injectWorkspaceDirIntoToolSchemas([...localSpecs, ...filtered]);
   responseObj.result = result;
   return responseObj;
@@ -3812,6 +3967,8 @@ function appendProjectHintToInitialize(responseObj, args, options = {}) {
   const ctxpackEnsureTool = displayToolNameForClient("ctxpack.ensure", useSafeToolAliases);
   const ctxpackMergeBriefTool = displayToolNameForClient("ctxpack.merge.brief", useSafeToolAliases);
   const ctxpackMergeExecuteTool = displayToolNameForClient("ctxpack.merge.execute", useSafeToolAliases);
+  const meListBotsTool = displayToolNameForClient("me.list-bots", useSafeToolAliases);
+  const meSendBotMessageTool = displayToolNameForClient("me.send-bot-message", useSafeToolAliases);
   const hintLines = [
     "High-priority project bootstrap rule:",
     ...(useSafeToolAliases
@@ -3825,6 +3982,7 @@ function appendProjectHintToInitialize(responseObj, args, options = {}) {
     `- Never handle a bare Project ID by local file/transcript search before \`${projectSummaryTool}\` succeeds.`,
     `- Run \`${ctxpackEnsureTool}\` only after \`${projectSummaryTool}\`, and only when additional ctxpack refresh/export context is needed.`,
     "- After project summary, use workitem/evidence/decision tools as follow-up.",
+    `- For direct bot posting, call \`${meListBotsTool}\` first, then use \`${meSendBotMessageTool}\`. The proxy delivers with your local provider token config and the current project's saved chat destination.`,
     `- Before any ctxpack merge, call \`${ctxpackMergeBriefTool}\` first, share recommendation to owner, get explicit owner confirmation, then call \`${ctxpackMergeExecuteTool}\`.`,
     "- IMPORTANT: When calling ANY tool, always include your current working directory / project folder path as the `workspace_dir` argument. This enables ctxpack files to be synced to the correct workspace location.",
   ];
@@ -3844,6 +4002,233 @@ function appendProjectHintToInitialize(responseObj, args, options = {}) {
   return responseObj;
 }
 
+function patchServerToolSpecsForLocalRouting(tools) {
+  return ensureArray(tools).map((tool) => {
+    const safeTool = safeObject(tool);
+    const name = String(safeTool.name || "").trim();
+    if (name !== "me.send-bot-message") return safeTool;
+    const inputSchema = {
+      ...safeObject(safeTool.inputSchema),
+      properties: {
+        ...safeObject(safeTool.inputSchema?.properties),
+        project_id: {
+          type: "string",
+          description: "Optional project UUID. Defaults to the current configured project scope.",
+        },
+        destination_id: {
+          type: "string",
+          description: "Optional project chat destination UUID when a project has multiple active destinations.",
+        },
+        destination_label: {
+          type: "string",
+          description: "Optional project chat destination label when a project has multiple active destinations.",
+        },
+      },
+    };
+    return {
+      ...safeTool,
+      description:
+        "Send a direct message through one bot profile using your local provider token config and the current project's saved chat destination. Call me.list-bots first to choose the correct bot_id.",
+      inputSchema,
+    };
+  });
+}
+
+function sanitizeTelegramAPIURL(rawURL) {
+  const text = String(rawURL || "").trim();
+  if (!text) return "";
+  return text.replace(/\/bot[^/]+/i, "/bot<redacted>");
+}
+
+function parseJSONText(rawText) {
+  try {
+    return JSON.parse(String(rawText || ""));
+  } catch {
+    return null;
+  }
+}
+
+function buildLocalToolJSONEnvelope(toolName, payload) {
+  const envelope = {
+    tool: String(toolName || "").trim(),
+    ...safeObject(payload),
+  };
+  return JSON.stringify(envelope, null, 2);
+}
+
+function buildLocalToolRPCResult(toolName, payload) {
+  const structuredContent = {
+    tool: String(toolName || "").trim(),
+    ...safeObject(payload),
+  };
+  return {
+    content: [
+      {
+        type: "text",
+        text: buildLocalToolJSONEnvelope(toolName, payload),
+      },
+    ],
+    structuredContent,
+  };
+}
+
+function normalizeChatDestination(record) {
+  const item = safeObject(record);
+  return {
+    id: String(item.id || "").trim(),
+    provider: String(item.provider || "").trim().toLowerCase(),
+    label: String(item.label || "").trim(),
+    chatID: String(item.chat_id || item.chatId || "").trim(),
+    isActive: item.is_active !== false && item.isActive !== false,
+  };
+}
+
+function selectProjectChatDestination(destinations, selectors = {}) {
+  const list = ensureArray(destinations)
+    .map(normalizeChatDestination)
+    .filter((item) => item.provider === "telegram" && item.chatID && item.isActive);
+  const destinationID = String(selectors.destinationID || "").trim();
+  const destinationLabel = String(selectors.destinationLabel || "").trim().toLowerCase();
+
+  if (destinationID) {
+    const match = list.find((item) => item.id === destinationID);
+    if (!match) {
+      throw new Error(`project chat destination ${destinationID} was not found or is inactive`);
+    }
+    return match;
+  }
+  if (destinationLabel) {
+    const match = list.find((item) => item.label.toLowerCase() === destinationLabel);
+    if (!match) {
+      throw new Error(`project chat destination label "${selectors.destinationLabel}" was not found or is inactive`);
+    }
+    return match;
+  }
+  if (list.length === 1) {
+    return list[0];
+  }
+  if (list.length === 0) {
+    throw new Error("no active Telegram chat destination is configured for this project");
+  }
+  const labels = list.map((item) => item.label || item.id).filter(Boolean);
+  throw new Error(
+    `multiple active Telegram chat destinations exist for this project; pass destination_id or destination_label (${labels.join(", ")})`,
+  );
+}
+
+async function handleLocalBotMessageToolCall({
+  requestObj,
+  toolArgs,
+  args,
+  token,
+  workspaceDir,
+}) {
+  const botID = String(toolArgs.bot_id || toolArgs.botId || "").trim();
+  const text = String(toolArgs.text || "").trim();
+  const destinationID = String(toolArgs.destination_id || toolArgs.destinationId || "").trim();
+  const destinationLabel = String(toolArgs.destination_label || toolArgs.destinationLabel || "").trim();
+  const projectID = String(
+    resolveProjectIDForRequest({
+      toolArgs,
+      args,
+      workspaceDir,
+    }),
+  ).trim();
+
+  if (!botID) {
+    throw new Error("bot_id is required");
+  }
+  if (!text) {
+    throw new Error("text is required");
+  }
+  if (!projectID || !isUUID(projectID)) {
+    throw new Error("project_id is required for local bot delivery; set --project-id during setup or include project_id");
+  }
+
+  const telegramEnv = loadTelegramEnvConfig();
+  if (!telegramEnv.ok) {
+    throw new Error(`local telegram env is not ready (${telegramEnv.error})`);
+  }
+
+  const siteBaseURL = normalizeSiteBaseURL(args.baseURL);
+  const encodedBotID = encodeURIComponent(botID);
+  const encodedProjectID = encodeURIComponent(projectID);
+  const botURL = `${siteBaseURL}/api/v1/me/bots/${encodedBotID}`;
+  const destinationURL = `${siteBaseURL}/api/v1/projects/${encodedProjectID}/chat-destinations`;
+
+  const bot = safeObject(await getJSONWithAuth(botURL, args.timeoutSeconds, token));
+  if (!String(bot.id || "").trim()) {
+    throw new Error("bot not found");
+  }
+  if (bot.is_active === false || bot.isActive === false) {
+    throw new Error("bot is inactive");
+  }
+
+  const destinations = ensureArray(await getJSONWithAuth(destinationURL, args.timeoutSeconds, token));
+  const destination = selectProjectChatDestination(destinations, {
+    destinationID,
+    destinationLabel,
+  });
+
+  const disableWebPagePreview = boolFromRaw(
+    Object.prototype.hasOwnProperty.call(toolArgs, "disable_web_page_preview")
+      ? toolArgs.disable_web_page_preview
+      : toolArgs.disableWebPagePreview,
+    true,
+  );
+  const replyToMessageIDRaw = toolArgs.reply_to_message_id ?? toolArgs.replyToMessageID;
+  const replyToMessageID =
+    replyToMessageIDRaw == null || String(replyToMessageIDRaw).trim() === ""
+      ? 0
+      : Number.parseInt(String(replyToMessageIDRaw), 10);
+  if (replyToMessageIDRaw != null && (!Number.isFinite(replyToMessageID) || replyToMessageID <= 0)) {
+    throw new Error("reply_to_message_id must be a positive integer");
+  }
+
+  const telegramURL = `https://api.telegram.org/bot${telegramEnv.token}/sendMessage`;
+  const telegramPayload = {
+    chat_id: destination.chatID,
+    text,
+    disable_web_page_preview: disableWebPagePreview,
+  };
+  if (replyToMessageID > 0) {
+    telegramPayload.reply_to_message_id = replyToMessageID;
+  }
+
+  const response = await postJSONWithoutAuth(telegramURL, args.timeoutSeconds, telegramPayload);
+  const responseJSON = parseJSONText(response.bodyText);
+  const deliveryOK = response.statusCode >= 200 && response.statusCode < 300 && Boolean(responseJSON?.ok ?? true);
+  if (!deliveryOK) {
+    const errorDetail =
+      String(responseJSON?.description || response.bodyText || "").trim() || `telegram api status ${response.statusCode}`;
+    if (response.statusCode === 401 || /unauthorized/i.test(errorDetail)) {
+      throw new Error(
+        `local telegram delivery failed (Unauthorized). Check TELEGRAM_BOT_TOKEN in ${telegramEnv.filePath}`,
+      );
+    }
+    throw new Error(`local telegram delivery failed (${errorDetail})`);
+  }
+
+  return jsonRpcResult(
+    requestObj,
+    buildLocalToolRPCResult("me.send-bot-message", {
+      ok: true,
+      local_delivery: true,
+      provider: "telegram",
+      bot_id: String(bot.id || botID).trim(),
+      bot_name: String(bot.name || "").trim(),
+      bot_role: String(bot.bot_role || bot.botRole || "").trim(),
+      project_id: projectID,
+      destination_id: destination.id,
+      destination_label: destination.label,
+      chat_id: destination.chatID,
+      status: response.statusCode,
+      url: sanitizeTelegramAPIURL(telegramURL),
+      body: responseJSON || response.bodyText,
+    }),
+  );
+}
+
 async function maybeAutoSyncCtxpackForCall({
   requestObj,
   toolName,
@@ -4746,6 +5131,21 @@ async function runProxy(flags) {
         return;
       }
     }
+    if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "me.send-bot-message") {
+      try {
+        const localSendResult = await handleLocalBotMessageToolCall({
+          requestObj,
+          toolArgs,
+          args,
+          token,
+          workspaceDir: requestWorkspaceDir,
+        });
+        writeProxyJson(localSendResult);
+      } catch (err) {
+        writeProxyJson(jsonRpcError(requestObj, -32001, String(err?.message || err)));
+      }
+      return;
+    }
 
     try {
       const requestWithDefaults = injectCtxpackPushDefaults(requestObj, toolName, requestWorkspaceDir);
@@ -5379,6 +5779,47 @@ function runSelftest(flags = {}) {
   const checks = [];
   const push = (name, ok, detail = "") => checks.push({ name, ok: Boolean(ok), detail: String(detail || "") });
 
+  const parsedEnv = parseSimpleEnvText("\n# comment\nTELEGRAM_BOT_TOKEN=\"abc:123\"\nEMPTY=\n");
+  push(
+    "telegram_env_parse_token",
+    String(parsedEnv.TELEGRAM_BOT_TOKEN || "") === "abc:123",
+    `token=${String(parsedEnv.TELEGRAM_BOT_TOKEN || "(missing)")}`,
+  );
+
+  try {
+    const selected = selectProjectChatDestination(
+      [
+        { id: "dest-1", provider: "telegram", label: "Main Room", chat_id: "-1001", is_active: true },
+        { id: "dest-2", provider: "slack", label: "Slack", chat_id: "C123", is_active: true },
+      ],
+      {},
+    );
+    push(
+      "telegram_destination_select_single_active",
+      selected.id === "dest-1" && selected.chatID === "-1001",
+      `selected=${selected.id || "(none)"}`,
+    );
+  } catch (err) {
+    push("telegram_destination_select_single_active", false, String(err?.message || err));
+  }
+
+  try {
+    selectProjectChatDestination(
+      [
+        { id: "dest-1", provider: "telegram", label: "Room A", chat_id: "-1001", is_active: true },
+        { id: "dest-2", provider: "telegram", label: "Room B", chat_id: "-1002", is_active: true },
+      ],
+      {},
+    );
+    push("telegram_destination_multi_requires_selector", false, "selection unexpectedly succeeded");
+  } catch (err) {
+    push(
+      "telegram_destination_multi_requires_selector",
+      String(err?.message || "").includes("multiple active Telegram chat destinations"),
+      String(err?.message || err),
+    );
+  }
+
   const aliasMaps = buildToolAliasMaps([
     { name: "project.summary" },
     { name: "ctxpack.merge.brief" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.49",
+  "version": "0.2.51",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [

package/postinstall.mjs

@@ -16,15 +16,10 @@ function template() {
   return [
     "# Metheus local Telegram bot settings",
     "# Keep this file on your machine only. Do not commit it.",
-    "# Server-side project Telegram destinations store chat_id metadata separately.",
+    "# Store only the Telegram bot token locally.",
+    "# Project chat_id must be managed on the Metheus server as a project Telegram destination.",
     "",
     "TELEGRAM_BOT_TOKEN=",
-    "# Optional local default for quick tests. Project chat_id is normally resolved from Metheus server.",
-    "TELEGRAM_DEFAULT_CHAT_ID=",
-    "# Optional CSV allowlist to avoid accidental sends to the wrong chats.",
-    "TELEGRAM_ALLOWED_CHAT_IDS=",
-    "# Optional parse mode: Markdown, MarkdownV2, HTML",
-    "TELEGRAM_DEFAULT_PARSE_MODE=",
     "",
   ].join("\n");
 }