@unboundai/tb-ppt-mgagent 0.1.0 → 0.2.0

package/README.md

@@ -15,7 +15,9 @@ Built against the official Managed Agents docs (session creation, session operat
 
 ## 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`.
+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 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`.
 
 ## Setup
 
@@ -36,14 +38,39 @@ Everything above matches the documented API and SDK method signatures verbatim (
    - `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.
+   - `TB_PPT_LOG_FILE` — optional. Path to the task log file. Defaults to `logs/tasks.log` next to this package.
+
+## Task logging
+
+Every tool call writes one JSON-lines entry to `TB_PPT_LOG_FILE` (default `logs/tasks.log`) and mirrors it to stderr (which the MCP host's own log viewer already shows, as seen in the `[powerpoint-creator]` logs). Each line has a `timestamp`, `tool`, and `status`, plus whatever's relevant to that outcome:
+
+| status | tool | meaning |
+|---|---|---|
+| `started` | either | call received, with its key arguments (outline preview/length, or sessionId) |
+| `success` | `generate_tb_powerpoint` | session created; includes `sessionId` |
+| `not_ready` | `get_tb_powerpoint_result` | session isn't `idle` yet; includes `sessionStatus` |
+| `not_end_turn` | `get_tb_powerpoint_result` | idle, but `stop_reason` wasn't `end_turn`; includes `stopReason` |
+| `no_output_file` | `get_tb_powerpoint_result` | finished cleanly but no `.pptx` found; includes `fileCount` |
+| `success` | `get_tb_powerpoint_result` | file downloaded; includes `filename`, `downloadUrl` |
+| `invalid_arguments` | either | zod validation failed; includes `details` |
+| `error` | either | anything else threw; includes `message` |
+
+All entries include `durationMs` except the initial `started` line. To see what's been run:
+
+```bash
+tail -f logs/tasks.log
+# or, for just failures:
+grep -E '"status":"(error|not_end_turn|no_output_file)"' logs/tasks.log
+```
 
-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`):
+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`). 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:
 
    ```json
    "tb-ppt-mgagent": {
-     "command": "node",
+     "command": "npx",
      "args": [
-       "/path/to/tb-ppt-mgAgent/build/index.js"
+       "-y",
+       "@unboundai/tb-ppt-mgagent"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
@@ -55,6 +82,25 @@ Everything above matches the documented API and SDK method signatures verbatim (
    }
    ```
 
+   Or, from a local checkout of this repo:
+
+   ```json
+   "tb-ppt-mgagent": {
+     "command": "node",
+     "args": [
+       "/path/to/tb-ppt-mgAgent/build/index.js"
+     ],
+     "env": { "...": "same as above" }
+   }
+   ```
+
+   ### Publishing a new version
+
+   ```bash
+   npm version patch   # or minor/major
+   npm publish         # prepublishOnly rebuilds automatically; will prompt for a 2FA OTP
+   ```
+
 ## Development
 
 ```bash

package/build/index.js

@@ -19,11 +19,13 @@
  * 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.
+ * Every call here is checked against @anthropic-ai/sdk's own .d.ts/source
+ * (v0.120.0, the latest published at the time of writing) rather than taken
+ * on faith from the docs prose - the docs' TypeScript sample for downloading
+ * a file shows `content.writeToFile(path)`, but that method does not exist
+ * on the installed SDK: `files.download()` resolves to a plain `Response`,
+ * read with `.arrayBuffer()` below. If a future SDK version reintroduces a
+ * writeToFile-style helper, this can simplify back down.
  *
  * Environment variables:
  * - ANTHROPIC_API_KEY: required. Anthropic API key with Managed Agents access.
@@ -35,6 +37,11 @@
  * - 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.
+ * - TB_PPT_LOG_FILE: optional. Path to a JSON-lines task log (one call per
+ *   line: tool, status, timing, and relevant ids). Defaults to logs/tasks.log
+ *   next to this package. Every entry is also mirrored to stderr, which the
+ *   MCP host's own log viewer already picks up - the file exists so history
+ *   survives a host restart and can be grepped/tailed directly.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -43,7 +50,27 @@ import { z } from "zod";
 import Anthropic from "@anthropic-ai/sdk";
 import fs from "fs";
 import path from "path";
+import { fileURLToPath } from "url";
 const MANAGED_AGENTS_BETA = "managed-agents-2026-04-01";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LOG_FILE = process.env.TB_PPT_LOG_FILE || path.join(__dirname, "..", "logs", "tasks.log");
+/**
+ * Records one line of task history: a JSON object to LOG_FILE, and a short
+ * human-readable echo to stderr (stdout is reserved for MCP's own JSON-RPC
+ * traffic in stdio mode - never write task logs there).
+ */
+function logTask(event) {
+    const record = { timestamp: new Date().toISOString(), ...event };
+    const line = JSON.stringify(record);
+    try {
+        fs.mkdirSync(path.dirname(LOG_FILE), { recursive: true });
+        fs.appendFileSync(LOG_FILE, line + "\n");
+    }
+    catch (err) {
+        console.error(`Failed to write task log to ${LOG_FILE}: ${err.message}`);
+    }
+    console.error(`[task] ${line}`);
+}
 const API_KEY = process.env.ANTHROPIC_API_KEY;
 const AGENT_ID = process.env.ANTHROPIC_AGENT_ID;
 const ENVIRONMENT_ID = process.env.ANTHROPIC_ENVIRONMENT_ID;
@@ -166,9 +193,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    const startedAt = Date.now();
     try {
         if (name === "generate_tb_powerpoint") {
             const { outline, deckType, clientName, filename } = GenerateTbPowerpointSchema.parse(args);
+            logTask({
+                tool: name,
+                status: "started",
+                outlinePreview: outline.slice(0, 120),
+                outlineLength: outline.length,
+                deckType: deckType ?? null,
+                clientName: clientName ?? null,
+                filename: filename ?? null
+            });
             const { apiKey, agentId, environmentId } = requireSessionConfig();
             const client = getClient(apiKey);
             const session = await client.beta.sessions.create({
@@ -189,6 +226,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     { type: "user.message", content: [{ type: "text", text: messageText }] }
                 ]
             });
+            logTask({
+                tool: name,
+                status: "success",
+                sessionId: session.id,
+                durationMs: Date.now() - startedAt
+            });
             return {
                 content: [{
                         type: "text",
@@ -202,10 +245,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         if (name === "get_tb_powerpoint_result") {
             const { sessionId } = GetTbPowerpointResultSchema.parse(args);
+            logTask({ tool: name, status: "started", sessionId });
             const apiKey = requireApiKey();
             const client = getClient(apiKey);
             const session = await client.beta.sessions.retrieve(sessionId);
             if (session.status !== "idle") {
+                logTask({
+                    tool: name,
+                    status: "not_ready",
+                    sessionId,
+                    sessionStatus: session.status,
+                    durationMs: Date.now() - startedAt
+                });
                 return {
                     content: [{
                             type: "text",
@@ -218,17 +269,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             // 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 ?? "")) {
+                    if (!latestIdleEvent || event.processed_at > latestIdleEvent.processed_at) {
                         latestIdleEvent = event;
                     }
                 }
             }
-            const stopReasonType = latestIdleEvent?.stop_reason?.type;
+            const stopReasonType = latestIdleEvent?.stop_reason.type;
             if (stopReasonType !== "end_turn") {
+                logTask({
+                    tool: name,
+                    status: "not_end_turn",
+                    sessionId,
+                    stopReason: stopReasonType ?? null,
+                    durationMs: Date.now() - startedAt
+                });
                 return {
                     content: [{
                             type: "text",
@@ -246,11 +303,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 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 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) {
+                logTask({
+                    tool: name,
+                    status: "no_output_file",
+                    sessionId,
+                    fileCount: fileList.length,
+                    durationMs: Date.now() - startedAt
+                });
                 return {
                     content: [{
                             type: "text",
@@ -267,10 +331,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { outputDir, publicUrlBase } = requireOutputConfig();
             const safeName = path.basename(chosen.filename || `${sessionId}.pptx`);
             const destPath = path.join(outputDir, safeName);
+            // files.download() resolves to a plain Response on this SDK version - no
+            // writeToFile() helper (see file header). Read the bytes and write them ourselves.
+            const response = await client.beta.files.download(chosen.id, {
+                betas: [MANAGED_AGENTS_BETA]
+            });
+            const arrayBuffer = await response.arrayBuffer();
             fs.mkdirSync(outputDir, { recursive: true });
-            const content = await client.beta.files.download(chosen.id);
-            await content.writeToFile(destPath);
+            fs.writeFileSync(destPath, Buffer.from(arrayBuffer));
             const downloadUrl = `${publicUrlBase.replace(/\/$/, "")}/${encodeURIComponent(safeName)}`;
+            logTask({
+                tool: name,
+                status: "success",
+                sessionId,
+                filename: safeName,
+                downloadUrl,
+                durationMs: Date.now() - startedAt
+            });
             return {
                 content: [{
                         type: "text",
@@ -288,17 +365,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         throw new Error(`Unknown tool: ${name}`);
     }
     catch (error) {
+        const durationMs = Date.now() - startedAt;
         if (error instanceof z.ZodError) {
+            const details = error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+            logTask({ tool: name, status: "invalid_arguments", details, durationMs });
             return {
                 content: [{
                         type: "text",
                         text: JSON.stringify({
                             error: "Invalid arguments",
-                            details: error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ")
+                            details
                         }, null, 2)
                     }]
             };
         }
+        logTask({ tool: name, status: "error", message: error.message, durationMs });
         return {
             content: [{
                     type: "text",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundai/tb-ppt-mgagent",
-  "version": "0.1.0",
+  "version": "0.2.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": {