Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tejavallabhaneni--sitecore-component-mcp/badge.svg)](/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

i

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
  1. # sitecore-component-mcp
  2. 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.
  3. 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.
  4. ## The problem
  5. 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.
  6. ## What it does
  7. | Tool | Purpose |
  8. | --- | --- |
  9. | `list_components` | One line per deployed component, with allowed placeholders |
  10. | `get_component_contract` | Exact fields, types, required flags, length guidance, allowed params |
  11. | `find_duplicate_components` | Groups identical, near-identical and subset components by field signature |
  12. | `find_orphaned_renderings` | Renderings in Sitecore with no matching component in source |
  13. | `validate_page_plan` | Checks a plan and returns each issue with a `fix` the agent can act on |
  14. | `build_page` | Creates the page and components after validating again on the server |
  15. | `revert_job` | Undoes an Agent API operation by job ID |
  16. 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:
  17. ```tsx
  18. /**
  19. * Two-column promotional block.
  20. * @placeholder main
  21. * @placeholder promo-zone
  22. * @maxPerPage 3
  23. * @param variant image-left | image-right | stacked
  24. */
  25. export type PromoSplitFields = {
  26. /** Two-line clamp on mobile — keep it tight. @maxLength 60 */
  27. Heading: Field<string>;
  28. Body: RichTextField;
  29. /** Omit unless there's a genuine secondary action. */
  30. SecondaryCta?: LinkField;
  31. };
  32. ```
  33. 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.
  34. ## Getting started
  35. Requires Node.js 20+.
  36. ```bash
  37. npm install
  38. cp .env.example .env.local # fill in your values
  39. export JSS_COMPONENTS_PATH=./example/src/components # or your JSS app's components folder
  40. npm run dev
  41. ```
  42. `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.
  43. ### Environment variables
  44. | Variable | Description |
  45. | --- | --- |
  46. | `SITECORE_CLIENT_ID` / `SITECORE_CLIENT_SECRET` | Environment automation client (SitecoreAI Deploy → Credentials) |
  47. | `SITECORE_ENV_HOST` | Authoring environment host name |
  48. | `JSS_COMPONENTS_PATH` | Path to your JSS components folder |
  49. | `MCP_SHARED_SECRET` | Bearer token required on `/api/mcp` |
  50. | `ALLOW_PRODUCTION_WRITES` | `build_page` refuses hosts without dev/qa/uat/staging in the name unless this is `true` |
  51. ### Connect a client
  52. Cursor (`.cursor/mcp.json` is included):
  53. ```json
  54. { "mcpServers": { "sitecore-components": { "url": "http://localhost:3000/api/mcp" } } }
  55. ```
  56. Claude Code:
  57. ```bash
  58. claude mcp add --transport http sitecore-components http://localhost:3000/api/mcp \
  59. --header "Authorization: Bearer $MCP_SHARED_SECRET"
  60. ```
  61. ## Before you point it at a real environment
  62. - **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.
  63. - **Start on a non-production environment.** Keep `ALLOW_PRODUCTION_WRITES=false`.
  64. - **The shared secret is a minimum.** For anything outside your team, use OAuth 2.1 as the MCP spec requires (`withMcpAuth` in mcp-handler).
  65. ## Tests
  66. ```bash
  67. npm test # validation, duplicate detection and manifest extraction
  68. npm run typecheck
  69. ```
  70. ## Differences from the article
  71. - 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.
  72. - 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`.
  73. - Validation and duplicate grouping are split into pure functions (`checkPlan`, `groupDuplicates`) so they can be tested without the Agent API.
  74. ## License
  75. MIT © Teja Vallabhaneni

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.