@olivaresai/alma-mcp 1.3.2 → 1.3.3

package/README.md

@@ -47,11 +47,11 @@ Then use `"command": "alma-mcp"` instead of `npx`.
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `ALMA_API_KEY` | Yes | Your Alma API key ([get one here](https://alma.olivares.ai/settings)) |
-| `ALMA_BASE_URL` | No | API base URL (default: `https://alma.olivares.ai/api/v1`) |
+| `ALMA_API_URL` | No | API base URL (default: `https://alma.olivares.ai/api/v1`). `ALMA_BASE_URL` is accepted as an alias. |
 | `ALMA_ENVIRONMENT_ID` | No | Default environment ID |
 | `ALMA_DEBUG` | No | Enable debug logging |
 
-## Tools (21)
+## Tools (35)
 
 ### Context
 
@@ -94,7 +94,31 @@ Then use `"command": "alma-mcp"` instead of `npx`.
 | `alma_list_environments` | List all environments |
 | `alma_create_environment` | Create a new environment |
 
-## Resources (9)
+### Cowork (Collaborative Workspaces)
+
+| Tool | Description |
+|------|-------------|
+| `cowork_list_workspaces` | List all collaborative workspaces |
+| `cowork_create_workspace` | Create a new collaborative workspace |
+| `cowork_list_files` | List all files in a workspace |
+| `cowork_read_file` | Read the content of a workspace file |
+| `cowork_write_file` | Write or update a file in a workspace |
+| `cowork_search` | Search across all files in a workspace |
+| `cowork_execute_skill` | Run an AI skill on a file (explain, refactor, review, test, fix, document, search, commit) |
+| `cowork_apply_diff` | Apply a pending operation diff to a workspace file |
+
+### Video
+
+| Tool | Description |
+|------|-------------|
+| `video_generate` | Start an AI video generation job |
+| `video_check_job` | Check the status of a video generation job |
+| `video_list_projects` | List all video projects |
+| `video_create_project` | Create a new video project |
+| `video_plan_scenes` | Use AI to plan scenes for a video project |
+| `video_stitch` | Stitch multiple video scenes into a single final video |
+
+## Resources (10)
 
 | Resource URI | Description |
 |-------------|-------------|
@@ -104,6 +128,7 @@ Then use `"command": "alma-mcp"` instead of `npx`.
 | `alma://environments` | All available environments |
 | `alma://conversations` | Recent conversations (last 20) |
 | `alma://budget` | Token budget status |
+| `alma://video-budget` | Video generation credits and usage |
 | `alma://blocks` | All soul memory blocks |
 | `alma://episodes` | Recent episodes (last 20) |
 | `alma://procedures` | All stored procedures (limit 50) |

package/dist/index.js

@@ -18,10 +18,40 @@ function loadConfig() {
     console.error("[alma-mcp] ALMA_API_URL must use HTTPS for non-localhost connections. Got:", cleanUrl);
     process.exit(1);
   }
+  if (!cleanUrl.startsWith("https://") && process.env.NODE_ENV !== "development" && process.env.ALMA_DEV !== "1") {
+    console.error(
+      `[alma-mcp] WARNING: ALMA_API_URL points at ${cleanUrl}. This is only correct for local development. For Alma cloud use https://alma.olivares.ai/api/v1 (or set NODE_ENV=development to silence this warning).`
+    );
+  }
   return { baseUrl: cleanUrl, apiKey, environmentId };
 }
 
 // src/client.ts
+function formatApiError(method, path, status, detail, code) {
+  const tail = detail ? ` ${detail}` : "";
+  if (status === 401) {
+    return `Alma rejected the API key. Generate a new one at https://alma.olivares.ai/settings (API Keys) and set ALMA_API_KEY in your MCP config.${tail}`;
+  }
+  if (status === 402) {
+    if (code === "BUDGET_EXHAUSTED" || /budget/i.test(detail)) {
+      return `Your Alma weekly AI budget is exhausted. Top up at https://alma.olivares.ai/settings/billing or wait until Monday 00:00 UTC for the budget to reset.${tail}`;
+    }
+    return `This action requires an active Alma plan or additional credits. Manage your subscription at https://alma.olivares.ai/settings/billing.${tail}`;
+  }
+  if (status === 403) {
+    if (code === "PLAN_API_RESTRICTED" || /api/i.test(detail)) {
+      return `The Alma API is available on the Max plan. Upgrade at https://alma.olivares.ai/settings/billing.${tail}`;
+    }
+    if (code === "BYOK_REQUIRED_PLAN") {
+      return `BYOK (bring your own keys) is available on the Max plan. Upgrade at https://alma.olivares.ai/settings/billing.${tail}`;
+    }
+    return `Forbidden \u2014 your plan does not include this feature. See https://alma.olivares.ai/settings/billing.${tail}`;
+  }
+  if (status === 429) {
+    return `Alma rate limit hit. Slow down and retry in a minute.${tail}`;
+  }
+  return `Alma API ${method} ${path} failed (${status}):${tail}`;
+}
 var AlmaClient = class _AlmaClient {
   constructor(config2) {
     this.config = config2;
@@ -83,12 +113,14 @@ var AlmaClient = class _AlmaClient {
     if (!res.ok) {
       const text = await res.text().catch(() => "");
       let detail = text;
+      let code;
       try {
         const json = JSON.parse(text);
         detail = json.error?.message ?? json.message ?? text;
+        code = json.error?.code ?? json.code;
       } catch {
       }
-      throw new Error(`Alma API ${method} ${path} failed (${res.status}): ${detail}`);
+      throw new Error(formatApiError(method, path, res.status, detail, code));
     }
     return res.json();
   }
@@ -185,7 +217,15 @@ var AlmaClient = class _AlmaClient {
     );
     if (!res.ok) {
       const text2 = await res.text().catch(() => "");
-      throw new Error(`Chat send failed (${res.status}): ${text2}`);
+      let detail = text2;
+      let code;
+      try {
+        const json = JSON.parse(text2);
+        detail = json.error?.message ?? json.message ?? text2;
+        code = json.error?.code ?? json.code;
+      } catch {
+      }
+      throw new Error(formatApiError("POST", `/chat/conversations/${conversationId}/messages`, res.status, detail, code));
     }
     const text = await res.text();
     const rawEvents = text.split("\n\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olivaresai/alma-mcp",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "MCP Server for Alma by OlivaresAI — persistent memory for AI agents",
   "type": "module",
   "bin": {