@sanity/context 0.0.3 → 0.0.5

package/scripts/uninstall-skill.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Preuninstall script for @sanity/context
+ * Removes skill files from consuming project's AI assistant skill directories
+ *
+ * Fails silently to never break npm uninstall
+ */
+
+import {existsSync, readdirSync, rmSync} from 'node:fs'
+import {dirname, join, resolve} from 'node:path'
+import {fileURLToPath} from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const SKILL_FOLDER_NAME = 'sanity-context-mcp'
+
+const SKILL_DIRS = ['.claude/skills', '.cursor/skills', '.windsurf/skills']
+
+/**
+ * Find the consuming project's root directory
+ */
+function findProjectRoot() {
+  let current = resolve(__dirname, '..')
+
+  while (current !== dirname(current)) {
+    current = dirname(current)
+
+    if (current.includes('node_modules')) {
+      continue
+    }
+
+    if (existsSync(join(current, 'package.json'))) {
+      return current
+    }
+  }
+
+  return null
+}
+
+/**
+ * Check if we're running in development mode (not as a dependency)
+ */
+function isDevMode() {
+  if (!__dirname.includes('node_modules')) {
+    return true
+  }
+
+  const initCwd = process.env.INIT_CWD
+  const packageDir = resolve(__dirname, '..')
+
+  if (initCwd && resolve(initCwd) === packageDir) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Remove directory if empty
+ */
+function removeIfEmpty(dirPath) {
+  try {
+    if (existsSync(dirPath)) {
+      const contents = readdirSync(dirPath)
+      if (contents.length === 0) {
+        rmSync(dirPath, {recursive: true})
+      }
+    }
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Main uninstall logic
+ */
+function main() {
+  try {
+    if (isDevMode()) {
+      return
+    }
+
+    const projectRoot = findProjectRoot()
+    if (!projectRoot) {
+      return
+    }
+
+    for (const skillDir of SKILL_DIRS) {
+      const targetDir = join(projectRoot, skillDir, SKILL_FOLDER_NAME)
+
+      try {
+        if (existsSync(targetDir)) {
+          // Remove the entire skill folder
+          rmSync(targetDir, {recursive: true, force: true})
+
+          // Clean up empty parent directories
+          const parentDir = join(projectRoot, skillDir)
+          removeIfEmpty(parentDir)
+
+          const grandparentDir = dirname(parentDir)
+          removeIfEmpty(grandparentDir)
+        }
+      } catch {
+        continue
+      }
+    }
+  } catch {
+    // Fail silently - never break npm uninstall
+  }
+}
+
+main()

package/skills/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: sanity-context-mcp
+description: Install and configure the Sanity Context MCP plugin in a Sanity Studio and create AgentContext documents.
+---
+
+# Sanity Context MCP Setup
+
+Help developers install the Context MCP plugin and configure it in their Sanity Studio.
+
+## What is Context MCP?
+
+An MCP server that gives AI agents structured access to Sanity content. Preserves schema structure instead of flattening to embeddings — agents can filter by real field values, follow references, and combine structural queries with semantic search.
+
+## Setup tasks
+
+### 1. Install the Studio plugin
+
+Install `@sanity/context` and add it to your Sanity Studio configuration:
+
+```ts
+// sanity.config.ts
+import {contextPlugin} from '@sanity/context/studio'
+
+export default defineConfig({
+  // ...
+  plugins: [contextPlugin()],
+})
+```
+
+This adds the `sanity.agentContext` document type to the Studio.
+
+### 2. Create an AgentContext document
+
+Create a `sanity.agentContext` document in the Studio with:
+
+- A `name` for display
+- A `slug` (auto-generated from name) that identifies the context
+- A `groqFilter` to scope what content the agent can access
+
+The slug becomes the MCP URL: `https://context-mcp.sanity.io/mcp/:projectId/:dataset/:slug`
+
+## Available MCP tools
+
+| Tool              | Purpose                                                |
+| ----------------- | ------------------------------------------------------ |
+| `initial_context` | Get compressed schema overview (types, fields, counts) |
+| `groq_query`      | Execute GROQ queries with optional semantic search     |
+| `schema_explorer` | Get detailed schema for a specific type                |
+
+## GROQ with semantic search
+
+Context MCP supports `text::embedding()` for semantic ranking inside `score()`:
+
+- **Basic filtering** — Standard GROQ filters on type, fields, references
+- **Semantic ranking** — Use `score(text::embedding("search terms"))` to rank by meaning
+- **Hybrid search** — Combine structural filters with `score(text::embedding(...))` for hybrid queries
+
+Always use `order(_score desc)` when using `score()` to get best matches first.
+
+Example hybrid query:
+
+```groq
+*[_type == "product" && category == "sweaters" && price < 100]
+  | score(text::embedding("cozy warm comfortable"))
+  | order(_score desc)
+  { _id, title, price }[0...10]
+```
+
+## Guidelines
+
+- Create AgentContext documents before connecting
+- Start with `initial_context` to understand available content types
+- Combine structural filters with semantic search for best results

package/src/studio/context-plugin/{AgentDocumentInput.tsx → AgentContextDocumentInput.tsx}

@@ -2,14 +2,14 @@ import {CopyIcon} from '@sanity/icons'
 import {Box, Button, Card, Flex, Stack, Text, useToast} from '@sanity/ui'
 import {getValueAtPath, type InputProps, useDataset, useProjectId} from 'sanity'
 
-export function AgentDocumentInput(props: InputProps) {
+export function AgentContextDocumentInput(props: InputProps) {
   const dataset = useDataset()
   const projectId = useProjectId()
   const toast = useToast()
 
   const slug = getValueAtPath(props.value, ['slug'])
   const currentSlug = slug && typeof slug === 'object' && 'current' in slug ? slug.current : ''
-  const MCP_URL = `https://context-mcp.sanity.io/${projectId}/${dataset}/${currentSlug}`
+  const MCP_URL = `https://context-mcp.sanity.io/mcp/${projectId}/${dataset}/${currentSlug}`
 
   const handleCopy = () => {
     try {

package/src/studio/context-plugin/agentContextSchema.ts

@@ -1,8 +1,12 @@
 import {DatabaseIcon} from '@sanity/icons'
 import {defineField, defineType} from 'sanity'
 
+import {AgentContextDocumentInput} from './AgentContextDocumentInput'
+import {GroqFilterInput} from './groq-filter-input/GroqFilterInput'
+
 /**
  * The name of the agent context schema type.
+ * @beta
  */
 export const AGENT_CONTEXT_SCHEMA_TYPE_NAME = 'sanity.agentContext'
 
@@ -20,11 +24,15 @@ export const agentContextSchema = defineType({
   title: AGENT_CONTEXT_SCHEMA_TITLE,
   type: 'document',
   icon: DatabaseIcon,
+  components: {
+    input: AgentContextDocumentInput,
+  },
   fields: [
     defineField({
       name: 'name',
       title: 'Name',
       type: 'string',
+      placeholder: 'My Agent Context',
     }),
     defineField({
       name: 'slug',
@@ -34,25 +42,15 @@ export const agentContextSchema = defineType({
         source: 'name',
       },
     }),
-    defineField({
-      name: 'organizationId',
-      title: 'Organization ID',
-      type: 'string',
-    }),
-    defineField({
-      name: 'projectId',
-      title: 'Project ID',
-      type: 'string',
-    }),
-    defineField({
-      name: 'dataset',
-      title: 'Dataset',
-      type: 'string',
-    }),
     defineField({
       name: 'groqFilter',
-      title: 'GROQ filter',
-      type: 'text',
+      title: 'Content filter',
+      description:
+        'Define which content AI agents can access. Pick types which will generate the filter, or manually enter the filter in the GROQ tab.',
+      type: 'string',
+      components: {
+        input: GroqFilterInput,
+      },
     }),
   ],
 })

package/src/studio/context-plugin/groq-filter-input/GroqFilterInput.tsx

@@ -0,0 +1,369 @@
+import {
+  CheckmarkIcon,
+  ChevronDownIcon,
+  CloseIcon,
+  ErrorOutlineIcon,
+  GroqIcon,
+  ListIcon,
+} from '@sanity/icons'
+import {
+  Box,
+  Button,
+  Card,
+  Flex,
+  Popover,
+  Stack,
+  Tab,
+  TabList,
+  TabPanel,
+  Text,
+  TextArea,
+  TextInput,
+  Tooltip,
+  useClickOutsideEvent,
+} from '@sanity/ui'
+import {useCallback, useMemo, useRef, useState} from 'react'
+import {
+  CommandList,
+  SanityDefaultPreview,
+  set,
+  type StringInputProps,
+  unset,
+  useSchema,
+} from 'sanity'
+
+import {isSimpleTypeQuery, listToQuery, queryToList, validateGroq} from './groqUtils'
+import {useComposedRefs} from './useComposedRefs'
+
+const TAB_IDS = {
+  TYPES_TAB: 'types-tab',
+  TYPES_PANEL: 'types-panel',
+  GROQ_TAB: 'groq-tab',
+  GROQ_PANEL: 'groq-panel',
+} as const
+
+const ITEM_HEIGHT = 43
+
+export function GroqFilterInput(props: StringInputProps) {
+  const {value, onChange, elementProps} = props
+  const {ref: refProp, ...restElementProps} = elementProps || {}
+
+  const [open, setOpen] = useState<boolean>(false)
+  const [inputElement, setInputElement] = useState<HTMLInputElement | null>(null)
+  const inputRef = useRef<HTMLInputElement>(null)
+  const popoverRef = useRef<HTMLDivElement>(null)
+  const openListButtonRef = useRef<HTMLButtonElement>(null)
+  const [searchQuery, setSearchQuery] = useState<string | null>(null)
+
+  const schema = useSchema()
+
+  // Compose the input ref with the ref prop
+  const setInputRef = useCallback(
+    (node: HTMLInputElement | null) => {
+      inputRef.current = node
+      setInputElement(node)
+    },
+    [inputRef],
+  )
+  const composedRef = useComposedRefs(setInputRef, refProp)
+
+  // Check if the current query is simple enough to edit via Types UI
+  const isSimple = useMemo(() => isSimpleTypeQuery(value), [value])
+
+  // Validate GROQ syntax
+  const validation = useMemo(() => validateGroq(value), [value])
+
+  // Initialize view based on whether the current query is simple or complex
+  const [panel, setPanel] = useState<'types' | 'groq'>(() =>
+    isSimpleTypeQuery(value) ? 'types' : 'groq',
+  )
+
+  const selectedTypes = useMemo(() => {
+    if (!value) return []
+    return queryToList(value)
+  }, [value])
+
+  // Filter the type names based on the search query
+  const filteredTypeNames = useMemo(() => {
+    const types = schema._original?.types || []
+    const typeNames = types.map((type) => type.name).filter((name) => !name.startsWith('sanity.'))
+    if (!searchQuery) return typeNames
+
+    return typeNames.filter((name) => name.toLowerCase().includes(searchQuery.toLowerCase()))
+  }, [searchQuery, schema._original?.types])
+
+  // Handle document type item click.
+  // 1. If the item is already selected, remove it from the selected types.
+  // 2. If the item is not selected, add it to the selected types.
+  // 3. Transform the updated selected types into a GROQ query and set it as the new value.
+  const handleDocumentTypeItemClick = (item: string) => {
+    const nextValue = selectedTypes.includes(item)
+      ? selectedTypes.filter((t) => t !== item)
+      : [...selectedTypes, item]
+
+    onChange(nextValue.length > 0 ? set(listToQuery(nextValue)) : unset())
+  }
+
+  const closeList = useCallback(() => {
+    setOpen(false)
+    setSearchQuery(null)
+  }, [])
+
+  const handleToggleList = useCallback(() => {
+    if (open) {
+      closeList()
+    } else {
+      setOpen(true)
+      inputRef.current?.focus()
+    }
+  }, [open, closeList])
+
+  const handleTextInputKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === 'Escape') {
+        closeList()
+      }
+    },
+    [closeList],
+  )
+
+  const getItemSelected = useCallback(
+    (index: number) => {
+      const item = filteredTypeNames[index]
+      return item ? selectedTypes.includes(item) : false
+    },
+    [filteredTypeNames, selectedTypes],
+  )
+
+  useClickOutsideEvent(
+    () => {
+      closeList()
+    },
+    () => [popoverRef.current, inputRef.current, openListButtonRef.current],
+  )
+
+  const isListOpen = open || searchQuery !== null
+
+  // If query is complex or invalid, force GROQ panel regardless of selection
+  const effectivePanel = !isSimple || !validation.valid ? 'groq' : panel
+
+  return (
+    <Stack space={2}>
+      <TabList space={1}>
+        <Tooltip
+          animate
+          disabled={isSimple && validation.valid}
+          content={
+            <Box padding={1} style={{maxWidth: '200px'}}>
+              <Text size={1}>
+                {!validation.valid
+                  ? 'The current filter has a syntax error that needs to be fixed in the GROQ tab.'
+                  : 'The current filter is too complex to edit here. Use the GROQ tab to edit it.'}
+              </Text>
+            </Box>
+          }
+          delay={{open: 200, close: 0}}
+          placement="bottom"
+          portal
+        >
+          <div>
+            <Tab
+              aria-controls={TAB_IDS.TYPES_PANEL}
+              disabled={!isSimple || !validation.valid}
+              icon={ListIcon}
+              id={TAB_IDS.TYPES_TAB}
+              label="Types"
+              onClick={() => isSimple && validation.valid && setPanel('types')}
+              padding={3}
+              selected={effectivePanel === 'types'}
+            />
+          </div>
+        </Tooltip>
+
+        <Tab
+          aria-controls={TAB_IDS.GROQ_PANEL}
+          icon={GroqIcon}
+          id={TAB_IDS.GROQ_TAB}
+          label="GROQ"
+          onClick={() => setPanel('groq')}
+          padding={3}
+          selected={effectivePanel === 'groq'}
+        />
+      </TabList>
+
+      {/* ----- Types panel ----- */}
+      <TabPanel
+        aria-labelledby={TAB_IDS.TYPES_TAB}
+        hidden={effectivePanel !== 'types'}
+        id={TAB_IDS.TYPES_PANEL}
+        tabIndex={-1}
+      >
+        <Stack space={3}>
+          <Popover
+            animate
+            constrainSize
+            fallbackPlacements={['bottom', 'top']}
+            matchReferenceWidth
+            open={isListOpen}
+            placement="bottom"
+            portal
+            ref={popoverRef}
+            content={
+              <Flex direction="column" height="fill">
+                {filteredTypeNames.length === 0 && (
+                  <Flex direction="column" overflow="hidden" flex={1} padding={5}>
+                    <Text align="center" size={1}>
+                      No document types found matching <b>{`"${searchQuery}"`}</b>
+                    </Text>
+                  </Flex>
+                )}
+
+                {filteredTypeNames.length > 0 && (
+                  <Flex direction="column" overflow="hidden" flex={1}>
+                    <CommandList
+                      activeItemDataAttr="data-hovered"
+                      ariaLabel="Document Types"
+                      ariaMultiselectable
+                      fixedHeight
+                      getItemKey={(item) => item}
+                      getItemSelected={getItemSelected}
+                      inputElement={inputElement}
+                      itemHeight={ITEM_HEIGHT}
+                      padding={1}
+                      items={filteredTypeNames}
+                      renderItem={(documentTypeName) => {
+                        const isSelected = selectedTypes.includes(documentTypeName)
+                        const schemaType = schema.get(documentTypeName)
+
+                        return (
+                          <Stack key={documentTypeName} padding={1}>
+                            <Button
+                              aria-label={`${isSelected ? 'Remove' : 'Add'} ${documentTypeName} to filter`}
+                              aria-selected={isSelected}
+                              mode="bleed"
+                              onClick={() => handleDocumentTypeItemClick(documentTypeName)}
+                              padding={0}
+                            >
+                              <Flex align="center" gap={2}>
+                                <Box flex={1}>
+                                  <SanityDefaultPreview
+                                    layout="compact"
+                                    title={schemaType?.title || documentTypeName}
+                                    schemaType={schemaType}
+                                    icon={schemaType?.icon}
+                                  />
+                                </Box>
+
+                                {isSelected && (
+                                  <Box paddingX={3}>
+                                    <Text size={1}>
+                                      <CheckmarkIcon />
+                                    </Text>
+                                  </Box>
+                                )}
+                              </Flex>
+                            </Button>
+                          </Stack>
+                        )
+                      }}
+                    />
+                  </Flex>
+                )}
+              </Flex>
+            }
+          >
+            <Card display="flex" border radius={2} overflow="hidden">
+              <Card flex={1} borderRight>
+                <TextInput
+                  {...restElementProps}
+                  autoComplete="off"
+                  border={false}
+                  onChange={(event) => setSearchQuery(event.currentTarget.value)}
+                  onKeyDown={handleTextInputKeyDown}
+                  placeholder="Search for document types"
+                  radius={0}
+                  ref={composedRef}
+                  value={searchQuery || ''}
+                />
+              </Card>
+
+              <Flex align="center" justify="center" sizing="border" padding={1} height="fill">
+                <Button
+                  aria-label="Open document types list"
+                  disabled={isListOpen}
+                  icon={ChevronDownIcon}
+                  mode="bleed"
+                  onClick={handleToggleList}
+                  padding={2}
+                  ref={openListButtonRef}
+                />
+              </Flex>
+            </Card>
+          </Popover>
+
+          <Flex wrap="wrap" gap={2}>
+            {selectedTypes.map((type) => {
+              const title = schema.get(type)?.title || type
+
+              return (
+                <Card key={type} padding={1} radius={3} border tone="transparent" paddingLeft={2}>
+                  <Flex align="center" gap={1} overflow="hidden">
+                    <Box flex={1}>
+                      <Text size={1} weight="medium" textOverflow="ellipsis">
+                        {title}
+                      </Text>
+                    </Box>
+
+                    <Button
+                      aria-label="Remove {type} from filter"
+                      fontSize={0}
+                      icon={CloseIcon}
+                      mode="bleed"
+                      onClick={() => handleDocumentTypeItemClick(type)}
+                      padding={2}
+                    />
+                  </Flex>
+                </Card>
+              )
+            })}
+          </Flex>
+        </Stack>
+      </TabPanel>
+
+      {/* ----- GROQ panel ----- */}
+      <TabPanel
+        aria-labelledby={TAB_IDS.GROQ_TAB}
+        hidden={effectivePanel !== 'groq'}
+        id={TAB_IDS.GROQ_PANEL}
+        tabIndex={-1}
+      >
+        <Stack space={3}>
+          <TextArea
+            {...restElementProps}
+            onChange={(event) =>
+              onChange(event.currentTarget.value ? set(event.currentTarget.value) : unset())
+            }
+            placeholder='_type in ["author", "post"]'
+            value={value || ''}
+            style={{fontFamily: 'monospace'}}
+            padding={4}
+          />
+        </Stack>
+      </TabPanel>
+
+      {/* ----- Result and validation errors ----- */}
+
+      {!validation.valid && (
+        <Card padding={3} radius={2} tone="critical" border>
+          <Flex align="flex-start" gap={2}>
+            <Text size={1}>
+              <ErrorOutlineIcon />
+            </Text>
+
+            <Text size={1}>{validation.error}</Text>
+          </Flex>
+        </Card>
+      )}
+    </Stack>
+  )
+}

package/src/studio/context-plugin/groq-filter-input/groqUtils.test.ts

@@ -0,0 +1,69 @@
+import {describe, expect, it} from 'vitest'
+
+import {isSimpleTypeQuery, listToQuery, queryToList, validateGroq} from './groqUtils'
+
+describe('groqUtils', () => {
+  describe('listToQuery', () => {
+    it('should convert a list of types to a GROQ query', () => {
+      expect(listToQuery(['author'])).toBe('_type in ["author"]')
+      expect(listToQuery(['author', 'book'])).toBe('_type in ["author", "book"]')
+    })
+
+    it('should return empty brackets for empty list', () => {
+      expect(listToQuery([])).toBe('_type in []')
+    })
+  })
+
+  describe('queryToList', () => {
+    it('should parse types from a GROQ query', () => {
+      expect(queryToList('_type in ["author"]')).toEqual(['author'])
+      expect(queryToList('_type in ["author", "book"]')).toEqual(['author', 'book'])
+    })
+
+    it('should handle queries with extra whitespace', () => {
+      expect(queryToList('_type  in  ["author" , "book"]')).toEqual(['author', 'book'])
+    })
+
+    it('should return empty array for non-matching queries', () => {
+      expect(queryToList('_type == "author"')).toEqual([])
+      expect(queryToList('')).toEqual([])
+    })
+  })
+
+  describe('isSimpleTypeQuery', () => {
+    it('should return true for simple _type in [...] queries', () => {
+      expect(isSimpleTypeQuery('_type in ["author"]')).toBe(true)
+      expect(isSimpleTypeQuery('_type in ["author", "book"]')).toBe(true)
+      expect(isSimpleTypeQuery('_type in []')).toBe(true)
+    })
+
+    it('should return true for undefined/empty queries', () => {
+      expect(isSimpleTypeQuery(undefined)).toBe(true)
+      expect(isSimpleTypeQuery('')).toBe(true)
+    })
+
+    it('should return false for complex queries', () => {
+      expect(isSimpleTypeQuery('_type in ["author"] && published')).toBe(false)
+      expect(isSimpleTypeQuery('_type == "author"')).toBe(false)
+      expect(isSimpleTypeQuery('*[_type in ["author"]]')).toBe(false)
+    })
+  })
+
+  describe('validateGroq', () => {
+    it('should return valid for correct GROQ syntax', () => {
+      expect(validateGroq('_type in ["author"]')).toEqual({valid: true})
+      expect(validateGroq('_type == "author" && published')).toEqual({valid: true})
+    })
+
+    it('should return valid for undefined/empty queries', () => {
+      expect(validateGroq(undefined)).toEqual({valid: true})
+      expect(validateGroq('')).toEqual({valid: true})
+    })
+
+    it('should return invalid with error for bad GROQ syntax', () => {
+      const result = validateGroq('_type in ["author"')
+      expect(result.valid).toBe(false)
+      expect(result.error).toBeDefined()
+    })
+  })
+})