biaws-mcp 0.3.0 → 0.5.0

package/README.md

@@ -66,13 +66,13 @@ O pacote público expõe o executável `biaws-mcp`. Clientes configurados pelo C
 usam uma versão fixada por meio do cache local do npm:
 
 ```bash
-npx --yes biaws-mcp@0.3.0
+npx --yes biaws-mcp@0.5.0
 ```
 
 Também é possível instalá-lo explicitamente:
 
 ```bash
-npm install --global biaws-mcp@0.3.0
+npm install --global biaws-mcp@0.5.0
 biaws-mcp
 ```
 
@@ -91,7 +91,7 @@ npm start
 Em um cliente MCP, configure o comando:
 
 ```bash
-npx --yes biaws-mcp@0.3.0
+npx --yes biaws-mcp@0.5.0
 ```
 
 O fluxo recomendado é gerar a configuração completa com:
@@ -105,6 +105,36 @@ node /caminho/para/biaws/biaws-cli/src/index.js \
 O processo de publicação e rollback está em
 [`docs/releasing.md`](docs/releasing.md).
 
+## Diagnóstico do transporte
+
+A partir da versão 0.5.0, o processo escreve um evento JSON por linha em
+`stderr`. O `stdout` permanece exclusivo para frames JSON-RPC do MCP. Cada
+execução recebe um `executionId` e cada chamada de tool recebe um `requestId`,
+permitindo correlacionar ciclo de vida, duração, tentativas HTTP, cancelamento e
+falhas de processo sem registrar argumentos, respostas ou credenciais.
+
+Os eventos principais são:
+
+- `mcp_server_started`, `mcp_shutdown_requested` e `mcp_server_stopped`;
+- `mcp_tool_call_started`, `mcp_tool_call_completed`,
+  `mcp_tool_call_failed` e `mcp_tool_call_cancelled`;
+- `mcp_http_attempt_completed`, `mcp_http_attempt_failed` e
+  `mcp_http_retry_scheduled`;
+- `mcp_input_error`, `mcp_stdout_error`, `mcp_uncaught_exception` e
+  `mcp_unhandled_rejection`.
+
+`BIAWS_MCP_LOG_LEVEL` aceita `debug`, `info`, `warn` ou `error` e usa `info` por
+padrão. O nível `debug` também registra o início de cada tentativa HTTP. O MCP
+seleciona somente origem, método, status, duração e dados de correlação; URLs
+completas, query strings, headers, argumentos, payloads e valores de ambiente
+não são emitidos.
+
+Para investigar `Transport closed`, preserve o `stderr` do processo configurado
+pelo cliente MCP e procure, usando o mesmo `executionId`, por
+`mcp_stdout_error`, eventos fatais, sinais ou encerramentos sem
+`mcp_server_stopped`. Um `mcp_tool_call_failed` com resposta MCP válida indica
+falha funcional ou da API, não fechamento do transporte.
+
 ## Ferramentas
 
 ### Catálogo e contexto de aplicações
@@ -213,6 +243,10 @@ conhecimento.
 - `issues_search`: busca issues com os mesmos filtros principais da
   `biaws-api`, inclusive por workspace, aplicação e componente afetado.
 - `issues_get`: obtém uma issue com comentários e metadados dos anexos.
+- `issues_add_comment`: adiciona um comentário em Markdown a uma issue
+  existente; a autoria é atribuída pela identidade autenticada na API.
+- `issues_update_comment`: atualiza o conteúdo e, opcionalmente, a data de um
+  comentário existente, preservando sua autoria original.
 - `issues_get_classification_catalog`: obtém a árvore taxonômica e os grupos de tags válidos; opcionalmente inclui listas achatadas de IDs e caminhos.
 - `issues_create_taxonomy_item`: inclui um item na raiz ou sob outro item,
   opcionalmente configurando seu escopo por aplicações.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "biaws-mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Servidor MCP de domínio para o Bondia Workspaces",
   "license": "Apache-2.0",
   "repository": {

package/src/domains/issues/service.js

@@ -130,6 +130,34 @@ export async function getIssueDetails(args = {}) {
   return fetchJson(`/api/issues/${encodeURIComponent(args.issueId)}`);
 }
 
+export async function addIssueComment(args = {}) {
+  const issueId = String(args.issueId || "").trim();
+  const text = String(args.text || "").trim();
+  if (!issueId) throw new Error("issueId is required");
+  if (!text) throw new Error("text is required");
+
+  return sendJson(
+    `/api/issues/${encodeURIComponent(issueId)}/comments`,
+    cleanParams({ text, date: args.date }),
+    {},
+    "POST",
+  );
+}
+
+export async function updateIssueComment(args = {}) {
+  const issueId = String(args.issueId || "").trim();
+  const commentId = String(args.commentId || "").trim();
+  const text = String(args.text || "").trim();
+  if (!issueId) throw new Error("issueId is required");
+  if (!commentId) throw new Error("commentId is required");
+  if (!text) throw new Error("text is required");
+
+  return sendJson(
+    `/api/issues/${encodeURIComponent(issueId)}/comments/${encodeURIComponent(commentId)}`,
+    cleanParams({ text, date: args.date }),
+  );
+}
+
 export async function getIssueClassificationCatalog(args = {}) {
   const payload = await fetchJson(
     "/api/issues/taxonomy",

package/src/httpClient.js

@@ -1,4 +1,7 @@
-import { currentRequestSignal } from "./requestContext.js";
+import {
+  currentRequestContext,
+  currentRequestSignal,
+} from "./requestContext.js";
 import { setTimeout as delay } from "node:timers/promises";
 
 const DEFAULT_TIMEOUT_MS = 15_000;
@@ -145,9 +148,10 @@ function attachmentSizeError(maxBytes, actualBytes) {
   return error;
 }
 
-function createRequestContext(path, params, maxRetries) {
+function createRequestContext(path, params, maxRetries, method) {
   const url = buildUrl(path, params);
   const externalSignal = currentRequestSignal();
+  const mcpContext = currentRequestContext();
   const timeoutSignal = AbortSignal.timeout(readTimeoutMs());
   return {
     url,
@@ -156,6 +160,10 @@ function createRequestContext(path, params, maxRetries) {
       ? AbortSignal.any([externalSignal, timeoutSignal])
       : timeoutSignal,
     maxRetries,
+    method: method || "GET",
+    logger: mcpContext?.logger,
+    requestId: mcpContext?.requestId,
+    tool: mcpContext?.tool,
   };
 }
 
@@ -174,8 +182,17 @@ function shouldRetryRequest(error, attempt, context) {
 }
 
 async function waitBeforeRetry(attempt, context) {
+  const backoffMs = 100 * 2 ** attempt;
+  context.logger?.warn("mcp_http_retry_scheduled", {
+    requestId: context.requestId,
+    tool: context.tool,
+    method: context.method,
+    origin: context.url.origin,
+    nextAttempt: attempt + 2,
+    backoffMs,
+  });
   try {
-    await delay(100 * 2 ** attempt, undefined, { signal: context.signal });
+    await delay(backoffMs, undefined, { signal: context.signal });
   } catch (error) {
     throw transportError(error, context.url, context.externalSignal);
   }
@@ -183,11 +200,40 @@ async function waitBeforeRetry(attempt, context) {
 
 async function requestWithRetries(context, operation) {
   for (let attempt = 0; ; attempt += 1) {
+    const startedAt = Date.now();
+    context.logger?.debug("mcp_http_attempt_started", {
+      requestId: context.requestId,
+      tool: context.tool,
+      method: context.method,
+      origin: context.url.origin,
+      attempt: attempt + 1,
+    });
     try {
-      return await operation(context);
+      const result = await operation(context);
+      context.logger?.info("mcp_http_attempt_completed", {
+        requestId: context.requestId,
+        tool: context.tool,
+        method: context.method,
+        origin: context.url.origin,
+        attempt: attempt + 1,
+        durationMs: Math.max(0, Date.now() - startedAt),
+        statusCode: context.responseStatus,
+      });
+      return result;
     } catch (cause) {
       const error = normalizeRequestError(cause, context);
-      if (!shouldRetryRequest(error, attempt, context)) throw error;
+      const retry = shouldRetryRequest(error, attempt, context);
+      context.logger?.[retry ? "warn" : "error"]("mcp_http_attempt_failed", {
+        requestId: context.requestId,
+        tool: context.tool,
+        method: context.method,
+        origin: context.url.origin,
+        attempt: attempt + 1,
+        durationMs: Math.max(0, Date.now() - startedAt),
+        willRetry: retry,
+        error,
+      });
+      if (!retry) throw error;
       await waitBeforeRetry(attempt, context);
     }
   }
@@ -217,14 +263,16 @@ async function requestJson(
   { method, body, params = {}, headers = {} } = {},
 ) {
   const maxRetries = !method || method === "GET" ? readMaxRetries() : 0;
-  const context = createRequestContext(path, params, maxRetries);
-  return requestWithRetries(context, async ({ url, signal }) => {
+  const context = createRequestContext(path, params, maxRetries, method);
+  return requestWithRetries(context, async (requestContext) => {
+    const { url, signal } = requestContext;
     const response = await fetch(url, {
       ...(method ? { method } : {}),
       headers: { ...authenticationHeaders(), ...headers },
       body,
       signal,
     });
+    requestContext.responseStatus = response.status;
     const payload = await readPayload(response);
     if (!response.ok) throw responseError(response, payload);
     return payload;
@@ -235,12 +283,14 @@ async function requestBinary(
   path,
   { params = {}, headers = {}, maxBytes } = {},
 ) {
-  const context = createRequestContext(path, params, readMaxRetries());
-  return requestWithRetries(context, async ({ url, signal }) => {
+  const context = createRequestContext(path, params, readMaxRetries(), "GET");
+  return requestWithRetries(context, async (requestContext) => {
+    const { url, signal } = requestContext;
     const response = await fetch(url, {
       headers: { ...authenticationHeaders(), ...headers },
       signal,
     });
+    requestContext.responseStatus = response.status;
     if (!response.ok) {
       throw responseError(response, await readPayload(response));
     }

package/src/index.js

@@ -1,9 +1,12 @@
+import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { createLogger } from "./logger.js";
 import { createMcpMessageHandler, protocolError } from "./mcpServer.js";
 import { dispatchTool, listTools } from "./tools.js";
 import { loadEnv } from "./loadEnv.js";
+import { SERVER_NAME, SERVER_VERSION } from "./version.js";
 
 const TOOL_DIR = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -12,9 +15,27 @@ const TOOL_DIR = path.resolve(
 
 // O workspace pertence à configuração do projeto/cliente MCP. O arquivo da
 // instância fornece URL e credencial, mas não pode mudar esse escopo.
-loadEnv(TOOL_DIR, { preserve: ["BIAWS_WORKSPACE_ID"] });
+const environment = loadEnv(TOOL_DIR, {
+  preserve: ["BIAWS_WORKSPACE_ID"],
+});
+const executionId = randomUUID();
+const startedAt = Date.now();
+const logger = createLogger({
+  service: SERVER_NAME,
+  version: SERVER_VERSION,
+  executionId,
+});
+
+// A broken stderr cannot be reported anywhere safely. Keep it from becoming a
+// second fatal error while preserving stdout exclusively for MCP frames.
+process.stderr.on("error", () => {});
 
 function writeMessage(message) {
+  if (process.stdout.destroyed || process.stdout.writableEnded) {
+    const error = new Error("MCP stdout is not writable");
+    error.code = "MCP_STDOUT_CLOSED";
+    throw error;
+  }
   process.stdout.write(`${JSON.stringify(message)}\n`);
 }
 
@@ -22,8 +43,20 @@ const server = createMcpMessageHandler({
   dispatchTool,
   listTools,
   writeMessage,
+  logger,
 });
 let buffer = "";
+let shuttingDown = false;
+
+logger.info("mcp_server_started", {
+  nodeVersion: process.versions.node,
+  pid: process.pid,
+  transport: "stdio",
+  environmentFilesLoaded: environment.loaded.length,
+  workspaceConfigured: Boolean(
+    String(process.env.BIAWS_WORKSPACE_ID || "").trim(),
+  ),
+});
 
 process.stdin.setEncoding("utf8");
 process.stdin.on("data", (chunk) => {
@@ -35,23 +68,92 @@ process.stdin.on("data", (chunk) => {
     if (!line.trim()) continue;
     try {
       void server.accept(JSON.parse(line));
-    } catch {
+    } catch (error) {
+      logger.warn("mcp_input_parse_failed", {
+        bytes: Buffer.byteLength(line),
+        error,
+      });
       writeMessage(protocolError(null, -32700, "Parse error"));
     }
   }
 });
 
 process.stdin.on("end", () => {
-  void server.waitForIdle().finally(shutdown);
+  logger.info("mcp_input_closed", { bufferedBytes: Buffer.byteLength(buffer) });
+  void shutdown({ reason: "stdin_end" });
+});
+
+process.stdin.on("error", (error) => {
+  logger.error("mcp_input_error", { error });
+  void shutdown({ reason: "stdin_error", exitCode: 1, cancel: true });
+});
+
+process.stdout.on("error", (error) => {
+  logger.error("mcp_stdout_error", { error });
+  void shutdown({ reason: "stdout_error", exitCode: 1, cancel: true });
 });
 
-function shutdown() {
-  process.exit(0);
+async function shutdown({ reason, signal, exitCode = 0, cancel = false }) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  logger.info("mcp_shutdown_requested", {
+    reason,
+    signal,
+    exitCode,
+    cancelActiveRequests: cancel,
+  });
+  if (cancel) server.cancelAll();
+
+  const timeoutMs = 5_000;
+  let timedOut = false;
+  let timer;
+  await Promise.race([
+    server.waitForIdle(),
+    new Promise((resolve) => {
+      timer = setTimeout(() => {
+        timedOut = true;
+        resolve();
+      }, timeoutMs);
+    }),
+  ]);
+  clearTimeout(timer);
+  if (timedOut) {
+    logger.warn("mcp_shutdown_timed_out", { reason, timeoutMs });
+  }
+  logger.info("mcp_server_stopped", {
+    reason,
+    exitCode,
+    graceful: !timedOut,
+    uptimeMs: Math.max(0, Date.now() - startedAt),
+  });
+  process.exit(exitCode);
 }
 
 for (const signal of ["SIGINT", "SIGTERM"]) {
   process.on(signal, () => {
-    server.cancelAll();
-    void server.waitForIdle().finally(shutdown);
+    void shutdown({
+      reason: "signal",
+      signal,
+      exitCode: 0,
+      cancel: true,
+    });
   });
 }
+
+process.on("uncaughtException", (error, origin) => {
+  logger.error("mcp_uncaught_exception", { origin, error });
+  void shutdown({
+    reason: "uncaught_exception",
+    exitCode: 1,
+    cancel: true,
+  });
+});
+
+process.on("unhandledRejection", (reason) => {
+  logger.error("mcp_unhandled_rejection", { error: reason });
+  void shutdown({
+    reason: "unhandled_rejection",
+    exitCode: 1,
+    cancel: true,
+  });
+});

package/src/logger.js

@@ -0,0 +1,97 @@
+const LEVELS = Object.freeze({ debug: 10, info: 20, warn: 30, error: 40 });
+const SENSITIVE_KEY =
+  /authorization|cookie|password|passwd|token|secret|api.?key|connection.?string/iu;
+
+function sanitizeText(value) {
+  return String(value)
+    .replace(/Bearer\s+[^\s,;]+/giu, "Bearer [REDACTED]")
+    .replace(/(https?:\/\/)[^/@\s]+@/giu, "$1[REDACTED]@")
+    .replace(
+      /([?&](?:token|key|secret|password)\s*=)[^&#\s]+/giu,
+      "$1[REDACTED]",
+    );
+}
+
+export function serializeError(error, depth = 0) {
+  if (!(error instanceof Error)) {
+    return { name: "Error", message: sanitizeText(error) };
+  }
+  const result = {
+    name: error.name,
+    message: sanitizeText(error.message),
+    ...(error.code === undefined ? {} : { code: String(error.code) }),
+    ...(Number.isInteger(error.statusCode)
+      ? { statusCode: error.statusCode }
+      : {}),
+    ...(typeof error.retryable === "boolean"
+      ? { retryable: error.retryable }
+      : {}),
+    ...(error.stack ? { stack: sanitizeText(error.stack) } : {}),
+  };
+  if (depth < 2 && error.cause !== undefined) {
+    result.cause = serializeError(error.cause, depth + 1);
+  }
+  return result;
+}
+
+function sanitize(value, key = "", seen = new WeakSet()) {
+  if (SENSITIVE_KEY.test(key)) return "[REDACTED]";
+  if (value instanceof Error) return serializeError(value);
+  if (typeof value === "string") return sanitizeText(value);
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.map((entry) => sanitize(entry, "", seen));
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([entryKey, entry]) => [
+      entryKey,
+      sanitize(entry, entryKey, seen),
+    ]),
+  );
+}
+
+function configuredLevel(level) {
+  const normalized = String(level || "info").toLowerCase();
+  return LEVELS[normalized] === undefined ? "info" : normalized;
+}
+
+export function createLogger({
+  service,
+  version,
+  executionId,
+  level = process.env.BIAWS_MCP_LOG_LEVEL,
+  stream = process.stderr,
+  now = () => new Date().toISOString(),
+} = {}) {
+  const minimumLevel = LEVELS[configuredLevel(level)];
+
+  function log(entryLevel, event, fields = {}) {
+    if (LEVELS[entryLevel] < minimumLevel) return false;
+    const record = sanitize({
+      timestamp: now(),
+      level: entryLevel,
+      service,
+      version,
+      executionId,
+      event,
+      ...fields,
+    });
+    try {
+      stream.write(`${JSON.stringify(record)}\n`);
+      return true;
+    } catch {
+      // stderr is the diagnostic fallback. Logging failures must never recurse
+      // or corrupt the MCP protocol on stdout.
+      return false;
+    }
+  }
+
+  return {
+    debug: (event, fields) => log("debug", event, fields),
+    info: (event, fields) => log("info", event, fields),
+    warn: (event, fields) => log("warn", event, fields),
+    error: (event, fields) => log("error", event, fields),
+  };
+}

package/src/mcpServer.js

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+
 import { runWithRequestContext } from "./requestContext.js";
 import { SERVER_NAME, SERVER_VERSION } from "./version.js";
 
@@ -59,6 +61,9 @@ export function createMcpMessageHandler({
   dispatchTool,
   listTools,
   writeMessage,
+  logger,
+  createRequestId = randomUUID,
+  now = () => Date.now(),
 }) {
   const activeRequests = new Map();
   const inFlight = new Set();
@@ -66,13 +71,41 @@ export function createMcpMessageHandler({
   async function handleToolCall(id, params) {
     const controller = new AbortController();
     activeRequests.set(id, controller);
+    const requestId = createRequestId();
+    const tool = String(params.name || "");
+    const startedAt = now();
+    const logContext = {
+      requestId,
+      rpcRequestId: ["string", "number"].includes(typeof id) ? id : undefined,
+      tool,
+    };
+    logger?.info("mcp_tool_call_started", {
+      ...logContext,
+      inFlight: activeRequests.size,
+    });
     try {
       const result = await runWithRequestContext(
-        { signal: controller.signal },
+        { signal: controller.signal, logger, requestId, tool },
         () => dispatchTool(params.name, params.arguments || {}),
       );
       writeMessage(success(id, toolResult(result)));
+      logger?.info("mcp_tool_call_completed", {
+        ...logContext,
+        durationMs: Math.max(0, now() - startedAt),
+      });
     } catch (error) {
+      const cancelled = error?.code === "REQUEST_CANCELLED";
+      const expectedFailure =
+        cancelled ||
+        (Number.isInteger(error?.statusCode) && error.statusCode < 500);
+      logger?.[expectedFailure ? "warn" : "error"](
+        cancelled ? "mcp_tool_call_cancelled" : "mcp_tool_call_failed",
+        {
+          ...logContext,
+          durationMs: Math.max(0, now() - startedAt),
+          error,
+        },
+      );
       writeMessage(success(id, toolErrorResult(error)));
     } finally {
       activeRequests.delete(id);
@@ -119,15 +152,31 @@ export function createMcpMessageHandler({
   }
 
   function accept(request) {
-    const operation = handleMessage(request).catch(() => {
+    const operation = handleMessage(request).catch((error) => {
+      logger?.error("mcp_message_handling_failed", {
+        rpcRequestId: ["string", "number"].includes(typeof request?.id)
+          ? request.id
+          : undefined,
+        method: String(request?.method || ""),
+        error,
+      });
       if (request?.id !== undefined) {
-        writeMessage(
-          protocolError(request.id, -32603, "Internal JSON-RPC error"),
-        );
+        try {
+          writeMessage(
+            protocolError(request.id, -32603, "Internal JSON-RPC error"),
+          );
+        } catch (writeError) {
+          logger?.error("mcp_error_response_write_failed", {
+            error: writeError,
+          });
+        }
       }
     });
     inFlight.add(operation);
-    void operation.finally(() => inFlight.delete(operation));
+    void operation.then(
+      () => inFlight.delete(operation),
+      () => inFlight.delete(operation),
+    );
     return operation;
   }
 

package/src/requestContext.js

@@ -9,3 +9,7 @@ export function runWithRequestContext(context, callback) {
 export function currentRequestSignal() {
   return requestContext.getStore()?.signal;
 }
+
+export function currentRequestContext() {
+  return requestContext.getStore();
+}

package/src/tools.js

@@ -1,4 +1,5 @@
 import {
+  addIssueComment,
   classifyIssue,
   createTaxonomyItem,
   createIssue,
@@ -10,6 +11,7 @@ import {
   summarizeIssuesForSupport,
   suggestTaxonomy,
   updateIssueState,
+  updateIssueComment,
   updateTaxonomyItem,
 } from "./domains/issues/service.js";
 import {
@@ -156,6 +158,58 @@ const tools = [
     },
     handler: getIssueDetails,
   },
+  {
+    name: "issues_add_comment",
+    description: "Adiciona um comentário em Markdown a uma issue existente.",
+    inputSchema: {
+      type: "object",
+      required: ["issueId", "text"],
+      additionalProperties: false,
+      properties: {
+        issueId: { type: "string", minLength: 1 },
+        text: {
+          type: "string",
+          minLength: 1,
+          description: "Conteúdo do comentário em Markdown.",
+        },
+        date: {
+          type: "string",
+          description:
+            "Data do comentário em formato aceito pela API; usa o momento atual quando omitida.",
+        },
+      },
+    },
+    handler: addIssueComment,
+  },
+  {
+    name: "issues_update_comment",
+    description:
+      "Atualiza o conteúdo e, opcionalmente, a data de um comentário de issue.",
+    inputSchema: {
+      type: "object",
+      required: ["issueId", "commentId", "text"],
+      additionalProperties: false,
+      properties: {
+        issueId: { type: "string", minLength: 1 },
+        commentId: {
+          type: "string",
+          minLength: 1,
+          description: "ID do comentário retornado por issues_get.",
+        },
+        text: {
+          type: "string",
+          minLength: 1,
+          description: "Novo conteúdo do comentário em Markdown.",
+        },
+        date: {
+          type: "string",
+          description:
+            "Nova data do comentário; usa o momento atual quando omitida.",
+        },
+      },
+    },
+    handler: updateIssueComment,
+  },
   {
     name: "issues_get_classification_catalog",
     description:

package/src/version.js

@@ -1,2 +1,2 @@
 export const SERVER_NAME = "biaws-mcp";
-export const SERVER_VERSION = "0.3.0";
+export const SERVER_VERSION = "0.5.0";