@kolbo/mcp 1.51.2 → 1.52.1

package/package.json

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

package/src/index.js

@@ -109,6 +109,10 @@ function createServer(opts = {}) {
     // The single most common failure mode is project confusion — spell out
     // the project contract here so every client gets it without a skill file.
     instructions: [
+      'LOCAL FILES: never upload a user file yourself with cloud credentials, a shell command, or an S3/Spaces script — Kolbo owns this. Over a remote connector (claude.ai / Claude Desktop) the server cannot see local paths at all: call `media_upload_widget` so the user picks the file, then pass the returned https:// URL to the generation/transcription tool. Use `upload_media` only when the path IS reachable from where the MCP server runs (local stdio installs). `list_media` returns URLs for assets already in the library.',
+      'PROMPT CONVENTIONS (Kolbo-specific — these change the OUTPUT, not just the metadata):',
+      'A. Visual DNA: passing `visual_dna_ids` is not enough — every DNA in play must ALSO be tagged inside the prompt text as `@Name`, using the DNA name (e.g. "@Kobi walks into frame"). Moodboards are referenced the same way with `#Name`. Resolve names via `list_visual_dnas` / `list_moodboards`.',
+      'B. The full Kolbo skill is available to you as MCP RESOURCES under `kolbo://skill/`. Read `kolbo://skill/SKILL.md` first — it is the core rules plus a routing index — then read the matching `kolbo://skill/references/...` file before writing prompts for a specific model or workflow (per-model prompt rules, Visual DNA workflow, Creative Director, marketing, cost validation). Do this instead of guessing; the references exist precisely because the rules differ per model.',
       'PROJECT CONTRACT (read this before generating anything):',
       'Everything in Kolbo lives inside a PROJECT — sessions, generations, and media are all project-scoped.',
       '1. When the user names a project ("in my Acme project", "for the summer campaign"), call `list_projects` ONCE to resolve the name to an id, then pass that id as `project_id` on EVERY subsequent generate_* / chat_send_message / upload_media call in the conversation. The target project is per-call, NOT sticky — any call that omits `project_id` silently lands in the default "API Generations" bucket (flagged is_default:true), which users experience as their work going to the wrong project.',
@@ -148,6 +152,9 @@ function createServer(opts = {}) {
   // MCP Apps widget resources (ui://kolbo/*). Registering resources is inert
   // for text-only hosts — they never fetch them.
   registerApps(server);
+  // Serve skill/ as standard MCP resources so connector clients — which never
+  // run `npx @kolbo/mcp install` — can still read the operating guidance.
+  registerSkillResources(server);
   // Declaration-level `_meta['ui/resourceUri']` on every widget-carrying tool —
   // claude.ai prepares the widget iframe from tools/list, not from the result.
   attachToolWidgetMeta(server);
@@ -171,6 +178,7 @@ async function main() {
 // internally, re-exported so a host never has to re-derive them. Additive
 // only — existing consumers (claude.ai, Desktop, npx) are unaffected.
 const { UI, TOOL_WIDGETS, uiMeta, widgetHtml } = require('./apps');
+const { registerSkillResources } = require('./skillResources');
 
 module.exports = { main, createServer, UI, TOOL_WIDGETS, uiMeta, widgetHtml };
 

package/src/skillResources.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * Kolbo skill, served as standard MCP resources.
+ *
+ * Why: `skill/` is installed into a LOCAL agent by `npx @kolbo/mcp install`.
+ * Connector clients (claude.ai / Claude Desktop) never run that install, so
+ * they get the tools but none of the operating guidance — which is why models
+ * on those surfaces write generation prompts without the `@VisualDNA` /
+ * `#Moodboard` conventions the skill mandates.
+ *
+ * Serving the same files as resources closes that gap for every client without
+ * duplicating the content: `skill/` stays the single source of truth (it is
+ * auto-mirrored from kolbo-code — never hand-edit it).
+ *
+ * These are registered with the SDK's own `server.resource(...)`, NOT the
+ * ext-apps `registerAppResource` used for widgets — widgets are deliberately
+ * hidden from generic resource listings, whereas the skill must be discoverable.
+ *
+ * Shape mirrors how the skill already works: SKILL.md is the always-loaded core
+ * with a routing index, and `references/**` are pulled on demand. Resources are
+ * pull-based, so nothing costs tokens until the model actually reads it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SKILL_DIR = path.join(__dirname, '..', 'skill');
+const URI_PREFIX = 'kolbo://skill/';
+
+/** Every markdown file under skill/, as posix-style paths relative to skill/. */
+function listSkillDocs(dir = SKILL_DIR, base = SKILL_DIR) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listSkillDocs(full, base));
+    else if (entry.isFile() && entry.name.endsWith('.md')) {
+      out.push(path.relative(base, full).split(path.sep).join('/'));
+    }
+  }
+  return out;
+}
+
+/** First markdown heading or frontmatter description, for the resource blurb. */
+function describe(text, rel) {
+  const heading = text.match(/^#\s+(.+)$/m);
+  if (heading) return heading[1].trim().slice(0, 160);
+  return `Kolbo skill reference: ${rel}`;
+}
+
+function registerSkillResources(server) {
+  const docs = listSkillDocs();
+  if (!docs.length) return 0;
+
+  for (const rel of docs) {
+    const uri = URI_PREFIX + rel;
+    const abs = path.join(SKILL_DIR, rel);
+    // Name the core doc distinctly so it stands out in a resource list.
+    const name = rel === 'SKILL.md'
+      ? 'Kolbo skill — START HERE (core rules + routing index)'
+      : `Kolbo skill — ${rel.replace(/^references\//, '').replace(/\.md$/, '')}`;
+
+    let blurb;
+    try {
+      blurb = describe(fs.readFileSync(abs, 'utf8'), rel);
+    } catch {
+      blurb = `Kolbo skill reference: ${rel}`;
+    }
+
+    server.resource(
+      name,
+      uri,
+      { mimeType: 'text/markdown', description: blurb },
+      // Read lazily on each request so a mirrored skill update is picked up
+      // without restarting the server.
+      async () => ({
+        contents: [{ uri, mimeType: 'text/markdown', text: fs.readFileSync(abs, 'utf8') }],
+      })
+    );
+  }
+  return docs.length;
+}
+
+module.exports = { registerSkillResources, listSkillDocs, SKILL_DIR, URI_PREFIX };

package/src/tools/_shared.js

@@ -186,8 +186,11 @@ async function resolveToBuffer(source, kind, opts = {}) {
   if (!path.isAbsolute(source)) {
     throw new Error(
       `Local file paths must be absolute: ${source}. ` +
-      `If you are using Kolbo over a remote connector (e.g. claude.ai), local files are not reachable — ` +
-      `pass a public https:// URL instead (upload the file somewhere first, or use a URL from list_media).`
+      `If you are using Kolbo over a remote connector (e.g. claude.ai), local files are not reachable. ` +
+      `DO NOT upload the file yourself with cloud credentials or a shell command — Kolbo has a tool for this. ` +
+      `Call \`media_upload_widget\` to have the user pick the file (remote connectors), or \`upload_media\` ` +
+      `when the file IS reachable from where the MCP server runs, then pass the returned https:// URL here. ` +
+      `A URL from \`list_media\` also works if the asset is already in the library.`
     );
   }
   let stat;
@@ -196,8 +199,11 @@ async function resolveToBuffer(source, kind, opts = {}) {
   } catch (err) {
     throw new Error(
       `Local file not found or unreadable: ${source}. ` +
-      `If you are using Kolbo over a remote connector (e.g. claude.ai), local file paths are not reachable — ` +
-      `pass a public https:// URL instead (upload the file somewhere first, or use a URL from list_media).` +
+      `If you are using Kolbo over a remote connector (e.g. claude.ai), local file paths are not reachable. ` +
+      `DO NOT upload the file yourself with cloud credentials or a shell command — Kolbo has a tool for this. ` +
+      `Call \`media_upload_widget\` to have the user pick the file (remote connectors), or \`upload_media\` ` +
+      `when the file IS reachable from where the MCP server runs, then pass the returned https:// URL here. ` +
+      `A URL from \`list_media\` also works if the asset is already in the library.` +
       (err && err.code ? ` [${err.code}]` : '')
     );
   }