@aistoragedepot/mcp 0.5.0 → 0.5.3

package/README.md

@@ -56,7 +56,7 @@ your library as **native** slash-commands, sync it to command files — for ever
 use, not just Claude:
 
 ```bash
-npx -y @aistoragedepot/mcp pull --token=aisd_your_token --to=all
+npx -y -p @aistoragedepot/mcp aistoragedepot-mcp pull --token=aisd_your_token --to=all
 ```
 
 | Target | Writes to | Commands appear as |

package/index.mjs

@@ -23,7 +23,7 @@ import {
 
 const BASE_URL = (process.env.AISD_BASE_URL || "https://www.aistoragedepot.com").replace(/\/+$/, "");
 
-// CLI mode: `aistoragedepot-mcp pull` syncs the library to native slash-command files, then
+// CLI mode: `npx -y @aistoragedepot/mcp pull` syncs the library to native slash-command files, then
 // exits. The brief settle delay lets undici finish closing its sockets (Connection: close)
 // before process.exit — a hard exit mid-teardown trips a libuv assert on Windows (Node 24)
 // that prints a scary-but-harmless message after the sync succeeds.
@@ -52,7 +52,12 @@ async function api(path) {
     headers: { Authorization: `Bearer ${TOKEN}`, Accept: "application/json" },
   });
   if (res.status === 401) throw new Error("AIStorageDepot rejected the token (401) — check AISD_TOKEN.");
-  if (!res.ok) throw new Error(`AIStorageDepot ${path} → HTTP ${res.status}`);
+  if (!res.ok) {
+    // Surface the server's own message when it sends one (e.g. the free-plan
+    // monthly pull limit returns 402 with an upgrade note) instead of a bare code.
+    const detail = await res.json().then((d) => d?.error).catch(() => null);
+    throw new Error(detail || `AIStorageDepot ${path} → HTTP ${res.status}`);
+  }
   return res.json();
 }
 
@@ -140,6 +145,34 @@ function fillBody(body, placeholders, args) {
   return out;
 }
 
+// Which MCP arg-names are required (their [placeholder] was marked required by the author).
+function requiredArgNames(placeholders, requiredFields = []) {
+  const req = new Set(requiredFields);
+  const out = new Set();
+  for (const [argName, original] of argMap(placeholders)) if (req.has(original)) out.add(argName);
+  return out;
+}
+
+// A "stop and ask first" instruction for any required field missing from the args — prepended to the
+// prompt so even clients that ignore `required` don't run half-blank. "" when nothing's missing.
+function missingRequiredPreamble(placeholders, requiredFields = [], args = {}) {
+  const req = new Set(requiredFields);
+  const missing = [];
+  for (const [argName, original] of argMap(placeholders)) {
+    if (!req.has(original)) continue;
+    const v = args?.[argName];
+    if (v == null || v === "") missing.push(original);
+  }
+  if (!missing.length) return "";
+  const list = missing.map((f) => `[${f}]`).join(", ");
+  const one = missing.length === 1;
+  return (
+    `⚠ Before doing anything else, ask me for a value for ${one ? "this field" : "these fields"}: ${list}. ` +
+    `Do not explore, run, generate, or take any action until I answer. Then substitute my ${one ? "answer" : "answers"} ` +
+    `for ${one ? "that field" : "those fields"} and carry out the prompt below.\n\n`
+  );
+}
+
 const server = new Server(
   { name: "aistoragedepot", version: "0.5.0" },
   { capabilities: { resources: {}, prompts: {}, tools: {} } },
@@ -172,13 +205,14 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
   const prompts = [];
   for (const [name, it] of scopedPromptIndex(await snapshot())) {
     const am = argMap(it.placeholders);
+    const req = requiredArgNames(it.placeholders, it.requiredFields);
     prompts.push({
       name,
       description: `${it.type?.name || "Prompt"}: “${it.title}” (AIStorageDepot)`,
       arguments: [...am.keys()].map((a) => ({
         name: a,
         description: `Value for [${am.get(a)}]`,
-        required: false,
+        required: req.has(a),
       })),
     });
   }
@@ -188,7 +222,8 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
 server.setRequestHandler(GetPromptRequestSchema, async (req) => {
   const it = scopedPromptIndex(await snapshot()).get(req.params.name);
   if (!it) throw new Error(`Unknown prompt: ${req.params.name}`);
-  const text = fillBody(it.body, it.placeholders, req.params.arguments || {});
+  const args = req.params.arguments || {};
+  const text = missingRequiredPreamble(it.placeholders, it.requiredFields, args) + fillBody(it.body, it.placeholders, args);
   return {
     description: it.title,
     messages: [{ role: "user", content: { type: "text", text } }],

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@aistoragedepot/mcp",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "Model Context Protocol server for your AIStorageDepot library — exposes your prompts, rules, docs, and skills to MCP-aware AI clients (Claude, Cursor, Cline, …).",
   "type": "module",
   "bin": {
+    "mcp": "index.mjs",
     "aistoragedepot-mcp": "index.mjs"
   },
   "files": [

package/pull.mjs

@@ -1,4 +1,4 @@
-// `aistoragedepot-mcp pull` — sync your library into native slash-command files for the
+// `npx @aistoragedepot/mcp pull` — sync your library into native slash-command files for the
 // AI tools you use.
 //
 // Every major client now reads commands from a folder of markdown files; only the folder
@@ -52,14 +52,22 @@ function fmFile(fm, body) {
   return ["---", ...Object.entries(fm).map(([k, v]) => `${k}: "${yq(v)}"`), "---", "", String(body).trim(), ""].join("\n");
 }
 
+// Required fields the author marked (intersected with the fields actually in this body).
+const reqOf = (it, fields) => (it.requiredFields || []).filter((f) => fields.includes(f));
+// A forceful "these are required — ask first" clause, or the gentle version when none are required.
+const askClause = (required) =>
+  required.length
+    ? ` ${required.length === 1 ? "This field is" : "These fields are"} REQUIRED: ${required.map((f) => `[${f}]`).join(", ")} — if a value wasn't provided, STOP and ask me first; don't explore, run, or generate anything until I answer.`
+    : ` Ask me for any value that's missing.`;
+
 // Tail for tools that substitute $ARGUMENTS (claude, codex).
-const argsTail = (fields) =>
+const argsTail = (fields, required = []) =>
   fields.length
-    ? `\n\nInput: $ARGUMENTS\n\nFill the bracketed ${fields.length === 1 ? "field" : "fields"} in the prompt above from the input — ask me for any value that's missing — then carry out the prompt.`
+    ? `\n\nInput: $ARGUMENTS\n\nFill the bracketed ${fields.length === 1 ? "field" : "fields"} in the prompt above from the input.${askClause(required)} Then carry out the prompt.`
     : "\n\n$ARGUMENTS";
 // Tail for tools that just pass the typed text along with the inserted prompt.
-const fillTail = (fields) =>
-  `\n\nFill the bracketed ${fields.length === 1 ? "field" : "fields"} (${fields.map((f) => `[${f}]`).join(", ")}) from anything I typed along with this command — ask me for any value that's missing — then carry out the prompt.`;
+const fillTail = (fields, required = []) =>
+  `\n\nFill the bracketed ${fields.length === 1 ? "field" : "fields"} (${fields.map((f) => `[${f}]`).join(", ")}) from anything I typed along with this command.${askClause(required)} Then carry out the prompt.`;
 
 // ── per-target renderers ─────────────────────────────────────────────────────
 
@@ -72,7 +80,7 @@ function renderClaude(it) {
     const fields = fieldsOf(content);
     const fm = { description: `Prompt — ${it.title} (AIStorageDepot)` };
     if (fields.length) fm["argument-hint"] = fields.map((f) => `[${f}]`).join(" ");
-    return fmFile(fm, content.trim() + argsTail(fields));
+    return fmFile(fm, content.trim() + argsTail(fields, reqOf(it, fields)));
   }
   if (/^---\r?\n/.test(body)) return body.endsWith("\n") ? body : `${body}\n`;
   return fmFile({ description: `${it.title} (AIStorageDepot)` }, body);
@@ -85,7 +93,7 @@ function renderCodex(it) {
   const fields = isPromptItem(it) ? fieldsOf(content) : [];
   const fm = { description: descFor(it, meta) };
   if (isPromptItem(it) && fields.length) fm["argument-hint"] = fields.map((f) => `[${f}]`).join(" ");
-  return fmFile(fm, content.trim() + (isPromptItem(it) ? argsTail(fields) : ""));
+  return fmFile(fm, content.trim() + (isPromptItem(it) ? argsTail(fields, reqOf(it, fields)) : ""));
 }
 
 // VS Code prompt files: description + argument-hint frontmatter; typed extras arrive as
@@ -95,21 +103,21 @@ function renderVscode(it) {
   const fields = isPromptItem(it) ? fieldsOf(content) : [];
   const fm = { description: descFor(it, meta) };
   if (fields.length) fm["argument-hint"] = fields.map((f) => `[${f}]`).join(" ");
-  return fmFile(fm, content.trim() + (fields.length ? fillTail(fields) : ""));
+  return fmFile(fm, content.trim() + (fields.length ? fillTail(fields, reqOf(it, fields)) : ""));
 }
 
 // Windsurf workflows: description frontmatter; 12k char cap per file (enforced by caller).
 function renderWindsurf(it) {
   const { meta, content } = splitFrontmatter(it.body || "");
   const fields = isPromptItem(it) ? fieldsOf(content) : [];
-  return fmFile({ description: descFor(it, meta) }, content.trim() + (fields.length ? fillTail(fields) : ""));
+  return fmFile({ description: descFor(it, meta) }, content.trim() + (fields.length ? fillTail(fields, reqOf(it, fields)) : ""));
 }
 
 // Cursor commands: plain markdown — no frontmatter dialect; the body IS the prompt.
 function renderCursor(it) {
   const { content } = splitFrontmatter(it.body || "");
   const fields = isPromptItem(it) ? fieldsOf(content) : [];
-  return content.trim() + (fields.length ? fillTail(fields) : "") + "\n";
+  return content.trim() + (fields.length ? fillTail(fields, reqOf(it, fields)) : "") + "\n";
 }
 
 // ── targets ──────────────────────────────────────────────────────────────────
@@ -196,7 +204,11 @@ export async function pull({ BASE_URL, argv }) {
       headers: { Authorization: `Bearer ${token}`, Accept: "application/json", Connection: "close" },
     });
     if (r.status === 401) throw new Error("Token rejected (401) — check it in Settings → API tokens.");
-    if (!r.ok) throw new Error(`${p} → HTTP ${r.status}`);
+    if (!r.ok) {
+      // Prefer the server's message (e.g. the free-plan pull limit's 402 upgrade note).
+      const detail = await r.json().then((d) => d?.error).catch(() => null);
+      throw new Error(detail || `${p} → HTTP ${r.status}`);
+    }
     return r.json();
   };