@shiftleftpt/sbd-toe-mcp 0.6.2 → 0.7.0

package/dist/index.js

@@ -5,12 +5,15 @@ import readline from "node:readline";
 import { getConfig, resolveAppPath } from "./config.js";
 import { formatSampledAnswerResult, inspectManualRetrieval, prepareManualAnsweringContext, searchManualQuestion } from "./orchestrator/ask-manual.js";
 import { loadSystemPromptTemplate } from "./prompt/system-prompt.js";
-import { getSnapshotCache, retrievePublishedContext } from "./backend/semantic-index-gateway.js";
+import { getSnapshotCache } from "./backend/semantic-index-gateway.js";
 import { handleGetSbdToeChapterBrief, handleListSbdToeChapters, handleMapSbdToeApplicability, handleQuerySbdToeEntities } from "./tools/structured-tools.js";
-import { handleGenerateDocument } from "./tools/generate-document.js";
 import { handleGenerateSbdToeSkill } from "./tools/generate-sbd-toe-skill.js";
 import { handleMapSbdToeReviewScope } from "./tools/map-review-scope.js";
 import { handlePlanRepoGovernance } from "./tools/plan-repo-governance.js";
+import { handleConsultSecurityRequirements } from "./tools/consult-security-requirements.js";
+import { handleGetThreatLandscape } from "./tools/get-threat-landscape.js";
+import { handleGetGuideByRole } from "./tools/get-guide-by-role.js";
+import { handleResolveEntities } from "./tools/resolve-entities.js";
 import { buildChapterApplicabilityJson, buildSetupAgentPrompt } from "./resources/sbd-toe-resources.js";
 const PROTOCOL_VERSION = "2025-03-26";
 const LOG_LEVELS = [
@@ -296,23 +299,23 @@ class McpRuntime {
                 {
                     name: "search_sbd_toe_manual",
                     title: "Search SbD-ToE Manual",
-                    description: "Recupera contexto grounded do manual SbD-ToE a partir do snapshot semântico local embutido.",
+                    description: "Retrieves grounded context from the SbD-ToE manual using the embedded local semantic snapshot.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             question: {
                                 type: "string",
-                                description: "Pergunta em linguagem natural sobre o manual."
+                                description: "Natural-language question about the manual."
                             },
                             debug: {
                                 type: "boolean",
-                                description: "Quando true, anexa o debug completo do retrieval."
+                                description: "When true, appends full retrieval debug information."
                             },
                             topK: {
                                 type: "integer",
                                 minimum: 1,
                                 maximum: 15,
-                                description: "Número máximo de records usados como contexto."
+                                description: "Maximum number of records used as context."
                             }
                         },
                         required: ["question"],
@@ -325,23 +328,26 @@ class McpRuntime {
                 {
                     name: "answer_sbd_toe_manual",
                     title: "Answer SbD-ToE Manual",
-                    description: "Faz retrieval do manual SbD-ToE e pede a resposta final ao modelo configurado no cliente via sampling MCP.",
+                    description: "Retrieves SbD-ToE manual context and requests the final answer from the client's model via MCP sampling. " +
+                        "Requires sampling support from the MCP client. " +
+                        "Without sampling, falls back to formatted retrieval output (same as search_sbd_toe_manual). " +
+                        "Prefer search_sbd_toe_manual for clients without sampling support.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             question: {
                                 type: "string",
-                                description: "Pergunta em linguagem natural sobre o manual."
+                                description: "Natural-language question about the manual."
                             },
                             debug: {
                                 type: "boolean",
-                                description: "Quando true, anexa o debug completo."
+                                description: "When true, appends full debug information."
                             },
                             topK: {
                                 type: "integer",
                                 minimum: 1,
                                 maximum: 15,
-                                description: "Número máximo de records usados como contexto."
+                                description: "Maximum number of records used as context."
                             }
                         },
                         required: ["question"],
@@ -354,19 +360,19 @@ class McpRuntime {
                 {
                     name: "inspect_sbd_toe_retrieval",
                     title: "Inspect SbD-ToE Retrieval",
-                    description: "Inspeciona retrieval, seleção de contexto e prompt final sem pedir resposta ao modelo do cliente.",
+                    description: "Inspects retrieval, context selection and final prompt without requesting an answer from the client model.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             question: {
                                 type: "string",
-                                description: "Pergunta a usar na inspeção do retrieval."
+                                description: "Question to use for the retrieval inspection."
                             },
                             topK: {
                                 type: "integer",
                                 minimum: 1,
                                 maximum: 15,
-                                description: "Número máximo de records selecionados para o prompt."
+                                description: "Maximum number of records selected for the prompt."
                             }
                         },
                         required: ["question"],
@@ -379,14 +385,14 @@ class McpRuntime {
                 {
                     name: "list_sbd_toe_chapters",
                     title: "List SbD-ToE Chapters",
-                    description: "Lista os capítulos do manual SbD-ToE com id, título e aplicabilidade.",
+                    description: "Lists SbD-ToE manual chapters with id, title and applicability.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             riskLevel: {
                                 type: "string",
                                 enum: ["L1", "L2", "L3"],
-                                description: "Filtrar por nível de risco."
+                                description: "Filter by risk level."
                             }
                         },
                         additionalProperties: false
@@ -396,7 +402,7 @@ class McpRuntime {
                 {
                     name: "query_sbd_toe_entities",
                     title: "Query SbD-ToE Entities",
-                    description: "Consulta entidades do manual por query, tipo, capítulo ou nível de risco.",
+                    description: "Queries manual entities by text, entity type, chapter or risk level.",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -414,7 +420,7 @@ class McpRuntime {
                 {
                     name: "get_sbd_toe_chapter_brief",
                     title: "Get SbD-ToE Chapter Brief",
-                    description: "Devolve resumo operacional de um capítulo: papel, fases, artefactos, intent_topics.",
+                    description: "Returns an operational summary of a chapter: role, phases, artefacts, intent_topics.",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -427,66 +433,22 @@ class McpRuntime {
                 },
                 {
                     name: "plan_sbd_toe_repo_governance",
-                    title: "Plan SbD-ToE Repo Governance",
-                    description: "Dado o tipo de repositório, plataforma e nível de risco, devolve um plano de governança com controlos aplicáveis, checkpoints de baseline, checklist de evidências e recomendações de plataforma.",
+                    title: "List SbD-ToE Manual Artefacts",
+                    description: "Returns the list of artefacts/documents identified in the SbD-ToE manual, " +
+                        "grouped by chapter, with risk level applicability. " +
+                        "Optionally filter by riskLevel (L1/L2/L3). " +
+                        "All data comes from the manual indices — nothing is invented. " +
+                        "The manual does not provide templates; ask the LLM to generate one if needed.",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            repoType: {
-                                type: "string",
-                                enum: ["library", "service", "webapp", "infrastructure", "pipeline", "monorepo"],
-                                description: "Tipo de repositório."
-                            },
-                            platform: {
-                                type: "string",
-                                enum: ["github", "gitlab"],
-                                description: "Plataforma de hosting do repositório."
-                            },
-                            riskLevel: {
-                                type: "string",
-                                enum: ["L1", "L2", "L3"],
-                                description: "Nível de risco do projecto."
-                            },
-                            organizationContext: {
-                                type: "object",
-                                description: "Contexto organizacional opcional.",
-                                properties: {
-                                    scale: { type: "string", enum: ["startup", "mid-size", "enterprise"] },
-                                    teamSize: { type: "integer", minimum: 1 },
-                                    enforcementLevel: { type: "string", enum: ["advisory", "enforced", "strict"] }
-                                },
-                                additionalProperties: false
-                            }
-                        },
-                        required: ["repoType", "platform", "riskLevel"],
-                        additionalProperties: false
-                    },
-                    annotations: { readOnlyHint: true }
-                },
-                {
-                    name: "generate_document",
-                    title: "Generate SbD-ToE Document",
-                    description: "Gera o esqueleto estruturado de um documento SbD-ToE (secções, campos obrigatórios, critérios de aceitação) para um tipo e nível de risco.",
-                    inputSchema: {
-                        type: "object",
-                        properties: {
-                            type: {
-                                type: "string",
-                                enum: ["classification-template", "threat-model-template", "checklist", "training-plan", "secure-config"],
-                                description: "Tipo de documento a gerar."
-                            },
                             riskLevel: {
                                 type: "string",
                                 enum: ["L1", "L2", "L3"],
-                                description: "Nível de risco do projecto."
-                            },
-                            context: {
-                                type: "object",
-                                description: "Contexto adicional do projecto (reservado, não usado na estrutura).",
-                                additionalProperties: true
+                                description: "Optional. If provided, only artefacts applicable at this risk level are returned."
                             }
                         },
-                        required: ["type", "riskLevel"],
+                        required: [],
                         additionalProperties: false
                     },
                     annotations: { readOnlyHint: true }
@@ -511,7 +473,7 @@ class McpRuntime {
                 {
                     name: "map_sbd_toe_review_scope",
                     title: "Map SbD-ToE Review Scope",
-                    description: "Dado um conjunto de ficheiros alterados, mapeia quais knowledge bundles SbD-ToE devem ser revistos, com reasoning explícito por path.",
+                    description: "Given a set of changed files, maps which SbD-ToE knowledge bundles should be reviewed, with explicit reasoning per path.",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -519,16 +481,16 @@ class McpRuntime {
                                 type: "array",
                                 items: { type: "string" },
                                 minItems: 1,
-                                description: "Lista de paths relativos ao raiz do repositório."
+                                description: "List of paths relative to the repository root."
                             },
                             riskLevel: {
                                 type: "string",
                                 enum: ["L1", "L2", "L3"],
-                                description: "Nível de risco do projecto."
+                                description: "Project risk level."
                             },
                             projectContext: {
                                 type: "object",
-                                description: "Contexto adicional do projecto (opcional).",
+                                description: "Additional project context (optional).",
                                 properties: {
                                     repoRole: { type: "string" },
                                     runtimeModel: { type: "string" },
@@ -539,7 +501,7 @@ class McpRuntime {
                             },
                             diffSummary: {
                                 type: "string",
-                                description: "Resumo do diff (truncado a 500 chars)."
+                                description: "Diff summary (truncated to 500 chars)."
                             }
                         },
                         required: ["changedFiles", "riskLevel"],
@@ -550,7 +512,7 @@ class McpRuntime {
                 {
                     name: "map_sbd_toe_applicability",
                     title: "Map SbD-ToE Applicability",
-                    description: "Mapeia capítulos/controlos activos, condicionais e excluídos para um nível de risco L1/L2/L3. Suporta contexto de projecto para activar bundles relevantes.",
+                    description: "Maps active, conditional and excluded chapters/controls for a given risk level L1/L2/L3. Supports project context to activate relevant bundles.",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -566,26 +528,161 @@ class McpRuntime {
                                         "network-segmentation", "cryptography"
                                     ]
                                 },
-                                description: "Tecnologias usadas no projecto."
+                                description: "Technologies used in the project."
                             },
                             hasPersonalData: {
                                 type: "boolean",
-                                description: "O projecto processa dados pessoais?"
+                                description: "Does the project process personal data?"
                             },
                             isPublicFacing: {
                                 type: "boolean",
-                                description: "O projecto tem exposição pública?"
+                                description: "Does the project have public-facing exposure?"
                             },
                             projectRole: {
                                 type: "string",
                                 enum: ["developer", "architect", "security", "devops", "manager"],
-                                description: "Papel do utilizador no projecto."
+                                description: "User role in the project."
                             }
                         },
                         required: ["riskLevel"],
                         additionalProperties: false
                     },
                     annotations: { readOnlyHint: true }
+                },
+                {
+                    name: "consult_security_requirements",
+                    title: "Consult SbD-ToE Security Requirements",
+                    description: "Deterministic resolution of security requirements and controls for a given application context. " +
+                        "Filters requirements by risk level, optionally narrows by concern domains (auth, logging, api, etc.), " +
+                        "then derives active controls via the ontology domain_mapping pipeline. " +
+                        "All data comes from the SbD-ToE ontology — nothing is invented.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            risk_level: {
+                                type: "string",
+                                enum: ["L1", "L2", "L3"],
+                                description: "Application risk level. Controls which requirements are active."
+                            },
+                            concerns: {
+                                type: "array",
+                                items: {
+                                    type: "string",
+                                    enum: ["auth", "logging", "validation", "api", "config", "integrity", "distribution", "ide", "requirements", "architecture", "iac", "encryption"]
+                                },
+                                description: "Optional concern domains to narrow scope (intersects with risk-level filter, does not replace)."
+                            },
+                            exposure: {
+                                type: "string",
+                                enum: ["local", "internal", "authenticated", "public"],
+                                description: "Application exposure level (informational — not yet used in filtering)."
+                            },
+                            data_sensitivity: {
+                                type: "string",
+                                enum: ["low", "personal", "regulated", "secrets"],
+                                description: "Data sensitivity level (informational — not yet used in filtering)."
+                            }
+                        },
+                        required: ["risk_level"],
+                        additionalProperties: false
+                    },
+                    annotations: { readOnlyHint: true }
+                },
+                {
+                    name: "get_threat_landscape",
+                    title: "Get SbD-ToE Threat Landscape",
+                    description: "Deterministic threat resolution for an application context using the SbD-ToE ontology threats pipeline. " +
+                        "Returns threats from mitigated_threats.json relevant to the active source chapters derived from " +
+                        "the risk-level-filtered requirements. Optionally narrowed by concern domains. " +
+                        "All data comes from the SbD-ToE ontology — nothing is invented.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            risk_level: {
+                                type: "string",
+                                enum: ["L1", "L2", "L3"],
+                                description: "Application risk level."
+                            },
+                            concerns: {
+                                type: "array",
+                                items: {
+                                    type: "string",
+                                    enum: ["auth", "logging", "validation", "api", "config", "integrity", "distribution", "ide", "requirements", "architecture", "iac", "encryption"]
+                                },
+                                description: "Optional concern domains to narrow which chapters are in scope."
+                            }
+                        },
+                        required: ["risk_level"],
+                        additionalProperties: false
+                    },
+                    annotations: { readOnlyHint: true }
+                },
+                {
+                    name: "get_guide_by_role",
+                    title: "Get SbD-ToE Guide by Role",
+                    description: "Returns practice assignments and user stories from the SbD-ToE manual for a given risk level, " +
+                        "optionally filtered by role and/or lifecycle phase. " +
+                        "Roles are resolved via canonical aliases (e.g. 'dev' → 'developer', 'appsec' → 'security-champion'). " +
+                        "Results grouped by role and phase. All data from the SbD-ToE ontology — nothing is invented.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            risk_level: {
+                                type: "string",
+                                enum: ["L1", "L2", "L3"],
+                                description: "Application risk level."
+                            },
+                            role: {
+                                type: "string",
+                                description: "Role to filter by (supports canonical IDs and aliases, e.g. 'developer', 'security-champion', 'devops', 'appsec')."
+                            },
+                            phase: {
+                                type: "string",
+                                description: "Lifecycle phase to filter by (e.g. 'design', 'implement', 'test', 'operate')."
+                            }
+                        },
+                        required: ["risk_level"],
+                        additionalProperties: false
+                    },
+                    annotations: { readOnlyHint: true }
+                },
+                {
+                    name: "resolve_entities",
+                    title: "Resolve SbD-ToE Entities",
+                    description: "Low-level entity resolver over the SbD-ToE enriched index. " +
+                        "Query any entity type by record_type with optional field filters. " +
+                        "Supports dot-notation for nested fields (e.g. 'applicable_levels.L2'), " +
+                        "comparison operators ({gte, lte} for numbers, {in: [...]} for set membership), " +
+                        "and array membership checks. " +
+                        "Use this when the high-level tools (consult_security_requirements, get_threat_landscape, " +
+                        "get_guide_by_role) do not cover your specific query. " +
+                        "All data from the SbD-ToE enriched entities index — nothing is invented.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            record_type: {
+                                type: "string",
+                                description: "Entity type to query. Well-known types: requirement, control, practice, threat, " +
+                                    "user_story, assignment, role, phase, maturity_mapping, chapter_bundle. " +
+                                    "Read sbd://toe/ontology to see all entity schemas."
+                            },
+                            filters: {
+                                type: "object",
+                                description: "Key-value filters on entity fields. " +
+                                    "Dot-notation for nested fields: {\"applicable_levels.L2\": true}. " +
+                                    "Comparison ops: {cvss_score: {gte: 7.0}} or {risk_level: {in: [\"L2\",\"L3\"]}}. " +
+                                    "Array fields: {roles_normalized: \"developer\"} checks membership.",
+                                additionalProperties: true
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Max results to return. Default: 50, max: 200."
+                            }
+                        },
+                        required: ["record_type"],
+                        additionalProperties: false
+                    },
+                    annotations: { readOnlyHint: true }
                 }
             ]
         });
@@ -594,11 +691,11 @@ class McpRuntime {
         return {
             name: "ask_sbd_toe_manual",
             title: "Ask SbD-ToE Manual",
-            description: "Prompt MCP para orientar o chat do VS Code a responder perguntas sobre o manual SbD-ToE com grounding.",
+            description: "MCP prompt to guide the AI chat to answer questions about the SbD-ToE manual with grounding.",
             arguments: [
                 {
                     name: "question",
-                    description: "Pergunta sobre o manual SbD-ToE.",
+                    description: "Question about the SbD-ToE manual.",
                     required: true
                 }
             ]
@@ -611,16 +708,16 @@ class McpRuntime {
                 {
                     name: "setup_sbd_toe_agent",
                     title: "Setup SbD-ToE Agent",
-                    description: "Prompt MCP para configurar um agente com o contexto e regras do manual SbD-ToE para um nível de risco.",
+                    description: "MCP prompt to configure an agent with SbD-ToE manual context and rules for a given risk level.",
                     arguments: [
                         {
                             name: "riskLevel",
-                            description: "Nível de risco do projecto: L1, L2 ou L3.",
+                            description: "Project risk level: L1, L2 or L3.",
                             required: true
                         },
                         {
                             name: "projectRole",
-                            description: "Papel ou descrição do projecto (opcional).",
+                            description: "Project role or description (optional).",
                             required: false
                         }
                     ]
@@ -636,10 +733,10 @@ class McpRuntime {
         if (name === "ask_sbd_toe_manual") {
             const question = typeof args.question === "string" ? args.question : "";
             const promptText = `${loadSystemPromptTemplate()}\n\n` +
-                "Use a ferramenta `search_sbd_toe_manual` antes de responder.\n" +
+                "Use the `search_sbd_toe_manual` tool before answering.\n" +
                 `Question: ${question}`;
             this.sendResponse(request.id, {
-                description: "Prompt grounded para perguntas sobre o manual SbD-ToE.",
+                description: "Grounded prompt for questions about the SbD-ToE manual.",
                 messages: [
                     {
                         role: "user",
@@ -655,13 +752,13 @@ class McpRuntime {
         if (name === "setup_sbd_toe_agent") {
             const riskLevel = args["riskLevel"];
             if (typeof riskLevel !== "string" || !["L1", "L2", "L3"].includes(riskLevel)) {
-                this.sendError(request.id, -32602, 'O argumento "riskLevel" é obrigatório e deve ser L1, L2 ou L3.');
+                this.sendError(request.id, -32602, 'The "riskLevel" argument is required and must be L1, L2 or L3.');
                 return;
             }
             const projectRole = typeof args["projectRole"] === "string" ? args["projectRole"] : undefined;
             const promptText = buildSetupAgentPrompt(riskLevel, projectRole);
             this.sendResponse(request.id, {
-                description: "Prompt para configurar um agente com o contexto SbD-ToE.",
+                description: "Prompt to configure an agent with SbD-ToE context.",
                 messages: [
                     {
                         role: "user",
@@ -674,7 +771,7 @@ class McpRuntime {
             });
             return;
         }
-        this.sendError(request.id, -32602, `Prompt desconhecida: ${name}`);
+        this.sendError(request.id, -32602, `Unknown prompt: ${name}`);
     }
     handleResourcesList(request) {
         this.sendResponse(request.id, {
@@ -696,6 +793,15 @@ class McpRuntime {
                     name: "SbD-ToE Index Compact",
                     description: "Compact JSON index of the full SbD-ToE manual. Injectable into system prompt to eliminate exploratory discovery.",
                     mimeType: "application/json"
+                },
+                {
+                    uri: "sbd://toe/ontology",
+                    name: "SbD-ToE Ontology",
+                    description: "Full SbD-ToE ontology YAML: domain_mapping (requirement category → control domains), " +
+                        "8 inference rules with priorities, 4 resolution pipelines (consult/guide/threats/review), " +
+                        "and entity schemas. Read once per session to understand the deterministic resolution model " +
+                        "before calling consult_security_requirements, get_threat_landscape or get_guide_by_role.",
+                    mimeType: "application/yaml"
                 }
             ]
         });
@@ -706,7 +812,7 @@ class McpRuntime {
         if (applicabilityMatch !== null) {
             const riskLevel = applicabilityMatch[1] ?? "";
             if (!["L1", "L2", "L3"].includes(riskLevel)) {
-                this.sendError(request.id, -32602, `riskLevel inválido: "${riskLevel}". Valores permitidos: L1, L2, L3.`);
+                this.sendError(request.id, -32602, `Invalid riskLevel: "${riskLevel}". Allowed values: L1, L2, L3.`);
                 return;
             }
             const data = buildChapterApplicabilityJson(riskLevel);
@@ -722,7 +828,7 @@ class McpRuntime {
                 indexText = readFileSync(indexPath, "utf-8");
             }
             catch {
-                this.sendError(request.id, -32603, "Não foi possível ler o índice compacto SbD-ToE.");
+                this.sendError(request.id, -32603, "Could not read the SbD-ToE compact index.");
                 return;
             }
             this.sendResponse(request.id, {
@@ -745,12 +851,27 @@ class McpRuntime {
             });
             return;
         }
-        this.sendError(request.id, -32602, `URI de resource desconhecida: ${uri}`);
+        if (uri === "sbd://toe/ontology") {
+            const ontologyPath = resolveAppPath("data/publish/sbdtoe-ontology.yaml");
+            let ontologyText;
+            try {
+                ontologyText = readFileSync(ontologyPath, "utf-8");
+            }
+            catch {
+                this.sendError(request.id, -32603, "Could not read SbD-ToE ontology YAML.");
+                return;
+            }
+            this.sendResponse(request.id, {
+                contents: [{ uri, mimeType: "application/yaml", text: ontologyText }]
+            });
+            return;
+        }
+        this.sendError(request.id, -32602, `Unknown resource URI: ${uri}`);
     }
     getStringArg(args, key) {
         const value = args[key];
         if (typeof value !== "string" || value.trim().length === 0) {
-            throw new Error(`O argumento "${key}" é obrigatório.`);
+            throw new Error(`The "${key}" argument is required.`);
         }
         return value;
     }
@@ -768,7 +889,7 @@ class McpRuntime {
     }
     async requestSampling(systemPrompt, userPrompt) {
         if (!this.supportsSampling()) {
-            throw new Error("O cliente MCP atual não declarou suporte para sampling.");
+            throw new Error("The current MCP client has not declared sampling support.");
         }
         const startedAt = Date.now();
         await this.log("debug", {
@@ -903,15 +1024,13 @@ class McpRuntime {
                     const debug = this.getOptionalBooleanArg(args, "debug");
                     const topK = this.getOptionalIntegerArg(args, "topK");
                     if (!this.supportsSampling()) {
-                        // Fallback gracioso: devolver top-3 documentos sem sampling
-                        const bundle = await retrievePublishedContext(question, 3);
-                        const fallbackResult = {
-                            sampling_unavailable: true,
-                            note: "Sampling não disponível neste cliente. Apresentando os 3 documentos mais relevantes como contexto.",
-                            results: bundle.retrieved
-                        };
+                        // Graceful fallback: delegate to searchManualQuestion (same retrieval, formatted output)
+                        const fallback = await searchManualQuestion(question, debug, topK ?? 3);
+                        const fallbackText = "**Note: MCP sampling not available in this client — returning formatted retrieval results. " +
+                            "For a synthesised answer, use `search_sbd_toe_manual` directly.**\n\n" +
+                            fallback.text;
                         this.sendResponse(request.id, {
-                            content: [{ type: "text", text: JSON.stringify(fallbackResult, null, 2) }]
+                            content: [{ type: "text", text: fallbackText }]
                         });
                         await this.log("info", {
                             event_type: "tool.call",
@@ -983,7 +1102,7 @@ class McpRuntime {
                     return;
                 }
                 case "plan_sbd_toe_repo_governance": {
-                    const result = handlePlanRepoGovernance(args);
+                    const result = handlePlanRepoGovernance(args, getSnapshotCache());
                     this.sendResponse(request.id, {
                         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
                     });
@@ -996,8 +1115,8 @@ class McpRuntime {
                     });
                     return;
                 }
-                case "generate_document": {
-                    const result = handleGenerateDocument(args);
+                case "generate_sbd_toe_skill": {
+                    const result = handleGenerateSbdToeSkill();
                     this.sendResponse(request.id, {
                         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
                     });
@@ -1010,8 +1129,8 @@ class McpRuntime {
                     });
                     return;
                 }
-                case "generate_sbd_toe_skill": {
-                    const result = handleGenerateSbdToeSkill();
+                case "map_sbd_toe_review_scope": {
+                    const result = handleMapSbdToeReviewScope(args);
                     this.sendResponse(request.id, {
                         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
                     });
@@ -1024,8 +1143,9 @@ class McpRuntime {
                     });
                     return;
                 }
-                case "map_sbd_toe_review_scope": {
-                    const result = handleMapSbdToeReviewScope(args);
+                case "map_sbd_toe_applicability": {
+                    const cache = getSnapshotCache();
+                    const result = handleMapSbdToeApplicability(args, cache);
                     this.sendResponse(request.id, {
                         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
                     });
@@ -1038,9 +1158,50 @@ class McpRuntime {
                     });
                     return;
                 }
-                case "map_sbd_toe_applicability": {
-                    const cache = getSnapshotCache();
-                    const result = handleMapSbdToeApplicability(args, cache);
+                case "consult_security_requirements": {
+                    const result = handleConsultSecurityRequirements(args);
+                    this.sendResponse(request.id, {
+                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+                    });
+                    await this.log("info", {
+                        event_type: "tool.call",
+                        outcome: "succeeded",
+                        duration_ms: Date.now() - startedAt,
+                        ...metadata,
+                        message: "Tool invocation completed"
+                    });
+                    return;
+                }
+                case "get_threat_landscape": {
+                    const result = handleGetThreatLandscape(args);
+                    this.sendResponse(request.id, {
+                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+                    });
+                    await this.log("info", {
+                        event_type: "tool.call",
+                        outcome: "succeeded",
+                        duration_ms: Date.now() - startedAt,
+                        ...metadata,
+                        message: "Tool invocation completed"
+                    });
+                    return;
+                }
+                case "get_guide_by_role": {
+                    const result = handleGetGuideByRole(args);
+                    this.sendResponse(request.id, {
+                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+                    });
+                    await this.log("info", {
+                        event_type: "tool.call",
+                        outcome: "succeeded",
+                        duration_ms: Date.now() - startedAt,
+                        ...metadata,
+                        message: "Tool invocation completed"
+                    });
+                    return;
+                }
+                case "resolve_entities": {
+                    const result = handleResolveEntities(args);
                     this.sendResponse(request.id, {
                         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
                     });
@@ -1062,11 +1223,11 @@ class McpRuntime {
                         error_code: -32602,
                         message: "Unknown tool requested"
                     });
-                    this.sendError(request.id, -32602, `Tool desconhecida: ${name}`);
+                    this.sendError(request.id, -32602, `Unknown tool: ${name}`);
             }
         }
         catch (error) {
-            // Erros com rpcError emitem JSON-RPC error (ex: -32602 para input inválido)
+            // Errors with rpcError emit JSON-RPC error (e.g. -32602 for invalid input)
             if (error instanceof Error &&
                 "rpcError" in error &&
                 error.rpcError !== null &&
@@ -1083,7 +1244,7 @@ class McpRuntime {
                 this.sendError(request.id, rpcError.code, rpcError.message, rpcError.data);
                 return;
             }
-            const message = error instanceof Error ? error.message : "Erro inesperado.";
+            const message = error instanceof Error ? error.message : "Unexpected error.";
             await this.log("error", {
                 event_type: "tool.call",
                 outcome: "failed",