Sitecore MCP Server

# Sitecore MCP Server [](https://github.com/GaryWenneker/SitecoreMCP/actions/workflows/ci.yml) [](https://github.com/GaryWenneker/SitecoreMCP/actions/workflows/root-scan.yml) [](https://www.typescriptlang.org/) [](https://prettier.io/) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) A Model Context Protocol (MCP) server for Sitecore with **GraphQL API**, **version control**, **parent navigation**, and **item statistics**. Query Sitecore items via AI assistants like Claude and GitHub Copilot. ## ✨ Features ### 🎯 Core Tools (21 total) **Item Operations:** - 🔍 **sitecore_get_item** - Get a specific Sitecore item (with version support) - 👶 **sitecore_get_children** - Get child items (with version support) - 📄 **sitecore_get_field_value** - Get a field value (with version support) - � **sitecore_get_item_fields** - Get all fields of an item (template-aware) - �🔎 **sitecore_query** - Execute Sitecore queries - 🔍 **sitecore_search** - Search items with filters and ordering - 📄 **sitecore_search_paginated** - Search with pagination support **Template Operations:** - 📋 **sitecore_get_template** - Get template information - 📚 **sitecore_get_templates** - Get multiple templates **Version Control:** - 🕐 **sitecore_get_item_versions** - See all versions of an item - 📊 **sitecore_get_item_with_statistics** - Get created/updated dates and users **Navigation:** - ⬆️ **sitecore_get_parent** - Navigate to parent item - 🧭 **sitecore_get_ancestors** - Get all ancestors (breadcrumb) **Layout & Sites:** - 🎨 **sitecore_get_layout** - Get layout/presentation information - 🌐 **sitecore_get_sites** - Get Sitecore site configurations **Mutations (Create/Update/Delete):** - ➕ **sitecore_create_item** - Create new Sitecore items - ✏️ **sitecore_update_item** - Update existing items - ❌ **sitecore_delete_item** - Delete items **Advanced Features:** - 🔬 **sitecore_scan_schema** - Automatic GraphQL schema analysis - 💬 **sitecore_command** - Natural language `/sitecore` commands in chat - 🔍 **sitecore_discover_item_dependencies** - Comprehensive item discovery with template, fields, and relationships ### 📣 Live progress (all tools) All MCP tools now report progress via stderr so you can see what's happening during longer operations in your AI client. - Format: `[tool_name] Message...` - Examples: - `[sitecore_get_item] Starting (path=/sitecore/content/Home, language=nl-NL)` - `[sitecore_get_item] Completed: Home (template=Page, version=1)` - `[sitecore_search_paginated] Completed: 50 item(s), hasNextPage=true` Note: We always mention the language in messages (critical for Sitecore). ### 🎨 Examples **Via Slash Command Menu** (Type `/` in chat): ```bash # 1. Type / to open the menu # 2. Choose "🔧 /sitecore - Sitecore command interface" # 3. Type your command (with or without /sitecore prefix) help get item /sitecore/content/Home get item /sitecore/content/Home version 2 # NEW: Version support! get parent /sitecore/content/Home/Article # NEW: Parent navigation! get ancestors /sitecore/content/Home/Article # NEW: Breadcrumb! search articles field Title from /sitecore/content/Home templates ``` **Direct Natural Language Commands**: ```bash /sitecore help /sitecore scan schema /sitecore get item /sitecore/content/Home /sitecore get item /sitecore/content/Home version 2 /sitecore get parent /sitecore/content/Home/Article /sitecore get ancestors /sitecore/content/Home/Article /sitecore search articles /sitecore field Title from /sitecore/content/Home /sitecore templates ``` **Version Control Examples**: ```typescript // Get specific version sitecore_get_item({ path: "/sitecore/content/Home", language: "en", version: 2 }) // Get all versions sitecore_get_item_versions({ path: "/sitecore/content/Home", language: "en" }) // Returns: { totalVersions: 5, versions: [...], latestVersion: 5 } // Get item with statistics sitecore_get_item_with_statistics({ path: "/sitecore/content/Home", language: "en" }) // Returns: { created: "20211011T073530Z", createdBy: "sitecore\admin", ... } ``` **Navigation Examples**: ```typescript // Get parent sitecore_get_parent({ path: "/sitecore/content/Home/Article" }) // Returns: { name: "Home", path: "/sitecore/content/Home", ... } // Get all ancestors (breadcrumb) sitecore_get_ancestors({ path: "/sitecore/content/Home/Article" }) // Returns: { // count: 3, // ancestors: [...], // breadcrumb: "sitecore > content > Home" // } ``` ## 📚 Docs Map - **docs/guides/** - Technical guides and implementation details (GUID formats, content discovery, slash commands, etc.) - **docs/releases/** - Release notes per version (RELEASE-NOTES-v1.x.md) - **docs/ready-to-ship/** - Release checklists and readiness documents per version - **docs/status/** - Progress reports and status updates - **docs/summaries/** - Version summaries and overviews - **docs/BACKLOG.md** - Product backlog and planning Tip: All documentation is organized under docs/. Root contains only README.md. ## 📁 Repository Structuur ``` SitecoreMCP/ ├── .github/ # CI/CD workflows en GitHub configuratie │ └── workflows/ │ └── root-scan.yml # Root hygiene enforcement │ ├── src/ # TypeScript source code │ ├── index.ts # MCP server entry point (11 tools) │ ├── sitecore-service.ts # GraphQL client & business logic │ ├── sitecore-types.ts # TypeScript type definitions (auto-generated) │ └── sitecore-types-FULL.ts # Extended type definitions │ ├── dist/ # Compiled JavaScript (build output) │ ├── scripts/ # All scripts organized by category │ ├── build/ │ │ └── build-vsix.ps1 # VS Code extension packaging │ │ │ ├── schema/ # GraphQL schema management │ │ ├── download-schema.ps1 # Download schema from Sitecore │ │ ├── download-full-schema.ps1 │ │ ├── analyze-schema.ps1 # Analyze schema structure │ │ ├── extract-schema-types.ps1 │ │ ├── find-mutations.ps1 # Find mutation capabilities │ │ ├── generate-types.ps1 # Generate TypeScript types │ │ ├── generate-types-full.ps1 │ │ └── check-search-schema.cjs # Validate search schema │ │ │ ├── tests/ # Test scripts (72 files) │ │ ├── Load-DotEnv.ps1 # Environment loader for tests │ │ ├── test-*.ps1 # PowerShell test scripts │ │ └── test-*.cjs # Node.js test scripts │ │ │ ├── tools/ # Utility tools │ │ ├── build-relationship-graph.ps1 # Build item relationship graphs │ │ ├── parse-field-references.ps1 # Parse field references │ │ └── Load-DotEnv.ps1 # Canonical environment loader │ │ │ └── wrappers/ # Backward compatibility wrappers │ ├── *.ps1 # PowerShell wrappers (deprecated) │ └── *.cjs # Node.js wrappers (deprecated) │ ├── docs/ # All documentation │ ├── guides/ # Technical guides (35+ documents) │ ├── releases/ # Release notes per version │ ├── ready-to-ship/ # Release readiness checklists │ ├── status/ # Status and progress reports │ ├── summaries/ # Version summaries │ └── BACKLOG.md # Product backlog │ ├── data/ # Schema and graph data (generated) │ ├── graphql-schema.json # GraphQL schema dump │ ├── graphql-schema-full.json # Full introspection result │ └── graph.json # Relationship graph data │ ├── .env.example # Environment variabelen template ├── package.json # NPM dependencies en scripts ├── tsconfig.json # TypeScript compiler configuratie ├── LICENSE # MIT licentie └── README.md # Dit bestand (quick start) ``` ### Purpose per Directory | Directory | Purpose | Allowed Files | |-----------|---------|---------------| | **Root** | Project metadata and entry point | Config files + README.md only | | **src/** | TypeScript source code | .ts files | | **dist/** | Build output | .js, .d.ts files (generated) | | **scripts/** | All scripts organized | Subdirectories per category | | **scripts/build/** | Build and packaging scripts | build-vsix.ps1 | | **scripts/schema/** | GraphQL schema management | Schema tools (9 scripts) | | **scripts/tests/** | Test scripts | Test files (72 files) | | **scripts/tools/** | Utility tools | Helpers and utilities (3 tools) | | **scripts/wrappers/** | Backward compatibility | Deprecated wrappers (11 files) | | **docs/** | All documentation | .md files in subdirectories | | **data/** | Generated data files | .json schema dumps (gitignored) | | **.github/** | CI/CD workflows | GitHub Actions workflows | **Hygiene Policy**: Root contains ONLY config files and README.md. All documentation is under docs/, all scripts under scripts/. This structure is enforced by CI workflow (root-scan.yml). ## ✅ API Status **GraphQL API is active and working!** - ✅ Item queries - ✅ Get children - ✅ Get field values - ✅ Template information - ✅ Variables in queries ## Requirements - Node.js 18 or higher - Sitecore instance with GraphQL endpoint: `/sitecore/api/graph/items/master` - Sitecore API Key (see configuration) ## 🚀 Quick Start ### 1. Install dependencies ```bash cd c:\gary\Sitecore\SitecoreMCP npm install npm run build ``` ### 2. Configure Environment Copy `.env.example` to `.env` and configure your Sitecore instance: ```bash SITECORE_HOST=https://your-sitecore-instance.com SITECORE_API_KEY=your-api-key-here ``` ### 3. Run Tests Verify that all MCP tools are working correctly: ```powershell .\scripts\tests\run-tests.ps1 ``` This will run a comprehensive test suite covering: - ✅ Basic queries (item retrieval, children, fields) - ✅ Advanced search & discovery - ✅ Navigation & hierarchy (parent, ancestors) - ✅ Utilities & extensions Expected output: **17/17 tests passed (100% success rate)** ### 4. Configure your IDE/Tool Choose your favorite tool and configure the Sitecore MCP server: **Claude Desktop**: `%APPDATA%\Claude\claude_desktop_config.json` **VS Code**: `.vscode/settings.json` or User Settings **Rider**: `%APPDATA%\JetBrains\Rider2024.3\options\mcp-servers.json` **Visual Studio**: `%USERPROFILE%\.github-copilot\mcp-servers.json` See [docs/guides/INSTALLATION.md](docs/guides/INSTALLATION.md) for detailed configuration per tool. **Example configuration** (Claude Desktop): ```json { "mcpServers": { "sitecore": { "command": "node", "args": ["c:\\gary\\Sitecore\\SitecoreMCP\\dist\\index.js"], "env": { "SITECORE_HOST": "https://your-sitecore-instance.com", "SITECORE_API_KEY": "your-api-key-here" } } } } ``` For VS Code, Rider and Visual Studio configurations, see [docs/guides/INSTALLATION.md](docs/guides/INSTALLATION.md). ### 5. Restart your tool - **Claude Desktop**: Close completely and restart - **VS Code**: Reload Window (Ctrl+Shift+P) - **Rider**: Invalidate Caches & Restart - **Visual Studio**: Close solution and reopen The Sitecore MCP server should now be available! ## 💡 Gebruik Voorbeelden ### Slash Command Menu (New in v1.2.0!) **Step 1**: Open your AI chat (Claude Desktop, VS Code Copilot, etc.) **Step 2**: Type `/` to open the slash command menu **Step 3**: Choose `🔧 /sitecore` from the menu **Step 4**: Type your command (prefix is automatically added) ```bash # Via slash menu: / → choose /sitecore → "help" / → choose /sitecore → "get item /sitecore/content/Home" / → choose /sitecore → "search articles" / → choose /sitecore → "field Title from /sitecore/content/Home" ``` ### Direct Commands You can also type direct commands: ``` Get the Home item: /sitecore/content/Home ``` ``` Show all children of /sitecore/content/Home ``` ``` Execute this query: /sitecore/content/Home//*[@@templatename='Sample Item'] ``` ``` Search for items with "contact" in the name ``` ``` What is the Title field of /sitecore/content/Home? ``` See [docs/guides/EXAMPLES.md](docs/guides/EXAMPLES.md) and [docs/guides/SLASH-COMMAND.md](docs/guides/SLASH-COMMAND.md) for more extensive examples. ## Sitecore PowerShell Extensions API This MCP server uses the Sitecore PowerShell Extensions (SPE) API endpoint: ``` POST https://your-sitecore-instance.com/sitecore/api/spe/v2/script ``` Ensure SPE is correctly configured and the API is accessible. ## 📚 Documentation For a complete overview of all directories and their purposes, see the **📁 Repository Structure** section above. **Main documents:** - **[README.md](README.md)** (this file): Overview and quick start - **[docs/guides/INSTALLATION.md](docs/guides/INSTALLATION.md)**: Detailed installation for all IDEs - **[docs/guides/EXAMPLES.md](docs/guides/EXAMPLES.md)**: Extensive usage examples and use cases - **[docs/guides/SLASH-COMMAND.md](docs/guides/SLASH-COMMAND.md)**: ⚡ Slash command menu guide - **[docs/guides/SITECORE-COMMAND-GUIDE.md](docs/guides/SITECORE-COMMAND-GUIDE.md)**: Natural language command reference **Documentation Structure:** - `docs/guides/` – Technical guides and how-to's (35+ documents) - `docs/releases/` – Release notes per version (RELEASE-NOTES-v1.x.md) - `docs/ready-to-ship/` – Release readiness checklists - `docs/status/` – Status and progress reports - `docs/summaries/` – Version summaries **Note**: All documentation is under `docs/`. The root contains only README.md. Scripts are under `scripts/` in categories (build, schema, tests, tools, wrappers). ## 🔧 Troubleshooting ### MCP server doesn't appear - **Claude**: Check `claude_desktop_config.json` syntax → Restart app - **VS Code**: Reload Window (Ctrl+Shift+P) → Check Output panel - **Rider**: Invalidate Caches → Check Event Log - **Visual Studio**: Restart as Administrator → Check Extension logs ### SPE API errors - Run `.\test-spe-api.ps1` to test the API - Verify that SPE remoting is enabled in `Spe.config` - Check Sitecore logs: `https://your-sitecore-instance.com/sitecore/admin/showlog.aspx` ### Items not found - Verify that the path exists (case-sensitive!) - Verify database (master/web/core) - Check language code (en/nl/etc.) For more details, see [docs/guides/INSTALLATION.md](docs/guides/INSTALLATION.md). ## ⚠️ Security **Warning**: This configuration is intended for LOCAL development! For production environments: - ✅ Use HTTPS with valid certificate - ✅ No credentials in configuration files - ✅ Use Sitecore API keys - ✅ Restrict SPE permissions - ✅ Enable SSL certificate verification ## 🤝 Contributing Suggestions and improvements are welcome! Create an issue or submit a pull request. ## 📄 License MIT