@uniformdev/uniform-mcp 20.23.0 → 20.23.1-alpha.9

package/references/uniform-sdk.mdc

@@ -1,97 +0,0 @@
----
-description:
-globs:
-alwaysApply: false
----
-# Uniform SDK Developer Reference
-
-This document details general information and practices about how Uniform works for developers writing frontend applications.
-
-[uniform.mdc](mdc:.cursor/rules/uniform.mdc) describes general Uniform principles and practices.
-
-## Authenticating to Uniform
-
-To fetch a composition, you need a Uniform API key configured. API keys are commonly stored as `UNIFORM_API_KEY` in a `.env` file. They follow the format `uf......`. The API key requires "Read Published Compositions" permission.
-
-## How Uniform transfers layout data to frontend applications
-
-Uniform provides _composition instances_, a hierarchical JSON structure of components that define screens or pages in an application. A composition is made up of any number of _components_ which have a type that we map to a frontend component.
-
-### Routing
-
-Uniform's _Project Map_ feature enables automatic dynamic route delegation to Uniform authors. Frontend applications define a wildcard route that delegates routing to the Uniform _Route API_, which takes a dynamic path and resolves the correct composition instance data to display for that path.
-
-### Syncing data with the Uniform CLI
-
-Uniform provides a CLI which can be used to sync the state of a Uniform project, such as component definitions, pattern definitions, or compositions, to files on disk. These files may be committed to source control and used to ensure the states of environment or developer-specific projects are kept up to date to reduce the chance of errors.
-
-#### Required package for Uniform CLI
-
-The Uniform CLI is contained in the `@uniformdev/cli` npm package.
-
-#### Authenticating with the Uniform CLI
-
-The Uniform CLI requires a Uniform API key to authenticate. The API key and other connectivity details are stored in a `.env` file. When creating an API key for the CLI, the user can use the "Copy as .env" function in the Uniform dashboard to get the appropriate environment variable values.
-API keys used for the Uniform CLI require read and write permissions to any entity types that are to be synced. The default 'developer' role is a shortcut to full permissions.
-
-#### Configuring the Uniform CLI
-
-Uniform CLI is configured using the `uniform.config.{ts,js}` file in the root of a project. The file can be configured in two ways: to sync everything (choose this for initial setup), or to pick specific entity types to sync. Sync operates as a mirror by default, meaning creates, updates, and deletes are all synced.
-
-`uniform.config.ts` (sync all):
-
-```ts
-import { uniformConfig } from "@uniformdev/cli/config";
-
-export default uniformConfig({ preset: "all" });
-```
-
-`uniform.config.ts` (sync explicit types and customization options):
-
-```ts
-import { uniformConfig } from "@uniformdev/cli/config";
-
-export default uniformConfig({
-  // 'none' starts with no entities, and each entity type to sync is added explicitly
-  preset: "none",
-  config: {
-    serialization: {
-      // optionally override the default `./uniform-data` to store serialized files
-      directory: "./custom-path-to-serialized-files",
-      // optionally change the default yaml format to json
-      format: "json",
-      entitiesConfig: {
-        // specify entity types to sync. Each type can optionally override
-        // the defaults just for itself, i.e. directory, format
-        component: {},
-        componentPattern: { publish: true },
-      },
-    },
-  },
-});
-```
-
-#### Invoking the Uniform CLI
-
-The Uniform CLI operates using two primary commands:
-
-`uniform sync push` - takes the serialized state of entities (files on disk) and pushes that state into a Uniform project online.
-
-`uniform sync pull` - takes the online state of a Uniform project and pulls it into serialized files.
-
-Conventionally these commands are registered as package scripts to make it unnecessary to install the CLI package globally:
-
-`package.json`:
-
-```json
-{
-  "scripts": {
-    "uniform:pull": "uniform sync pull",
-    "uniform:push": "uniform sync push"
-  }
-}
-```
-
-#### Getting Uniform CLI help
-
-The Uniform CLI has a built-in help system. To get help on a command, run `uniform <command> --help`, for example `uniform sync pull --help`.

package/references/uniform.mdc

@@ -1,153 +0,0 @@
----
-description: Uniform Content Modeling Reference - details content modeling options and techniques in Uniform CMS
-globs:
-alwaysApply: true
----
-
-## Uniform Core Concepts
-
-Uniform is a modern, headless, component-based Content Management System (CMS). Its primary purpose is to allow non-technical authors (marketers, etc) to create and maintain websites and other similar experiences in a visual editor.
-
-### Uniform Compositions
-
-A composition instance in Uniform is roughly equivalent to a page. Composition definitions define a reusable schema for composition instances. Composition definitions have a structure identical to a Uniform Component, i.e. parameters and slots. Composition instances differ from components in that they also define a route or page. Instances of a composition create pages or routes within an application. The term "Composition" can be used to refer either to a definition or instance of a composition, you will need to infer which is meant (schema/reusable template = definition, page/route = instance).
-
-Composition parameters should only be used for global content that will never need to be personalized.
-Good example: OpenGraph data and meta tags (if they exist)
-Bad example: "hero title" belongs in a Hero component in the content slot.
-
-A single composition definition called 'Page' is generally a good starting point. Additional composition definitions are only required if the page shell is different (e.g. Page, Popup, Minimal Page), or if there are different parameters needed on the composition definition
-
-In developer terms, a composition instance is a dynamic layout that is defined by non-technical authors; a composition definition is a hierarchical content schema definition.
-
-### Uniform Components
-
-Uniform Components are used to allow CMS authors to create and manipulate visual elements on a composition. Each property of a Uniform Component, such as a title or image, is called a _Component Parameter_. See _Uniform Parameter/Field Types_ for the exact types of parameter that are allowed. Components have both a definition (their schema) and instances (when an instance of that schema is placed within a slot on a composition).
-
-Uniform Components can define named _slots_.
-
-- A slot allows additional components to be inserted within the Uniform Component. For example an accordion component could have an 'items' slot that allows adding Accordion Item components.
-- Each named slot has 0..n child components. The order in the slot determines the order of rendering.
-- Each slot definition allows only specific Uniform Components to be placed within it (by public id). It can also define the minimum and maximum number of components allowed.
-- Components allowed within slots can also have their own slots, with no depth limit - but it is generally undesirable to nest more than 2-3 levels deep to improve author understanding.
-- When a Uniform Composition is defined, it almost always has a generic 'content' slot added to it that allows using various components to define the layout.
-
-Uniform Component Definition attributes:
-
-- _name_
-- _public ID_
-- _parameters_
-- _slots_
-
-Uniform Slot Definition attributes:
-
-- _name_
-- _public ID_
-- _allowed components_
-- _min components_
-- _max components_
-
-In technical terms, a Uniform Component maps directly to a presentational frontend component such as a React component. The parameters are component props. Slots are component props that contain rendered child components.
-
-### Uniform Content Types
-
-Uniform Content Types define a reusable structure for individual reusable pieces of content. A Uniform content type differs from a Uniform component because a component represents a specific visual element on a composition/page, but a content type is an abstract, reusable content schema. An instance of a Uniform Content Type is called an _Entry_. Entries each have their own built-in slug: there is no need to define an explicit slug field.
-
-For example a Product might be a Uniform Content Type, and the data from instances of that Product could be presented in different contexts by Uniform Patterns such as Product List, Product Detail, or Product Card.
-
-Uniform Content Types define content properties called _Fields_ (e.g. a blog post could have a single-line text input for title, and a rich text editor for body). See _Uniform Parameter/Field Types_ for the exact types of field that are allowed.
-
-Uniform Content Type attributes:
-
-- _name_
-- _public ID_
-- _fields_
-
-### Uniform Patterns
-
-Patterns allow reusing the same content across compositions. The simplest way to think of a pattern is that it is a _shared component instance_ that can be placed within a slot to insert the pattern's content there. The pattern, like any other component instance, can have values in its parameters and child components in its slots. All usages of the same pattern reference the same shared content. Updates made to patterns are immediately reflected to all usages. Patterns may be nested within each other (e.g. a Blog Post Hero pattern could include a Author Bio pattern in one of its slots). Nesting beyond 2-3 levels can cause performance issues.
-
-#### Uniform Pattern Overrides
-
-Parameters on patterns can be defined _overridable_ by the pattern definition. Overridable parameter values default to using the value defined on the pattern, but consumers of the pattern may choose to break the inheritance of that parameter value and replace it with their own instance-specific value. Patterns that contain other patterns may not alter the overridability of nested pattern parameters: once overridable, any consumer of the pattern can change the value. Overrides are used to allow partial content sharing and exception cases.
-
-#### Using Uniform Patterns as Shared Content Snippets
-
-Patterns can be used to reuse shared content, for example the same legal disclaimer might be required on every press release. Both patterns and components allow content reuse: the difference is that patterns reuse exact content, whereas components reuse content schemas but do not provide content values.
-
-#### Using Uniform Patterns as Data Binding Templates
-
-Patterns can be used to create bindings between structured data (from Uniform Entries or external data sources, like REST APIs or other CMSes) and presentation parameters. A pattern can define a _Data Resource_ which is the result of fetching from a data source. Then parameters in the pattern can use _Dynamic Tokens_ to bind to elements within the data resource. For example, we might have a Card component that has a title and image. Then we create a Product Card pattern, based on the Card component, which has a Uniform Entry Data Resource that fetches an entry specified by the pattern consumer. The Product Card automatically binds the title and image from the product entry to the Card component's parameters. As an author, one can then insert a Product Card pattern, choose the product to use, and have the title and image automatically set up for them.
-
-Example of a resolved Data Resource (named 'myEntry'):
-{ "myEntry": { "fields": { "title": "hello world" } } }
-
-Example of a Dynamic Token in a text parameter referencing the myEntry title:
-"today's greeting: ${#jptr:/myEntry/fields/title}" (this resolves to "today's greeting: hello world")
-
-#### Uniform Pattern attributes
-
-- _name_
-- _type_ - public ID of the base Uniform Component
-- _public id_ - id of the pattern
-- _data resources_ (name, type)
-- _parameters_ (value, overridable)
-- _slots_
-
-## Conventions
-
-### Uniform Field/Parameter Types
-
-Uniform Fields or Uniform Parameters attributes:
-
-- _name_
-- _public ID_. Must be unique within a Uniform Component or Uniform Content Type (including the ID of group fields/parameters)
-- _localizable_. Localizable values have a distinct value for each locale; otherwise the value is the same for all locales.
-- _required_. Required means that a CMS author must input a value in order to be considered valid.
-- _type_. See list below.
-- _guidance_. Brief LLM instructions used when generating or editing values.
-- _overridable_. Only applies for fields/parameters on a pattern definition. Allows consumers of the pattern to break inheritance and change the pattern definition's value for the field/parameter.
-
-Exhaustive list of allowed field/parameter types:
-
-- _text_: Plain text content
-- _richText_: Formatted text with styling (Lexical JSON format)
-- _select_: Choose between a controlled vocabulary of options
-- _multi-select_: Choose between a controlled vocabulary of options, allowing multiple selections
-- _number_: Numeric value
-- _date_: Calendar date
-- _dateTime_: Date with timezone
-- _checkbox_: Boolean toggle
-- _link_: URL or internal reference
-- _asset_: Image, video, audio, or other file
-- _json_: A JSON object. Not for use in author-facing fields/parameters, who will have trouble editing JSON.
-- _contentReference_: References a single or multiple Entries of a specified type. Can only be used in Fields on Content Types (not Parameters on Components)
-- _enrichmentTag_: Tag content with enrichments (relevant segments) to make viewing the content alter the classification of the visitor that saw it.
-- _group_: Group multiple fields/parameters together visually, for example a group of address fields. IMPORTANT: fields added to a group must come directly after the group in the fields list.
-
-### Uniform Naming Conventions
-
-- All names should be title-cased prose, not technical shorthand (e.g. "Main Header" not "main-header" or "MainHeader"). There is no need to include the type of entity in a name (e.g. 'Hero' not 'Hero Component').
-- Do not name Uniform Components, Uniform Content Types, or Fields/Parameters based on visible content found in inputs; treat it as FPO (e.g. <h1>Hello</h1> does not mean name the component 'Hello' - describe its meaning instead, such as 'Headline').
-- _Public ID_ are developer-facing identifiers for Uniform entities. They are based on a slugified version of the name. Use a camel case, for example if the name is "Main Header", the public ID is "mainHeader". Public IDs must be unique within a given entity type (e.g. Uniform Components). You cannot alter public IDs after creating an entity.
-- Descriptions or help text should be no longer than 1 short sentence. It is not necessary to write help text unless we have specific expectations for authors. For example a 'Title' doesn't need help text. But if we identify an image that needs to be 250x250px, that expectation belongs in help text. Descriptions and help text are plain text, no markdown or HTML.
-
-## Tool Usage Tips
-
-- Before creating or updating Uniform Patterns, fetch Uniform Component Definitions to ensure you know about valid component types and parameters.
-- When making multiple updates to the same Uniform Pattern, such as adding a component and setting a parameter value, batch changes together into a single tool call to improve performance and consistency.
-- When a Uniform tool provides you with an edit URL offer it to the user as a link, unless you already have recently.
-- Before inserting, removing, or reordering parameters or fields from a Uniform Component or Uniform Content Type, make sure to fetch the latest definition data to ensure you target the correct location.
-- If you are tasked with reordering fields or parameters, you must remove them and re-add them in the new order
-
-## Unsupported Features
-
-The following Uniform features cannot currently be changed using MCP/AI. If asked to perform the following actions, explain you cannot yet do that, and when possible offer a link to perform the task in the Uniform web app.
-
-- Managing Uniform locales, both global registration and enablement on compositions or entries
-- Managing the project map, including adding or fetching nodes, or attaching compositions to project map nodes.
-- Managing compositions or entries (creating, updating)
-- Managing entry patterns
-- Managing block fields/parameters, or block type definitions
-- Setting the value of asset or reference type fields/parameters
-- Data sources, data types, and data resources