headlesshost-mcp-server 1.2.0 → 1.3.0

package/README.md

@@ -1,85 +1,13 @@
 # Headlesshost MCP Server
 
-A comprehensive Model Context Protocol (MCP) server that provides complete communication with the Headlesshost platform API endpoints. This server enables AI assistants to interact with all aspects of the Headlesshost platform including user management, content site operations, staging site management, content generation, analytics, and system administration.
+A Model Context Protocol (MCP) server that provides complete communication with the Headlesshost platform API. This server enables AI assistants to manage content sites, staging sites, pages, sections, audiences, users, and file uploads through the Headlesshost platform.
+
+Built with `@modelcontextprotocol/sdk` v1.26 and includes tool annotations, structured logging, and Zod input validation.
 
 ## Demo
 
 https://www.youtube.com/watch?v=xGGwcrI7gSo&feature=youtu.be
 
-## Features
-
-### 🔧 General System Tools (4 tools)
-
-- **Ping**: Test authentication and connection to the Headlesshost API
-- **Health**: Check API health status and connectivity
-- **Reference Data**: Access system reference data and lookups
-
-### 📁 File Management (2 tools)
-
-- **Upload Profile Image**: Upload user profile images
-- **Upload Staging Site File**: Upload files to staging sites
-
-### 👥 Membership Management (8 tools)
-
-- **User Registration**: Register new users with account creation
-- **User Management**: Full CRUD operations for users with claims/roles support
-- **Account Management**: View and update account information
-
-### 🏢 Content Site Management (6 tools)
-
-- **Content Site Creation**: Create new content site entities
-- **Content Site Listing**: View all content sites with optional filters
-- **Content Site Details**: Get comprehensive content site information
-- **Content Site Updates**: Modify content site settings and configuration
-- **Content Site Deletion**: Remove content sites from the platform
-
-### 🌐 Staging Site Management (67 tools)
-
-Comprehensive staging site functionality including:
-
-#### Core Operations (4 tools)
-
-- **Site Operations**: Update, delete, publish staging sites
-- **Site Information**: Get staging site details and metadata
-- **Site Management**: Clone, promote, and revert staging sites
-- **Published Sites**: Access published site versions
-
-#### Page Management (4 tools)
-
-- **Page CRUD**: Create, read, update, delete staging site pages
-- **Page Content**: Handle page content and structure
-- **Page Analytics**: Track page-level performance
-- **Page Logs**: Monitor page activity and changes
-
-#### Section Management (6 tools)
-
-- **Section CRUD**: Create, read, update, delete page sections
-- **Section Content**: Manage section-specific content
-- **Section Logs**: Track section-level modifications
-
-#### User Management (5 tools)
-
-- **User Access Control**: Grant and manage user access to staging sites
-- **Role Management**: Assign and update user roles per site
-- **Permissions**: Configure granular user permissions
-- **User Listing**: View all site users and their roles
-
-#### Business Operations (7 tools)
-
-- **Business Logs**: Access business activity and audit trails
-- **Business Analytics**: Business-level performance metrics
-- **User Management**: Business user access and permissions
-- **Role Management**: Business role definitions and assignments
-
-#### System Resources (8 tools)
-
-- **Hit Tracking**: Raw analytics data and visitor metrics
-- **System Health**: Monitor platform connectivity and status
-
-## 📈 Total Coverage
-
-**87 Tools** providing complete API coverage across all Headlesshost platform functionality!
-
 ## Installation
 
 1. Clone this repository
@@ -96,36 +24,61 @@ Comprehensive staging site functionality including:
 
 ## Configuration
 
-Set up your environment variables:
+The server requires a Headlesshost API key set via the `HEADLESSHOST_API_KEY` environment variable.
+
+## Usage
+
+### With Claude Desktop
+
+Add this configuration to your Claude Desktop config file:
 
 ```bash
-export HEADLESSHOST_API_KEY="your-auth-token"
+MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+Windows: %APPDATA%\Claude\claude_desktop_config.json
 ```
 
-Or create a `.env` file:
+#### Local development
 
-```env
-HEADLESSHOST_API_KEY=your-auth-token
+```json
+{
+  "mcpServers": {
+    "headlesshost-cms": {
+      "command": "node",
+      "args": ["/path/to/kapiti.mcp/build/index.js"],
+      "env": {
+        "HEADLESSHOST_API_KEY": "your-auth-token"
+      }
+    }
+  }
+}
 ```
 
-## Usage
+#### Via npx
 
-### With Claude Desktop
+```json
+{
+  "mcpServers": {
+    "headlesshost-cms": {
+      "command": "npx",
+      "args": ["headlesshost-mcp-server"],
+      "env": {
+        "HEADLESSHOST_API_KEY": "your-auth-token"
+      }
+    }
+  }
+}
+```
 
-Add this configuration to your Claude Desktop config file:
+### With Claude Code
 
-On a Mac (edit or create this file).
-
-```bash
-/Users/warren/Library/Application Support/Claude/claude_desktop_config.json
-```
+Add to your `.claude/settings.json`:
 
 ```json
 {
   "mcpServers": {
-    "Headlesshost-cms": {
+    "headlesshost-cms": {
       "command": "node",
-      "args": ["/path/to/Headlesshost-mcp/build/index.js"],
+      "args": ["/path/to/kapiti.mcp/build/index.js"],
       "env": {
         "HEADLESSHOST_API_KEY": "your-auth-token"
       }
@@ -136,20 +89,134 @@ On a Mac (edit or create this file).
 
 ### With Other MCP Clients
 
-This server is compatible with any MCP client including:
-
-- VS Code with MCP extensions
-- Zed Editor
-- Continue.dev
-- Custom MCP implementations
+This server is compatible with any MCP client including VS Code, Zed Editor, Continue.dev, and custom MCP implementations.
 
 Configure your client to use:
 
 - **Command**: `node`
-- **Args**: `["/path/to/Headlesshost.mcp/build/index.js"]`
+- **Args**: `["/path/to/kapiti.mcp/build/index.js"]`
 - **Environment**: Set `HEADLESSHOST_API_KEY`
 
-### Development
+## Tools (53)
+
+All tools include MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) to help clients present appropriate UI and confirmation prompts.
+
+### General (3)
+
+| Tool | Description |
+|------|-------------|
+| `ping` | Test authentication and connection |
+| `health` | Check API health status |
+| `get_ref_data` | Get system reference data and lookups |
+
+### User Management (4)
+
+| Tool | Description |
+|------|-------------|
+| `create_user` | Create a new user in the current account |
+| `get_user` | Get user details by ID |
+| `update_user` | Update user information and claims |
+| `delete_user` | Delete a user from the system |
+
+### Account Management (3)
+
+| Tool | Description |
+|------|-------------|
+| `create_account` | Create a new user account |
+| `get_account` | Get current account information |
+| `update_account` | Update account information |
+
+### File Uploads (3)
+
+| Tool | Description |
+|------|-------------|
+| `upload_user_profile_image` | Upload a profile image for a user |
+| `upload_staging_site_file` | Upload a file to a staging site |
+| `upload_staging_site_image` | Upload an image to a staging site |
+
+### Content Sites (5)
+
+| Tool | Description |
+|------|-------------|
+| `create_content_site` | Create a new content site |
+| `get_content_sites` | Get all content sites in the account |
+| `get_content_site` | Get content site details by ID |
+| `update_content_site` | Update content site information |
+| `delete_content_site` | Delete a content site |
+
+### Staging Sites (9)
+
+| Tool | Description |
+|------|-------------|
+| `update_staging_site` | Update staging site information |
+| `delete_staging_site` | Delete a staging site |
+| `publish_staging_site` | Publish a staging site to make it live |
+| `get_staging_site` | Get staging site details |
+| `get_staging_site_pages` | Get staging site pages |
+| `get_staging_site_configuration` | Get staging site configuration including section types |
+| `get_staging_site_logs` | Get change logs since last publish |
+| `get_published_sites` | Get published sites for a content site |
+| `revert_staging_site` | Revert a staging site to a previous state |
+| `clone_staging_site` | Clone a staging site |
+
+### Pages (6)
+
+| Tool | Description |
+|------|-------------|
+| `create_staging_site_page` | Create a new page |
+| `get_staging_site_page` | Get page details (with optional sections) |
+| `update_staging_site_page` | Update a page |
+| `delete_staging_site_page` | Delete a page |
+| `revert_staging_site_page` | Revert a page to a previous state |
+| `get_staging_site_page_logs` | Get page change logs since last publish |
+
+### Sections (7)
+
+| Tool | Description |
+|------|-------------|
+| `create_staging_site_section` | Create a new section in a page |
+| `get_staging_site_section` | Get section details |
+| `update_staging_site_section` | Update a section |
+| `delete_staging_site_section` | Delete a section |
+| `publish_staging_site_section` | Publish a single section |
+| `revert_staging_site_section` | Revert a section to a previous state |
+| `get_staging_site_section_logs` | Get section change logs since last publish |
+
+### Site Audiences (4)
+
+| Tool | Description |
+|------|-------------|
+| `create_staging_site_audience` | Create an audience (locale/segment combination) for a site |
+| `get_staging_site_audience` | Get audience details |
+| `update_staging_site_audience` | Update an audience |
+| `delete_staging_site_audience` | Delete an audience (base audience cannot be deleted) |
+
+### Section Audiences (4)
+
+| Tool | Description |
+|------|-------------|
+| `create_staging_site_section_audience` | Create an audience override for a section |
+| `get_staging_site_section_audience` | Get section audience details |
+| `update_staging_site_section_audience` | Update a section audience override |
+| `delete_staging_site_section_audience` | Delete a section audience override |
+
+### Analytics (4)
+
+| Tool | Description |
+|------|-------------|
+| `get_content_site_logs` | Get the last 15 activity logs |
+| `get_content_site_hits` | Get daily hit analytics |
+| `get_content_site_accounts` | Get associated accounts |
+| `get_content_site_claims` | Get current user claims |
+
+## Resources
+
+The server provides 2 resources for configuration and monitoring:
+
+- **API Configuration** (`config://api`) — Available endpoints and current settings
+- **API Health Status** (`health://api`) — Real-time connectivity and response time
+
+## Development
 
 Build the server:
 
@@ -157,37 +224,36 @@ Build the server:
 npm run build
 ```
 
-Run the server directly:
+Run in development mode:
 
 ```bash
-npm start
+npm run dev
 ```
 
-Run the MCP inspector for debugging:
+Watch for changes:
 
 ```bash
-npm run inspector
+npm run watch
 ```
 
-## Resources
-
-The server provides 2 resources for configuration and monitoring:
+Run the MCP inspector for debugging:
 
-- **API Configuration**: Current Headlesshost API settings and endpoints
-- **API Health Status**: Real-time connectivity and health information
+```bash
+npm run inspector
+```
 
 ## Error Handling
 
-The server includes comprehensive error handling with:
+The server includes structured error handling:
 
 - API authentication validation
 - Network connectivity checks
-- Detailed error messages and troubleshooting information
+- Structured logging via MCP logging capability (errors are sent to the client)
 - Graceful fallbacks for API timeouts
 
 ## Security
 
 - API key authentication required for all operations
 - Secure environment variable handling
-- Request/response logging for audit trails
-- Input validation and sanitization
+- Input validation via Zod schemas on all tool inputs
+- Tool annotations signal destructive operations to clients