@unboundai/tb-ppt-mgagent 0.5.0 → 0.7.0

package/README.md

@@ -2,25 +2,69 @@
 
 A Model Context Protocol (MCP) server that hands a presentation outline to Anthropic's hosted **Managed Agent** for building Traffic Builders-branded PowerPoints, then retrieves the finished file once it's done.
 
-Brand assets (the design brief, logos, Outfit font) are **not** assumed to already exist in the agent's environment. A Managed Agents "deployment" (scheduled/cron runs) was investigated as a way to pin a session to a specific pre-configured setup, but it only re-sends a fixed baked-in message on a schedule — it offers no extra asset-targeting capability over a plain session. So instead, this server uploads each brand asset once via the Files API (a one-time step, see [Setup](#setup)) and attaches them explicitly to **every** session it creates via the `resources` array, mounted into the sandbox for the agent to read.
+Brand assets (the design brief, logos, Outfit and Figtree fonts) are **not** assumed to already exist in the agent's environment. A Managed Agents "deployment" (scheduled/cron runs) was investigated as a way to pin a session to a specific pre-configured setup, but it only re-sends a fixed baked-in message on a schedule — it offers no extra asset-targeting capability over a plain session. So instead, this server uploads each brand asset once via the Files API (a one-time step, see [Setup](#setup)) and attaches them explicitly to **every** session it creates via the `resources` array, mounted into the sandbox for the agent to read.
 
 Built against the official Managed Agents docs (session creation, session operations, events & streaming, files, event/type reference) using the official `@anthropic-ai/sdk` client, which sets the `managed-agents-2026-04-01` beta header automatically for session endpoints.
 
 ## Available tools
 
-- **`generate_tb_powerpoint(outline, deckType?, clientName?, filename?)`** — creates a session against the configured agent + environment, attaches whichever brand asset `resources` are configured (see Setup), sends the outline as the first message, returns `{ success, sessionId, message }`. Does not wait for the deck to finish.
+- **`generate_tb_powerpoint(outline, deckType?, clientName?, filename?, attachments?)`** — creates a session against the configured agent + environment, attaches whichever brand asset `resources` are configured (see Setup), uploads any chat attachments to the Files API and mounts them too, sends the outline as the first message, returns `{ success, sessionId, message, attachmentsAttached, imageWarnings? }`. Does not wait for the deck to finish. `attachments` is an optional array (max 10) of `{ path? | url? | data? | fileId?, filename?, mimeType?, placement? }` — any file type (images to embed, PDFs/spreadsheets/documents as source material). `images` still works as a deprecated alias. See [Chat attachments](#chat-attachments).
 
 - **`get_tb_powerpoint_result(sessionId)`** — checks on a generation started above:
   1. Retrieves the session. If its `status` isn't `idle`, returns `{ ready: false, status }` — still running, try again later.
   2. If idle, finds the most recent `session.status_idle` event and checks its `stop_reason.type`. Only proceeds if it's `end_turn` (a clean finish) — a different stop reason (e.g. a budget cap) also returns `{ ready: false, ... }` rather than treating the session as done.
   3. Lists files scoped to the session, filters for a `.pptx` filename (preferring one whose path looks like it's under an outputs directory), downloads it via the Files API into `TB_PPT_OUTPUT_DIR` (the local folder synced to GCS outside this server), and returns a download link built from `TB_PPT_PUBLIC_URL_BASE`.
 
+## Chat attachments
+
+An MCP tool call cannot see chat attachments by itself, so the calling model passes a reference:
+
+- **`path`** (preferred in Claude Desktop / Claude Code): the attachment is stored on disk and the model knows its absolute path. The server reads the file itself, so no bytes travel through the model.
+- **`url`**: a directly fetchable URL (server-side `fetch`).
+- **`data`**: base64 bytes, as a last resort (costs tokens).
+- **`fileId`**: a file already in the Files API, mounted without re-uploading.
+
+Each file is uploaded to the Anthropic Files API and mounted at `/mnt/session/uploads/user-attachments/<n>-<name>`; the first message tells the agent to insert images at the given `placement` and to use other files as source material. A source that fails (bad path, HTTP error) is skipped and reported in `imageWarnings` instead of failing the whole call.
+
+Optional hardening: set `TB_PPT_ATTACHMENT_ROOTS` to one or more folders (separated by `;` on Windows, `:` elsewhere); `path` attachments outside them are refused. Unset means any readable local file is allowed.
+
+### TypingMind (URL flow)
+
+A plain MCP tool call (which is what `generate_tb_powerpoint` is) has no visibility into chat attachments at all — TypingMind only exposes `resources.userMessage.attachments` to a **JavaScript-implementation regular plugin** with the `read_user_message` permission, never to a native/remote MCP tool. So getting an attached image into a deck is a two-step chain:
+
+1. **A small companion TypingMind plugin surfaces the attachment.** In TypingMind's Admin Panel → Plugins → Create New Plugin, set up a plugin like this (a "Regular Plugin", separate from this MCP server's registration):
+   - **Name:** `get_chat_attachments`
+   - **Description** (used for tool selection): "Returns the direct URL, MIME type, and filename of any file/image the user attached to their most recent message in this chat. Call this whenever the user references an attachment (e.g. 'insert this logo', 'use this screenshot') so its URL can be passed to another tool such as generate_tb_powerpoint's `images` parameter."
+   - **Parameters:** none
+   - **Permissions:** `read_user_message`
+   - **Implementation type:** JavaScript Code
+     ```javascript
+     async function get_chat_attachments(params, userSettings, resources) {
+       const attachments = (resources && resources.userMessage && resources.userMessage.attachments) || [];
+       if (attachments.length === 0) {
+         return JSON.stringify({ attachments: [], message: "No attachments found on the user's most recent message." });
+       }
+       return JSON.stringify({
+         attachments: attachments.map(function (a) {
+           return { url: a.url, type: a.type, name: a.name };
+         })
+       });
+     }
+     ```
+   - **Plugin Context** (recommended, injected into the system prompt): "When the user says they attached/added/pasted an image or file and references it (e.g. 'zet dit logo op de titelslide'), call get_chat_attachments first to get its URL, then pass that URL into generate_tb_powerpoint's `images` array along with a `placement` describing what the user asked for, in their own words."
+
+2. **The model chains the two tools itself.** With both plugins active in the same chat, the flow the model follows is: user attaches an image and says where it goes → model calls `get_chat_attachments` → gets back `{ url, type, name }` → calls `generate_tb_powerpoint` with `images: [{ url, mimeType: type, filename: name, placement: "<what the user asked for>" }]`. This server then fetches that URL itself (a plain server-side fetch — no browser/CORS involved), uploads the bytes to the Files API exactly like the brand logos, and mounts it into the session at `/user-images/image-N.ext`, telling the agent in the message text where to insert it.
+
+**One real unknown, worth testing before relying on this:** it isn't confirmed whether the `url` TypingMind's attachment object returns is a plain, publicly-fetchable link, or one scoped to TypingMind's own browser session (which this server's server-side `fetch()` couldn't reach). Test it once by attaching an image, calling `get_chat_attachments`, and trying to fetch the returned URL independently (e.g. `curl -I <url>`) from outside TypingMind. **If that fails**, the fallback is already built in: `images` entries also accept `data` (base64 image bytes) instead of `url` — change the plugin's JS code above to fetch the attachment's `url` itself (`fetch(a.url).then(r => r.arrayBuffer())`, browser-side, where TypingMind's own session auth applies) and return base64-encoded `data` instead of `url`; no MCP-server code change is needed either way.
+
 ## What's still an assumption
 
 Every SDK call in `src/index.ts` (`sessions.create`, `sessions.events.send`, `sessions.retrieve`, `sessions.events.list`, `files.list`, `files.download`) is checked against `@anthropic-ai/sdk`'s own `.d.ts`/source (installed version, not just the docs prose) — that's how a real bug was caught in 0.1.0: the docs' TypeScript sample for downloading a file shows `content.writeToFile(path)`, but that method doesn't exist on the installed SDK. `files.download()` actually resolves to a plain `Response`; 0.1.1 fixes this by reading it with `.arrayBuffer()` and writing the bytes directly. The `resources` shape (`{ type: "file", file_id, mount_path }`) is likewise checked against the SDK source, not just the docs.
 
 The one thing still **not** confirmed against a real response is the exact `filename`/path convention the Files API returns for a file the agent wrote to its outputs directory — the code guesses by matching `/outputs?[\/]/i` against the filename and falling back to any `.pptx` file on the session if nothing matches that pattern. If a real run's file list looks different, adjust the filter in `get_tb_powerpoint_result` in `src/index.ts`.
 
+`generate_tb_powerpoint`'s image-forwarding path (`client.beta.files.upload(...)`, via the SDK's `toFile()` helper) is checked against the SDK source the same way, and is exercised by the same `resources` mechanism already used for brand assets — but the TypingMind-side attachment flow that's meant to feed it a URL has not been run end-to-end yet; see [Sending an attached image from TypingMind](#sending-an-attached-image-from-typingmind) for the one open question there.
+
 ## Setup
 
 1. **Install dependencies**:
@@ -37,7 +81,7 @@ The one thing still **not** confirmed against a real response is the exact `file
    ```
    .\uploadAssets.ps1 -ApiKey "sk-ant-..."
    ```
-   Uploads `TrafficBuilders-PPT-Handoff.md`, all five `logos/*.png`, and `fonts/Outfit-VariableFont_wght.ttf` to the Files API, and prints a `file_id` per asset along with the matching env var name. These are just config, not code — plug them into step 5 below and there's nothing else to change or republish.
+   Uploads `TrafficBuilders-PPT-Handoff.md`, all five `logos/*.png`, and both `fonts/*-VariableFont_wght.ttf` (Outfit, Figtree) to the Files API, and prints a `file_id` per asset along with the matching env var name. These are just config, not code — plug them into step 5 below and there's nothing else to change or republish.
 
 4. **Configure environment variables**:
    - `ANTHROPIC_API_KEY` — Anthropic API key with Managed Agents access.
@@ -47,7 +91,8 @@ The one thing still **not** confirmed against a real response is the exact `file
    - `TB_PPT_OUTPUT_DIR` — required for `get_tb_powerpoint_result`. Local folder that's synced to GCS by something outside this server; finished `.pptx` files are written here.
    - `TB_PPT_PUBLIC_URL_BASE` — required for `get_tb_powerpoint_result`. Base URL the synced folder is served from (e.g. `https://storage.googleapis.com/bucket/prefix`), used to build the returned download link.
    - `TB_PPT_LOG_FILE` — optional. Path to the task log file. Defaults to `logs/tasks.log` next to this package.
-   - `TB_DESIGN_BRIEF_FILE_ID`, `TB_LOGO_HORIZONTAL_FILE_ID`, `TB_LOGO_HORIZONTAL_WHITE_FILE_ID`, `TB_LOGO_ICON_FILE_ID`, `TB_LOGO_ICON_WHITE_FILE_ID`, `TB_LOGO_ICON_TAGLINE_FILE_ID`, `TB_FONT_FILE_ID` — all optional but strongly recommended, from step 3. Any left unset are just skipped (with a warning in the log) rather than failing the call — the deck still gets built, just without that asset available to the agent.
+   - `TB_PPT_ATTACHMENT_ROOTS` — optional. Folders that `path` attachments must live in.
+   - `TB_DESIGN_BRIEF_FILE_ID`, `TB_LOGO_HORIZONTAL_FILE_ID`, `TB_LOGO_HORIZONTAL_WHITE_FILE_ID`, `TB_LOGO_ICON_FILE_ID`, `TB_LOGO_ICON_WHITE_FILE_ID`, `TB_LOGO_ICON_TAGLINE_FILE_ID`, `TB_FONT_FILE_ID`, `TB_FONT_BODY_FILE_ID` — all optional but strongly recommended, from step 3. Any left unset are just skipped (with a warning in the log) rather than failing the call — the deck still gets built, just without that asset available to the agent.
 
 5. **Register with your MCP client** (Claude Desktop / TypingMind's local MCP connector — same pattern as this repo's siblings, e.g. `tb-gcs-assembly-mcp`). Published to npm as [`@unboundai/tb-ppt-mgagent`](https://www.npmjs.com/package/@unboundai/tb-ppt-mgagent), so `npx` can run it without a local checkout:
 
@@ -70,7 +115,8 @@ The one thing still **not** confirmed against a real response is the exact `file
        "TB_LOGO_ICON_FILE_ID": "file_...",
        "TB_LOGO_ICON_WHITE_FILE_ID": "file_...",
        "TB_LOGO_ICON_TAGLINE_FILE_ID": "file_...",
-       "TB_FONT_FILE_ID": "file_..."
+       "TB_FONT_FILE_ID": "file_...",
+       "TB_FONT_BODY_FILE_ID": "file_..."
      }
    }
    ```
@@ -138,4 +184,4 @@ Both tools were smoke-tested end-to-end over the real MCP protocol (`tools/list`
 
 ## Design brief reference
 
-`TrafficBuilders-PPT-Handoff.md`, `logos/`, and `fonts/` in this repo are the source material — pulled from the "Traffic Builders Design System" Claude Design project (colors, type scale, the 19 slide archetypes, brand logo PNGs, Outfit variable font) — that `uploadAssets.ps1` uploads and every session attaches via `resources`. Update the files here first if the design system changes, then re-run `uploadAssets.ps1` and update the env vars with the new file_ids. No slide-image assets are attached separately — the handoff brief embeds a literal HTML/CSS reference snippet per archetype, which is enough on its own (see its closing section for when a visual PNG reference would be worth adding).
+`TrafficBuilders-PPT-Handoff.md`, `logos/`, and `fonts/` in this repo are the source material — pulled from the "Traffic Builders Design System" Claude Design project (colors, type scale, the 21 slide archetypes, brand logo PNGs, Outfit variable font) — that `uploadAssets.ps1` uploads and every session attaches via `resources`. Update the files here first if the design system changes, then re-run `uploadAssets.ps1` and update the env vars with the new file_ids. No slide-image assets are attached separately — the handoff brief embeds a literal HTML/CSS reference snippet per archetype, which is enough on its own (see its closing section for when a visual PNG reference would be worth adding).

package/build/index.js

@@ -51,18 +51,31 @@
  * - TB_DESIGN_BRIEF_FILE_ID, TB_LOGO_HORIZONTAL_FILE_ID,
  *   TB_LOGO_HORIZONTAL_WHITE_FILE_ID, TB_LOGO_ICON_FILE_ID,
  *   TB_LOGO_ICON_WHITE_FILE_ID, TB_LOGO_ICON_TAGLINE_FILE_ID,
- *   TB_FONT_FILE_ID: all optional but strongly recommended. Files API
+ *   TB_FONT_FILE_ID (Outfit), TB_FONT_BODY_FILE_ID (Figtree): all optional but strongly recommended. Files API
  *   file_ids (from uploadAssets.ps1) for the design brief, each logo
- *   variant, and the Outfit font. Any that are set get mounted into every
+ *   variant, and the Outfit and Figtree fonts. Any that are set get mounted into every
  *   session via `resources`; any left unset are just skipped (with a
  *   warning), so the agent falls back to approximating the brand from the
  *   prompt text alone.
+ *
+ * User-supplied attachments (a client logo, screenshot, PDF, spreadsheet...):
+ * generate_tb_powerpoint's optional `attachments` argument takes
+ * `{ path | url | data | fileId, filename?, mimeType?, placement? }` entries
+ * (`images` is kept as a deprecated alias). A plain MCP tool call cannot see a
+ * chat attachment by itself, but Claude Desktop / Claude Code store attachments
+ * on disk and the model knows their path, so `path` is the preferred source;
+ * `url` and base64 `data` remain for clients that expose attachments that way.
+ * This server reads/fetches each file itself, uploads the bytes to the Files
+ * API (like uploadAssets.ps1 does for brand assets), and mounts the result into
+ * the session's `resources` under /user-attachments/, with the `placement` text
+ * relayed to the agent. Set TB_PPT_ATTACHMENT_ROOTS (optional, folders separated
+ * by the OS path delimiter) to restrict which local folders `path` may read from.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import Anthropic from "@anthropic-ai/sdk";
+import Anthropic, { toFile } from "@anthropic-ai/sdk";
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
@@ -116,7 +129,8 @@ const ASSET_RESOURCES = [
     { envVar: "TB_LOGO_ICON_FILE_ID", mountPath: "/design/logos/logo-icon.png", label: "logo-icon.png (full-color square mark)" },
     { envVar: "TB_LOGO_ICON_WHITE_FILE_ID", mountPath: "/design/logos/logo-icon-white.png", label: "logo-icon-white.png (reversed square mark)" },
     { envVar: "TB_LOGO_ICON_TAGLINE_FILE_ID", mountPath: "/design/logos/logo-icon-tagline.png", label: "logo-icon-tagline.png (icon + tagline lockup)" },
-    { envVar: "TB_FONT_FILE_ID", mountPath: "/design/fonts/Outfit-VariableFont_wght.ttf", label: "Outfit variable font (weights 300-900)" }
+    { envVar: "TB_FONT_FILE_ID", mountPath: "/design/fonts/Outfit-VariableFont_wght.ttf", label: "Outfit variable font (weights 300-900) - headings, numbers, eyebrows" },
+    { envVar: "TB_FONT_BODY_FILE_ID", mountPath: "/design/fonts/Figtree-VariableFont_wght.ttf", label: "Figtree variable font (weights 300-900) - body copy and labels" }
 ];
 const missingAssetEnvVars = ASSET_RESOURCES.filter((a) => !(process.env[a.envVar] || "").trim());
 if (missingAssetEnvVars.length > 0) {
@@ -149,11 +163,77 @@ function getClient(apiKey) {
         ...(API_BASE ? { baseURL: API_BASE } : {})
     });
 }
+/** Maps a MIME type (or, failing that, a URL/filename extension) to a file extension. */
+function guessExtension(mimeType, hint) {
+    const byMime = {
+        "image/png": ".png",
+        "image/jpeg": ".jpg",
+        "image/jpg": ".jpg",
+        "image/webp": ".webp",
+        "image/gif": ".gif",
+        "image/svg+xml": ".svg",
+        "application/pdf": ".pdf",
+        "text/csv": ".csv",
+        "text/plain": ".txt",
+        "text/markdown": ".md",
+        "application/json": ".json",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx"
+    };
+    const fromMime = mimeType ? byMime[mimeType.toLowerCase().split(";")[0].trim()] : undefined;
+    if (fromMime)
+        return fromMime;
+    const match = hint.match(/\.[a-zA-Z0-9]+(?=$|[?#])/);
+    return match ? match[0].toLowerCase() : ".bin";
+}
+const byExt = {
+    ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp",
+    ".gif": "image/gif", ".svg": "image/svg+xml", ".pdf": "application/pdf", ".csv": "text/csv",
+    ".txt": "text/plain", ".md": "text/markdown", ".json": "application/json",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+};
+/**
+ * Optional safety net for the `path` source: a list of folders (separated by the
+ * OS path delimiter, ";" on Windows) that local attachments must live inside.
+ * Unset = any readable local file is allowed.
+ */
+const ATTACHMENT_ROOTS = (process.env.TB_PPT_ATTACHMENT_ROOTS || "")
+    .split(path.delimiter)
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .map((p) => path.resolve(p));
+function assertPathAllowed(resolved) {
+    if (ATTACHMENT_ROOTS.length === 0)
+        return;
+    const ok = ATTACHMENT_ROOTS.some((root) => {
+        const rel = path.relative(root, resolved);
+        return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    });
+    if (!ok)
+        throw new Error(`path is outside TB_PPT_ATTACHMENT_ROOTS: ${resolved}`);
+}
+const AttachmentInputSchema = z.object({
+    path: z.string().optional().describe("Absolute local file path of a chat attachment (Claude Desktop / Claude Code store attachments on disk)"),
+    url: z.string().url("attachment url must be a valid, fetchable URL").optional(),
+    data: z.string().optional().describe("base64-encoded file bytes, if neither path nor url is available"),
+    fileId: z.string().optional().describe("An already-uploaded Files API file_id - mounted as-is, no re-upload"),
+    filename: z.string().optional(),
+    mimeType: z.string().optional(),
+    placement: z.string().optional().describe("Where/how the file should be used in the deck")
+}).refine((a) => Boolean(a.path || a.url || a.data || a.fileId), {
+    message: "one of path, url, data or fileId is required"
+});
 const GenerateTbPowerpointSchema = z.object({
     outline: z.string().min(1, "outline is required"),
     deckType: z.string().optional(),
     clientName: z.string().optional(),
-    filename: z.string().optional()
+    filename: z.string().optional(),
+    attachments: z.array(AttachmentInputSchema).max(10, "at most 10 attachments per deck").optional(),
+    /** Deprecated alias of `attachments`, kept for existing callers. */
+    images: z.array(AttachmentInputSchema).max(10, "at most 10 images per deck").optional()
 });
 const GetTbPowerpointResultSchema = z.object({
     sessionId: z.string().min(1, "sessionId is required")
@@ -180,7 +260,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     "the outline as the first message, and returns the session id right away - it does NOT " +
                     "wait for the deck to finish building. Use this whenever the user has typed or drafted " +
                     "an outline/agenda and wants it turned into a Traffic Builders PowerPoint. Follow up later " +
-                    "with get_tb_powerpoint_result using the returned session id to fetch the finished file.",
+                    "with get_tb_powerpoint_result using the returned session id to fetch the finished file. " +
+                    "If the user attached files in this chat (logo, screenshot, PDF, spreadsheet, brief...) and " +
+                    "wants them used in the deck, pass them via the `attachments` argument: give the local file " +
+                    "`path` of the attachment (Claude Desktop / Claude Code keep chat attachments on disk), or a " +
+                    "`url`, or base64 `data`. This tool uploads each file to Anthropic's Files API and mounts it " +
+                    "in the session for the agent. Add a `placement` saying where/how it should be used.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -199,6 +284,50 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         filename: {
                             type: "string",
                             description: "Optional filename without extension for the resulting .pptx."
+                        },
+                        attachments: {
+                            type: "array",
+                            description: "Optional files from the chat to include in the deck (images to embed, or PDFs/spreadsheets/documents as source material). At most 10. Each needs one of path, url, data or fileId.",
+                            maxItems: 10,
+                            items: {
+                                type: "object",
+                                properties: {
+                                    path: {
+                                        type: "string",
+                                        description: "Absolute local file path of the attachment (preferred in Claude Desktop / Claude Code)."
+                                    },
+                                    url: {
+                                        type: "string",
+                                        description: "A direct, fetchable URL to the file."
+                                    },
+                                    data: {
+                                        type: "string",
+                                        description: "Base64-encoded file bytes, if no path or URL is available."
+                                    },
+                                    fileId: {
+                                        type: "string",
+                                        description: "An already-uploaded Files API file_id; mounted as-is without re-uploading."
+                                    },
+                                    filename: {
+                                        type: "string",
+                                        description: "Original filename, used for the mounted file name."
+                                    },
+                                    mimeType: {
+                                        type: "string",
+                                        description: "MIME type if known (e.g. 'image/png', 'application/pdf'); inferred otherwise."
+                                    },
+                                    placement: {
+                                        type: "string",
+                                        description: "Where/how the file should be used, in the user's own words (e.g. 'titelslide achtergrond', 'bron voor de cijfers op slide 4'). Strongly recommended."
+                                    }
+                                }
+                            }
+                        },
+                        images: {
+                            type: "array",
+                            description: "Deprecated alias of `attachments`.",
+                            maxItems: 10,
+                            items: { type: "object" }
                         }
                     },
                     required: ["outline"]
@@ -231,7 +360,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const startedAt = Date.now();
     try {
         if (name === "generate_tb_powerpoint") {
-            const { outline, deckType, clientName, filename } = GenerateTbPowerpointSchema.parse(args);
+            const parsed = GenerateTbPowerpointSchema.parse(args);
+            const { outline, deckType, clientName, filename } = parsed;
+            const attachments = [...(parsed.attachments ?? []), ...(parsed.images ?? [])];
             logTask({
                 tool: name,
                 status: "started",
@@ -239,7 +370,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 outlineLength: outline.length,
                 deckType: deckType ?? null,
                 clientName: clientName ?? null,
-                filename: filename ?? null
+                filename: filename ?? null,
+                attachmentCount: attachments.length
             });
             const { apiKey, agentId, environmentId } = requireSessionConfig();
             const client = getClient(apiKey);
@@ -252,16 +384,95 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 attached: attachedAssets.map((a) => a.mountPath),
                 missing: missingAssetEnvVars.map((a) => a.envVar)
             });
+            // User-supplied attachments from the chat (logos, screenshots, PDFs, ...) - see
+            // the "User-supplied attachments" note in the file header. Each one is read from a
+            // local path / fetched from a URL / decoded from base64, uploaded to the Files API,
+            // and mounted into the session. One at a time, so a bad source only drops that
+            // one file instead of failing the whole call.
+            const uploadedImages = [];
+            const imageWarnings = [];
+            if (attachments.length > 0) {
+                logTask({ tool: name, status: "fetching_user_attachments", count: attachments.length });
+                for (let i = 0; i < attachments.length; i++) {
+                    const att = attachments[i];
+                    const index = i + 1;
+                    try {
+                        if (att.fileId) {
+                            // Already in the Files API - mount as-is.
+                            const ext = guessExtension(att.mimeType, att.filename || "");
+                            uploadedImages.push({
+                                mountPath: `/user-attachments/${index}-${path.basename(att.filename || `attachment${ext}`)}`,
+                                label: att.filename || att.fileId,
+                                fileId: att.fileId,
+                                placement: att.placement
+                            });
+                            continue;
+                        }
+                        let bytes;
+                        let contentType = att.mimeType;
+                        let hint = att.filename || "";
+                        if (att.path) {
+                            const resolved = path.resolve(att.path);
+                            assertPathAllowed(resolved);
+                            bytes = fs.readFileSync(resolved);
+                            hint = hint || resolved;
+                        }
+                        else if (att.data) {
+                            bytes = Buffer.from(att.data, "base64");
+                        }
+                        else {
+                            const response = await fetch(att.url);
+                            if (!response.ok) {
+                                throw new Error(`fetch returned HTTP ${response.status}`);
+                            }
+                            contentType = contentType || response.headers.get("content-type") || undefined;
+                            bytes = Buffer.from(await response.arrayBuffer());
+                            hint = hint || att.url;
+                        }
+                        const ext = guessExtension(contentType, hint);
+                        contentType = contentType || byExt[ext];
+                        const baseName = path.basename(att.filename || (att.path ? att.path : `attachment-${index}${ext}`));
+                        const uploaded = await client.beta.files.upload({
+                            file: await toFile(bytes, baseName, contentType ? { type: contentType } : undefined)
+                        });
+                        uploadedImages.push({
+                            mountPath: `/user-attachments/${index}-${baseName}`,
+                            label: baseName,
+                            fileId: uploaded.id,
+                            placement: att.placement
+                        });
+                    }
+                    catch (err) {
+                        const message = err.message;
+                        const ref = att.path || att.url || att.filename || `#${index}`;
+                        imageWarnings.push(`Attachment ${index} (${ref}) could not be attached: ${message}`);
+                        logTask({ tool: name, status: "attachment_failed", index, ref, message });
+                    }
+                }
+                logTask({
+                    tool: name,
+                    status: "user_attachments_attached",
+                    attached: uploadedImages.map((img) => img.mountPath),
+                    warnings: imageWarnings
+                });
+            }
             const session = await client.beta.sessions.create({
                 agent: agentId,
                 environment_id: environmentId,
-                ...(attachedAssets.length > 0
+                ...(attachedAssets.length > 0 || uploadedImages.length > 0
                     ? {
-                        resources: attachedAssets.map((a) => ({
-                            type: "file",
-                            file_id: a.fileId,
-                            mount_path: a.mountPath
-                        }))
+                        resources: [
+                            ...attachedAssets.map((a) => ({
+                                type: "file",
+                                file_id: a.fileId,
+                                mount_path: a.mountPath
+                            })),
+                            ...uploadedImages.map((img) => ({
+                                type: "file",
+                                file_id: img.fileId,
+                                mount_path: img.mountPath
+                            }))
+                        ]
                     }
                     : {})
             });
@@ -276,9 +487,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const assetsNote = attachedAssets.length > 0
                 ? `## Attached brand assets\nThese files are mounted in your sandbox:\n${attachedAssets
                     .map((a) => `- /mnt/session/uploads${a.mountPath} - ${a.label}`)
-                    .join("\n")}\n\nRead the design brief first and follow it exactly: brand colors, type scale, and the 19 slide archetypes it defines. Follow its logo lockup rule precisely - it is not a simple per-background swap: the wordmark logo appears ONLY on Title and Section-divider slides (top-left), while a small icon mark appears bottom-right on EVERY slide regardless of archetype; use the white logo variants on brand-blue backgrounds and the full-color variants on white backgrounds. Embed/register the attached font file and use it for all text - ExtraBold (800) for headings, Regular (400) for body - instead of a fallback typeface.\n\n---\n\n`
+                    .join("\n")}\n\nRead the design brief first and follow it exactly: brand colors, type scale, and the 21 slide archetypes it defines. Choose each slide's archetype by the shape of its content using the brief's section 7 table, and obey its variation rules (card-block slides are the exception, never the default; never two in a row). Follow its logo lockup rule precisely - it is not a simple per-background swap: the wordmark logo appears ONLY on Title and Section-divider slides (top-left), while a small icon mark appears bottom-right on EVERY slide regardless of archetype; use the white logo variants on brand-blue backgrounds and the full-color variants on white backgrounds. Embed/register BOTH attached font files: Outfit (ExtraBold 800) for headings, big numbers, eyebrows and tags; Figtree (Regular 400, SemiBold 600 for table headers) for body copy, card copy and labels - instead of a fallback typeface.\n\n---\n\n`
+                : "";
+            const userImagesNote = uploadedImages.length > 0
+                ? `## User-provided attachments\nThese files from the user are mounted in your sandbox. Images MUST be inserted into the deck (not just described) at the placement given; other files (PDF, spreadsheet, document) are source material to read and use for the content as described:\n${uploadedImages
+                    .map((img) => `- /mnt/session/uploads${img.mountPath} (${img.label}) - placement/use: ${img.placement || "not specified - use your judgement"}`)
+                    .join("\n")}\n\n---\n\n`
                 : "";
-            const messageText = `Build a Traffic Builders PowerPoint from the following outline.\n\n${assetsNote}${meta}## Outline\n${outline}`;
+            const messageText = `Build a Traffic Builders PowerPoint from the following outline.\n\n${assetsNote}${userImagesNote}${meta}## Outline\n${outline}`;
             await client.beta.sessions.events.send(session.id, {
                 events: [
                     { type: "user.message", content: [{ type: "text", text: messageText }] }
@@ -289,6 +505,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 status: "success",
                 sessionId: session.id,
                 assetsAttached: attachedAssets.length,
+                attachmentsAttached: uploadedImages.length,
+                imageWarnings,
                 durationMs: Date.now() - startedAt
             });
             return {
@@ -297,6 +515,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         text: JSON.stringify({
                             success: true,
                             sessionId: session.id,
+                            attachmentsAttached: uploadedImages.length,
+                            ...(imageWarnings.length > 0 ? { imageWarnings } : {}),
                             message: "Generation started. Call get_tb_powerpoint_result with this session id later to check on it and fetch the finished file."
                         }, null, 2)
                     }]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundai/tb-ppt-mgagent",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "MCP server that hands a presentation outline to the Traffic Builders PowerPoint Managed Agent, then retrieves the finished .pptx",
   "main": "build/index.js",
   "bin": {