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 130 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.3 — SEO & AI

Feature	Summary
AI Traffic	See which AI crawlers read your site (training vs. AI search vs. user-initiated fetches), what they read most, and how many visits ChatGPT, Perplexity, Claude, Gemini and Copilot send you.
AI Crawler Policy	Allow or block AI training, AI search and user fetches separately, with per-crawler overrides and an optional Content-Signal line, rendered into robots.txt.
Markdown Copies	Every page is also available as clean Markdown at /<page>.md, linked from the page and from llms.txt, so agents can read it without the HTML.
Richer Structured Data	Authors, publisher with logo, breadcrumbs, FAQ markup, and modified dates that only move when the page content actually changes.
RSS & Atom Feeds	/feed.xml, /atom.xml and per-collection feeds with full content.
Hide from Search & AI	Per-page noindex that also removes the page from the sitemap, llms.txt, feeds and IndexNow.

What's New in v7.2

Feature	Summary
IndexNow	Published, edited, moved and deleted pages are pushed to Bing, Yandex and other IndexNow engines right away. Zero-config: each install generates its own key, verifies it owns its BASE_URL before submitting, and submits the whole site once on first activation. Status and history at Tools → IndexNow.
CMS Agent	Configurable email digests (via Resend) covering site health, traffic, review queue, agent activity and broken links, with optional AI commentary.

What's New in v7.1

Feature	Summary
Ambient Copilot	The copilot is a slide-in drawer on every admin page — floating 🤖 button, fullscreen toggle, ChatGPT-style searchable chat history, live typing indicator, and rendered tables. It edits, creates, publishes, and reads analytics and maintenance reports in plain language.
Analytics Ranges	60/90-day presets and custom date ranges across all analytics views.
Fast AI-Crawler Endpoints	llms.txt serves in ~1 second on large sites (projected queries), and homepages emit schema.org WebSite JSON-LD with SearchAction.
Version Visibility	The admin sidebar shows the running version.

What's New in v7.0

Feature	Summary
Agent Sandbox ("PRs for content")	Agents work in an isolated fork with copy-on-write; humans review a per-field diff and merge. Live content is untouchable until merge.
Agent Governance	Scoped API keys, sandbox-only keys (server-enforced), per-session change ledger with one-call rollback, and per-version provenance (human vs agent, which session).
Admin Copilot	/cm/copilot — edit, create, and publish content in plain language, with RBAC and full audit logging.
llms.txt + JSON-LD	Auto-generated /llms.txt and /llms-full.txt for AI crawlers, schema.org structured data on every page.
MCP for Readers	Public read-only MCP endpoint at /mcp-public — visitors' agents can search and read the site natively.
Local Embeddings	LIGHTCMS_EMBEDDINGS_PROVIDER=ollama for fully self-hosted semantic search — no API credits.
Self-Maintaining Sites	Daily maintenance scans surface stale pages, missing meta, and broken links as an agent-ready work queue.

What's New in v6.0

Feature	Summary
Content Approvals	Contributors submit content for approval; editors/admins approve or reject from /cm/approvals. Rejection comments auto-post to the discussion thread.
Contributor Role	New RBAC role between Viewer and Editor. Can create content + upload assets (pending), post comments, and submit for approval — but cannot publish directly or manage system settings.
Approval Workflows	Configurable trigger-based workflows (contributor, folder path, template ID, or tag). Sequential or concurrent mode with configurable approver lists.
Content Discussion	Inline comment thread at the bottom of every edit page. @mention autocomplete, live badge count, admin delete.
Tabbed Bottom Panel	Discussion, Version History, and Forks organized into tabs on the content edit page.
Approvals Dashboard	My Queue + Other Pending + Workflow Config at /cm/approvals. Sidebar badge shows pending count.
Dashboard Sections	Requiring Approvals and Recent Comments appear on the admin dashboard when relevant.
New Webhook Events	comment.created, content.pending_approval, asset.pending_review.
14 new MCP tools	Full comment and approval lifecycle — list/create/delete comments, full workflow CRUD, list/get/submit/approve/reject/cancel approval requests.

What's New in v5.0

Feature	Summary
Import Pipeline	Three new import types — RSS/Atom feeds, Markdown/ZIP upload, CSV bulk import — with a unified job dashboard at /cm/imports.
RSS/Atom Import	Configure recurring feed sources with hourly/daily/weekly schedules, template mapping, folder targeting, and auto-publish.
Markdown Import	Upload .md files or .zip archives with YAML frontmatter. Supports Notion exports, Obsidian vaults, Hugo/Jekyll migrations, and AI-generated content.
CSV Import	Upload CSV files and map columns to content fields. Specify the title column; all other columns become fields automatically.
Real-time Job Status	SSE-powered live log stream at /cm/imports/{jobID}. Watch imports happen line-by-line or review full history after the fact.
10 new MCP import tools	list_import_sources, create_import_source, update_import_source, delete_import_source, trigger_import_source, import_markdown, import_csv, list_import_jobs, get_import_job, cancel_import_job.
Agentic bulk content creation	import_markdown is designed for AI agents to generate and import large content batches in a single call. See MCP.md.
Deduplication	Imports match by full_path — re-importing the same slug updates rather than duplicates.

What's New in v4.5

Feature	Summary
Webhooks	HMAC-SHA256 signed events for publish, unpublish, delete, create, update. Admin UI at /cm/webhooks with delivery history and a docs page.
Scheduled Publishing	Set a future publish_at timestamp on any content item; a background scheduler auto-publishes at the right time.
Content Locking	Advisory lock when editing (30-min expiry). Warning banner if another user is already editing. Admins can force-unlock.
Incremental Static Regeneration (ISR)	Template layout changes regenerate affected pages in 20-page batches, preventing server overload on large sites.
Edge Caching Headers	ETag, Cache-Control, Last-Modified, and Vary headers on all public pages. 304 Not Modified support.
Cloudflare Integration	Configure Zone ID + API Token to auto-purge Cloudflare cache on publish/unpublish.
Structured JSON Logging	All server logs emit structured JSON with timestamp, level, message, and context fields.
Rate Limit Dashboard	New tab on the audit log page showing locked IPs, attempt counts, and a one-click clear button.
MCP Prompt Resources	Three new MCP resources: lightcms://site/structure, lightcms://content/recent, lightcms://theme/config.

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 130 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: Quill 2 for visual content editing (vendored in static/admin/quill/, served from the site itself)
• 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. Feed URLs must be publicly reachable (private and loopback addresses are refused, v7.4.3).
• 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, keeping the publish state they had in the fork (normally draft) unless the merge is run with publish_new
• Merges Clean Up (v7.4+): A merge deletes the fork's page copies and keeps the fork record, with created/updated counts, as history. Forks merged before v7.4 can be cleaned with purge_fork_copies
• Fork Copies Stay Out of the Way (v7.4+): Fork copies are left out of content listings and search unless include_forks is set, and can never be published directly or in bulk — only merged
• Hold Flag (v7.4+): Mark any draft hold to block every way of publishing it (publish, bulk publish, scheduled publish, approval, fork merge) until the flag is cleared
• Full MCP Toolset: 9 dedicated fork tools — list_forks, create_fork, get_fork, fork_page, remove_fork_page, merge_fork, archive_fork, delete_fork, purge_fork_copies

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 <script> tag — self-contained, no build step required
• Two-Phase Pipeline: Each visitor query runs hybrid semantic+fulltext search to retrieve relevant content excerpts, then streams those excerpts through Claude Haiku for a conversational synthesized answer
• SSE Streaming: Haiku's token-by-token output is forwarded live to the browser via Server-Sent Events; falls back to plain JSON for non-SSE clients
• AI-Optional: Without an Anthropic API key, the widget works as a search-in-chat experience returning ranked excerpts — no API cost
• Fully Configurable: Admin "Chat Widget" page controls title, welcome message, placeholder text, primary color, position (bottom-left/right), max results, and editable system/user prompt templates
• Dedicated Rate Limiting: Separate per-IP (5/min) and global (30/min) limiters independent from the search and API limiters
• Source Attribution: Every response includes the content pages whose excerpts were used, with titles and paths

Multi-User Access Control & Approvals (v2.0+, v6.0+)

• Role-Based Access Control (RBAC): Four roles — admin, editor, contributor, viewer — with granular permission enforcement on all admin UI pages and REST API endpoints
• Contributor Role (v6.0+): Create content, upload assets, post comments, and submit for editorial approval — without publish rights
• Approval Workflows (v6.0+): Configurable trigger-based workflows (by role, folder, template, or tag). Sequential or concurrent mode. Default (no workflow): any editor or admin can approve
• Content Approvals Dashboard (v6.0+): My Queue, Other Pending, and Workflow Config at /cm/approvals. Sidebar badge shows pending count
• Content Discussion (v6.0+): Inline threaded comments on every content edit page. @mention autocomplete, admin delete, live count badge
• User Management: Admin panel for creating users, assigning roles, disabling accounts, and resetting passwords
• Audit Log: Persistent, searchable log of all mutations (who did what, when) with 365-day retention
• Rate Limit Dashboard (v4.5+): New tab on the audit log page showing locked IPs, attempt counts, and a clear button
• User-Scoped API Keys: API keys inherit the permissions of their owning user
• Force Password Change: Temporary passwords trigger a mandatory change on first login

Smart End-User Search

• Hybrid Search: Combines full-text exact matching with semantic vector search (Voyage AI embeddings), merged via reciprocal rank fusion
• Configurable Ranking: All ranking weights editable in the admin panel — nav boost, title boost, boosted templates, demoted path prefixes, and penalty scores
• Intelligent Defaults: Nav-linked pages surface first, concept-template pages rank above generic content, video transcripts are deprioritised
• Title Boost: Pages where the query appears in the title always rank above body-only matches
• Typeahead Suggestions: Fast prefix-matching suggestions — pages for direct navigation, keywords for full search — with the same structural ranking
• Works Without Embeddings: Falls back to full-text search if no Voyage API key is configured
• Rate Limiting: Per-IP and global rate limiting for DDoS protection

Developer & Integration

• REST API: Full /api/v1/ JSON API with API key and OAuth token authentication, RBAC-enforced
• MCP Server: 130 tools + 3 prompt resources for agentic website management (stdio + HTTP streamable)
• OAuth 2.1: Authorization code flow with PKCE for remote MCP clients — no embedded passwords
• CLI Tool: Command-line interface for all content management operations
• URL Redirects: 301/302 redirect rules managed from the admin panel
• Webhooks (v4.5+): HMAC-SHA256 signed event delivery for 6 event types (content.create, content.update, content.publish, content.unpublish, content.delete, and more); per-webhook secrets; delivery history with retry visibility; admin UI at /cm/webhooks. Webhook URLs must be publicly reachable: a URL that resolves to a loopback, private or link-local address is refused and logged as "blocked" (v7.4.3)
• Cloudflare Integration (v4.5+): Auto-purge Cloudflare cache on publish/unpublish via Zone ID + API Token
• Edge Caching Headers (v4.5+): ETag, Cache-Control, Last-Modified, Vary, and 304 Not Modified on all public pages
• Structured JSON Logging (v4.5+): All server logs emit structured JSON with timestamp, level, message, and context fields

Site Customization

• Theme Customization: Colors, fonts, border radius, custom CSS — all editable in the admin panel with version history
• Header/Footer HTML: Full HTML control over site chrome injected around all pages
• Asset Management: Upload and manage images, documents, and other files with path-based serving

Prerequisites

• Go 1.24 or later
• MongoDB Atlas account (free tier works great)

Quick Start

1. Clone the repository
2. Copy config.dev.json.example to config.dev.json
3. Edit config.dev.json with your MongoDB connection string
4. Run go run cmd/server/main.go
5. Visit http://localhost:8082/cm and log in with your email and password
6. On first run, an admin account is created — set LIGHTCMS_ADMIN_EMAIL to use your email, or it defaults to admin@localhost

MongoDB Atlas Setup

Step 1: Create an Atlas Account

1. Go to MongoDB Atlas
2. Sign up for a free account (no credit card required)

Step 2: Create a Cluster

1. Click "Build a Database"
2. Select "M0 FREE" (Shared) tier
3. Choose your preferred cloud provider and region (closest to you)
4. Click "Create Deployment"

Step 3: Set Up Database Access

1. Create a database user:

   • Username: lightcms (or your choice)
   • Password: Generate a secure password (save this!)
   • Click "Create User"

2. Add your IP address:

   • Click "Add My Current IP Address"
   • Or add 0.0.0.0/0 to allow access from anywhere (less secure, but convenient for development)
   • Click "Finish and Close"

Step 4: Get Your Connection String

1. Click "Connect" on your cluster
2. Select "Drivers"
3. Copy the connection string, it looks like:

   mongodb+srv://lightcms:<password>@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority
   

4. Replace <password> with your actual password

Step 5: Create Your Config File

For development, copy the example and fill in your values:

cp config.dev.json.example config.dev.json

Edit config.dev.json:

{
  "port": "8082",
  "mongo_uri": "mongodb+srv://lightcms:YOUR_PASSWORD@cluster0.xxxxx.mongodb.net/lightcms",
  "env": "development",
  "session_secret": "any-random-string-for-dev"
}

For production, use config.prod.json:

cp config.prod.json.example config.prod.json

Edit with production values (use openssl rand -hex 32 for session_secret).

Installation

# Clone or navigate to the project
cd lightcms

# Install dependencies
go mod tidy

# Run the server
go run cmd/server/main.go

Or use the run script:

./run.sh

Configuration

LightCMS uses JSON config files. Create either:

• config.dev.json - for development
• config.prod.json - for production (takes precedence if both exist)

Field	Description
port	Server port (e.g., "8082" for dev, "80" for prod)
mongo_uri	MongoDB Atlas connection string
database_name	MongoDB database name. Optional, default lightcms
env	Environment: "development" or "production"
session_secret	Random string for session encryption
base_url	Public URL of the site
secure_cookies	true in production (HTTPS). false for local development over plain HTTP