@latellu/atlas-mcp 1.0.5 → 1.0.7

package/README.md

@@ -5,6 +5,8 @@
 
 MCP (Model Context Protocol) server for Atlas CMS — enables AI agents to manage content.
 
+**Docs & dashboard:** concepts and API reference live at **[docs.atlas.latellu.com](https://docs.atlas.latellu.com)**; the app where you create workspaces, content, and API keys is **[cms.atlas.latellu.com](https://cms.atlas.latellu.com)**.
+
 ## Overview
 
 This MCP server exposes Atlas CMS content management operations as tools for AI agents (Claude, Cursor, etc.). It enables AI agents to:
@@ -14,6 +16,19 @@ This MCP server exposes Atlas CMS content management operations as tools for AI
 - Create, update, publish, and delete content
 - Upload media files from local filesystem
 
+Building a custom app instead of wiring up an AI agent? Use the [`@latellu/atlas-sdk`](https://www.npmjs.com/package/@latellu/atlas-sdk) TypeScript SDK — this server only exposes tools for MCP clients (Claude Desktop, Cursor, etc.), it isn't a general-purpose HTTP client.
+
+## Core Concepts
+
+New to Atlas? A **workspace** is your tenant — it owns all content types, entries, pages, media, and API keys, isolated from other workspaces. Within a workspace:
+
+- **[Content type](https://docs.atlas.latellu.com/docs/content-types)** — a schema (e.g. "Article") defining the fields an entry can have.
+- **[Entry](https://docs.atlas.latellu.com/docs/entries)** — a record of a content type, with a **draft → published → archived** lifecycle.
+- **[Page](https://docs.atlas.latellu.com/docs/pages)** — like an entry, but composed of ordered **blocks** and carries its own SEO metadata.
+- **[Locale](https://docs.atlas.latellu.com/docs/localization)** — a language variant; localized fields fall back to the workspace's default locale when untranslated.
+
+See the [Getting Started guide](https://docs.atlas.latellu.com/docs/getting-started) for the full picture.
+
 ## Features
 
 ### Schema & Discovery
@@ -63,23 +78,30 @@ atlas-mcp
 
 ### Getting an API Key
 
-1. Open the Atlas dashboard: **https://cms.atlas.latellu.com**
-2. Go to **Settings → API Keys**
-3. Click **Create API Key**, give it a name, and save
-4. Copy the key — it is only shown once
+1. Open **[cms.atlas.latellu.com/dashboard/api-keys](https://cms.atlas.latellu.com/dashboard/api-keys)** (sidebar: **Developer → API Keys**)
+2. Click **Create API Key**, give it a name, pick its scopes, and save
+3. Copy the key — it is only shown once
 
 **Key types:**
-- `atlas_live_*` — Read-only access (delivery API). Use for fetching content.
-- `atlas_mgmt_*` — Read-write access (management API). Use for creating/updating content.
+- `atlas_live_*` — Delivery API key. Required for every **read** tool (`get_workspace_schema`, `list_*`, `get_*`).
+- `atlas_mgmt_*` — Management API key. Required for every **write** tool (`create_*`, `update_*`, `delete_*`, `publish_*`, `unpublish_*`, `archive_*`, `duplicate_*`, `upload_media`).
+
+The backend enforces one key type per route group — a management key cannot read `/api/v1/public/*`, and a delivery key cannot write to `/api/v1/manage/*`. **For the full tool set (read + write), configure both keys.** A single key only unlocks the half of the tools matching its type; calling a tool that needs the other key type returns a clear error naming the missing env var.
+
+See [docs.atlas.latellu.com/docs/authentication](https://docs.atlas.latellu.com/docs/authentication) for how scopes work and the full authentication reference.
 
 ### Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `ATLAS_API_KEY` | Yes | Atlas API key (`atlas_live_*` for read-only, `atlas_mgmt_*` for full access) |
+| `ATLAS_API_KEY` | One of the three below | Single key, auto-detected by prefix (`atlas_live_*` enables read tools, `atlas_mgmt_*` enables write tools) — kept for backward compatibility |
+| `ATLAS_LIVE_API_KEY` | No | Delivery key (`atlas_live_*`), explicitly enables read tools |
+| `ATLAS_MGMT_API_KEY` | No | Management key (`atlas_mgmt_*`), explicitly enables write tools |
 | `ATLAS_API_URL` | No | Atlas API base URL (default: `https://api.atlas.latellu.com`) |
 | `MCP_ALLOWED_UPLOAD_PATHS` | No | Comma-separated list of allowed directories for media upload |
 
+At least one of `ATLAS_API_KEY`, `ATLAS_LIVE_API_KEY`, or `ATLAS_MGMT_API_KEY` must be set. Set `ATLAS_LIVE_API_KEY` and `ATLAS_MGMT_API_KEY` together to enable both read and write tools in the same server.
+
 ### Claude Desktop Configuration
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
@@ -91,7 +113,8 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
       "command": "npx",
       "args": ["-y", "@latellu/atlas-mcp"],
       "env": {
-        "ATLAS_API_KEY": "atlas_mgmt_xxx...",
+        "ATLAS_LIVE_API_KEY": "atlas_live_xxx...",
+        "ATLAS_MGMT_API_KEY": "atlas_mgmt_xxx...",
         "MCP_ALLOWED_UPLOAD_PATHS": "/Users/you/Documents,/Users/you/Pictures"
       }
     }
@@ -99,6 +122,8 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
+Write-only setups (no read tools needed) can still set just `ATLAS_API_KEY` to a single `atlas_mgmt_*` key.
+
 ### Cursor Configuration
 
 Add to `.cursor/mcp.json`:
@@ -110,7 +135,8 @@ Add to `.cursor/mcp.json`:
       "command": "npx",
       "args": ["-y", "@latellu/atlas-mcp"],
       "env": {
-        "ATLAS_API_KEY": "atlas_mgmt_xxx..."
+        "ATLAS_LIVE_API_KEY": "atlas_live_xxx...",
+        "ATLAS_MGMT_API_KEY": "atlas_mgmt_xxx..."
       }
     }
   }
@@ -159,8 +185,9 @@ AI: → Calls upload_media with file_path='/Users/you/Pictures/tokyo.png'
 ### Permission Model
 
 **Layer 1: API Key**
-- `atlas_live_*` — Read-only access (delivery API)
-- `atlas_mgmt_*` — Read-write access (management API)
+- `atlas_live_*` — Read tools only (delivery API)
+- `atlas_mgmt_*` — Write tools only (management API)
+- Configure both (`ATLAS_LIVE_API_KEY` + `ATLAS_MGMT_API_KEY`) for the full tool set
 
 **Layer 2: Filesystem Permission**
 - Configurable via `MCP_ALLOWED_UPLOAD_PATHS` env var
@@ -172,7 +199,7 @@ AI: → Calls upload_media with file_path='/Users/you/Pictures/tokyo.png'
 
 ### Best Practices
 
-1. **Scope API keys**: For management keys, grant only the scopes each tool needs — `content:write` for create/update/delete/reorder, `content:publish` for publish/unpublish/archive/schedule, `media:write` for uploads/deletes. Leave unused scopes off.
+1. **Scope API keys**: For management keys, grant only the scopes each tool needs — `content:write` for create/update/delete/reorder, `content:publish` for publish/unpublish/archive/schedule, `media:write` for uploads/deletes. Leave unused scopes off. Scopes are picked when you create the key at [Developer → API Keys](https://cms.atlas.latellu.com/dashboard/api-keys); see the [scope reference](https://docs.atlas.latellu.com/docs/authentication) for the full list.
 2. **Restrict upload paths**: Only allow necessary directories
 3. **Rotate keys**: Regularly rotate API keys
 4. **Monitor usage**: Review MCP tool calls for suspicious activity

package/dist/index.js

@@ -12556,27 +12556,44 @@ function detectMimeType(fileName) {
 }
 var AtlasClient = class {
   baseUrl;
-  apiKey;
-  constructor(baseUrl, apiKey) {
+  liveKey;
+  mgmtKey;
+  constructor(baseUrl, keys) {
     this.baseUrl = baseUrl;
-    this.apiKey = apiKey;
+    this.liveKey = keys.liveKey;
+    this.mgmtKey = keys.mgmtKey;
   }
-  async request(path2, options) {
+  async httpRequest(path2, apiKey, options) {
     const url = `${this.baseUrl}${path2}`;
     const response = await fetch(url, {
       ...options,
       headers: {
         "Content-Type": "application/json",
-        "X-API-Key": this.apiKey,
+        "X-API-Key": apiKey,
         ...options?.headers
       }
     });
     return this.handleResponse(response);
   }
-  // Write requests to /api/v1/manage/* carry an Idempotency-Key so that
-  // AI-agent-driven retries don't risk double-create/double-publish.
-  async writeRequest(path2, options) {
-    return this.request(path2, {
+  // Reads against /api/v1/public/* require a delivery key (atlas_live_*).
+  async publicRequest(path2, options) {
+    if (!this.liveKey) {
+      throw new Error(
+        "This operation requires a delivery API key (atlas_live_*). Set ATLAS_LIVE_API_KEY (or ATLAS_API_KEY to an atlas_live_* key) to enable read operations."
+      );
+    }
+    return this.httpRequest(path2, this.liveKey, options);
+  }
+  // Writes against /api/v1/manage/* require a management key (atlas_mgmt_*)
+  // and carry an Idempotency-Key so AI-agent-driven retries don't risk
+  // double-create/double-publish.
+  async manageRequest(path2, options) {
+    if (!this.mgmtKey) {
+      throw new Error(
+        "This operation requires a management API key (atlas_mgmt_*). Set ATLAS_MGMT_API_KEY (or ATLAS_API_KEY to an atlas_mgmt_* key) to enable write operations."
+      );
+    }
+    return this.httpRequest(path2, this.mgmtKey, {
       ...options,
       headers: {
         "Idempotency-Key": crypto.randomUUID(),
@@ -12596,7 +12613,7 @@ var AtlasClient = class {
   }
   // Schema endpoints
   async getWorkspaceSchema() {
-    return this.request("/api/v1/public/schema");
+    return this.publicRequest("/api/v1/public/schema");
   }
   async listContentTypes() {
     const schema = await this.getWorkspaceSchema();
@@ -12617,45 +12634,45 @@ var AtlasClient = class {
     if (params?.page) searchParams.set("page", params.page.toString());
     if (params?.limit) searchParams.set("limit", params.limit.toString());
     if (params?.status) searchParams.set("status", params.status);
-    return this.request(`/api/v1/public/entries?${searchParams.toString()}`);
+    return this.publicRequest(`/api/v1/public/entries?${searchParams.toString()}`);
   }
   async getEntry(contentType, slug) {
-    return this.request(`/api/v1/public/entries/${slug}`);
+    return this.publicRequest(`/api/v1/public/entries/${slug}`);
   }
   async createEntry(contentType, data, slug) {
-    return this.writeRequest(`/api/v1/manage/content-types/${contentType}/entries`, {
+    return this.manageRequest(`/api/v1/manage/content-types/${contentType}/entries`, {
       method: "POST",
       body: JSON.stringify({ slug, data })
     });
   }
   async updateEntry(contentType, slug, data) {
-    return this.writeRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}`, {
+    return this.manageRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}`, {
       method: "PUT",
       body: JSON.stringify({ data })
     });
   }
   async deleteEntry(contentType, slug) {
-    return this.writeRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}`, {
+    return this.manageRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}`, {
       method: "DELETE"
     });
   }
   async publishEntry(contentType, slug) {
-    return this.writeRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}/publish`, {
+    return this.manageRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}/publish`, {
       method: "PATCH"
     });
   }
   async unpublishEntry(contentType, slug) {
-    return this.writeRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}/unpublish`, {
+    return this.manageRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}/unpublish`, {
       method: "PATCH"
     });
   }
   async archiveEntry(contentType, slug) {
-    return this.writeRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}/archive`, {
+    return this.manageRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}/archive`, {
       method: "PATCH"
     });
   }
   async duplicateEntry(contentType, slug) {
-    return this.writeRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}/duplicate`, {
+    return this.manageRequest(`/api/v1/manage/content-types/${contentType}/entries/${slug}/duplicate`, {
       method: "POST"
     });
   }
@@ -12664,38 +12681,43 @@ var AtlasClient = class {
     const searchParams = new URLSearchParams();
     if (params?.page) searchParams.set("page", params.page.toString());
     if (params?.limit) searchParams.set("limit", params.limit.toString());
-    return this.request(`/api/v1/public/pages?${searchParams.toString()}`);
+    return this.publicRequest(`/api/v1/public/pages?${searchParams.toString()}`);
   }
   async getPage(slug) {
-    return this.request(`/api/v1/public/pages/${slug}`);
+    return this.publicRequest(`/api/v1/public/pages/${slug}`);
   }
   async createPage(data) {
-    return this.writeRequest("/api/v1/manage/pages", {
+    return this.manageRequest("/api/v1/manage/pages", {
       method: "POST",
       body: JSON.stringify(data)
     });
   }
   async updatePage(slug, data) {
-    return this.writeRequest(`/api/v1/manage/pages/${slug}`, {
+    return this.manageRequest(`/api/v1/manage/pages/${slug}`, {
       method: "PUT",
       body: JSON.stringify(data)
     });
   }
   async deletePage(slug) {
-    return this.writeRequest(`/api/v1/manage/pages/${slug}`, {
+    return this.manageRequest(`/api/v1/manage/pages/${slug}`, {
       method: "DELETE"
     });
   }
   async publishPage(slug) {
-    return this.writeRequest(`/api/v1/manage/pages/${slug}/publish`, {
+    return this.manageRequest(`/api/v1/manage/pages/${slug}/publish`, {
       method: "PATCH"
     });
   }
   // Media endpoints
   async getMedia(id) {
-    return this.request(`/api/v1/public/media/${id}`);
+    return this.publicRequest(`/api/v1/public/media/${id}`);
   }
   async uploadMedia(filePath, folder, altText) {
+    if (!this.mgmtKey) {
+      throw new Error(
+        "This operation requires a management API key (atlas_mgmt_*). Set ATLAS_MGMT_API_KEY (or ATLAS_API_KEY to an atlas_mgmt_* key) to enable write operations."
+      );
+    }
     const fs = await import("fs");
     const path2 = await import("path");
     if (!fs.existsSync(filePath)) {
@@ -12711,7 +12733,7 @@ var AtlasClient = class {
     const response = await fetch(`${this.baseUrl}/api/v1/manage/media/upload`, {
       method: "POST",
       headers: {
-        "X-API-Key": this.apiKey,
+        "X-API-Key": this.mgmtKey,
         "Idempotency-Key": crypto.randomUUID()
       },
       body: formData
@@ -12740,13 +12762,25 @@ function validateFilePath(filePath, allowedPaths) {
 
 // src/index.ts
 var ATLAS_API_URL = process.env.ATLAS_API_URL || "https://api.atlas.latellu.com";
-var ATLAS_API_KEY = process.env.ATLAS_API_KEY;
 var MCP_ALLOWED_UPLOAD_PATHS = process.env.MCP_ALLOWED_UPLOAD_PATHS ? process.env.MCP_ALLOWED_UPLOAD_PATHS.split(",").map((p) => p.trim()) : [];
-if (!ATLAS_API_KEY) {
-  console.error("ATLAS_API_KEY environment variable is required");
+var LIVE_KEY_PREFIX = "atlas_live_";
+var MGMT_KEY_PREFIX = "atlas_mgmt_";
+function resolveKeys() {
+  const legacyCandidates = [process.env.ATLAS_LIVE_API_KEY, process.env.ATLAS_MGMT_API_KEY, process.env.ATLAS_API_KEY].filter(
+    (v) => !!v
+  );
+  const liveKey2 = process.env.ATLAS_LIVE_API_KEY ?? legacyCandidates.find((k) => k.startsWith(LIVE_KEY_PREFIX));
+  const mgmtKey2 = process.env.ATLAS_MGMT_API_KEY ?? legacyCandidates.find((k) => k.startsWith(MGMT_KEY_PREFIX));
+  return { liveKey: liveKey2, mgmtKey: mgmtKey2 };
+}
+var { liveKey, mgmtKey } = resolveKeys();
+if (!liveKey && !mgmtKey) {
+  console.error(
+    "No valid Atlas API key found. Set ATLAS_API_KEY to an atlas_live_* or atlas_mgmt_* key, or set ATLAS_LIVE_API_KEY / ATLAS_MGMT_API_KEY explicitly (both, for full read+write access)."
+  );
   process.exit(1);
 }
-var atlasClient = new AtlasClient(ATLAS_API_URL, ATLAS_API_KEY);
+var atlasClient = new AtlasClient(ATLAS_API_URL, { liveKey, mgmtKey });
 var server = new McpServer({
   name: "atlas-mcp",
   version: "1.0.0"
@@ -13279,7 +13313,9 @@ server.tool(
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error("Atlas MCP server started");
+  console.error(
+    `Atlas MCP server started (read tools: ${liveKey ? "enabled" : "disabled, needs atlas_live_*"}, write tools: ${mgmtKey ? "enabled" : "disabled, needs atlas_mgmt_*"})`
+  );
 }
 main().catch((error) => {
   console.error("Fatal error:", error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latellu/atlas-mcp",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "publishConfig": {
     "access": "public"
   },