sitecore-component-mcp
Component-aware MCP server for SitecoreAI: gives AI agents your JSS component contracts, finds duplicate components, and validates page plans before writing via the Agent API.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/tejavallabhaneni--sitecore-component-mcp)HTML
<a href="/listings/tejavallabhaneni--sitecore-component-mcp"><img src="/api/listings/tejavallabhaneni--sitecore-component-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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"
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 103 lines
- # 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](https://sitecore-component-mcp.vercel.app)**, 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.
- ## 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:
- ```tsx
- /**
- * 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+.
- ```bash
- 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):
- ```json
- { "mcpServers": { "sitecore-components": { "url": "http://localhost:3000/api/mcp" } } }
- ```
- Claude Code:
- ```bash
- 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](https://api-docs.sitecore.com/sai/agent-api) 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
- ```bash
- 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.