@unboundai/tb-ppt-mgagent 0.1.1 → 0.2.0

package/README.md

@@ -38,6 +38,30 @@ The one thing still **not** confirmed against a real response is the exact `file
    - `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`). 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:
 

package/build/index.js

@@ -37,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";
@@ -45,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;
@@ -168,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({
@@ -191,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",
@@ -204,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",
@@ -230,6 +279,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             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",
@@ -252,6 +308,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             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",
@@ -277,6 +340,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             fs.mkdirSync(outputDir, { recursive: true });
             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",
@@ -294,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.1",
+  "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": {