@trillet-ai/mcp 0.7.3

package/dist/tools/flowSettings.js

@@ -0,0 +1,406 @@
+import { z } from "zod";
+import { ok, guard, workspaceParam } from "../helpers.js";
+const perDaySchema = z
+    .record(z.string(), z.object({ enabled: z.boolean(), start: z.string(), end: z.string() }))
+    .describe('FULL day names as keys: {"Monday": {enabled, start "HH:MM", end "HH:MM"}, ...}');
+const transferSchema = z
+    .object({
+    friendly_name: z.string().describe("Unique per flow; how the prompt refers to this transfer"),
+    method: z
+        .enum(["warm", "cold", "whisper", "agent"])
+        .default("cold")
+        .describe("The transfer type field is named method, NOT type"),
+    destination: z.string().describe("E.164 number, or target agent/pathway id for method=agent"),
+    destinationType: z.enum(["SIP", "dynamic", "variable", "agent"]).default("SIP"),
+    isSummary: z.boolean().default(true).describe("Speak a summary to the receiving human (warm)"),
+    summary_format: z.string().optional(),
+    warmTransferTimeout: z.number().optional().describe("Seconds to wait for pickup (15-60 typical)"),
+    transferTimeoutAction: z.enum(["end_call", "continue_with_message"]).optional(),
+    timeoutMessage: z.string().optional(),
+    extension: z.string().optional().describe("DTMF digits dialled after connect"),
+    transferGreetingMessage: z.string().optional().describe("Spoken to the caller before transferring"),
+    transferInitiationMessage: z.string().optional(),
+    conditionGroups: z
+        .array(z.object({
+        error_message: z.string(),
+        conditions: z.array(z.object({
+            conditional_variable: z.string().describe('e.g. "_response.customer_id"'),
+            operator: z.enum(["exists", "not_empty", "equals", "not_equals", "greater_than", "less_than"]),
+            value: z.string().optional(),
+            connector: z.enum(["AND", "OR"]).optional(),
+        })),
+    }))
+        .optional()
+        .describe("Gate the transfer on call state; error_message is spoken when blocked"),
+    officeHoursRestriction: z
+        .object({
+        enabled: z.boolean(),
+        error_message: z.string().optional(),
+        specialDays_error_message: z.string().optional(),
+        perDay: perDaySchema.optional(),
+        specialDays: z.array(z.string()).optional().describe('Blocked dates ["YYYY-MM-DD"]'),
+    })
+        .optional()
+        .describe("BLOCK the transfer outside hours (agent apologises instead)"),
+    businessHoursRouting: z
+        .object({
+        enabled: z.boolean(),
+        timezone: z.string().describe("IANA timezone"),
+        schedule: perDaySchema.describe("NOTE: key is 'schedule' here, not 'perDay'"),
+        workingHours: z.object({
+            destinations: z.array(z.string()).describe("Ordered E.164 list, tried sequentially"),
+            message: z.string().optional(),
+            blocked: z.boolean().optional(),
+            blocked_message: z.string().optional(),
+        }),
+        afterHours: z.object({
+            destinations: z.array(z.string()),
+            message: z.string().optional(),
+            blocked: z.boolean().optional(),
+            blocked_message: z.string().optional(),
+        }),
+    })
+        .optional()
+        .describe("REROUTE by time of day. Validation: each of workingHours/afterHours needs >=1 destination unless blocked=true, else the save 400s."),
+    custom_headers: z
+        .array(z.object({ key: z.string(), value: z.string() }))
+        .optional()
+        .describe("SIP headers; values support {{_metadata.X}} / {{_response.X}} placeholders"),
+})
+    .describe("One transfer destination");
+export function registerFlowSettingTools(server, client) {
+    const putSettings = async (flow_id, settings, workspace_id) => {
+        const res = await client.request("PUT", `/v1/api/call-flows/${flow_id}`, {
+            body: { settings },
+            workspaceId: workspace_id,
+        });
+        return res.pathway ?? res;
+    };
+    server.registerTool("trillet_set_transfers", {
+        title: "Set call transfers",
+        description: "Replace the flow's transfer destinations (COMPLETE array; arrays replace wholesale). Transfers let the agent hand the call to humans: method warm (announce first), cold (blind), whisper, or agent (another AI flow). To let the model trigger them, also mention each transfer's friendly_name in the prompt. Set enableTransferInstructions true on settings when transfers exist (this tool does it automatically when the list is non-empty).",
+        inputSchema: {
+            flow_id: z.string(),
+            transfers: z.array(transferSchema),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, transfers, workspace_id }) => {
+        const p = await putSettings(flow_id, { transfers, enableTransferInstructions: transfers.length > 0 }, workspace_id);
+        return ok({
+            id: p._id,
+            transfers: (p.settings?.transfers ?? []).map((t) => `${t.friendly_name} (${t.method} -> ${t.destination})`),
+        });
+    }));
+    server.registerTool("trillet_set_office_hours", {
+        title: "Set flow office hours",
+        description: "Set the flow-level office hours (settings.OfficeHoursSettings, perDay shape with FULL day names). SEMANTICS: this DEFERS OUTBOUND calls to the next open slot (call shows as scheduled with pendingReason office_hours); it does NOT block inbound calls. To gate transfers by time use officeHoursRestriction/businessHoursRouting on the transfer instead.",
+        inputSchema: {
+            flow_id: z.string(),
+            enabled: z.boolean(),
+            timezone: z.string().describe("IANA timezone, e.g. Australia/Melbourne"),
+            per_day: perDaySchema,
+            blocked_dates: z.array(z.string()).default([]).describe('["YYYY-MM-DD"]'),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, enabled, timezone, per_day, blocked_dates, workspace_id }) => {
+        const p = await putSettings(flow_id, { OfficeHoursSettings: { enabled, timezone, perDay: per_day, blockedDates: blocked_dates } }, workspace_id);
+        return ok({ id: p._id, OfficeHoursSettings: p.settings?.OfficeHoursSettings });
+    }));
+    server.registerTool("trillet_set_call_settings", {
+        title: "Set call settings",
+        description: "Update call behavior settings (deep-merges; only sent keys change). Covers silence handling, duration limits, voicemail detection, IVR navigation, recording, LLM cache, transcript redaction, and post-call analysis model.",
+        inputSchema: {
+            flow_id: z.string(),
+            end_call_on_silence: z.number().optional().describe("Seconds of caller silence before ending"),
+            silence_reminder_retries: z.number().optional(),
+            max_call_duration: z.number().optional().describe("Seconds (default 1800)"),
+            max_call_duration_message: z.string().optional(),
+            reminder_messages: z.array(z.string()).optional(),
+            post_call_analysis_model: z.string().optional().describe('Default "gemini-2.5-flash"'),
+            disable_metadata: z.boolean().optional().describe("Stop auto-appending call metadata to in-call API requests (required for strict APIs)"),
+            redact_transcription: z.boolean().optional(),
+            enable_llm_cache: z.boolean().optional().describe("CAUTION: also defers {{var}} substitution to speak-time"),
+            voicemail_detection: z
+                .object({
+                enabled: z.boolean(),
+                action: z.enum(["hangup", "leave_message"]),
+                leaveMessage: z.string().optional(),
+                amdDetection: z.boolean().optional(),
+                amdTimeout: z.number().optional(),
+            })
+                .optional(),
+            ivr_handling: z
+                .object({
+                enabled: z.boolean(),
+                mode: z.enum(["converse", "auto", "sequence"]).describe("sequence requires keySequence"),
+                keySequence: z.array(z.string()).optional().describe("Digits/*/# steps, max 10 (only for mode=sequence)"),
+                maxAttempts: z.number().optional(),
+                dtmfDelaySeconds: z.number().optional(),
+                priorityList: z.array(z.string()).optional().describe("What to ask the IVR for, in priority order (auto mode)"),
+                holdQueue: z.object({ enabled: z.boolean(), maxWaitSeconds: z.number() }).optional(),
+            })
+                .optional()
+                .describe("Outbound IVR menu navigation. There is no separate dtmfSettings key; DTMF lives here."),
+            enable_recording: z.boolean().optional().describe("settings.enableRecording (flow-level)"),
+            enable_public_recording: z.boolean().optional(),
+            customer_location: z.string().optional().describe("IANA timezone used for time context and timestamps"),
+            time_context_enabled: z.boolean().optional().describe("Agent knows current date/time (on unless explicitly false)"),
+            utilize_prior_calls_context: z.boolean().optional(),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guard(async (a) => {
+        const cs = {};
+        if (a.end_call_on_silence !== undefined)
+            cs.endCallOnSilence = a.end_call_on_silence;
+        if (a.silence_reminder_retries !== undefined)
+            cs.silenceReminderRetries = a.silence_reminder_retries;
+        if (a.max_call_duration !== undefined)
+            cs.maxCallDuration = a.max_call_duration;
+        if (a.max_call_duration_message !== undefined)
+            cs.maxCallDurationMessage = a.max_call_duration_message;
+        if (a.reminder_messages !== undefined)
+            cs.reminderMessages = a.reminder_messages;
+        if (a.post_call_analysis_model !== undefined)
+            cs.postCallAnalysisModel = a.post_call_analysis_model;
+        if (a.disable_metadata !== undefined)
+            cs.disableMetadata = a.disable_metadata;
+        if (a.redact_transcription !== undefined)
+            cs.redactTranscription = a.redact_transcription;
+        if (a.enable_llm_cache !== undefined)
+            cs.enableLlmCache = a.enable_llm_cache;
+        if (a.voicemail_detection !== undefined)
+            cs.voicemailDetection = a.voicemail_detection;
+        if (a.ivr_handling !== undefined)
+            cs.ivrHandling = a.ivr_handling;
+        const settings = {};
+        if (Object.keys(cs).length)
+            settings.callSetting = cs;
+        if (a.enable_recording !== undefined)
+            settings.enableRecording = a.enable_recording;
+        if (a.enable_public_recording !== undefined)
+            settings.enablePublicRecording = a.enable_public_recording;
+        if (a.customer_location !== undefined)
+            settings.customerLocation = a.customer_location;
+        if (a.time_context_enabled !== undefined)
+            settings.timeContextEnabled = a.time_context_enabled;
+        if (a.utilize_prior_calls_context !== undefined)
+            settings.utilizePriorCallsContext = a.utilize_prior_calls_context;
+        const p = await putSettings(a.flow_id, settings, a.workspace_id);
+        return ok({ id: p._id, callSetting: p.settings?.callSetting, applied: Object.keys(settings) });
+    }));
+    server.registerTool("trillet_set_speech_settings", {
+        title: "Set speech settings",
+        description: "Tune conversational feel: responsiveness (1-10, higher = replies faster), interruptionSensitivity (1-10, higher = easier for the caller to interrupt; 5.5 recommended), vadModel, preemptive generation, TTS pronunciation overrides, and welcome message behavior.",
+        inputSchema: {
+            flow_id: z.string(),
+            responsiveness: z.number().optional(),
+            interruption_sensitivity: z.number().optional(),
+            vad_model: z.string().optional().describe('"stt" | "default" | "multilingualModel"'),
+            enable_preemptive_generation: z.boolean().optional(),
+            pronunciation: z
+                .array(z.object({ word: z.string(), alias: z.string() }))
+                .optional()
+                .describe("TTS pronunciation overrides (how the agent SAYS words)"),
+            welcome_message_interruptible: z.boolean().optional(),
+            welcome_message_delay_ms: z.number().optional().describe("0-5000 ms"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guard(async (a) => {
+        const ss = {};
+        if (a.responsiveness !== undefined)
+            ss.responsiveness = a.responsiveness;
+        if (a.interruption_sensitivity !== undefined)
+            ss.interruptionSensitivity = a.interruption_sensitivity;
+        if (a.vad_model !== undefined)
+            ss.vadModel = a.vad_model;
+        if (a.enable_preemptive_generation !== undefined)
+            ss.enablePreemptiveGeneration = a.enable_preemptive_generation;
+        if (a.pronunciation !== undefined)
+            ss.pronunciation = a.pronunciation;
+        const settings = {};
+        if (Object.keys(ss).length)
+            settings.speechSetting = ss;
+        if (a.welcome_message_interruptible !== undefined)
+            settings.welcomeMessageInterruptible = a.welcome_message_interruptible;
+        if (a.welcome_message_delay_ms !== undefined)
+            settings.welcomeMessageDelay = a.welcome_message_delay_ms;
+        const p = await putSettings(a.flow_id, settings, a.workspace_id);
+        return ok({ id: p._id, speechSetting: p.settings?.speechSetting });
+    }));
+    server.registerTool("trillet_set_welcome_message", {
+        title: "Set welcome message",
+        description: "Set the greeting for inbound and/or outbound (and web test) calls. selected 'customMessage' speaks the exact text; 'aiFirst' lets the model generate from aiGreetingPrompt. NEVER also script a greeting inside the prompt (causes double greeting). Web/dashboard test calls use the Outbound greeting.",
+        inputSchema: {
+            flow_id: z.string(),
+            inbound_message: z.string().optional(),
+            outbound_message: z.string().optional(),
+            mode: z.enum(["customMessage", "aiFirst"]).default("customMessage"),
+            ai_greeting_prompt: z.string().optional().describe("Only for mode aiFirst"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, inbound_message, outbound_message, mode, ai_greeting_prompt, workspace_id }) => {
+        const mk = (msg) => ({
+            selected: mode,
+            customMessage: msg ?? "",
+            aiGreetingPrompt: ai_greeting_prompt ?? "",
+        });
+        const cfg = {};
+        if (inbound_message !== undefined || mode === "aiFirst")
+            cfg.Inbound = mk(inbound_message);
+        if (outbound_message !== undefined || mode === "aiFirst")
+            cfg.Outbound = mk(outbound_message);
+        const p = await putSettings(flow_id, { welcomeMessageConfig: cfg }, workspace_id);
+        return ok({ id: p._id, welcomeMessageConfig: p.settings?.welcomeMessageConfig });
+    }));
+    server.registerTool("trillet_set_code_actions", {
+        title: "Set code actions (feature-gated)",
+        description: "Replace the flow's code actions: Python functions the agent can run mid-call ({name, description, code, variables[{name,description}]}). FEATURE-GATED per workspace: non-whitelisted workspaces get the codeActions SILENTLY STRIPPED (the save returns 200 without them) — this tool verifies persistence and reports if the workspace lacks access.",
+        inputSchema: {
+            flow_id: z.string(),
+            code_actions: z.array(z.object({
+                name: z.string(),
+                description: z.string(),
+                code: z.string().describe("Python source"),
+                enabled: z.boolean().default(true),
+                variables: z.array(z.object({ name: z.string(), description: z.string() })).default([]),
+            })),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, code_actions, workspace_id }) => {
+        const body = { codeActions: code_actions.map((c) => ({ ...c, language: "python" })) };
+        const res = await client.request("PUT", `/v1/api/call-flows/${flow_id}`, {
+            body,
+            workspaceId: workspace_id,
+        });
+        const p = res.pathway ?? res;
+        const saved = (p.codeActions ?? []).map((c) => c.name);
+        const requested = code_actions.map((c) => c.name);
+        const stripped = requested.filter((n) => !saved.includes(n));
+        return ok({
+            id: p._id,
+            savedCodeActions: saved,
+            ...(stripped.length
+                ? {
+                    warning: `Workspace is not whitelisted for CODE_ACTIONS; these were silently stripped by the API: ${stripped.join(", ")}. Ask Trillet to whitelist the workspace.`,
+                }
+                : {}),
+        });
+    }));
+    server.registerTool("trillet_set_background_audio", {
+        title: "Set background audio",
+        description: "Set the flow's background audio (settings.backgroundNoise, deep-merges; only sent keys change): an ambient soundscape played under the whole call, a thinking sound while the model generates, and hold music during transfers, each with its own 0-1 volume. Use ambient_sound \"none\" to switch ambience off.",
+        inputSchema: {
+            flow_id: z.string(),
+            ambient_sound: z
+                .string()
+                .optional()
+                .describe('Ambient background sound: "none", "call_center.mp3", or "quiet_office.mp3"'),
+            thinking_sound: z
+                .string()
+                .optional()
+                .describe('Sound played while the AI is thinking: "none" or "keyboard"'),
+            hold_sound: z
+                .string()
+                .optional()
+                .describe('Hold music during transfers: only "none" is available (plays the platform Lobby Hold Music)'),
+            ambient_volume: z.number().min(0).max(1).optional().describe("Ambient volume 0-1 (default 0.5)"),
+            thinking_volume: z.number().min(0).max(1).optional().describe("Thinking-sound volume 0-1 (default 0.5)"),
+            hold_volume: z.number().min(0).max(1).optional().describe("Hold-music volume 0-1 (default 0.5)"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guard(async (a) => {
+        const noise = {};
+        if (a.ambient_sound !== undefined)
+            noise.ambient_sound = a.ambient_sound;
+        if (a.thinking_sound !== undefined)
+            noise.thinking_sound = a.thinking_sound;
+        if (a.hold_sound !== undefined)
+            noise.hold_sound = a.hold_sound;
+        if (a.ambient_volume !== undefined)
+            noise.ambient_volume = a.ambient_volume;
+        if (a.thinking_volume !== undefined)
+            noise.thinking_volume = a.thinking_volume;
+        if (a.hold_volume !== undefined)
+            noise.hold_volume = a.hold_volume;
+        if (!Object.keys(noise).length)
+            return ok({ error: "No changes specified" });
+        const p = await putSettings(a.flow_id, { backgroundNoise: noise }, a.workspace_id);
+        return ok({ id: p._id, backgroundNoise: p.settings?.backgroundNoise });
+    }));
+    server.registerTool("trillet_set_security_settings", {
+        title: "Set security and access settings",
+        description: "Update the flow's security, access and memory settings (deep-merges; only sent keys change). Covers HIPAA compliance (settings.security.hipaaCompliance; enabling it also turns call recording off, as the dashboard does), public access for demo links (settings.security.publicAccess), redirect-incoming-calls-to-a-human (settings.redirectToHuman: forwards inbound calls straight to a number, optionally gated by conditions), and identifier-based web demo memory (settings.identifierBasedWebDemoMemory; needs utilizePriorCallsContext on, see trillet_set_call_settings).",
+        inputSchema: {
+            flow_id: z.string(),
+            hipaa_compliance: z
+                .boolean()
+                .optional()
+                .describe("Enable HIPAA compliance. Enabling also disables enableRecording and enablePublicRecording."),
+            public_access: z
+                .boolean()
+                .optional()
+                .describe("Allow public (unauthenticated) access to this flow, e.g. for web demo links"),
+            redirect_to_human: z
+                .object({
+                enabled: z.boolean().optional().describe("Forward inbound calls to a human instead of the AI"),
+                phoneNumber: z.string().optional().describe("E.164 number to redirect to"),
+                redirectMessageEnabled: z.boolean().optional().describe("Speak a message before redirecting"),
+                redirectMessage: z.string().optional().describe("Message spoken before the redirect"),
+                conditions: z
+                    .array(z.object({
+                    conditional_variable: z.string().describe('Response variable path, e.g. "_response.vip"'),
+                    operator: z.enum(["exists", "not_empty", "equals", "not_equals", "greater_than", "less_than"]),
+                    value: z.string().optional().describe("Only for equals/not_equals/greater_than/less_than"),
+                    error_message: z.string().optional(),
+                }))
+                    .optional()
+                    .describe("Only redirect when every condition holds (array replaces wholesale)"),
+            })
+                .optional()
+                .describe("settings.redirectToHuman (the dashboard's Redirect incoming calls section)"),
+            identifier_based_web_demo_memory: z
+                .boolean()
+                .optional()
+                .describe("Remember web demo visitors by identifier across sessions (requires utilizePriorCallsContext)"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guard(async (a) => {
+        const settings = {};
+        const security = {};
+        if (a.hipaa_compliance !== undefined) {
+            security.hipaaCompliance = a.hipaa_compliance;
+            if (a.hipaa_compliance) {
+                settings.enableRecording = false;
+                settings.enablePublicRecording = false;
+            }
+        }
+        if (a.public_access !== undefined)
+            security.publicAccess = a.public_access;
+        if (Object.keys(security).length)
+            settings.security = security;
+        if (a.redirect_to_human !== undefined) {
+            settings.redirectToHuman = Object.fromEntries(Object.entries(a.redirect_to_human).filter(([, v]) => v !== undefined));
+        }
+        if (a.identifier_based_web_demo_memory !== undefined)
+            settings.identifierBasedWebDemoMemory = a.identifier_based_web_demo_memory;
+        if (!Object.keys(settings).length)
+            return ok({ error: "No changes specified" });
+        const p = await putSettings(a.flow_id, settings, a.workspace_id);
+        return ok({
+            id: p._id,
+            security: p.settings?.security,
+            redirectToHuman: p.settings?.redirectToHuman,
+            identifierBasedWebDemoMemory: p.settings?.identifierBasedWebDemoMemory,
+            enableRecording: p.settings?.enableRecording,
+            applied: Object.keys(settings),
+        });
+    }));
+}

package/dist/tools/knowledgeBases.js

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import { ok, guard, workspaceParam } from "../helpers.js";
+const MIME = {
+    ".pdf": "application/pdf",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".csv": "text/csv",
+    ".json": "application/json",
+};
+export function registerKnowledgeBaseTools(server, client) {
+    server.registerTool("trillet_list_knowledge_bases", {
+        title: "List knowledge bases",
+        description: "List the workspace's knowledge bases: id, name, description, file/text presence.",
+        inputSchema: { ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ workspace_id }) => {
+        const res = await client.request("GET", "/v1/api/knowledgebase/", {
+            workspaceId: workspace_id,
+        });
+        const list = Array.isArray(res) ? res : res.knowledgeBases ?? res.data ?? [];
+        return ok(list.map((k) => ({
+            id: k._id,
+            name: k.name,
+            description: k.description,
+            files: (k.files ?? []).map((f) => f.fileName ?? f.fileKey ?? f),
+            hasText: Boolean(k.textContent),
+            updatedAt: k.updatedAt,
+        })));
+    }));
+    server.registerTool("trillet_get_knowledge_base", {
+        title: "Get knowledge base",
+        description: "Fetch one knowledge base (metadata + file list), optionally with which call flows use it (include_usage).",
+        inputSchema: {
+            knowledge_base_id: z.string(),
+            include_usage: z.boolean().default(false),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ knowledge_base_id, include_usage, workspace_id }) => {
+        const kb = await client.request("GET", `/v1/api/knowledgebase/${knowledge_base_id}`, {
+            workspaceId: workspace_id,
+        });
+        const out = { knowledgeBase: kb.knowledgeBase ?? kb };
+        if (include_usage) {
+            out.usage = await client
+                .request("GET", `/v1/api/knowledgebase/${knowledge_base_id}/usage`, {
+                workspaceId: workspace_id,
+            })
+                .catch((e) => ({ error: String(e?.message ?? e) }));
+        }
+        return ok(out);
+    }));
+    server.registerTool("trillet_delete_knowledge_base", {
+        title: "Delete knowledge base (or one file)",
+        description: "Delete an entire knowledge base, or just one file from it when file_key is given. Check usage first (trillet_get_knowledge_base include_usage=true): flows still pointing at a deleted KB lose retrieval. Always confirm with the user; requires confirm=true.",
+        inputSchema: {
+            knowledge_base_id: z.string(),
+            file_key: z.string().optional().describe("Delete only this file (fileKey) instead of the whole KB"),
+            confirm: z
+                .boolean()
+                .describe("Must be true. Only set after the user explicitly approved the deletion."),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ knowledge_base_id, file_key, confirm, workspace_id }) => {
+        if (!confirm) {
+            return ok({
+                blocked: true,
+                message: "Refusing to delete: confirm=false. Ask the user to approve and retry with confirm=true.",
+            });
+        }
+        const path = file_key
+            ? `/v1/api/knowledgebase/knowledgeBases/${knowledge_base_id}/files/${file_key}`
+            : `/v1/api/knowledgebase/${knowledge_base_id}`;
+        const res = await client.request("DELETE", path, { workspaceId: workspace_id });
+        return ok(res ?? { deleted: file_key ?? knowledge_base_id });
+    }));
+    server.registerTool("trillet_create_knowledge_base", {
+        title: "Create knowledge base",
+        description: "Create an empty knowledge base. Add content with trillet_add_kb_text or trillet_upload_kb_file, then attach it to a call flow with trillet_attach_knowledge_bases.",
+        inputSchema: {
+            name: z.string(),
+            description: z.string().optional(),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, guard(async ({ name, description, workspace_id }) => {
+        const res = await client.request("POST", "/v1/api/knowledgebase/", {
+            body: { name, description },
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_add_kb_text", {
+        title: "Add text to knowledge base",
+        description: "Add plain-text content to a knowledge base. The text is chunked and vector-embedded immediately.",
+        inputSchema: {
+            knowledge_base_id: z.string(),
+            text: z.string().describe("The content to embed"),
+            name: z.string().optional().describe("Label for this text block"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, guard(async ({ knowledge_base_id, text, name, workspace_id }) => {
+        const res = await client.request("POST", `/v1/api/knowledgebase/${knowledge_base_id}/text`, { body: { text, name }, workspaceId: workspace_id });
+        return ok(res);
+    }));
+    server.registerTool("trillet_upload_kb_file", {
+        title: "Upload file to knowledge base",
+        description: "Upload a local file (PDF, DOCX, TXT, MD, CSV, JSON) to a knowledge base. Text is extracted and vector-embedded synchronously in the same request. GOTCHA: each knowledge base holds ONE file; uploading replaces the existing file. Use separate knowledge bases for separate documents.",
+        inputSchema: {
+            knowledge_base_id: z.string(),
+            file_path: z.string().describe("Absolute path to the local file"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ knowledge_base_id, file_path, workspace_id }) => {
+        const data = await readFile(file_path);
+        const mimetype = MIME[extname(file_path).toLowerCase()] ?? "application/octet-stream";
+        const res = await client.upload(`/v1/api/knowledgebase/${knowledge_base_id}/files`, "uploadedFile", basename(file_path), data, mimetype, workspace_id);
+        return ok(res);
+    }));
+    server.registerTool("trillet_attach_knowledge_bases", {
+        title: "Attach knowledge bases to call flow",
+        description: "Set the COMPLETE list of knowledge base ids on a call flow (the list replaces the previous one; pass an empty array to detach all). The runtime automatically retrieves relevant content during calls.",
+        inputSchema: {
+            flow_id: z.string(),
+            knowledge_base_ids: z.array(z.string()),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, knowledge_base_ids, workspace_id }) => {
+        const res = await client.request("PUT", `/v1/api/call-flows/${flow_id}`, {
+            body: { settings: { knowledgeBases: knowledge_base_ids } },
+            workspaceId: workspace_id,
+        });
+        const p = res.pathway ?? res;
+        return ok({ id: p._id, knowledgeBases: p.settings?.knowledgeBases });
+    }));
+}