metheus-governance-mcp-cli 0.2.35 → 0.2.37

package/cli.mjs

@@ -3491,6 +3491,83 @@ function ensureArray(value) {
   return Array.isArray(value) ? value : [];
 }
 
+function normalizeSafeToolAliasName(rawName) {
+  const base = String(rawName || "")
+    .trim()
+    .replace(/[^a-zA-Z0-9_]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  if (!base) return "";
+  if (/^[0-9]/.test(base)) return `tool_${base}`;
+  return base;
+}
+
+function buildToolAliasMaps(tools) {
+  const canonicalNames = new Set(
+    ensureArray(tools)
+      .map((tool) => String(tool?.name || "").trim())
+      .filter(Boolean),
+  );
+  const aliasToCanonical = new Map();
+  const canonicalToAlias = new Map();
+  const reserved = new Set(canonicalNames);
+
+  for (const canonicalName of canonicalNames) {
+    const aliasBase = normalizeSafeToolAliasName(canonicalName);
+    if (!aliasBase || aliasBase === canonicalName) continue;
+    let alias = aliasBase;
+    let counter = 2;
+    while (reserved.has(alias) || aliasToCanonical.has(alias)) {
+      alias = `${aliasBase}_${counter}`;
+      counter += 1;
+    }
+    aliasToCanonical.set(alias, canonicalName);
+    canonicalToAlias.set(canonicalName, alias);
+    reserved.add(alias);
+  }
+  return { aliasToCanonical, canonicalToAlias };
+}
+
+function applyToolAliasesToToolsListResponse(responseObj, canonicalToAlias) {
+  const result = safeObject(responseObj.result);
+  const tools = ensureArray(result.tools);
+  result.tools = tools.map((tool) => {
+    const safeTool = safeObject(tool);
+    const currentName = String(safeTool.name || "").trim();
+    const aliasName = canonicalToAlias.get(currentName);
+    if (!aliasName) return safeTool;
+    return { ...safeTool, name: aliasName };
+  });
+  responseObj.result = result;
+  return responseObj;
+}
+
+function rewriteAliasedToolCallToCanonical(requestObj, aliasToCanonical) {
+  if (!isJsonRpcMethod(requestObj, "tools/call")) return requestObj;
+  const params = safeObject(requestObj.params);
+  const currentName = String(params.name ?? params.tool_name ?? params.toolName ?? "").trim();
+  if (!currentName) return requestObj;
+  const canonicalName = String(aliasToCanonical.get(currentName) || "").trim();
+  if (!canonicalName) return requestObj;
+
+  const nextParams = { ...params, name: canonicalName };
+  if (Object.prototype.hasOwnProperty.call(nextParams, "tool_name")) {
+    nextParams.tool_name = canonicalName;
+  }
+  if (Object.prototype.hasOwnProperty.call(nextParams, "toolName")) {
+    nextParams.toolName = canonicalName;
+  }
+  return { ...requestObj, params: nextParams };
+}
+
+function shouldUseSafeToolAliasesForClient(initParamsRaw) {
+  const initParams = safeObject(initParamsRaw);
+  const clientInfo = safeObject(initParams.clientInfo);
+  const name = String(clientInfo.name || "").trim().toLowerCase();
+  if (!name) return false;
+  return name.includes("cursor") || name.includes("antigravity");
+}
+
 function injectWorkspaceDirIntoToolSchemas(tools) {
   const workspaceDirProp = {
     type: "string",
@@ -4044,10 +4121,35 @@ async function runProxy(flags) {
   let lastRefreshError = "";
   let sessionWorkspaceDir = "";
   let sessionWorkspaceTrusted = false;
+  let sessionUseSafeToolAliases = false;
+  let sessionToolAliasToCanonical = new Map();
+  let sessionToolCanonicalToAlias = new Map();
 
   // Proxy-initiated requests (e.g., roots/list) pending client responses.
   const pendingProxyRequests = new Map(); // id → callback(responseObj)
   let proxyRequestIdCounter = 0;
+  let stdoutEnvelopeMode = "line"; // "line" | "framed"
+
+  function writeProxyMessage(messageText) {
+    const normalized = String(messageText || "").trim();
+    if (!normalized) return;
+    if (stdoutEnvelopeMode === "framed") {
+      const contentLength = Buffer.byteLength(normalized, "utf8");
+      process.stdout.write(`Content-Length: ${contentLength}\r\n\r\n${normalized}`);
+      return;
+    }
+    process.stdout.write(`${normalized}\n`);
+  }
+
+  function writeProxyJson(payload) {
+    writeProxyMessage(JSON.stringify(payload));
+  }
+
+  function clientSupportsRootsList(initParamsRaw) {
+    const initParams = safeObject(initParamsRaw);
+    const capabilities = safeObject(initParams.capabilities);
+    return Object.prototype.hasOwnProperty.call(capabilities, "roots");
+  }
 
   /**
    * Probe the MCP client for workspace roots via the standard roots/list request.
@@ -4093,16 +4195,16 @@ async function runProxy(flags) {
         } catch { /* best-effort */ }
       }
     }, 10000);
-    process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, method: "roots/list" })}\n`);
+    writeProxyJson({ jsonrpc: "2.0", id, method: "roots/list" });
   }
 
   const handleIncomingMessage = async (lineRaw) => {
     const line = String(lineRaw || "").trim();
     if (!line) return;
 
-    const requestObj = tryJsonParse(line);
+    let requestObj = tryJsonParse(line);
     if (requestObj == null) {
-      process.stdout.write(`${JSON.stringify(jsonRpcError(null, -32700, "parse error"))}\n`);
+      writeProxyJson(jsonRpcError(null, -32700, "parse error"));
       return;
     }
 
@@ -4141,20 +4243,25 @@ async function runProxy(flags) {
           ? `; expired token ignored: ${resolved.expired.source}${resolved.expired.expires ? ` (${resolved.expired.expires})` : ""}`
           : "";
       const refreshHint = lastRefreshError ? `; refresh failed: ${lastRefreshError}` : "";
-      process.stdout.write(
-        `${JSON.stringify(
-          jsonRpcError(
-            requestObj,
-            -32001,
-            `missing auth token (set METHEUS_TOKEN or run 'metheus-governance-mcp auth login --base-url ${normalizeSiteBaseURL(
-              args.baseURL,
-            )}'; login: ${helpURL}${expiredHint}${refreshHint})`,
-          ),
-        )}\n`,
+      writeProxyJson(
+        jsonRpcError(
+          requestObj,
+          -32001,
+          `missing auth token (set METHEUS_TOKEN or run 'metheus-governance-mcp auth login --base-url ${normalizeSiteBaseURL(
+            args.baseURL,
+          )}'; login: ${helpURL}${expiredHint}${refreshHint})`,
+        ),
       );
       return;
     }
 
+    if (isJsonRpcMethod(requestObj, "initialize") && shouldUseSafeToolAliasesForClient(requestObj?.params)) {
+      sessionUseSafeToolAliases = true;
+    }
+    if (sessionUseSafeToolAliases) {
+      requestObj = rewriteAliasedToolCallToCanonical(requestObj, sessionToolAliasToCanonical);
+    }
+
     const { name: toolName, args: toolArgs } = extractToolCall(requestObj);
     let strongRequestWorkspaceCandidate = "";
     let weakRequestWorkspaceCandidate = "";
@@ -4239,15 +4346,11 @@ async function runProxy(flags) {
         }),
       ).trim();
       if (!projectID) {
-        process.stdout.write(
-          `${JSON.stringify(jsonRpcError(requestObj, -32001, "project_id is required (or set --project-id during setup)"))}\n`,
-        );
+        writeProxyJson(jsonRpcError(requestObj, -32001, "project_id is required (or set --project-id during setup)"));
         return;
       }
       if (!isUUID(projectID)) {
-        process.stdout.write(
-          `${JSON.stringify(jsonRpcError(requestObj, -32001, "project_id must be a valid UUID"))}\n`,
-        );
+        writeProxyJson(jsonRpcError(requestObj, -32001, "project_id must be a valid UUID"));
         return;
       }
       try {
@@ -4274,23 +4377,19 @@ async function runProxy(flags) {
           workspaceSignalTrusted,
         });
         const text = buildProjectSummaryText(summary);
-        process.stdout.write(
-          `${JSON.stringify(
-            jsonRpcResult(requestObj, {
-              content: [
-                {
-                  type: "text",
-                  text,
-                },
-              ],
-              structuredContent: summary,
-            }),
-          )}\n`,
+        writeProxyJson(
+          jsonRpcResult(requestObj, {
+            content: [
+              {
+                type: "text",
+                text,
+              },
+            ],
+            structuredContent: summary,
+          }),
         );
       } catch (err) {
-        process.stdout.write(
-          `${JSON.stringify(jsonRpcError(requestObj, -32001, String(err?.message || err)))}\n`,
-        );
+        writeProxyJson(jsonRpcError(requestObj, -32001, String(err?.message || err)));
       }
       return;
     }
@@ -4303,15 +4402,11 @@ async function runProxy(flags) {
         }),
       ).trim();
       if (!projectID) {
-        process.stdout.write(
-          `${JSON.stringify(jsonRpcError(requestObj, -32001, "project_id is required (or set --project-id during setup)"))}\n`,
-        );
+        writeProxyJson(jsonRpcError(requestObj, -32001, "project_id is required (or set --project-id during setup)"));
         return;
       }
       if (!isUUID(projectID)) {
-        process.stdout.write(
-          `${JSON.stringify(jsonRpcError(requestObj, -32001, "project_id must be a valid UUID"))}\n`,
-        );
+        writeProxyJson(jsonRpcError(requestObj, -32001, "project_id must be a valid UUID"));
         return;
       }
 
@@ -4320,14 +4415,12 @@ async function runProxy(flags) {
           const statusRaw = String(toolArgs.status || "").trim().toLowerCase();
           const statusFilter = normalizeMergeStatusFilter(statusRaw);
           if (statusRaw && !statusFilter) {
-            process.stdout.write(
-              `${JSON.stringify(
-                jsonRpcError(
-                  requestObj,
-                  -32001,
-                  "status must be one of: open, review, approved, rejected, merged, closed, all",
-                ),
-              )}\n`,
+            writeProxyJson(
+              jsonRpcError(
+                requestObj,
+                -32001,
+                "status must be one of: open, review, approved, rejected, merged, closed, all",
+              ),
             );
             return;
           }
@@ -4342,13 +4435,11 @@ async function runProxy(flags) {
             workspaceDir: requestWorkspaceDir,
           });
           const text = buildCtxpackMergeBriefText(brief);
-          process.stdout.write(
-            `${JSON.stringify(
-              jsonRpcResult(requestObj, {
-                content: [{ type: "text", text }],
-                structuredContent: brief,
-              }),
-            )}\n`,
+          writeProxyJson(
+            jsonRpcResult(requestObj, {
+              content: [{ type: "text", text }],
+              structuredContent: brief,
+            }),
           );
           return;
         }
@@ -4360,16 +4451,12 @@ async function runProxy(flags) {
             toolArgs.owner_confirmation || toolArgs.ownerConfirmation || "",
           ).trim();
           if (!mergeRequestID || !isUUID(mergeRequestID)) {
-            process.stdout.write(
-              `${JSON.stringify(jsonRpcError(requestObj, -32001, "merge_request_id must be a valid UUID"))}\n`,
-            );
+            writeProxyJson(jsonRpcError(requestObj, -32001, "merge_request_id must be a valid UUID"));
             return;
           }
           if (!action) {
-            process.stdout.write(
-              `${JSON.stringify(
-                jsonRpcError(requestObj, -32001, "action must be one of: review, approve, reject, close, merge"),
-              )}\n`,
+            writeProxyJson(
+              jsonRpcError(requestObj, -32001, "action must be one of: review, approve, reject, close, merge"),
             );
             return;
           }
@@ -4384,20 +4471,16 @@ async function runProxy(flags) {
             workspaceDir: requestWorkspaceDir,
           });
           const text = buildCtxpackMergeExecuteText(result);
-          process.stdout.write(
-            `${JSON.stringify(
-              jsonRpcResult(requestObj, {
-                content: [{ type: "text", text }],
-                structuredContent: result,
-              }),
-            )}\n`,
+          writeProxyJson(
+            jsonRpcResult(requestObj, {
+              content: [{ type: "text", text }],
+              structuredContent: result,
+            }),
           );
           return;
         }
       } catch (err) {
-        process.stdout.write(
-          `${JSON.stringify(jsonRpcError(requestObj, -32001, String(err?.message || err)))}\n`,
-        );
+        writeProxyJson(jsonRpcError(requestObj, -32001, String(err?.message || err)));
         return;
       }
     }
@@ -4429,11 +4512,18 @@ async function runProxy(flags) {
               requestWorkspaceDir,
               workspaceSignalTrusted,
             );
-            process.stdout.write(`${JSON.stringify(patched)}\n`);
+            writeProxyJson(patched);
             return;
           }
           if (isJsonRpcMethod(requestObj, "tools/list")) {
             patched = appendLocalToolToToolsList(patched);
+            if (sessionUseSafeToolAliases) {
+              const tools = ensureArray(safeObject(patched.result).tools);
+              const aliasMaps = buildToolAliasMaps(tools);
+              sessionToolAliasToCanonical = aliasMaps.aliasToCanonical;
+              sessionToolCanonicalToAlias = aliasMaps.canonicalToAlias;
+              patched = applyToolAliasesToToolsListResponse(patched, sessionToolCanonicalToAlias);
+            }
           } else if (isJsonRpcMethod(requestObj, "initialize")) {
             patched = appendProjectHintToInitialize(patched, args);
             // Log initialize params for workspace debugging.
@@ -4445,10 +4535,12 @@ async function runProxy(flags) {
                 `[${new Date().toISOString()}] initialize: clientInfo=${JSON.stringify(initParams.clientInfo || {})} capabilities=${JSON.stringify(initParams.capabilities || {})} rootUri=${initParams.rootUri || "(none)"} workspaceFolders=${JSON.stringify(initParams.workspaceFolders || []).substring(0, 300)}\n`,
               );
             } catch { /* best-effort */ }
-            // Probe client workspace roots via MCP roots/list protocol.
-            // Use setImmediate so the initialize response is flushed to stdout first;
-            // the client must see the response before it can handle server-initiated requests.
-            setImmediate(() => sendRootsListProbe());
+            // Probe roots/list only when client advertised roots capability.
+            // Some MCP clients reject unsolicited server requests and then hide tools.
+            if (clientSupportsRootsList(requestObj?.params)) {
+              // Use setImmediate so the initialize response is flushed first.
+              setImmediate(() => sendRootsListProbe());
+            }
           } else if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "workitem.list") {
             patched = await appendWorkitemListHints(patched, args, toolArgs, token, workspaceSignalTrusted);
           } else if (isJsonRpcMethod(requestObj, "tools/call") && toolName === "ctxpack.ensure") {
@@ -4463,21 +4555,17 @@ async function runProxy(flags) {
           if (autoSyncSummary) {
             patched = appendAutoCtxpackSyncHint(patched, autoSyncSummary);
           }
-          process.stdout.write(`${JSON.stringify(patched)}\n`);
+          writeProxyJson(patched);
           return;
         }
-        process.stdout.write(`${responseText}\n`);
+        writeProxyMessage(responseText);
         return;
       }
       if (Object.prototype.hasOwnProperty.call(requestObj, "id")) {
-        process.stdout.write(
-          `${JSON.stringify(jsonRpcError(requestObj, -32001, "empty gateway response"))}\n`,
-        );
+        writeProxyJson(jsonRpcError(requestObj, -32001, "empty gateway response"));
       }
     } catch (err) {
-      process.stdout.write(
-        `${JSON.stringify(jsonRpcError(requestObj, -32001, String(err?.message || err)))}\n`,
-      );
+      writeProxyJson(jsonRpcError(requestObj, -32001, String(err?.message || err)));
     }
   };
 
@@ -4576,6 +4664,7 @@ async function runProxy(flags) {
       if (pendingInputBuffer.length === 0) break;
 
       if (startsWithContentLengthHeader(pendingInputBuffer)) {
+        stdoutEnvelopeMode = "framed";
         const framed = extractFramedMessage(pendingInputBuffer);
         if (!framed) break;
         pendingInputBuffer = framed.remaining;

package/package.json

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