biaws-mcp 0.4.0 → 0.6.0

package/README.md

@@ -9,19 +9,18 @@ O servidor separa os domínios:
   topologia operacional.
 - `issues_*`: chamados, incidentes, requisições operacionais, taxonomia e classificação.
 - `demands_*`: melhorias, especificações, jornadas, prazos e contexto para desenvolvimento.
-- `procedures_*`: procedimentos operacionais em Markdown, com tags e classificação taxonômica compartilhadas com issues.
-- `documents_*`: regras, decisões, guidelines, features e referências técnicas
-  relacionado a aplicações e componentes.
+- `documents_*`: regras, decisões, guidelines, features, referências técnicas e
+  procedimentos relacionados ao workspace, a aplicações e a componentes.
 - `knowledge_context_load`: regras ativas e decisões aceitas para o contexto
   solicitado.
 - `attachments_*`: envio, download, classificação e exclusão de arquivos de
-  chamados, melhorias, tarefas e procedimentos.
+  chamados, melhorias, tarefas e documentos.
 - `secrets_*`: consulta e registro de metadados de segredos, sem acesso aos valores.
 - `monitoring_templates_*`, `runtime_active_monitors_*` e
   `runtime_monitoring_results_list`: administração versionada de templates,
   configuração de monitores e consulta do histórico dos runtimes.
 - `resource_collections_*` e `*_move_to_collection`: organização hierárquica
-  de aplicações, regras, decisões, procedimentos, segredos, skills e servidores.
+  de aplicações, documentos, melhorias, segredos, skills e servidores.
 
 O carregamento de ambiente é autocontido no pacote. Em um checkout, ele preserva
 o fallback para o `.env` da raiz; no pacote publicado, usa o `.env` local ou o
@@ -66,13 +65,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.6.0
 ```
 
 Também é possível instalá-lo explicitamente:
 
 ```bash
-npm install --global biaws-mcp@0.3.0
+npm install --global biaws-mcp@0.6.0
 biaws-mcp
 ```
 
@@ -91,7 +90,7 @@ npm start
 Em um cliente MCP, configure o comando:
 
 ```bash
-npx --yes biaws-mcp@0.3.0
+npx --yes biaws-mcp@0.6.0
 ```
 
 O fluxo recomendado é gerar a configuração completa com:
@@ -105,6 +104,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
@@ -190,19 +219,19 @@ monitor antes de provisionar o executor, crie-o com `enabled: false`.
 - `resource_collections_delete`: exclui somente uma coleção vazia, sem
   subcoleções nem itens vinculados;
 - `applications_move_to_collection`, `servers_move_to_collection`,
-  `secrets_move_to_collection`, `skills_move_to_collection` e
-  `procedures_move_to_collection`: movem um item para uma coleção validada ou
+  `secrets_move_to_collection`, `skills_move_to_collection`,
+  `demands_move_to_collection` e `documents_move_to_collection`: movem um item
+  para uma coleção validada ou
   para a raiz quando `collectionId` é vazio.
 
 As quatro ferramentas `resource_collections_*` aceitam `resourceType` com os
-valores `applications`, `procedures`, `secrets`, `skills` ou `servers`.
-Procedimentos usam sua árvore própria na API; os demais recursos usam a árvore
-compartilhada por tipo. Todas as mutações mantêm as validações contra ciclos,
+valores `applications`, `demands`, `documents`, `secrets`, `skills` ou
+`servers`. Todas as mutações mantêm as validações contra ciclos,
 escopo do workspace, permissões e auditoria da API.
 
 `applications_get_context` entrega, em uma única consulta, a aplicação,
 integrações, componentes, repositórios, deployments, runtimes, servidores referenciados e
-resumos de issues, melhorias e procedimentos associados. O argumento `limit`
+resumos de issues, melhorias e documentos associados. O argumento `limit`
 vale separadamente para cada grupo, tem teto de 100 e padrão 25. O resultado
 informa totais e truncamentos e não contém credenciais, endereços dos
 servidores, metadata dos runtimes, anexos nem os textos extensos da base de
@@ -264,7 +293,7 @@ conhecimento.
   conteúdo armazenado.
 
 As quatro ferramentas aceitam `entityType` com `issue`, `demand`, `task` ou
-`procedure`. `entityId` identifica o chamado, melhoria ou procedimento. Para
+`document`. `entityId` identifica o chamado, melhoria ou documento. Para
 `task`, `entityId` deve ser o ID da melhoria pai e `taskId` deve identificar a
 tarefa por ID ou código.
 
@@ -285,15 +314,25 @@ quando essas permissões tiverem sido removidas ou ainda não existirem, um
 administrador deverá concedê-las. Operações no contexto de tarefa usam as
 permissões de anexos da melhoria pai.
 
-### Procedimentos
-
-- `procedures_search`: pesquisa por ID, texto (título, sumário e conteúdo),
-  taxonomia (incluindo descendentes), tag e contexto.
-- `procedures_get_classification_catalog`: obtém a árvore taxonômica e os grupos de tags; opcionalmente inclui listas achatadas de IDs válidos.
-- `procedures_create`: cria um procedimento com título, sumário, conteúdo,
-  classificação e contexto opcionais.
-- `procedures_update`: atualiza parcialmente título, sumário, conteúdo,
-  classificação ou contexto.
+### Documentos
+
+- `document_types_list`: consulta o contrato oficial de cada tipo, incluindo
+  estados, contexto obrigatório e campos específicos de `details`;
+- `documents_search` e `documents_get`: localizam documentos e carregam seu
+  conteúdo completo sob demanda;
+- `documents_create`: cria regras, decisões, guidelines, features, referências
+  técnicas e procedimentos usando um schema discriminado por `documentType`;
+- `documents_update`: atualiza conteúdo, contexto e metadados, preservando o
+  tipo imutável;
+- `documents_add_observation`: acrescenta uma observação imutável.
+
+Regras de negócio, decisões arquiteturais e features exigem `applicationId`.
+Referências técnicas podem pertencer ao workspace ou a uma aplicação.
+Procedimentos também podem pertencer ao workspace ou ser vinculados a uma
+aplicação e seus componentes; são documentos com `documentType=procedure`.
+Guidelines usam `details.scope`: `workspace` proíbe `applicationId`,
+`application` o exige e `component` exige também `affectedComponentIds`.
+Componentes sempre devem estar ativos e pertencer à aplicação informada.
 
 ### Metadados de segredos
 
@@ -313,8 +352,8 @@ O grupo padrão `agent-operator` recebe `secrets.metadata.read` e
 `secrets.value.reveal`.
 
 Issues e melhorias criadas pelo MCP sempre pertencem a uma aplicação e podem
-informar `affectedComponentIds`. Procedimentos podem permanecer gerais ao
-workspace ou ser vinculados opcionalmente a uma aplicação e seus componentes.
+informar `affectedComponentIds`. Documentos seguem as regras de contexto
+declaradas por `document_types_list`.
 Nas ferramentas de consulta, os filtros comuns são `workspaceId`,
 `applicationId` e `componentId`.
 

package/package.json

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

package/src/domains/knowledge/documentTypeCatalog.js

@@ -0,0 +1,7 @@
+// Keep this published copy synchronized with shared/documentTypes.js. The MCP
+// package cannot import files outside its package root; the parity test prevents
+// the API and MCP contracts from drifting.
+export {
+  DOCUMENT_TYPE_CATALOG,
+  DOCUMENT_TYPES,
+} from "./documentTypeCatalogData.js";

package/src/domains/knowledge/documentTypeCatalogData.js

@@ -0,0 +1,104 @@
+export const DOCUMENT_TYPE_CATALOG = Object.freeze({
+  "business-rule": Object.freeze({
+    type: "business-rule",
+    label: "Regra de negócio",
+    description: "Condições e comportamentos esperados do domínio.",
+    defaultStatus: "draft",
+    statuses: Object.freeze(["draft", "active", "retired", "archived"]),
+    currentStatuses: Object.freeze(["active"]),
+    applicationRequired: true,
+    details: Object.freeze({
+      ruleCode: Object.freeze({ type: "string", maxLength: 80 }),
+      effectiveFrom: Object.freeze({ type: "date" }),
+    }),
+  }),
+  "architecture-decision": Object.freeze({
+    type: "architecture-decision",
+    label: "Decisão arquitetural",
+    description: "Escolhas técnicas, contexto, alternativas e consequências.",
+    defaultStatus: "proposed",
+    statuses: Object.freeze([
+      "proposed",
+      "accepted",
+      "rejected",
+      "superseded",
+      "archived",
+    ]),
+    currentStatuses: Object.freeze(["accepted"]),
+    applicationRequired: true,
+    details: Object.freeze({
+      decidedAt: Object.freeze({ type: "date" }),
+    }),
+  }),
+  guideline: Object.freeze({
+    type: "guideline",
+    label: "Guideline",
+    description: "Diretrizes e padrões de desenvolvimento.",
+    defaultStatus: "draft",
+    statuses: Object.freeze(["draft", "published", "deprecated", "archived"]),
+    currentStatuses: Object.freeze(["published"]),
+    applicationRequired: false,
+    details: Object.freeze({
+      scope: Object.freeze({
+        type: "string",
+        enum: Object.freeze(["workspace", "application", "component"]),
+        default: "workspace",
+      }),
+      enforcement: Object.freeze({
+        type: "string",
+        enum: Object.freeze(["required", "recommended", "informative"]),
+        default: "recommended",
+      }),
+    }),
+  }),
+  feature: Object.freeze({
+    type: "feature",
+    label: "Feature",
+    description: "Descrição funcional e técnica aprofundada de uma capacidade.",
+    defaultStatus: "draft",
+    statuses: Object.freeze(["draft", "published", "deprecated", "archived"]),
+    currentStatuses: Object.freeze(["published"]),
+    applicationRequired: true,
+    details: Object.freeze({
+      maturity: Object.freeze({
+        type: "string",
+        enum: Object.freeze(["planned", "beta", "stable", "retired"]),
+        default: "stable",
+      }),
+    }),
+  }),
+  "technical-reference": Object.freeze({
+    type: "technical-reference",
+    label: "Referência técnica",
+    description: "Arquitetura atual, contratos, schemas e mecanismos.",
+    defaultStatus: "draft",
+    statuses: Object.freeze(["draft", "published", "deprecated", "archived"]),
+    currentStatuses: Object.freeze(["published"]),
+    applicationRequired: false,
+    details: Object.freeze({
+      referenceKind: Object.freeze({
+        type: "string",
+        enum: Object.freeze([
+          "architecture",
+          "contract",
+          "schema",
+          "protocol",
+          "mechanism",
+        ]),
+        default: "architecture",
+      }),
+    }),
+  }),
+  procedure: Object.freeze({
+    type: "procedure",
+    label: "Procedimento",
+    description: "Instruções operacionais reutilizáveis.",
+    defaultStatus: "draft",
+    statuses: Object.freeze(["draft", "published", "deprecated", "archived"]),
+    currentStatuses: Object.freeze(["published"]),
+    applicationRequired: false,
+    details: Object.freeze({}),
+  }),
+});
+
+export const DOCUMENT_TYPES = Object.freeze(Object.keys(DOCUMENT_TYPE_CATALOG));

package/src/domains/knowledge/service.js

@@ -1,9 +1,11 @@
 import { cleanParams, fetchJson, sendJson } from "../../httpClient.js";
+import { DOCUMENT_TYPE_CATALOG } from "./documentTypeCatalog.js";
 
 const BASE_PATH = "/api/knowledge/documents";
 
 function documentPayload(args = {}, current = {}) {
   return {
+    identifier: args.identifier ?? current.identifier,
     documentType: args.documentType ?? current.documentType,
     title: args.title ?? current.title,
     summary: args.summary ?? current.summary,
@@ -29,6 +31,28 @@ function documentPayload(args = {}, current = {}) {
   };
 }
 
+export function listDocumentTypes() {
+  return {
+    documentTypes: Object.values(DOCUMENT_TYPE_CATALOG).map((config) => ({
+      ...config,
+      context: config.applicationRequired
+        ? { applicationId: "required", affectedComponentIds: "optional" }
+        : config.type === "guideline"
+          ? {
+              applicationId: "depends-on-details.scope",
+              affectedComponentIds: "required-when-scope-is-component",
+            }
+          : { applicationId: "optional", affectedComponentIds: "optional" },
+    })),
+    commonRules: {
+      workspaceId: "implicit-from-mcp-configuration",
+      affectedComponentIds: "requires-applicationId",
+      documentType: "immutable-after-creation",
+      repositorySource: "repositoryId-and-path-required",
+    },
+  };
+}
+
 export async function searchDocuments(args = {}) {
   return fetchJson(
     BASE_PATH,

package/src/domains/knowledge/tools.js

@@ -2,78 +2,271 @@ import {
   addDocumentObservation,
   createDocument,
   getDocument,
+  listDocumentTypes,
   loadKnowledgeContext,
   searchDocuments,
   updateDocument,
 } from "./service.js";
+import {
+  DOCUMENT_TYPE_CATALOG,
+  DOCUMENT_TYPES,
+} from "./documentTypeCatalog.js";
 
 const ID = { type: "string", minLength: 1 };
+const DATE = {
+  type: "string",
+  pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+  description: "Data no formato YYYY-MM-DD.",
+};
 const DOCUMENT_TYPE = {
   type: "string",
-  enum: [
-    "business-rule",
-    "architecture-decision",
-    "guideline",
-    "feature",
-    "technical-reference",
-    "procedure",
-  ],
+  enum: DOCUMENT_TYPES,
+  description:
+    "Tipo imutável do documento. Consulte document_types_list para o contrato completo.",
 };
 const REFERENCES = {
   type: "array",
   maxItems: 100,
+  description: "Relações com outros documentos do mesmo workspace.",
   items: {
     type: "object",
     required: ["targetDocumentId"],
     additionalProperties: false,
     properties: {
       targetDocumentId: ID,
-      relationship: { type: "string" },
+      relationship: {
+        type: "string",
+        maxLength: 80,
+        description: "Tipo da relação; usa related quando omitido.",
+      },
+    },
+  },
+};
+const SOURCE = {
+  type: "object",
+  description:
+    "Origem canônica. Em mode=repository, repositoryId e path são obrigatórios.",
+  additionalProperties: false,
+  properties: {
+    mode: { type: "string", enum: ["native", "repository"] },
+    repositoryId: { type: "string", maxLength: 160 },
+    path: { type: "string", maxLength: 500 },
+  },
+  oneOf: [
+    {
+      properties: { mode: { const: "native" } },
+      required: ["mode"],
+    },
+    {
+      properties: { mode: { const: "repository" } },
+      required: ["mode", "repositoryId", "path"],
+    },
+  ],
+};
+const CLASSIFICATION = {
+  type: "object",
+  description: "Taxonomias e tags aplicáveis ao contexto do documento.",
+  additionalProperties: false,
+  properties: {
+    primaryTaxonomyId: { type: "string" },
+    secondaryTaxonomyIds: { type: "array", items: ID },
+    tags: {
+      type: "object",
+      additionalProperties: { type: "array", items: ID },
     },
   },
 };
+
+function detailProperty(definition) {
+  if (definition.type === "date") return DATE;
+  return {
+    type: definition.type,
+    ...(definition.enum ? { enum: definition.enum } : {}),
+    ...(definition.maxLength ? { maxLength: definition.maxLength } : {}),
+    ...(definition.default !== undefined
+      ? { default: definition.default }
+      : {}),
+  };
+}
+
+function detailsSchema(type, scope) {
+  const config = DOCUMENT_TYPE_CATALOG[type];
+  const properties = Object.fromEntries(
+    Object.entries(config.details).map(([field, definition]) => [
+      field,
+      detailProperty(definition),
+    ]),
+  );
+  if (scope) properties.scope = { const: scope };
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties,
+    ...(scope ? { required: ["scope"] } : {}),
+  };
+}
+
+const ALL_STATUSES = [
+  ...new Set(
+    Object.values(DOCUMENT_TYPE_CATALOG).flatMap(({ statuses }) => statuses),
+  ),
+];
+
 const COMMON = {
+  identifier: {
+    type: "string",
+    pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+    maxLength: 80,
+    description:
+      "Identificador opcional e único no workspace, usando minúsculas, números e hífens simples.",
+  },
   documentType: DOCUMENT_TYPE,
-  title: ID,
+  title: { ...ID, maxLength: 240 },
   summary: { type: "string", minLength: 1, maxLength: 500 },
   markdown: ID,
-  applicationId: { type: "string" },
-  affectedComponentIds: { type: "array", maxItems: 100, items: ID },
+  applicationId: {
+    type: "string",
+    minLength: 1,
+    description:
+      "Obrigatório para regras, decisões, features e documentos cujo escopo seja aplicação ou componente; omita no escopo do workspace.",
+  },
+  affectedComponentIds: {
+    type: "array",
+    maxItems: 100,
+    items: ID,
+    description:
+      "Componentes ativos da applicationId. Não pode ser informado sem aplicação.",
+  },
   collectionId: { type: "string" },
-  status: { type: "string" },
-  details: { type: "object" },
-  classification: {
+  status: {
+    type: "string",
+    enum: ALL_STATUSES,
+    description:
+      "Estado válido para o documentType; quando omitido, usa o estado inicial do tipo.",
+  },
+  details: {
     type: "object",
+    description:
+      "Metadados específicos do documentType, validados pelo ramo correspondente do schema.",
+  },
+  classification: CLASSIFICATION,
+  source: SOURCE,
+  references: REFERENCES,
+  definedAt: DATE,
+  lastReviewedAt: {
+    type: "string",
+    description: "YYYY-MM-DD ou vazio.",
+  },
+  nextReviewAt: { type: "string", description: "YYYY-MM-DD ou vazio." },
+  changeSummary: { type: "string" },
+};
+
+function typeBranch(type) {
+  const config = DOCUMENT_TYPE_CATALOG[type];
+  return {
+    description: `${config.label}: ${config.description}`,
+    properties: {
+      documentType: { const: type },
+      status: { type: "string", enum: config.statuses },
+      details: detailsSchema(type),
+    },
+    required: [
+      "documentType",
+      ...(config.applicationRequired ? ["applicationId"] : []),
+    ],
+  };
+}
+
+function optionalApplicationBranches(type) {
+  const config = DOCUMENT_TYPE_CATALOG[type];
+  const properties = {
+    documentType: { const: type },
+    status: { type: "string", enum: config.statuses },
+    details: detailsSchema(type),
+  };
+  return [
+    {
+      description: `${config.label} geral do workspace; applicationId e componentes devem ser omitidos.`,
+      properties: {
+        ...properties,
+        applicationId: { const: null },
+        affectedComponentIds: { type: "array", maxItems: 0 },
+      },
+      required: ["documentType"],
+    },
+    {
+      description: `${config.label} vinculada a uma aplicação e, opcionalmente, a seus componentes.`,
+      properties,
+      required: ["documentType", "applicationId"],
+    },
+  ];
+}
+
+const CREATE_VARIANTS = [
+  typeBranch("business-rule"),
+  typeBranch("architecture-decision"),
+  typeBranch("feature"),
+  ...optionalApplicationBranches("technical-reference"),
+  ...optionalApplicationBranches("procedure"),
+  {
+    description:
+      "Guideline geral do workspace; applicationId deve ser omitido.",
     properties: {
-      primaryTaxonomyId: { type: "string" },
-      secondaryTaxonomyIds: { type: "array", items: ID },
-      tags: {
-        type: "object",
-        additionalProperties: { type: "array", items: ID },
+      documentType: { const: "guideline" },
+      status: {
+        type: "string",
+        enum: DOCUMENT_TYPE_CATALOG.guideline.statuses,
       },
+      details: detailsSchema("guideline", "workspace"),
+      applicationId: { const: null },
+      affectedComponentIds: { type: "array", maxItems: 0 },
     },
+    required: ["documentType", "details"],
   },
-  source: {
-    type: "object",
+  {
+    description: "Guideline vinculada a uma aplicação.",
     properties: {
-      mode: { type: "string", enum: ["native", "repository"] },
-      repositoryId: { type: "string" },
-      path: { type: "string" },
+      documentType: { const: "guideline" },
+      status: {
+        type: "string",
+        enum: DOCUMENT_TYPE_CATALOG.guideline.statuses,
+      },
+      details: detailsSchema("guideline", "application"),
     },
+    required: ["documentType", "details", "applicationId"],
   },
-  references: REFERENCES,
-  definedAt: { type: "string", description: "YYYY-MM-DD" },
-  lastReviewedAt: { type: "string", description: "YYYY-MM-DD ou vazio" },
-  nextReviewAt: { type: "string", description: "YYYY-MM-DD ou vazio" },
-  changeSummary: { type: "string" },
-};
+  {
+    description: "Guideline vinculada a ao menos um componente da aplicação.",
+    properties: {
+      documentType: { const: "guideline" },
+      status: {
+        type: "string",
+        enum: DOCUMENT_TYPE_CATALOG.guideline.statuses,
+      },
+      details: detailsSchema("guideline", "component"),
+      affectedComponentIds: {
+        type: "array",
+        minItems: 1,
+        maxItems: 100,
+        items: ID,
+      },
+    },
+    required: [
+      "documentType",
+      "details",
+      "applicationId",
+      "affectedComponentIds",
+    ],
+  },
+];
 
-function schema(properties, required = []) {
+function schema(properties, required = [], extra = {}) {
   return {
     type: "object",
     ...(required.length ? { required } : {}),
     additionalProperties: false,
     properties,
+    ...extra,
   };
 }
 
@@ -96,6 +289,12 @@ export const knowledgeTools = [
       ["applicationId"],
     ),
   ),
+  definition(
+    "document_types_list",
+    "Lista o contrato oficial de cada tipo de documento: contexto exigido, estados e campos details.",
+    listDocumentTypes,
+    schema({}),
+  ),
   definition(
     "documents_search",
     "Busca documentos por tipo, aplicação, componente, coleção, estado ou texto.",
@@ -106,7 +305,7 @@ export const knowledgeTools = [
       applicationId: ID,
       componentId: ID,
       collectionId: ID,
-      status: { type: "string" },
+      status: { type: "string", enum: ALL_STATUSES },
       currentOnly: { type: "boolean" },
       includeWorkspace: { type: "boolean" },
       includeArchived: { type: "boolean" },
@@ -122,13 +321,15 @@ export const knowledgeTools = [
   ),
   definition(
     "documents_create",
-    "Cria um documento tipado no workspace ou em uma aplicação.",
+    "Cria um documento usando o contrato discriminado pelo documentType. O workspace vem da configuração do MCP; applicationId e details seguem as regras de cada tipo.",
     createDocument,
-    schema(COMMON, ["documentType", "title", "summary", "markdown"]),
+    schema(COMMON, ["documentType", "title", "summary", "markdown"], {
+      oneOf: CREATE_VARIANTS,
+    }),
   ),
   definition(
     "documents_update",
-    "Atualiza conteúdo, contexto, metadados e relações de um documento.",
+    "Atualiza um documento existente. documentType é imutável; consulte documents_get antes de alterar contexto, status ou details.",
     updateDocument,
     schema({ documentId: ID, ...COMMON }, ["documentId"]),
   ),

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

@@ -236,7 +236,7 @@ const tools = [
   {
     name: "issues_create_taxonomy_item",
     description:
-      "Inclui um item na taxonomia compartilhada de issues e procedimentos, na raiz ou sob um item pai.",
+      "Inclui um item na taxonomia compartilhada de issues e documentos, na raiz ou sob um item pai.",
     inputSchema: {
       type: "object",
       required: ["id", "label"],
@@ -831,6 +831,45 @@ function validateEnum(value, schema, path, fields) {
   }
 }
 
+function validateConst(value, schema, path, fields) {
+  if (Object.hasOwn(schema, "const") && value !== schema.const) {
+    addValidationField(
+      fields,
+      path,
+      "invalid_const",
+      `${path} must be ${JSON.stringify(schema.const)}`,
+    );
+  }
+}
+
+function validateString(value, schema, path, fields) {
+  if (typeof value !== "string") return;
+  if (schema.minLength !== undefined && value.length < schema.minLength) {
+    addValidationField(
+      fields,
+      path,
+      "min_length",
+      `${path} must contain at least ${schema.minLength} characters`,
+    );
+  }
+  if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+    addValidationField(
+      fields,
+      path,
+      "max_length",
+      `${path} must contain at most ${schema.maxLength} characters`,
+    );
+  }
+  if (schema.pattern && !new RegExp(schema.pattern, "u").test(value)) {
+    addValidationField(
+      fields,
+      path,
+      "pattern",
+      `${path} must match ${schema.pattern}`,
+    );
+  }
+}
+
 function validateNumber(value, schema, path, fields) {
   if (typeof value !== "number") return;
   if (schema.minimum !== undefined && value < schema.minimum) {
@@ -921,13 +960,73 @@ function validateObject(value, schema, path, fields) {
   validateObjectEntries(value, schema, path, fields);
 }
 
+function validateNot(value, schema, path, fields) {
+  if (!schema.not) return;
+  const nestedFields = [];
+  validateValue(value, schema.not, path, nestedFields);
+  if (!nestedFields.length) {
+    addValidationField(
+      fields,
+      path,
+      "not",
+      `${path || "arguments"} contains a forbidden combination of fields`,
+    );
+  }
+}
+
+function validateOneOf(value, schema, path, fields) {
+  if (!schema.oneOf?.length) return;
+  const candidates = schema.oneOf.map((candidate) => {
+    const candidateFields = [];
+    validateValue(value, candidate, path, candidateFields);
+    return candidateFields;
+  });
+  const matches = candidates.filter(
+    (candidateFields) => !candidateFields.length,
+  );
+  if (matches.length === 1) return;
+  if (!matches.length) {
+    const discriminatedIndexes = schema.oneOf.flatMap((candidate, index) => {
+      const matchesDiscriminator = Object.entries(
+        candidate.properties || {},
+      ).some(
+        ([property, definition]) =>
+          Object.hasOwn(definition, "const") &&
+          isPlainObject(value) &&
+          value[property] === definition.const,
+      );
+      return matchesDiscriminator ? [index] : [];
+    });
+    const eligible = discriminatedIndexes.length
+      ? discriminatedIndexes.map((index) => candidates[index])
+      : candidates;
+    const best = eligible.reduce((selected, candidate) =>
+      candidate.length < selected.length ? candidate : selected,
+    );
+    if (best.length) {
+      fields.push(...best);
+      return;
+    }
+  }
+  addValidationField(
+    fields,
+    path,
+    "one_of",
+    `${path || "arguments"} must match exactly one supported schema variant`,
+  );
+}
+
 function validateValue(value, schema, path, fields) {
   if (!schema || value === undefined) return;
   if (!validateSchemaType(value, schema, path, fields)) return;
+  validateConst(value, schema, path, fields);
   validateEnum(value, schema, path, fields);
+  validateString(value, schema, path, fields);
   validateNumber(value, schema, path, fields);
   validateArray(value, schema, path, fields);
   validateObject(value, schema, path, fields);
+  validateNot(value, schema, path, fields);
+  validateOneOf(value, schema, path, fields);
 }
 
 function validateArguments(tool, args) {

package/src/version.js

@@ -1,2 +1,2 @@
 export const SERVER_NAME = "biaws-mcp";
-export const SERVER_VERSION = "0.4.0";
+export const SERVER_VERSION = "0.6.0";