@latellu/atlas-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Latellu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# Atlas MCP Server
+
+MCP (Model Context Protocol) server for Atlas CMS — enables AI agents to manage content.
+
+## Overview
+
+This MCP server exposes Atlas CMS content management operations as tools for AI agents (Claude, Cursor, etc.). It enables AI agents to:
+
+- Discover workspace schema (content types, fields, locales)
+- Read entries, pages, and media
+- Create, update, publish, and delete content
+- Upload media files from local filesystem
+
+## Features
+
+### Schema & Discovery
+- `get_workspace_schema` — Get all content types, fields, and locales
+- `list_content_types` — List all content types
+- `get_content_type` — Get single content type with fields
+
+### Entry Operations
+- `list_entries` — List entries for a content type
+- `get_entry` — Get single entry by slug
+- `create_entry` — Create new draft entry
+- `update_entry` — Update existing entry
+- `delete_entry` — Delete entry
+- `publish_entry` — Publish draft entry
+- `unpublish_entry` — Unpublish published entry
+- `archive_entry` — Archive entry
+- `duplicate_entry` — Duplicate entry as new draft
+
+### Page Operations
+- `list_pages` — List all pages
+- `get_page` — Get page with blocks and SEO
+- `create_page` — Create new draft page
+- `update_page` — Update page
+- `delete_page` — Delete page
+- `publish_page` — Publish page
+
+### Media Operations
+- `get_media` — Get media metadata by ID
+- `upload_media` — Upload file from local path
+
+## Installation
+
+```bash
+npx @latellu/atlas-mcp
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ATLAS_API_KEY` | Yes | Atlas API key (`atlas_live_*` for read-only, `atlas_mgmt_*` for full access) |
+| `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 |
+
+### Claude Desktop Configuration
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "atlas": {
+      "command": "npx",
+      "args": ["-y", "@latellu/atlas-mcp"],
+      "env": {
+        "ATLAS_API_KEY": "atlas_mgmt_xxx...",
+        "MCP_ALLOWED_UPLOAD_PATHS": "/Users/you/Documents,/Users/you/Pictures"
+      }
+    }
+  }
+}
+```
+
+### Cursor Configuration
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "atlas": {
+      "command": "npx",
+      "args": ["-y", "@latellu/atlas-mcp"],
+      "env": {
+        "ATLAS_API_KEY": "atlas_mgmt_xxx..."
+      }
+    }
+  }
+}
+```
+
+## Usage Examples
+
+### Schema Discovery
+
+```
+User: "What content types exist in this workspace?"
+AI: → Calls get_workspace_schema
+    → Returns list of content types with fields
+```
+
+### Content Creation
+
+```
+User: "Create a new article about AI"
+AI: → Calls get_workspace_schema to understand article fields
+    → Calls create_entry with article data
+    → Returns created entry with slug
+```
+
+### Content Publishing
+
+```
+User: "Publish the article with slug 'ai-intro'"
+AI: → Calls publish_entry with content_type='article', slug='ai-intro'
+    → Returns published entry
+```
+
+### Media Upload
+
+```
+User: "Upload /Users/you/Pictures/tokyo.png as cover image"
+AI: → Calls upload_media with file_path='/Users/you/Pictures/tokyo.png'
+    → MCP server validates path against allowed directories
+    → Uploads file to Atlas
+    → Returns media ID and URL
+```
+
+## Security
+
+### Permission Model
+
+**Layer 1: API Key**
+- `atlas_live_*` — Read-only access (delivery API)
+- `atlas_mgmt_*` — Read-write access (management API)
+
+**Layer 2: Filesystem Permission**
+- Configurable via `MCP_ALLOWED_UPLOAD_PATHS` env var
+- Path validation: only files within allowed directories can be uploaded
+
+**Layer 3: File Validation**
+- Max 10MB file size
+- Allowed MIME types: `image/*`, `video/*`, `application/pdf`
+
+### Best Practices
+
+1. **Scope API keys**: Use minimal scopes required
+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
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
+### Build
+
+```bash
+npm run build
+```
+
+### Test
+
+```bash
+npm test
+```
+
+## Architecture
+
+The MCP server connects to Atlas via REST API:
+
+```
+┌─────────────────────────────────────┐
+│           MCP Client (AI)           │
+│  (Claude Desktop, Cursor, etc.)     │
+└──────────────────┬──────────────────┘
+                   │
+              Stdio Transport
+                   │
+         ┌─────────▼─────────┐
+         │    MCP Server     │
+         │  (TypeScript)     │
+         └─────────┬─────────┘
+                   │
+              REST API calls
+                   │
+         ┌─────────▼─────────┐
+         │   Atlas Backend   │
+         │  (Go, Echo)       │
+         └───────────────────┘
+```
+
+## License
+
+MIT License