biaws-mcp 0.5.0 → 0.7.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.5.0
+npx --yes biaws-mcp@0.6.0
 ```
 
 Também é possível instalá-lo explicitamente:
 
 ```bash
-npm install --global biaws-mcp@0.5.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.5.0
+npx --yes biaws-mcp@0.6.0
 ```
 
 O fluxo recomendado é gerar a configuração completa com:
@@ -158,7 +157,8 @@ As escritas estruturadas são:
 - `integrations_create` e `integrations_update`;
 - `repositories_create` e `repositories_update`;
 - `servers_create` e `servers_update`;
-- `deployments_create` e `deployments_update`;
+- `deployments_create`, `deployments_update` e
+  `deployments_record_publication`;
 - `runtimes_create` e `runtimes_update`.
 
 As ferramentas de escrita usam `POST` ou `PATCH` da API e, portanto, herdam
@@ -220,19 +220,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
@@ -294,7 +294,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.
 
@@ -315,15 +315,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
 
@@ -343,8 +353,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.5.0",
+  "version": "0.7.0",
   "description": "Servidor MCP de domínio para o Bondia Workspaces",
   "license": "Apache-2.0",
   "repository": {

package/src/domains/catalog/service.js

@@ -256,6 +256,16 @@ export async function updateDeployment(args = {}) {
   );
 }
 
+export async function recordDeploymentPublication(args = {}) {
+  const deploymentId = requiredId(args, "deploymentId");
+  return sendJson(
+    `${entityPath("deployments", deploymentId)}/publications`,
+    mutationPayload(args, ["deploymentId"]),
+    {},
+    "POST",
+  );
+}
+
 export async function listRuntimes(args = {}) {
   const deploymentId = requiredId(args, "deploymentId");
   return fetchJson(

package/src/domains/catalog/tools.js

@@ -23,6 +23,7 @@ import {
   listRuntimes,
   listServers,
   listWorkspaces,
+  recordDeploymentPublication,
   updateApplication,
   updateComponent,
   updateDeployment,
@@ -165,6 +166,18 @@ const SERVER_PROPERTIES = {
   tags: TAGS,
 };
 
+const PUBLICATION_PROPERTIES = {
+  version: STRING,
+  revision: STRING,
+  repositoryId: { type: ["string", "null"] },
+  status: {
+    type: "string",
+    enum: ["planned", "canceled", "deployed"],
+  },
+  publishedAt: { type: ["string", "null"] },
+  description: STRING,
+};
+
 const DEPLOYMENT_PROPERTIES = {
   key: APPLICATION_PROPERTIES.key,
   name: STRING,
@@ -183,15 +196,7 @@ const DEPLOYMENT_PROPERTIES = {
       required: ["version"],
       properties: {
         id: ID,
-        version: STRING,
-        revision: STRING,
-        repositoryId: { type: ["string", "null"] },
-        status: {
-          type: "string",
-          enum: ["planned", "canceled", "deployed"],
-        },
-        publishedAt: { type: ["string", "null"] },
-        description: STRING,
+        ...PUBLICATION_PROPERTIES,
         recordedAt: { type: ["string", "null"] },
         recordedBy: STRING,
       },
@@ -553,6 +558,15 @@ export const catalogTools = [
       ["deploymentId"],
     ),
   ),
+  definition(
+    "deployments_record_publication",
+    "Registra uma publicação no histórico append-only de um deployment sem reenviar as entradas existentes.",
+    recordDeploymentPublication,
+    schema({ deploymentId: ID, ...PUBLICATION_PROPERTIES }, [
+      "deploymentId",
+      "version",
+    ]),
+  ),
   definition(
     "runtimes_create",
     "Cria um runtime de deployment com metadata limitada e sem segredos.",

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/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.5.0";
+export const SERVER_VERSION = "0.7.0";