BCMS

SKILL.md

---
name: bcms
description: >
  BCMS headless CMS for coding agents. Build with the @thebcms/client SDK (templates, entries,
  groups, widgets, media, functions, webhooks, API keys, permissions) and operate content through
  the BCMS Model Context Protocol (MCP) server—scoped keys, Streamable HTTP, entry/media tools.
  Use for content modeling, framework integrations (Next.js, Nuxt, Astro, Svelte, Gatsby, Vite),
  and agent-driven content operations.
---

# BCMS Skill

**Canonical copy:** edit this file at `ai/skills/bcms/SKILL.md`. The **Claude Code** and **Cursor** plugins package the same file via symlinks under `ai/providers/*/plugin/skills/bcms/` (see `ai/README.md` and `ai/AGENTS.md`). On Windows, if symlinks are unavailable, copy this file into those paths when publishing.

This skill gives the AI coding agent concise, BCMS‑specific guidance and defers longer explanations to the files in `references/`.
The agent should keep this file under roughly 500 lines and load deeper guides only when needed.

**Setup guide:** [thebcms.com/agents](https://thebcms.com/agents) — MCP connection, skill install, and the content CLI.

It covers two modes: **building** with the `@thebcms/client` SDK (application code, CI, scripts) and **operating** content through BCMS **MCP** tools (when the agent has them configured). Use the SDK for app code and builds; use MCP tools for content operations when available—see [BCMS MCP (agents and IDEs)](#bcms-mcp-agents-and-ides) and `references/mcp.md`.

Key topics:

- Setup and client initialization (see `references/bcms-api-basics.md`)
- Working with templates (see `references/templates.md`)
- Entries (see `references/entries.md`)
- Groups (see `references/groups.md`)
- Widgets (see `references/widgets.md`)
- Media (see `references/media.md`)
- Properties and field types (see `references/properties.md`)
- Functions and webhooks (see `references/functions-webhooks.md`)
- Permissions (see `references/permissions.md`)
- Framework integrations (see `references/frameworks.md`)
- MCP for agents and IDEs (see `references/mcp.md`)

## Integration principles and defaults

- **Default to the latest BCMS stack**: use the latest BCMS features and the newest `@thebcms/*` packages unless the user explicitly targets an older version. Generated types usually live under `bcms/types/ts` after `bcms --pull types` (see [framework guides](https://thebcms.com/docs/integrations)); some setups import from `@thebcms/types` or an alias—match the project you are editing.
- **Model content with BCMS primitives first**: prefer **templates + entries** as your main content model, with **groups** for reusable structures, **widgets** for reusable content blocks, and the **media library** for files.
- **Use CLI starters when possible**: for framework projects (Next, Nuxt, Astro, etc.) prefer the official `@thebcms/cli` starters before hand‑rolling integration; see `references/frameworks.md`.
- **Render via BCMS components**: in UI frameworks, prefer `BCMSContentManager` and `BCMSImage` (or their framework equivalents) to render rich text, widgets and media instead of building your own renderers.
- **Always isolate secrets**: store the **three‑part API key** (`keyId.secret.instanceId`) in environment variables (e.g. `BCMS_API_KEY`, plus a public key var where the framework docs require it), use separate keys per environment (dev/stage/prod), and prefer scoped keys, especially for media delivery; see `references/bcms-api-basics.md` and `references/permissions.md`.
- **Design for localisation**: when sites are multi‑lingual, use BCMS locales and model `meta`/`content` per locale; see `references/entries.md` and `references/properties.md`.
- **Evolve schemas, don't break them**: when changing content models, add or migrate fields via templates and groups; avoid destructive changes on production data; see `references/templates.md` and `references/groups.md`.
- **MCP when the agent has BCMS tools**: if the environment exposes BCMS MCP tools, use them for content and schema operations — listing, creating, updating, and **deleting** entries, templates, groups, and widgets, plus media discovery and uploads. Use `@thebcms/client` for application code, builds, and anything outside MCP (see `references/mcp.md`).

## Patterns to avoid (and what to do instead)

- **Never hard‑code API keys or use admin keys in the browser**.
  Instead, store secrets in environment variables and use minimally scoped keys; see `references/bcms-api-basics.md` and `references/permissions.md`.
- **Never ship MCP API keys to browsers, public repos, or client bundles**.
  MCP keys are for trusted agents and local config only; scope them like any write-capable key; see `references/mcp.md` and `references/permissions.md`.
- **Never delete templates, groups, widgets or media in production without checking impact**.
  Always inspect usage first (`group.whereIsItUsed`, `widget.whereIsItUsed`, `template.whereIsItUsed`) and plan a migration path; see `references/templates.md`, `references/groups.md`, `references/widgets.md`, and `references/media.md`.
- **Avoid stuffing unstructured JSON into `meta` or `content` when a property, group or widget fits**.
  Prefer explicit properties (string, rich text, enum, pointers, media) and reusable groups/widgets for structure; see `references/properties.md`, `references/groups.md`, and `references/widgets.md`.
- **Avoid re‑implementing rich‑text and widget rendering when `BCMSContentManager` is available**.
  Use the official components (`@thebcms/components-*`) with `BCMSContentManager` and `BCMSImage`, and only drop down to custom parsing when you have a clear requirement; see `references/entries.md` and `references/frameworks.md`.
- **Avoid exposing unnecessary write capabilities to public clients**.
  Do not use keys with create/update/delete rights from the frontend; keep mutations behind server‑side code or functions, and use read‑only or media‑only keys in the browser; see `references/permissions.md`.
- **Do not bypass webhook security**.
  Always verify webhook signatures, check timestamps, and design idempotent handlers; see `references/functions-webhooks.md`.

## When to reach for which BCMS features

- **Marketing, blog, or documentation sites**
  Use templates like `page`, `blog`, `doc` with structured properties, groups for SEO/author blocks, widgets for reusable sections, and the media library for images; render with `BCMSContentManager` and `BCMSImage`.
  See `references/templates.md`, `references/entries.md`, `references/groups.md`, `references/widgets.md`, and `references/media.md`.

- **Multi‑locale content**
  Model `meta` and `content` per locale, use BCMS locales, and ensure frontends handle missing translations gracefully using generated types (e.g. from `bcms/types/ts` or your project’s type package).
  See `references/entries.md` and `references/properties.md`.

- **Asset‑heavy or image‑driven experiences**
  Rely on the media library, folder structure, and auto‑generated sizes; use a dedicated media API key for public delivery and `BCMSImage` (or equivalent) to serve optimised variants.
  See `references/media.md` and `references/bcms-api-basics.md`.

- **Framework‑based frontends (Next.js, Nuxt, Astro, Gatsby, Svelte, Vite)**
  Prefer the official BCMS starters; otherwise, follow the framework‑specific guides, using the standard `Client` constructor, generated types, and the appropriate `@thebcms/components-*` package.
  See `references/frameworks.md`.

- **AI assistants and IDE workflows (Cursor, Claude Code, etc.)**
  Enable **MCP** on a dedicated API key, configure the MCP URL with least‑privilege template and media scopes, and use the exposed tools for content operations. Do not embed those keys in shipped apps.
  See `references/mcp.md` and [BCMS MCP documentation](https://thebcms.com/docs/mcp).

## BCMS MCP (agents and IDEs)

BCMS hosts an MCP server so assistants can work with BCMS **content and schema** using a key that has **MCP** enabled. Official overview: [thebcms.com/docs/mcp](https://thebcms.com/docs/mcp).

- **URL pattern**: `https://app.thebcms.com/api/v3/mcp?mcpKey=<keyId.secret.instanceId>` (the query param is **`mcpKey`**; adjust host if your org uses a custom app URL).
- **Auth**: the three‑part API key must have the **MCP flag** enabled, or the endpoint returns `403`.
- **Transport**: Streamable HTTP; after `initialize`, send **`mcp-session-id`** on follow‑up requests.
- **Capabilities**: fixed **kebab‑case** tools (IDs are passed as arguments, not encoded in tool names) covering full CRUD on **entries** (including **delete**) and on **templates / groups / widgets**, plus entry statuses, entry history, languages, media (list, folders, pre‑signed upload URL), pointer links, and trash. The full tool set is exposed to any MCP‑enabled key.
- **Rich text**: entry bodies use **node trees** (`paragraph`, `heading`, `bulletList`/`orderedList`, `listItem`, `text`, `codeBlock`, `hardBreak`, `horizontalRule`, `widget`, `media` — there is **no** `image` node); use **`get-entry-pointer-link`** and **`get-media-pointer-link`** for internal BCMS links in link marks.

Full tool names, resources, troubleshooting, and MCP vs SDK guidance: **`references/mcp.md`**.

## Setup and Client Initialization

- Always use **environment variables** for secrets, never hard‑code BCMS credentials.
- Use separate **API keys per environment** (development, staging, production).
- Prefer **scoped keys** with the minimum necessary permissions.

**Preferred for app starters (matches [Next.js](https://thebcms.com/docs/integrations/next-js) / [Nuxt](https://thebcms.com/docs/integrations/nuxt-js) docs):** one **three‑part API key** string in env (`keyId.secret.instanceId`) and a **single‑argument** client:

```ts
import { Client } from '@thebcms/client';

// Private: reads BCMS_API_KEY from the environment by default
export const bcmsPrivate = new Client({ injectSvg: true });

// Public / browser-safe key (example for Next.js)
export const bcmsPublic = new Client({
  apiKey: process.env.NEXT_PUBLIC_BCMS_API_KEY,
  injectSvg: true,
});
```

**Scripts and servers:** set `BCMS_API_KEY` to the same three‑part string and use `new Client({ injectSvg: true, useMemCache: true, enableSocket: false })` (see [`ai/scripts/init-client.ts`](../../scripts/init-client.ts)). Details match [thebcms.com/docs](https://thebcms.com/docs) integration guides.

For env variable patterns and security, see `references/bcms-api-basics.md`.

## Working with Templates

- Treat **templates** as your content types (e.g., `blog`, `page`, `author`).
- Use **singular, descriptive names** and rely on groups for reusable structures.
- Only admins (or keys with advanced rights) should create or modify templates.

Common operations:

- List all templates: `await bcms.template.getAll()`
- Get a template by ID or name
- Update or delete templates when refactoring content models

See `references/templates.md` for naming conventions, creation guidelines and code examples.

## Entries

- **Entries** are instances of templates (e.g., a single blog post).
- Entries usually have:
  - `meta` fields (title, slug, SEO, etc.)
  - `content` fields, often localized by language code

Example: get all entries for a `blog` template:

```ts
const blogPosts = await bcms.entry.getAll('blog');
```

Agents should be able to:

- Create, update and delete entries
- Retrieve entries by ID, slug or status
- Filter entries by template and status (e.g., draft vs. published)

See `references/entries.md` for full CRUD examples and multilingual details.

## Groups, Widgets and Media

- **Groups** are reusable structures that can be nested inside templates, widgets or other groups.
- **Widgets** are reusable content blocks embedded in rich‑text fields.
- **Media** refers to files in the BCMS media library (images, documents, etc.).

Typical operations:

- Groups:
  - `bcms.group.getAll()`
  - `bcms.group.whereIsItUsed(groupId)`
- Widgets:
  - `bcms.widget.getAll()`
  - `bcms.widget.whereIsItUsed(widgetId)`
- Media:
  - `bcms.media.getAll()`, `bcms.media.getById(id)`
  - Create folders and upload files using media API helpers

Widgets cannot currently be deleted via the SDK and must be removed via the BCMS dashboard.
See `references/groups.md`, `references/widgets.md` and `references/media.md` for concrete examples and media best‑practices.

## Properties and Field Types

BCMS supports various property types used in templates, groups and widgets, including:

- String, rich‑text, number, date, boolean
- Enumeration
- Entry pointer, group pointer
- Media fields (single and multiple)

Agents should choose appropriate field types based on content modelling goals and reusability.
See `references/properties.md`, `references/groups.md`, `references/widgets.md` and `references/templates.md` for details.

## Permissions and API Key Scopes

- BCMS enforces granular **permissions** for users and API keys.
- Permissions can be:
  - **Simple**: broad access levels
  - **Advanced**: per‑resource `get/create/update/delete` scopes
- Only admins can create templates, widgets, groups and API keys.

API keys:

- Should be scoped per template, function and media access where possible.
- Use **least privilege**: grant only the rights needed for the specific integration.

See `references/permissions.md` for a deeper explanation and configuration examples.

## Functions and Webhooks

- **Functions** are serverless handlers you deploy inside BCMS and call via REST.
- **Webhooks** notify external systems about events such as entry or media changes.

Agents should:

- Call functions using the correct URL and headers, including an API key with function permissions.
- Configure and secure webhooks by:
  - Verifying the `X-Bcms-Webhook-Signature` header
  - Validating timestamps to avoid replay attacks
  - Making handlers idempotent and rate‑limited

See `references/functions-webhooks.md` for full examples and security notes.

## Local repo examples (`ai/scripts/`)

Human developers (and agents with repo access) can run the TypeScript examples under [`ai/scripts/`](../../scripts/):

- **`init-client.ts`** — construct `Client` with `BCMS_API_KEY` (three‑part key).
- **`call-function.ts`** — call a BCMS function by ID with a JSON body (`BCMS_API_KEY`, `BCMS_BASE_URL`, `BCMS_FUNCTION_ID`).

These are **not** MCP; they illustrate SDK usage. See each file’s header for how to run them (e.g. `npx tsx` with env set).

Repo-level notes for automation: **`ai/AGENTS.md`**. Change history for this skill pack: **`ai/CHANGELOG.md`**.

## Best Practices and Troubleshooting

- Prefer TypeScript and generated BCMS types (`bcms/types/ts` after CLI pull, or your framework’s documented import path) where available.
- Use caching (e.g., in‑memory or application‑level) for frequently read data.
- Separate dev, staging and production environments and API keys.
- On errors, check:
  - URL correctness (org, instance, function ID)
  - API key scopes and permissions
  - Network and TLS configuration

For in‑depth guidance, always cross‑reference the official BCMS documentation from the `references/` files.