@kolbo/mcp 1.6.8 → 1.6.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.6.8",
+  "version": "1.6.9",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/src/client.js

@@ -198,12 +198,21 @@ class KolboClient {
 
   async _doRequest(method, reqPath, body = null) {
     const url = `${this.baseUrl}${reqPath}`;
+    const headers = {
+      'X-API-Key': this.apiKey,
+      'Content-Type': 'application/json'
+    };
+    // Stable per-app-launch identifier from the parent process (Kolbo Code
+    // sets this in the MCP env when spawning us). kolbo-api tags every
+    // CreditUsage record with it so the desktop UI and the get_session_usage
+    // tool can aggregate spend without enumerating individual generations.
+    const callerSessionId = process.env.KOLBO_CALLER_SESSION_ID;
+    if (callerSessionId) {
+      headers['X-Kolbo-Caller-Session-Id'] = callerSessionId;
+    }
     const options = {
       method,
-      headers: {
-        'X-API-Key': this.apiKey,
-        'Content-Type': 'application/json'
-      }
+      headers,
     };
 
     if (body) {
@@ -270,6 +279,11 @@ class KolboClient {
       'X-API-Key': this.apiKey,
       ...formData.getHeaders()
     };
+    // Same caller-session header as JSON requests — see _doRequest.
+    const callerSessionId = process.env.KOLBO_CALLER_SESSION_ID;
+    if (callerSessionId) {
+      headers['X-Kolbo-Caller-Session-Id'] = callerSessionId;
+    }
 
     // Serialize form-data to a Buffer before passing to fetch(). Node's
     // built-in fetch (undici) can't consume legacy Node.js streams from

package/src/tools/_shared.js

@@ -200,6 +200,36 @@ async function resolveToBuffer(source, kind, opts = {}) {
   };
 }
 
+/**
+ * Extract real, multiplier-adjusted credit cost from a polled getStatus
+ * response. kolbo-api returns `credits_used` (final number deducted) and
+ * `credits_breakdown` (per-CreditUsage detail) when the generation is
+ * complete. Returns `{}` when the API didn't include them so spreading
+ * the result into a tool's response object is a no-op (forward-compatible
+ * with old kolbo-api versions).
+ *
+ * Usage in every generation tool:
+ *   return {
+ *     content: [{ type: 'text', text: JSON.stringify({
+ *       urls: result.result.urls,
+ *       model: result.result.model,
+ *       ...creditFields(result),   // adds credits_used + credits_breakdown
+ *       _followup_hint: '...',
+ *     }, null, 2) }]
+ *   };
+ */
+function creditFields(polledResult) {
+  if (!polledResult) return {};
+  const out = {};
+  if (typeof polledResult.credits_used === 'number') {
+    out.credits_used = polledResult.credits_used;
+  }
+  if (Array.isArray(polledResult.credits_breakdown) && polledResult.credits_breakdown.length) {
+    out.credits_breakdown = polledResult.credits_breakdown;
+  }
+  return out;
+}
+
 module.exports = {
   MAX_FILE_BYTES,
   VISUAL_DNA_MAX_BYTES,
@@ -208,5 +238,6 @@ module.exports = {
   safeFetch,
   guessFilename,
   guessContentType,
-  resolveToBuffer
+  resolveToBuffer,
+  creditFields,
 };

package/src/tools/chat.js

@@ -5,6 +5,7 @@
 
 const { z } = require('zod');
 const { pollUntilDone } = require('../polling');
+const { creditFields } = require('./_shared');
 
 function registerChatTools(server, client) {
   // ─── chat_send_message ─────────────────────────────────────
@@ -49,6 +50,7 @@ function registerChatTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             session_id: gen.session_id,
             message_id: gen.message_id,
             model: r.model || gen.model,

package/src/tools/generate.js

@@ -6,7 +6,7 @@
 const { z } = require('zod');
 const FormData = require('form-data');
 const { pollUntilDone } = require('../polling');
-const { resolveToBuffer } = require('./_shared');
+const { resolveToBuffer, creditFields } = require('./_shared');
 
 function registerGenerateTools(server, client) {
   // ─── generate_image ────────────────────────────────────────
@@ -41,6 +41,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
             prompt_used: result.result.prompt_used,
@@ -86,6 +87,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
             prompt_used: result.result.prompt_used,
@@ -139,6 +141,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             scenes,
             total_scenes: result.scenes?.length || 0,
             completed_scenes: scenes.length,
@@ -181,6 +184,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
             duration: result.result.duration,
@@ -221,6 +225,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             model: result.result.model,
             duration: result.result.duration,
@@ -260,6 +265,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             title: result.result.title,
             duration: result.result.duration,
@@ -294,6 +300,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             voice: result.result.voice,
             duration: result.result.duration
@@ -327,6 +334,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result.urls,
             duration: result.result.duration
           }, null, 2)
@@ -454,6 +462,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -523,6 +532,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -593,6 +603,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -657,6 +668,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             duration: result.result?.duration || null,
@@ -697,6 +709,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             text: result.result?.text || '',
             srt_url: result.result?.srt_url || null,
             word_by_word_srt_url: result.result?.word_by_word_srt_url || null,
@@ -749,6 +762,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             thumbnail_url: result.result?.thumbnail_url || null,
             mode: result.result?.mode || null,
@@ -790,6 +804,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             edit_type: result.result?.edit_type || null,
             model: result.result?.model || null
@@ -838,6 +853,7 @@ function registerGenerateTools(server, client) {
         content: [{
           type: 'text',
           text: JSON.stringify({
+            ...creditFields(result),
             urls: result.result?.urls || [],
             download_url: result.result?.download_url || null,
             edit_type: result.result?.edit_type || null,

package/src/tools/models.js

@@ -113,6 +113,38 @@ function registerModelTools(server, client) {
       };
     }
   );
+
+  // ─── get_session_usage ─────────────────────────────────────
+  // Real, multiplier-adjusted credit spend tagged with the caller's
+  // X-Kolbo-Caller-Session-Id (set automatically by the parent process —
+  // no need to pass it). Use this to give the user an honest "you've spent
+  // X credits in this app session" instead of estimating from base credits.
+  server.tool(
+    'get_session_usage',
+    'Fetch real, multiplier-adjusted credit spend for the current Kolbo Code app session. Use when the user asks "how much did I spend?" or before/after a large bulk job so you can quote actual cost (not an estimate from base credits). Returns total + per-tool breakdown + per-model breakdown + a recent list. The caller-session-id is forwarded automatically by the MCP HTTP client.',
+    {},
+    async () => {
+      try {
+        const r = await client.get('/credit-usage/by-caller-session');
+        // The endpoint returns { message, data: { total, count, by_tool, by_model, recent[] } }
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(r.data || r, null, 2)
+          }]
+        };
+      } catch (err) {
+        // 400 from the endpoint means no caller-session-id was forwarded —
+        // surface a clear hint instead of a generic API error.
+        const hint = err?.status === 400
+          ? 'No caller-session-id was forwarded. Ensure the parent process (Kolbo Code / desktop sidecar) sets KOLBO_CALLER_SESSION_ID in this MCP\'s env, or call again after at least one media generation has fired.'
+          : err?.message || 'Failed to fetch session usage';
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ error: hint }, null, 2) }]
+        };
+      }
+    }
+  );
 }
 
 module.exports = { registerModelTools };