Skip to main content
Glama

sitecore-component-mcp

A component-aware MCP server for SitecoreAI. It gives AI agents (Cursor, Claude Code, any MCP client) the real contracts of your JSS components, finds duplicate components in your library, and validates a page plan before anything is written through the SitecoreAI Agent API.

This is the companion code for the article Your Agent Doesn't Know Your Components, which explains every file step by step.

The problem

Marketer MCP and the Agent API know Sitecore primitives: renderings, placeholders, field types. They don't know the layer you own: which fields are required, how long a heading can be, which placeholders a component is allowed in, or that PromoSplit and PromoBanner are the same component under two names. An agent without that knowledge picks components by name match and invents field names.

Related MCP server: Questionnaire Component Governance MCP Demo

What it does

Tool

Purpose

list_components

One line per deployed component, with allowed placeholders

get_component_contract

Exact fields, types, required flags, length guidance, allowed params

find_duplicate_components

Groups identical, near-identical and subset components by field signature

find_orphaned_renderings

Renderings in Sitecore with no matching component in source

validate_page_plan

Checks a plan and returns each issue with a fix the agent can act on

build_page

Creates the page and components after validating again on the server

revert_job

Undoes an Agent API operation by job ID

Contracts come from your JSS source at build time. scripts/generate-manifest.ts uses ts-morph to read each <ComponentName>Fields type and its JSDoc tags:

/**
 * Two-column promotional block.
 * @placeholder main
 * @placeholder promo-zone
 * @maxPerPage 3
 * @param variant image-left | image-right | stacked
 */
export type PromoSplitFields = {
  /** Two-line clamp on mobile — keep it tight. @maxLength 60 */
  Heading: Field<string>;
  Body: RichTextField;
  /** Omit unless there's a genuine secondary action. */
  SecondaryCta?: LinkField;
};

At runtime the manifest is reconciled with the renderings the Agent API reports, so the agent only sees components that are actually deployed to the environment.

Getting started

Requires Node.js 20+.

npm install
cp .env.example .env.local   # fill in your values
export JSS_COMPONENTS_PATH=./example/src/components   # or your JSS app's components folder
npm run dev

npm run manifest regenerates generated/manifest.json. npm run manifest:check fails if the committed manifest is out of date, which is useful in CI.

Environment variables

Variable

Description

SITECORE_CLIENT_ID / SITECORE_CLIENT_SECRET

Environment automation client (SitecoreAI Deploy → Credentials)

SITECORE_ENV_HOST

Authoring environment host name

JSS_COMPONENTS_PATH

Path to your JSS components folder

MCP_SHARED_SECRET

Bearer token required on /api/mcp

ALLOW_PRODUCTION_WRITES

build_page refuses hosts without dev/qa/uat/staging in the name unless this is true

Connect a client

Cursor (.cursor/mcp.json is included):

{ "mcpServers": { "sitecore-components": { "url": "http://localhost:3000/api/mcp" } } }

Claude Code:

claude mcp add --transport http sitecore-components http://localhost:3000/api/mcp \
  --header "Authorization: Bearer $MCP_SHARED_SECRET"

Before you point it at a real environment

  • Check the Agent API paths. Every endpoint is in lib/sitecore/agent-api.ts. Verify them, and the request bodies in lib/build.ts, against the Agent API OpenAPI definition for your environment.

  • Start on a non-production environment. Keep ALLOW_PRODUCTION_WRITES=false.

  • The shared secret is a minimum. For anything outside your team, use OAuth 2.1 as the MCP spec requires (withMcpAuth in mcp-handler).

Tests

npm test          # validation, duplicate detection and manifest extraction
npm run typecheck

Differences from the article

  • Uses mcp-handler 2.x: the route lives at app/api/mcp/route.ts and maxDuration is a route segment export, because 2.x leaves routing to Next.js.

  • Fixes @param parsing in the extractor. TypeScript keeps a @param tag's name separate from its comment, so the article's version recorded image-left as the parameter name instead of variant.

  • Validation and duplicate grouping are split into pure functions (checkPlan, groupDuplicates) so they can be tested without the Agent API.

License

MIT © Teja Vallabhaneni

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers