@ateam-ai/mcp 0.4.82 → 0.4.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai/mcp",
-  "version": "0.4.82",
+  "version": "0.4.84",
   "mcpName": "io.github.ariekogan/ateam-mcp",
   "description": "A-Team MCP Server — build, validate, and deploy multi-agent solutions from any AI environment",
   "type": "module",

package/src/api.js

@@ -493,8 +493,11 @@ function headers(sessionId) {
 
 /**
  * Format an API error into a user-friendly message with actionable hints.
+ *
+ * Exported so the hints can be TESTED as behaviour rather than as source text.
+ * A test that greps for the right-looking code passes on code that never runs.
  */
-function formatError(method, path, status, body, baseUrl) {
+export function formatError(method, path, status, body, baseUrl) {
   const hints = {
     400: "Bad request — see the error details above for what to fix.",
     401: "Your API key may be invalid or expired. Get a valid key at https://mcp.ateam-ai.com/get-api-key then call ateam_auth(api_key: \"your_key\").",
@@ -532,6 +535,23 @@ function formatError(method, path, status, body, baseUrl) {
     }
   }
 
+  // A 404 ON /spec IS NOT A MISSING SOLUTION.
+  //
+  // The table answers every 404 with "check the solution_id or skill_id".
+  // /spec/* takes neither. Asking for a topic this deployment does not serve —
+  // which happens the moment the tool ships ahead of the backend, as
+  // device-capabilities did on 2026-09-04 — sent the reader looking for a
+  // solution that was never involved. The environment is the whole answer, so
+  // name it: the same call against a newer deployment succeeds.
+  if (status === 404 && /^\/spec(\/|$)/.test(String(path || ""))) {
+    const topic = String(path).replace(/^\/spec\/?/, "") || "(index)";
+    hints[404] =
+      `Nothing to do with solutions — /spec takes no solution_id or skill_id. The A-Team API at ` +
+      `${baseUrl || "this URL"} does not serve the topic "${topic}". Either the topic name is wrong (ateam_get_spec ` +
+      `with topic:"overview" lists what this deployment has), or this backend is OLDER than the tool you are ` +
+      `calling from and the topic has not been deployed here yet. Retrying will not change either.`;
+  }
+
   // A 500 THAT NAMES A MISSING CONFIGURATION IS NOT "TRY AGAIN IN A MINUTE".
   //
   // /chat answered 500 {"message":"OPENAI_API_KEY is not set"} and this table

package/src/tools.js

@@ -3129,6 +3129,18 @@ const handlers = {
     design_advisor: {
       _important: "BEFORE and WHILE you design any skill/solution you MUST consult ateam_design_advisor. You do NOT know which platform capabilities exist or when to use them — the advisor does. Describe your goal to it and it returns pointers to the right capabilities (per-actor storage, widgets, triggers, sub-agents, mobile data, run-scripts, multi-skill handoff, GitHub, …) with the /spec topic to read next and the tool to wire each. It's advisory — you decide and own the design — but skipping it means you'll miss capabilities the platform already provides.",
       how: "ateam_design_advisor({ goal: '<what you are building, in your words>', design_state: {} }). Re-call it as the design evolves (pass the current design_state) to get 'what's still missing' hints. Then ateam_get_spec(topic) for any capability it points you to. For anything deeper — details, examples, or topics outside the capability list — ateam_spec_search({ query: '<how do I…>' }) does a semantic search over the FULL spec docs.",
+      // A MANDATE WITH NO FALLBACK IS A SINGLE POINT OF FAILURE, and it failed:
+      // on 2026-09-04 the advisor errored three times for one design and the
+      // agent, told to consult it and given nowhere else to go, fell back to
+      // reading whichever spec topic happened to mention the thing it wanted —
+      // and concluded a capability was absent that had shipped. Name the other
+      // doors here, at the point where the obligation is stated.
+      if_the_advisor_does_not_answer:
+        "It is not the only door and you are NOT stuck. ateam_get_spec(topic:'device-capabilities') is the GENERATED " +
+        "capability matrix (what the phone can do, per API, with status) and ateam_spec_search({query}) searches the full " +
+        "spec corpus — neither has an LLM in the path, so neither fails the way the advisor can. If the advisor answers " +
+        "with `truncated: true`, what you got is CORRECT but INCOMPLETE: use it, and treat a capability's absence as " +
+        "UNKNOWN rather than 'no' — re-ask with a narrower goal, or check the two tools above.",
     },
     what_is_a_team: {
       definition: "A Team is a structured multi-role AI system composed of Skills, Connectors, Governance contracts, and Managed Runtime deployment.",