Sitecore MCP Server

# CRITICAL: Schema Migration Required - Search API Changed **Date**: October 16, 2025 **Status**: 🚨 BREAKING CHANGES FOUND **Priority**: HIGH --- ## 🚨 Problem Summary The `/items/master` schema has **COMPLETELY DIFFERENT** search API than `/edge`. The current code uses old `/edge` syntax which doesn't work. ### Current Issues 1. ❌ `executeQuery()` - Uses old `where: { name, value, operator }` syntax (BROKEN) 2. ❌ `searchItems()` - Same old syntax (BROKEN) 3. ✅ `getChildren()` - Fixed in v1.2.1 (WORKING) 4. ✅ `getItem()`, `getFieldValue()`, `getTemplate()` - Never used search (WORKING) --- ## 📊 Schema Test Results Ran `test-schema-validation.ps1`: ### ✅ PASSING (7/8): 1. ✅ `item()` → Direct Item object 2. ✅ `item().children()` → Direct [Item] array 3. ✅ `item().field()` → Direct string 4. ✅ `item().fields()` → [ItemField] array 5. ✅ `item().template` → Direct Template object 6. ✅ Endpoint `/items/master` → Correct 7. ✅ `children(first: N)` → Pagination works ### ❌ FAILING (1/8): 8. ❌ `search()` → Uses wrong syntax --- ## 🔍 Correct /items/master Search Schema ### Search Arguments ```graphql search( first: Int # Limit results after: String # Cursor (default: "0") rootItem: String # Path/ID to search under keyword: String # Keyword search fieldsEqual: [ItemSearchFieldQuery] # Field equality fieldsContain: [ItemSearchFieldQuery] # Field contains language: String # Language filter # Many more filters... ) ``` ### Return Type Structure ```graphql type ContentSearchResults { results: ContentSearchResultConnection! # Main results facets: [FacetResult] # Search facets totalCount: Int! # Total matches } type ContentSearchResultConnection { items: [SearchResultItem]! # ⚠️ Items array (not direct!) pageInfo: PageInfo # Pagination info } type SearchResultItem { item: Item! # ⚠️ Wrapped in 'item'! } ``` ### Correct Query Example ```graphql query { search( keyword: "home" rootItem: "/sitecore/content" first: 10 ) { results { items { # ⚠️ Access via .items item { # ⚠️ Then via .item id name path } } } totalCount } } ``` ### Access Pattern ```typescript // ❌ OLD (doesn't work): const items = result.search.results; // ✅ NEW (correct): const items = result.search.results.items.map(i => i.item); ``` --- ## 🛠️ Required Code Changes ### Priority 1: Disable Broken Tools Until search is fixed, these tools will return errors: - `sitecore_query` (uses executeQuery) - `sitecore_search` (uses searchItems) **Recommendation**: Add try/catch with clear error message: ```typescript throw new Error( "Search API migration in progress. " + "This tool currently doesn't work with /items/master schema. " + "Use sitecore_get_item or sitecore_get_children instead." ); ``` ### Priority 2: Fix Search Methods #### File: `src/sitecore-service.ts` **Method 1: `executeQuery()` (line ~200)** ```typescript // Current (BROKEN): search( where: { name: "_path", value: $path, operator: CONTAINS } first: $first language: $language ) { results { id name } // ❌ Wrong structure } // Should be: search( rootItem: $path first: $first language: $language ) { results { items { // ✅ Correct structure item { id name displayName path template { id name } } } } totalCount } ``` **Method 2: `searchItems()` (line ~270)** ```typescript // Current (BROKEN): search( where: { name: "_name", value: $searchText, operator: CONTAINS } first: $first ) { results { id name } // ❌ Wrong structure } // Should be: search( keyword: $searchText rootItem: $rootPath first: $first ) { results { items { // ✅ Correct structure item { id name path } } } totalCount } ``` --- ## ⚠️ Impact Assessment ### Tools Currently Broken 1. ❌ `sitecore_query` - Query execution (uses search) 2. ❌ `sitecore_search` - Search items (uses search) 3. ❌ `sitecore_command` - Natural language "search" commands ### Tools Still Working 1. ✅ `sitecore_get_item` - Get single item 2. ✅ `sitecore_get_children` - Get children (fixed v1.2.1) 3. ✅ `sitecore_get_field_value` - Get field value 4. ✅ `sitecore_get_template` - Get template info 5. ✅ `sitecore_scan_schema` - Schema scanning (if introspection works) ### User Impact - **Low**: Most common operations (get item, children, fields) still work - **Medium**: Search functionality is broken - **Workaround**: Use `get_children` recursively or manually --- ## 📝 Action Items ### Immediate (This Session) - [x] Document schema differences - [x] Create SCHEMA-REFERENCE.md with correct patterns - [x] Update copilot-instructions.md - [x] Remove all /edge references - [ ] Add error messages to broken search tools - [ ] Update documentation (README, etc.) ### Next Session - [ ] Rewrite `executeQuery()` with new search syntax - [ ] Rewrite `searchItems()` with new search syntax - [ ] Test all search scenarios - [ ] Update natural language parser for search commands - [ ] Full regression testing ### Future - [ ] Add advanced search filters (fieldsEqual, fieldsContain) - [ ] Add facet support - [ ] Add search result highlighting - [ ] Performance optimization --- ## 🎯 Workarounds for Users Until search is fixed: ### Instead of Search: ```typescript // ❌ Broken: /sitecore search articles // ✅ Use: /sitecore get children /sitecore/content // Then manually filter results ``` ### Instead of Query: ```typescript // ❌ Broken: /sitecore query /sitecore/content//*[@@templatename='Article'] // ✅ Use: /sitecore get children /sitecore/content // Then check template names manually ``` --- ## 📚 References - **SCHEMA-REFERENCE.md** - Complete schema documentation - **SCHEMA-FIX-CHILDREN.md** - Children fix (v1.2.1) - **test-schema-validation.ps1** - Schema validation tests - **graphql-schema-full.json** - Full schema JSON (217 MB) --- **Status**: Documentation complete, code fixes pending **Version**: 1.2.1 (search broken), next 1.3.0 (search fixed) **Priority**: HIGH - Search is core functionality