LightCMS

LightCMS is a Go-powered content management system built for the AI era. It’s simultaneously AI-native (semantic search, built-in Claude-powered chat widget, MCP server for agent control), agentically controllable (Claude Code and any MCP client can read, write, publish, and bulk-import content via 106 MCP tools), and agentically updatable (the codebase is clean, well-structured Go — coding agents can safely extend it). For teams that want a CMS that works with AI rather than around it.

What’s New in v7.1

What’s New in v7.0

What’s New in v6.0

What’s New in v5.0

What’s New in v4.5

Why LightCMS?

Lightweight: A clean, focused codebase that’s easy to understand, modify, and extend. No bloated frameworks or complex abstractions.

AI-Native: Built from the ground up for the AI era:

• MCP Integration: Full Model Context Protocol server with 106 tools and 3 prompt resources for website management. Supports both local stdio and HTTP streamable transports — connect from Claude Code, Claude Desktop, or any MCP-compatible client.
• OAuth 2.1 for Remote Agents: Sandboxed desktop apps like Claude’s Cowork can securely connect over HTTP using OAuth 2.1 with PKCE. No embedded passwords — just authorize once and the agent manages your site.
• Fork-Friendly: Designed to be forked and customized by Claude Code. Ask Claude to add new content types, modify templates, or build custom features — the codebase is structured for AI-assisted development.
• Natural Language Website Management: Skip the admin UI entirely. Create pages, manage assets, customize themes, and publish content through conversation.

Features

Content Management

• Template System: Define reusable content structures with custom fields (text, richtext, image, date, select, markdown)
• Static Page Generation: Fast page loads from pre-rendered HTML — no runtime templating overhead
• Content Versioning: Full version history with diff comparison and one-click revert
• Soft Delete: Recover deleted content with undelete functionality
• Content Tagging: Tag any content item with one or more freeform labels, then query by tag across your site
• Snippets: Named HTML template fragments used as reusable rendering units in dynamic queries
• lc:query Directives: Embed live content queries directly in template layouts — at publish time they expand into rendered lists of matching pages
• Content Collections: Auto-generated paginated listing pages filtered by category
• Folders & URL Organization: Hierarchical content organization with clean URL paths
• Rich Text Editor: TinyMCE integration for visual content editing
• Regex Search & Replace: Site-wide or scoped search-and-replace with RE2 regex support, capture groups, and mandatory preview step
• Bulk Operations: Update or apply field operations across up to 100 pages in a single API call; export/transform/re-import pipelines
• Scheduled Publishing (v4.5+): Set a future publish_at timestamp; a background scheduler auto-publishes at the right time
• Content Locking (v4.5+): Advisory lock while editing (30-min expiry); warning banner if another user holds the lock; admins can force-unlock
• Incremental Static Regeneration (v4.5+): Template layout changes regenerate pages in 20-page batches to prevent server overload on large sites

Import Pipeline (v5.0+)

• RSS/Atom Feed Sources: Configure recurring import sources with configurable schedule (hourly/daily/weekly), template mapping, folder targeting, and auto-publish. Manage sources and run history from /cm/imports.
• Markdown + ZIP Import: Upload .md files or .zip archives of Markdown. YAML frontmatter in each file controls title, slug, folder, template, tags, and scheduled publish time. Supports Notion exports, Obsidian vaults, Hugo/Jekyll site migrations, and AI-generated content.
• CSV Bulk Import: Upload a CSV and specify which column is the title; all other columns are stored as content fields automatically.
• Real-time SSE Job Status: Live log stream at /cm/imports/{jobID} — watch imports happen line-by-line or review full history after the fact.
• MCP-first Design: import_markdown is specifically designed for AI agents to generate and import large content batches in a single call, replacing dozens of create_content calls with one import_markdown + one get_import_job. See MCP.md for workflow examples.

Content Forks (v4.0+)

• Fork Workspaces: Create named staging workspaces where sets of page edits can be authored, previewed, and reviewed before going live
• Sparse Model: Only edited pages live in a fork — unmodified pages fall through to live content automatically
• Fork Preview Mode: Activate via a floating bar injected into the live site; a cookie routes all page requests through the fork so you see exactly how the site will look after merge
• Merge with Conflict Detection: Admins merge forks into live content; if a live page was changed after the fork was created, the conflict is recorded (fork wins). New pages created in the fork are inserted into live on merge
• Full MCP Toolset: 8 dedicated fork tools — list_forks, create_fork, get_fork, fork_page, remove_fork_page, merge_fork, archive_fork, delete_fork

Batch & Parallel Operations

Designed for agents that prefer parallelized, high-throughput workflows over sequential single-item calls:

• bulk_update_content: Update up to 100 pages in a single API call. Each item uses merge semantics — only the fields you specify are touched. Supports dry_run validation before committing, and auto_republish to re-publish all previously-published pages in the same call, eliminating a separate publish step
• bulk_field_operation: Apply a single operation (set, clear, prepend, append, wrap) to a field across every matching page in one call. Scope by template, folder, category, or explicit ID list. Ideal for adding disclaimers, updating metadata, or clearing stale fields across a content type
• publish_multiple: Publish a list of IDs — or all drafts at once with publish_all_drafts: true — in a single request instead of looping over publish_content
• export_content: Dump full field data for a scoped set of pages as a structured JSON array. Designed for export → transform → re-import pipelines; pair with bulk_update_content for large-scale content migrations
• Scoped Search & Replace: Both scoped_search_replace_preview and scoped_search_replace_execute accept scope filters (folder, template, category, IDs) so agents can target precise subsets rather than running site-wide operations
• Parallel-Safe Read API: list_content with include_data: true returns full field values in one fetch; agents can fan out reads across multiple list_content / get_content calls concurrently and then batch-write with bulk_update_content

Recommended agent pattern for large updates: list_content → transform in parallel → bulk_update_content (up to 50/call) → publish_multiple.

AI Chat Widget (v4.2+)

• Embeddable Widget: Add a floating AI chat bubble to any page with a single `

#### Ranking Configuration

Ranking weights are configurable in the admin panel under **Tools → End User Search → Search Ranking**. Defaults: title-match boost 0.20, nav-page boost 0.15, concept-template boost 0.05, video-path penalty −0.05. Configure your Voyage AI key under **Configuration** to enable semantic search.

## Project Structure

lightcms/ ├── cmd/ │ ├── server/main.go # HTTP server entry point │ ├── mcp/main.go # MCP server entry point │ ├── cli/main.go # CLI tool entry point │ └── resetpw/main.go # Password reset utility ├── config/ │ └── config.go # Configuration loading ├── internal/ │ ├── apiclient/ # Reusable HTTP client for REST API │ ├── auth/ # Authentication, RBAC permissions, session management │ ├── cli/ # CLI subcommands and output formatting │ ├── database/ # MongoDB connection & operations │ ├── handlers/ # HTTP handlers (admin UI + REST API) │ ├── mcp/ # MCP server and tool definitions │ ├── middleware/ # API auth middleware (API keys + OAuth) │ ├── models/ # Data models & default templates │ ├── oauth/ # OAuth 2.1 authorization server │ └── services/ # Business logic (content, search, users, audit, etc.) ├── static/ # CSS, JS, and uploaded files ├── content/ # Custom pages and generated HTML └── .goreleaser.yaml # Release configuration

## Default Templates

### Blog Post
Fields: title, excerpt, featured_image, content, author, tags

### Press Release
Fields: headline, subheadline, dateline, release_date, body, boilerplate, contact_info

### Explanatory Page
Fields: title, subtitle, hero_image, intro, main_content, sidebar, cta_text, cta_link

### Concept Page
Fields: title, definition, topic_links — ideal for wiki-style knowledge base entries

### Standard Page, Blank Page, Homepage
General-purpose layouts for flexible content.

## Multi-User Access Control

LightCMS v2.0+ supports multiple users with role-based permissions.

### Roles

| Role | Capabilities |
|------|-------------|
| **admin** | Full access: manage users, templates, theme, settings, audit log, all API keys |
| **editor** | Create/edit/delete/publish content; upload and delete assets; manage own API keys |
| **viewer** | Read-only access to content, templates, assets, and settings |

### Audit Log

Every mutation (content create/update/delete/publish, user management, settings changes, logins) is logged with the acting user's email, timestamp, and relevant details. Logs are retained for 365 days and accessible at `/cm/audit`.

### API Key Permissions

API keys created by a user inherit that user's role. A key created by an editor cannot perform admin-only operations even if its token is shared. Admins can manage all keys; non-admins can only manage their own.

### First-Time Migration

On first startup with an empty `users` collection, LightCMS automatically creates an admin user from the existing password hash in the database. Set the `LIGHTCMS_ADMIN_EMAIL` environment variable to specify which email address to use (defaults to `admin@localhost`).

## API Keys

API keys are required for the REST API, MCP server, and CLI tool. Create them from the admin panel.

1. Log in at `/cm`
2. Go to **Settings** → **API Keys**
3. Click **Create New Key**, give it a name and description
4. Copy the key immediately — it's only shown once

Keys use the format `lc_` followed by 32 hex characters. They're stored as SHA-256 hashes and inherit the permissions of the creating user.

## OAuth 2.1 Authorization

LightCMS implements OAuth 2.1 so that remote MCP clients (like Claude's Cowork) can securely connect without embedding passwords or API keys. This follows the standard authorization code flow with PKCE.

### Endpoints

| Endpoint | Purpose |
|----------|---------|
| `POST /oauth/register` | Dynamic client registration (RFC 7591) |
| `GET /oauth/authorize` | Authorization page (admin login + consent) |
| `POST /oauth/token` | Token exchange and refresh |
| `POST /oauth/revoke` | Token revocation (RFC 7009) |
| `GET /oauth/jwks` | JWKS endpoint (opaque tokens, returns empty) |

### Security

- **PKCE (S256)** required for all authorization requests
- **Token rotation**: refresh tokens are single-use; a new pair is issued each time
- **Short-lived access tokens**: 1-hour TTL
- **Refresh tokens**: 30-day TTL, revocable
- **Rate limiting**: failed login attempts trigger progressive lockouts (1 min → 5 min → 15 min)
- **All tokens stored as SHA-256 hashes** in the database

### How Clients Connect

1. Client fetches `/.well-known/oauth-authorization-server` to discover endpoints
2. Client calls `POST /oauth/register` with its name and redirect URI
3. Client redirects admin to `/oauth/authorize` with PKCE challenge
4. Admin enters password and approves access
5. Client exchanges the authorization code for access + refresh tokens
6. Client uses the access token as a Bearer token on `/mcp` or `/api/v1/` endpoints

This is all handled automatically by MCP-compatible clients — you just provide your LightCMS URL and approve the connection.

## REST API

LightCMS provides a full REST API at `/api/v1/` authenticated with API keys or OAuth tokens. All endpoints enforce RBAC — the permissions of the authenticated user (or key owner) determine what's allowed.

### Authentication

Include an API key or OAuth access token in the `Authorization` header:

```bash
# With API key
curl -H "Authorization: Bearer lc_your_key_here" http://localhost:8082/api/v1/content

# With OAuth token
curl -H "Authorization: Bearer " http://localhost:8082/api/v1/content

Endpoints

All endpoints return JSON. PUT endpoints support partial updates (only include fields you want to change).

CLI Tool

The lightcms CLI provides command-line access to all content management operations.

Installation

# Build from source
go build -o bin/lightcms ./cmd/cli

# Or download a release binary from GitHub

Configuration

export LIGHTCMS_URL=http://localhost:8082
export LIGHTCMS_API_KEY=lc_your_key_here

Or use flags: --url and --api-key.

Commands

lightcms content list                    # List all content
lightcms content get                 # Get content by ID
lightcms content create --template  --title "My Post" --slug my-post --data '{"body":"Hello"}'
lightcms content publish             # Publish content
lightcms content versions            # Show version history

lightcms template list                   # List templates
lightcms asset upload --file logo.png --path /images/logo.png
lightcms theme update --primary-color "#1a1a2e"
lightcms search "search terms"           # Search content
lightcms api-key create --name "CI/CD"   # Create API key

lightcms --json content list             # JSON output

Run lightcms --help for full usage.

MCP Server (AI-Powered Content Management)

LightCMS includes a full MCP (Model Context Protocol) server with 92 tools and 3 prompt resources for managing your entire website through AI agents. It supports two transport modes:

• Stdio — for local tools like Claude Code
• HTTP Streamable — for remote/sandboxed clients like Claude’s Cowork, Claude Desktop, or any MCP-compatible app

Option A: Local Setup (Claude Code via Stdio)

Best for developers using Claude Code directly on the same machine.

1. Create an API key in the admin panel at /cm → Settings → API Keys
2. Run the setup script:

export LIGHTCMS_API_KEY=lc_your_key_here
./setup-mcp.sh

Or register manually:

go build -o bin/lightcms-mcp ./cmd/mcp

claude mcp add --transport stdio lightcms-mcp \
  -e LIGHTCMS_URL="http://localhost:8082" \
  -e LIGHTCMS_API_KEY="lc_your_key_here" \
  -- /path/to/lightcms/bin/lightcms-mcp

Restart Claude Code and run /mcp to verify.

Option B: Remote Setup (Cowork / Claude Desktop via HTTP + OAuth)

Best for sandboxed desktop apps that can’t run local binaries. The HTTP MCP endpoint at /mcp supports OAuth 2.1 authorization — no API keys or passwords need to be embedded in the client.

How it works:

1. The client discovers your LightCMS instance via well-known endpoints
2. It registers as an OAuth client (one-time, automatic)
3. You authorize the client by entering your admin password in the browser
4. The client receives short-lived access tokens and refreshes them automatically

To connect from a remote MCP client, just provide your LightCMS URL (e.g., https://yoursite.example.com). The client handles the rest using standard OAuth 2.1 discovery.

Discovery endpoints:

Authentication

The MCP HTTP endpoint accepts both authentication methods:

• API keys (lc_ prefix) — long-lived, created in admin panel
• OAuth 2.1 tokens — short-lived, obtained through the authorization flow

Both methods enforce RBAC based on the authenticated user’s role.

Available Tools (106 total) + 3 Prompt Resources

• Content (20): create, read, update, delete, publish, unpublish, restore, versioning, revert, preview, bulk update, bulk field operation, export, backlinks, update by path, publish multiple
• Templates (5): create, read, update, delete, list
• Snippets (5): create, read, update, delete, list
• Assets (6): upload, upload from URL, read, delete, list files and folders
• Search (7): full-text search, end-user search, search-and-replace (global + scoped, preview + execute), reindex embeddings
• Settings (23): theme CRUD + versioning + pinning, site config, redirects, folders, collections, regenerate all content
• Forks (8): list, create, get, fork page, remove page, merge, archive, delete
• Import (10, v5.0+): list/create/update/delete/trigger import sources, import markdown, import CSV, list/get/cancel import jobs
• Webhooks (6, v4.5+): list, create, get, update, delete webhooks; regenerate secret
• Content Locking (4, v4.5+): get lock, acquire lock, release lock, force-unlock
• Scheduled Publishing (3, v4.5+): schedule publish, list scheduled, cancel scheduled
• Audit & Link Check (3, v4.5+): get audit log, check links, list broken links
• Comments (3, v6.0+): list comments, post comment, delete comment
• Approvals (11, v6.0+): list/get/create/update/delete approval workflows; list/get/submit/approve/reject/cancel approval requests
• Prompt Resources (3, v4.5+): lightcms://site/structure, lightcms://content/recent, lightcms://theme/config

For detailed API documentation, see MCP.md.

Environment Variables (Stdio Mode)

• LIGHTCMS_URL — Server URL (default: http://localhost:8082)
• LIGHTCMS_API_KEY — API key (required for stdio mode)

MCP Examples

These examples show how the MCP tools work together to manage a website through natural language. Each example lists the user prompt and the exact MCP tool calls that execute behind the scenes.

Example 1: Create and Publish a Blog Post

Prompt: “Create a blog post about AI agents and publish it”

Tool calls:

1. list_templates — finds the Blog Post template and its ID
2. create_content — creates the post with template ID, title, slug, and field data:

   {
     "template_id": "6971098ad0761968133b8e43",
     "title": "The Rise of AI Agents",
     "slug": "rise-of-ai-agents",
     "data": {
       "excerpt": "How autonomous AI agents are reshaping software development.",
       "content": "AI agents represent a fundamental shift...",
       "author": "Editorial Team"
     }
   }
   

3. publish_content — makes it live; a static HTML page is generated at /rise-of-ai-agents

Example 2: Update the Site Theme

Prompt: “Change the site colors to a dark theme with blue accents”

Tool calls:

1. get_theme — reads current theme settings (colors, fonts, header/footer HTML)
2. update_theme — applies the new palette:

   {
     "primary_color": "#1a1a2e",
     "secondary_color": "#16213e",
     "accent_color": "#0f3460",
     "background_color": "#0a0a0a",
     "text_color": "#e0e0e0"
   }
   

   All published pages are automatically regenerated with the new theme.

Example 3: Search and Replace Across the Entire Site

Prompt: “Replace ‘Acme Corp’ with ‘Acme Industries’ everywhere on the site”

Tool calls:

1. search_replace_preview — shows affected pages without making changes:

   { "search": "Acme Corp", "replace": "Acme Industries" }
   

   Returns a list of content items, matched fields, and match counts.
2. search_replace_execute — applies the replacement after user confirmation. Each affected content item gets a new version for rollback capability.

Example 4: Create a Custom Template

Prompt: “Create a template for team member profiles with name, role, bio, and photo”

Tool calls:

1. create_template — defines the structure and HTML layout:

   {
     "name": "Team Member",
     "slug": "team-member",
     "fields": [
       { "name": "role", "label": "Role", "type": "text", "required": true },
       { "name": "photo", "label": "Photo", "type": "image", "required": false },
       { "name": "bio", "label": "Biography", "type": "richtext", "required": true }
     ],
     "html_layout": ""
   }
   

   The template is immediately available for creating content.

Example 5: Upload an Image and Use It in Content

Prompt: “Upload this logo and add it to the about page”

Tool calls:

1. upload_asset — uploads the file as base64 with a serve path:

   {
     "filename": "logo.png",
     "serve_path": "/images/logo.png",
     "data_base64": "iVBORw0KGgoAAAANSUhEUg..."
   }
   

   The image is now accessible at /images/logo.png.
2. get_content — retrieves the about page by path to get its current data
3. update_content — adds the image reference to the page’s content field

Example 6: Set Up URL Redirects

Prompt: “The old blog moved from /news to /blog — set up redirects for the old URLs”

Tool calls:

1. create_redirect — creates a permanent redirect:

   {
     "from_path": "/news",
     "to_path": "/blog",
     "status_code": 301,
     "description": "Blog section moved from /news to /blog"
   }
   

   Visitors to /news are automatically redirected to /blog. Multiple redirects can be created in sequence for different paths.

Example 7: Content Versioning and Rollback

Prompt: “Show me the version history for the homepage, then revert to version 2”

Tool calls:

1. get_content — retrieves the homepage by path (/) to get its ID
2. get_content_versions — returns the full version history with timestamps and comments:

   Version 5 — "Updated hero section" — 2026-02-25
   Version 4 — "Added testimonials" — 2026-02-20
   Version 3 — "Redesigned layout" — 2026-02-15
   Version 2 — "Initial content" — 2026-02-10
   Version 1 — "Created page" — 2026-02-08
   

3. revert_to_version — rolls back to version 2, creating a new version 6 with the old data. The published page is regenerated immediately.

Example 8: Organize Content with Folders

Prompt: “Create a /docs section and move the API reference page into it”

Tool calls:

1. create_folder — creates the URL path segment:

   { "name": "Documentation", "slug": "docs" }
   

2. get_content — retrieves the API reference page to get its ID
3. update_content — moves it into the new folder:

   { "id": "...", "folder_path": "/docs" }
   

   The page is now accessible at /docs/api-reference instead of /api-reference.

Example 9: Build a Content Collection (Blog Index)

Prompt: “Create a blog listing page that shows all blog posts sorted by newest first”

Tool calls:

1. create_collection — defines the collection with category filter, sorting, and display templates:

   {
     "name": "Blog",
     "slug": "blog",
     "category": "blog",
     "sort_field": "created_at",
     "sort_order": "desc",
     "items_per_page": 10,
     "item_template": "{{.Title}}{{.excerpt}}{{.PublishedAt}}",
     "page_template": ""
   }
   

   A paginated blog listing is now live at /blog, automatically including any content with category “blog”.

Example 10: Build a Dynamic Tagged Index Page

Prompt: “Create a glossary index that automatically lists all my concept pages grouped by category, and keep it updated as I add new pages”

Tool calls:

1. create_snippet — creates a reusable rendering template for each result:

   {
     "name": "glossary-pill",
     "html": "{{.Title}}"
   }
   

2. create_template — creates the index page template with lc:query directives embedded:

   {
     "name": "Concepts Index",
     "slug": "concepts-index",
     "fields": [
       { "name": "intro", "label": "Introduction", "type": "textarea" }
     ],
     "html_layout": "\n{{.title}}\n{{if .intro}}{{.intro}}{{end}}\n\nAI & Machine Intelligence\n\n\nGames & Interactive Experiences\n\n"
   }
   

3. create_content — creates the index page using the new template:

   {
     "template_id": "",
     "title": "Concepts Glossary",
     "slug": "glossary",
     "data": {
       "intro": "An index of all concepts, grouped by category."
     }
   }
   

4. update_content — tags several existing concept pages (each call):

   { "tags": ["AI & Machine Intelligence"] }
   

5. publish_content — publishes the index page; the lc:query directives are resolved at this moment and the page is generated with all currently-tagged content already populated.

From now on, every time a new concept page is published with a matching tag, the index page at /glossary is automatically regenerated — no further action needed.

Example 11: Full-Text Search and Content Audit

Prompt: “Find all pages that mention ‘pricing’ and show me which ones are still in draft”

Tool calls:

1. search_content — performs a full-text search across all content fields:

   { "query": "pricing", "search_type": "fulltext" }
   

   Returns matching content items with their publish status, paths, and which fields matched:

   Found 4 results for 'pricing':
   - "Pricing Plans" at /pricing — published — matched in: content
   - "Enterprise FAQ" at /enterprise-faq — published — matched in: content, sidebar
   - "New Pricing Draft" at /new-pricing — draft — matched in: title, content
   - "Q1 Press Release" at /press/q1-update — draft — matched in: body
   

   The two draft items can then be reviewed, edited, and published as needed.

Example 12: Bulk Content Migration

Prompt: “Add a ‘last_reviewed’ field to every page in our /docs section and publish them all”

Tool calls:

1. list_content — fetches all content under /docs with full field data in one call:

   { "folder_path": "/docs", "include_data": true }
   

   Returns IDs, titles, current field values, and publish status for all 34 pages.

2. (parallel) Agent fans out into batches of 50 and calls bulk_update_content concurrently:

   {
     "updates": [
       { "id": "abc123", "data": { "last_reviewed": "2026-03-24" } },
       { "id": "def456", "data": { "last_reviewed": "2026-03-24" } }
     ],
     "version_comment": "Added last_reviewed field — Q1 2026 audit",
     "auto_republish": true
   }
   

   auto_republish: true re-publishes every previously-published page immediately — no separate publish step needed.

All 34 pages are updated and live in two parallel calls instead of 34 sequential ones.

Example 13: Fork-Based Staged Redesign

Prompt: “Redesign the homepage and /about page in a staging area so I can preview before publishing”

Tool calls:

1. create_fork — creates a named staging workspace:

   { "name": "Q2 Redesign", "description": "Homepage and About refresh" }
   

   Returns a fork ID. The live site is completely unaffected.

2. fork_page — copies the homepage into the fork and applies edits:

   {
     "fork_id": "fork_abc123",
     "content_id": "homepage_id",
     "data": { "hero_headline": "Build the web with AI", "hero_subtext": "..." }
   }
   

3. fork_page — does the same for /about:

   {
     "fork_id": "fork_abc123",
     "content_id": "about_id",
     "data": { "body": "Updated company story..." }
   }
   

   A floating preview bar is injected into the live site — visiting it with the fork cookie active shows both pages exactly as they’ll look after merge.

4. merge_fork — after approval, merges both fork pages into live content and regenerates their static HTML:

   { "fork_id": "fork_abc123" }
   

   Returns a summary of merged pages and any conflicts detected.

Example 14: Site-Wide Notice with Auto-Republish

Prompt: “Prepend a deprecation notice to all pages in our /v1 docs section and republish them”

Tool calls:

1. bulk_field_operation — appends the notice to a specific field across the entire folder in one call:

   {
     "operation": "prepend",
     "field": "body",
     "value": "\n\n",
     "folder_path": "/v1",
     "auto_republish": true,
     "version_comment": "Added v1 deprecation notice"
   }
   

   Returns counts of updated and republished pages. The live site reflects the change immediately.

If the notice ever needs to be removed, a single scoped_search_replace_execute with the exact notice HTML reverts all pages in one call.

Working with Snippets

# List all snippets
list_snippets

# Create a callout snippet
create_snippet {
  "name": "callout-warning",
  "description": "Warning callout box",
  "html": ""
}

# Use a snippet inline in content
update_content {
  "id": "...",
  "data": {
    "body": "Here is important information:\n\n[[include:callout-warning]]\n\nContinued text..."
  }
}

Content Tagging & Index Pages

# Tag a page at creation time
create_content {
  "template_id": "...",
  "title": "Introduction to AI",
  "slug": "intro-to-ai",
  "tags": ["AI & Machine Intelligence", "Getting Started"],
  "data": { "body": "..." }
}

# Inline tagging via content body
update_content {
  "id": "...",
  "data": {
    "body": "This page covers #machine-learning and #neural-networks."
  }
}

# Query directive in a template layout (for index pages)

Bulk Operations

# Step 1: Export all Concept Pages with specific fields
export_content {
  "template_name": "Concept Page",
  "fields": ["definition", "layer_badge"]
}

# Step 2: Transform the data externally, then bulk update
bulk_update_content {
  "updates": [
    { "id": "abc123", "data": { "layer_badge": "" } },
    { "id": "def456", "data": { "layer_badge": "" } }
  ],
  "version_comment": "Updated layer badges"
}

# Clear a field across all pages of a template
bulk_field_operation {
  "operation": "clear",
  "field": "old_badge",
  "template_name": "Concept Page",
  "version_comment": "Cleared deprecated field"
}

# Prepend a disclaimer to all blog posts
bulk_field_operation {
  "operation": "prepend",
  "field": "body",
  "value": "",
  "template_name": "Blog Post",
  "version_comment": "Added disclaimer to all posts"
}

Regex Search & Replace

# Preview: find all pages with old badge HTML pattern
scoped_search_replace_preview {
  "search": "",
  "replace": "",
  "regex": true,
  "template_name": "Concept Page",
  "version_comment": "Removed old v1 badge HTML"
}

Wikilinks

# Link to another page by title
update_content {
  "id": "...",
  "data": {
    "body": "See also: [[Machine Learning]] and [[AI Ethics|ethics considerations]]."
  }
}

# Find what pages link to a given path
get_backlinks { "path": "/concepts/machine-learning" }

Content Versioning

# See version history for a page
get_content_versions { "content_id": "abc123" }

# Restore a previous version
revert_to_version {
  "content_id": "abc123",
  "version": 3,
  "version_comment": "Reverted to pre-redesign version"
}

Development

# Run with hot reload (using air)
go install github.com/cosmtrek/air@latest
air

# Build all binaries
go build -o bin/lightcms-server ./cmd/server
go build -o bin/lightcms-mcp ./cmd/mcp
go build -o bin/lightcms ./cmd/cli

# Run the server
./bin/lightcms-server

Security Notes

For production:

1. Use a strong session_secret — minimum 32 characters (generate with openssl rand -hex 32). The server hard-fails on startup if this requirement isn’t met in production.
2. Set LIGHTCMS_ADMIN_EMAIL so the initial admin account uses your real email
3. Change the default admin password immediately after first login
4. Use HTTPS (put behind a reverse proxy like nginx or caddy)
5. Restrict MongoDB Atlas IP whitelist to your server IPs
6. API keys inherit the permissions of their owning user — keep admin keys secure
7. Review the audit log regularly at /cm/audit
8. Regularly backup your MongoDB database
9. Configure max_upload_bytes in site settings to cap file upload size for your use case

Security features built in:

• CSRF protection on all /cm routes
• RBAC permission checks on all admin handlers and REST API endpoints
• Session cookies: SameSite=Strict, 24-hour expiry, Secure in production
• File uploads: extension whitelist + MIME validation + configurable size cap
• API request body cap: 10 MiB enforced on all /api/v1/ endpoints
• Login rate limiting: escalating lockouts (1 min → 5 min → 15 min)
• Per-endpoint rate limiters: regenerate (2/min), search-replace execute (10/min), bulk-update (5/min), export (5/min), reindex (1/min)
• Passwords: bcrypt with cost=12
• Audit logging on all mutations with 365-day retention
• Fly.io deployments: Fly-Client-IP header used for real client IP (unspoofable, unlike X-Forwarded-For)
• Chat widget prompt injection defense: user input wrapped in XML delimiters, </ sequences escaped

Privacy Policy

LightCMS is self-hosted software — you control your database, your hosting, and your data. The MCP server and CLI tool connect to your LightCMS instance via the REST API — no data is transmitted to Metavert LLC or any third party.

For the full privacy policy, see: https://www.metavert.io/lightcms-privacy-policy

License

MIT