@unboundai/tb-ppt-mgagent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Traffic Builders
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# Traffic Builders PowerPoint MCP Server
+
+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 (logos, Outfit font) and the design brief are already provisioned in that agent's environment — this server does not upload anything, it just starts the run and later collects the result.
+
+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, sends the outline as the first message, returns `{ success, sessionId, message }`. Does not wait for the deck to finish.
+
+- **`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`.
+
+## What's still an assumption
+
+Everything above matches the documented API and SDK method signatures verbatim (verified against platform.claude.com/docs/en/managed-agents/\* while building this). The one thing **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`.
+
+## Setup
+
+1. **Install dependencies**:
+   ```
+   npm install
+   ```
+
+2. **Build the project**:
+   ```
+   npm run build
+   ```
+
+3. **Configure environment variables**:
+   - `ANTHROPIC_API_KEY` — Anthropic API key with Managed Agents access.
+   - `ANTHROPIC_AGENT_ID` — e.g. `agent_01H8osDSMeEtGcEHT1ajzuin`.
+   - `ANTHROPIC_ENVIRONMENT_ID` — e.g. `env_01VHzZmqBababsghFjQoAGFx`.
+   - `ANTHROPIC_API_BASE` — optional, overrides the SDK's default API base URL.
+   - `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.
+
+4. **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`):
+
+   ```json
+   "tb-ppt-mgagent": {
+     "command": "node",
+     "args": [
+       "/path/to/tb-ppt-mgAgent/build/index.js"
+     ],
+     "env": {
+       "ANTHROPIC_API_KEY": "sk-ant-...",
+       "ANTHROPIC_AGENT_ID": "agent_...",
+       "ANTHROPIC_ENVIRONMENT_ID": "env_...",
+       "TB_PPT_OUTPUT_DIR": "/path/to/gcs-synced-folder",
+       "TB_PPT_PUBLIC_URL_BASE": "https://storage.googleapis.com/your-bucket/your-prefix"
+     }
+   }
+   ```
+
+## Development
+
+```bash
+# Watch mode
+npm run dev
+```
+
+Both tools were smoke-tested end-to-end over the real MCP protocol (`tools/list`, and calling each with a dummy API key to confirm the SDK calls actually reach `api.anthropic.com` and get a real `401 authentication_error` back rather than failing on a wrong method/shape before the network call).
+
+## Design brief reference
+
+`TrafficBuilders-PPT-Handoff.md`, `logos/`, and `fonts/` in this repo are the source material that was provisioned into the Managed Agent's environment (colors, type scale, the six slide archetypes, brand logo PNGs, Outfit variable font). Kept here as the local record of what the environment should contain — not read or uploaded by this server at runtime.

package/build/index.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+/**
+ * Traffic Builders PowerPoint MCP Server
+ *
+ * Hands a presentation outline to Anthropic's hosted Managed Agent that
+ * builds Traffic Builders-branded PowerPoints (brand assets and design
+ * brief are already provisioned in that agent's environment - this server
+ * does not upload any brand files itself), then later retrieves the
+ * finished .pptx once the agent's turn has ended.
+ *
+ * Built against the documented Managed Agents API:
+ *   https://platform.claude.com/docs/en/managed-agents/sessions
+ *   https://platform.claude.com/docs/en/managed-agents/session-operations
+ *   https://platform.claude.com/docs/en/managed-agents/events-and-streaming
+ *   https://platform.claude.com/docs/en/managed-agents/files
+ *   https://platform.claude.com/docs/en/managed-agents/reference
+ * using the official @anthropic-ai/sdk client (client.beta.sessions.*,
+ * client.beta.files.*), which sets the managed-agents beta header
+ * automatically for session endpoints. The Files API additionally takes an
+ * explicit `betas` array on list/download, per the docs' own example.
+ *
+ * A couple of the beta SDK's exact TypeScript types for newer event/file
+ * fields (stop_reason, processed_at, filename) aren't fully pinned down
+ * here - those spots are narrowed with `as any` and a comment rather than
+ * guessed field names baked into strict types, so a real API response can't
+ * silently mismatch a wrong compile-time shape.
+ *
+ * Environment variables:
+ * - ANTHROPIC_API_KEY: required. Anthropic API key with Managed Agents access.
+ * - ANTHROPIC_AGENT_ID: required. e.g. "agent_01H8osDSMeEtGcEHT1ajzuin".
+ * - ANTHROPIC_ENVIRONMENT_ID: required. e.g. "env_01VHzZmqBababsghFjQoAGFx".
+ * - ANTHROPIC_API_BASE: optional. Overrides the SDK's default API base URL.
+ * - TB_PPT_OUTPUT_DIR: required for retrieval. Local folder (synced to GCS
+ *   by something outside this server) that finished .pptx files are saved into.
+ * - TB_PPT_PUBLIC_URL_BASE: required for retrieval. Base URL the synced
+ *   folder is served from (e.g. "https://storage.googleapis.com/bucket/prefix"),
+ *   used to build the download link returned to the caller.
+ */
+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 fs from "fs";
+import path from "path";
+const MANAGED_AGENTS_BETA = "managed-agents-2026-04-01";
+const API_KEY = process.env.ANTHROPIC_API_KEY;
+const AGENT_ID = process.env.ANTHROPIC_AGENT_ID;
+const ENVIRONMENT_ID = process.env.ANTHROPIC_ENVIRONMENT_ID;
+const API_BASE = process.env.ANTHROPIC_API_BASE;
+const OUTPUT_DIR = process.env.TB_PPT_OUTPUT_DIR;
+const PUBLIC_URL_BASE = process.env.TB_PPT_PUBLIC_URL_BASE;
+if (!API_KEY)
+    console.error("Warning: ANTHROPIC_API_KEY environment variable is not set");
+if (!AGENT_ID)
+    console.error("Warning: ANTHROPIC_AGENT_ID environment variable is not set");
+if (!ENVIRONMENT_ID)
+    console.error("Warning: ANTHROPIC_ENVIRONMENT_ID environment variable is not set");
+if (!OUTPUT_DIR)
+    console.error("Warning: TB_PPT_OUTPUT_DIR environment variable is not set (needed for get_tb_powerpoint_result)");
+if (!PUBLIC_URL_BASE)
+    console.error("Warning: TB_PPT_PUBLIC_URL_BASE environment variable is not set (needed for get_tb_powerpoint_result)");
+function requireSessionConfig() {
+    if (!API_KEY)
+        throw new Error("ANTHROPIC_API_KEY is not configured on this MCP server.");
+    if (!AGENT_ID)
+        throw new Error("ANTHROPIC_AGENT_ID is not configured on this MCP server.");
+    if (!ENVIRONMENT_ID)
+        throw new Error("ANTHROPIC_ENVIRONMENT_ID is not configured on this MCP server.");
+    return { apiKey: API_KEY, agentId: AGENT_ID, environmentId: ENVIRONMENT_ID };
+}
+function requireApiKey() {
+    if (!API_KEY)
+        throw new Error("ANTHROPIC_API_KEY is not configured on this MCP server.");
+    return API_KEY;
+}
+function requireOutputConfig() {
+    if (!OUTPUT_DIR)
+        throw new Error("TB_PPT_OUTPUT_DIR is not configured on this MCP server.");
+    if (!PUBLIC_URL_BASE)
+        throw new Error("TB_PPT_PUBLIC_URL_BASE is not configured on this MCP server.");
+    return { outputDir: OUTPUT_DIR, publicUrlBase: PUBLIC_URL_BASE };
+}
+function getClient(apiKey) {
+    return new Anthropic({
+        apiKey,
+        ...(API_BASE ? { baseURL: API_BASE } : {})
+    });
+}
+const GenerateTbPowerpointSchema = z.object({
+    outline: z.string().min(1, "outline is required"),
+    deckType: z.string().optional(),
+    clientName: z.string().optional(),
+    filename: z.string().optional()
+});
+const GetTbPowerpointResultSchema = z.object({
+    sessionId: z.string().min(1, "sessionId is required")
+});
+// Create MCP server
+const server = new Server({
+    name: "tb-ppt-mgagent",
+    version: "1.0.0"
+}, {
+    capabilities: {
+        tools: {
+            listChanged: false
+        }
+    }
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "generate_tb_powerpoint",
+                description: "Start generating a Traffic Builders-branded PowerPoint from a presentation outline, " +
+                    "via Anthropic's hosted Managed Agent (brand assets and design brief already provisioned " +
+                    "in that agent's environment - nothing is uploaded here). Creates a new session, sends " +
+                    "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.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        outline: {
+                            type: "string",
+                            description: "The presentation outline: section/slide topics in order, with any sub-points, KPIs, or copy the user already wrote."
+                        },
+                        deckType: {
+                            type: "string",
+                            description: "Optional short label for the deck (e.g. 'SEA Audit', 'Kwartaalupdate')."
+                        },
+                        clientName: {
+                            type: "string",
+                            description: "Optional client/company name for title-slide and footer placeholders."
+                        },
+                        filename: {
+                            type: "string",
+                            description: "Optional filename without extension for the resulting .pptx."
+                        }
+                    },
+                    required: ["outline"]
+                }
+            },
+            {
+                name: "get_tb_powerpoint_result",
+                description: "Check on a Traffic Builders PowerPoint generation started with generate_tb_powerpoint, and " +
+                    "fetch the finished file once ready. Retrieves the session, and ONLY looks for output files " +
+                    "if the session is idle AND its most recent status_idle event has stop_reason 'end_turn' " +
+                    "(a clean finish - not idle for another reason like a budget cap). When ready, finds a " +
+                    ".pptx file under the session's outputs, downloads it into the local GCS-synced output " +
+                    "folder, and returns a download link. If not ready yet, reports the current status instead.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        sessionId: {
+                            type: "string",
+                            description: "The session id returned by generate_tb_powerpoint."
+                        }
+                    },
+                    required: ["sessionId"]
+                }
+            }
+        ]
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        if (name === "generate_tb_powerpoint") {
+            const { outline, deckType, clientName, filename } = GenerateTbPowerpointSchema.parse(args);
+            const { apiKey, agentId, environmentId } = requireSessionConfig();
+            const client = getClient(apiKey);
+            const session = await client.beta.sessions.create({
+                agent: agentId,
+                environment_id: environmentId
+            });
+            const lines = [];
+            if (deckType)
+                lines.push(`Deck type: ${deckType}`);
+            if (clientName)
+                lines.push(`Client name: ${clientName}`);
+            if (filename)
+                lines.push(`Save the resulting file as "${filename}.pptx".`);
+            const meta = lines.length ? `${lines.join("\n")}\n\n` : "";
+            const messageText = `Build a Traffic Builders PowerPoint from the following outline.\n\n${meta}## Outline\n${outline}`;
+            await client.beta.sessions.events.send(session.id, {
+                events: [
+                    { type: "user.message", content: [{ type: "text", text: messageText }] }
+                ]
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            sessionId: session.id,
+                            message: "Generation started. Call get_tb_powerpoint_result with this session id later to check on it and fetch the finished file."
+                        }, null, 2)
+                    }]
+            };
+        }
+        if (name === "get_tb_powerpoint_result") {
+            const { sessionId } = GetTbPowerpointResultSchema.parse(args);
+            const apiKey = requireApiKey();
+            const client = getClient(apiKey);
+            const session = await client.beta.sessions.retrieve(sessionId);
+            if (session.status !== "idle") {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                ready: false,
+                                status: session.status,
+                                message: `Session is "${session.status}", not ready yet. Try again shortly.`
+                            }, null, 2)
+                        }]
+                };
+            }
+            // Find the most recent session.status_idle event to read its stop_reason.
+            // (Its exact field shape isn't pinned down in our TS types yet - see file header.)
+            let latestIdleEvent = null;
+            for await (const event of client.beta.sessions.events.list(sessionId)) {
+                if (event.type === "session.status_idle") {
+                    if (!latestIdleEvent || (event.processed_at ?? "") > (latestIdleEvent.processed_at ?? "")) {
+                        latestIdleEvent = event;
+                    }
+                }
+            }
+            const stopReasonType = latestIdleEvent?.stop_reason?.type;
+            if (stopReasonType !== "end_turn") {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                ready: false,
+                                status: session.status,
+                                stopReason: stopReasonType ?? null,
+                                message: `Session is idle but its stop reason is "${stopReasonType ?? "unknown"}", not "end_turn" - not fetching files yet.`
+                            }, null, 2)
+                        }]
+                };
+            }
+            // Session finished cleanly - look for a .pptx output file.
+            const files = await client.beta.files.list({
+                scope_id: sessionId,
+                betas: [MANAGED_AGENTS_BETA]
+            });
+            const fileList = files.data ?? [];
+            const pptxFiles = fileList.filter((f) => /\.pptx$/i.test(f.filename ?? ""));
+            const outputPptxFiles = pptxFiles.filter((f) => /outputs?[\\/]/i.test(f.filename ?? ""));
+            const chosen = outputPptxFiles[0] ?? pptxFiles[0];
+            if (!chosen) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                ready: true,
+                                status: "idle",
+                                stopReason: "end_turn",
+                                message: "Session finished but no .pptx output file was found.",
+                                sessionFiles: fileList.map((f) => ({ id: f.id, filename: f.filename }))
+                            }, null, 2)
+                        }]
+                };
+            }
+            const { outputDir, publicUrlBase } = requireOutputConfig();
+            const safeName = path.basename(chosen.filename || `${sessionId}.pptx`);
+            const destPath = path.join(outputDir, safeName);
+            fs.mkdirSync(outputDir, { recursive: true });
+            const content = await client.beta.files.download(chosen.id);
+            await content.writeToFile(destPath);
+            const downloadUrl = `${publicUrlBase.replace(/\/$/, "")}/${encodeURIComponent(safeName)}`;
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            ready: true,
+                            status: "idle",
+                            stopReason: "end_turn",
+                            filename: safeName,
+                            savedTo: destPath,
+                            downloadUrl
+                        }, null, 2)
+                    }]
+            };
+        }
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Invalid arguments",
+                            details: error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ")
+                        }, null, 2)
+                    }]
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "Tool call failed",
+                        message: error.message
+                    }, null, 2)
+                }]
+        };
+    }
+});
+async function main() {
+    try {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error("Traffic Builders PowerPoint MCP Server running on stdio");
+    }
+    catch (error) {
+        console.error("Error during startup:", error);
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@unboundai/tb-ppt-mgagent",
+  "version": "0.1.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": {
+    "tb-ppt-mgagent": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "dev": "tsc -w",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "powerpoint",
+    "managed-agents",
+    "anthropic",
+    "claude",
+    "unboundai"
+  ],
+  "type": "module",
+  "author": "Traffic Builders",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.120.0",
+    "@modelcontextprotocol/sdk": "^1.8.0",
+    "@types/node": "^18.19.84",
+    "typescript": "^5.8.2",
+    "zod": "^3.24.2"
+  }
+}