dial-your-context

コンテキストを調整する

Sanity Context MCP サーバーの Instructions フィールドに記載する内容をユーザーが作成できるよう支援します。目標は、簡潔な純粋な差分、つまり自動生成されたスキーマからエージェントが把握できない情報だけをまとめることです。

このスキルは、データセットソースの GROQ モードエンドポイント向けです。ナレッジベースモードのエンドポイントの場合、Context アプリで問題を解決し、ソースを修正すると、回答の質が向上します。詳しくは、ナレッジベースの問題を解決するをご覧ください。

作成するもの

Sanity Context MCP サーバーは、すでに以下の情報をエージェントに提供しています。

• すべてのドキュメントタイプとフィールドを圧縮したスキーマ
• 効率性と正確性に関するガイダンス
• groq_query ツールの説明に記載された GROQ クエリのチュートリアル
• GROQ クエリ、セマンティック検索などのツールの説明

作成する Instructions フィールドは、Context アプリにある MCP エンドポイントの Instructions フィールドです。初期コンテキストの先頭にある Context Instructions 見出しの下に表示され、効率性、正確性、ツール、スキーマの各セクションより前に置かれます。ここに含めるのは、スキーマからは明らかでない情報だけにしてください。

• 直感に反するフィールド名（例：body は実際にはスラッグ、hero は mediaAsset への参照です）
• スキーマ上でつながりが示されていない、二段階以上の参照チェーン（例：「Dolby Atmos に対応する製品を探すには、product → productFeature とたどり、機能の id フィールドで一致させます。スキーマには各段階が示されていますが、全体の経路は示されていません」）
• スキーマでは明らかにならないデータ品質の問題（例：「product 型には features 配列がありますが、常に空です。代わりに support-product を使用してください」）
• エージェントが常に適用する必要があるフィルター（ロケール、編集ステータスのフィールドなど）
• ユーザーが確認した既知のデータ欠落（例：「subtitle フィールドは使われていないため、無視してください」）
• スキーマからは明らかでない、よくある用途向けのクエリパターン
• 主な方法でうまくいかなかった場合の代替手段

スキーマがすでに明確に伝えている内容を重複させないでください。

前提条件

以下が必要です。

• MCP エンドポイントの URL：Context アプリのエンドポイントに表示される https://api.sanity.io/v1/context/organizations/:organizationId/mcp/:endpointName
• Context へのアクセス権を持つ組織 API トークン（このセッションでは Viewer 権限で十分です）

すべてのテストはエンドポイントの URL クエリパラメーターを使って行うため、セッション中に本番環境のエージェントに影響することはありません。

• ?instructions=<URL-encoded> は、そのリクエストに限り、エンドポイントの Instructions を置き換えます。空の ?instructions= を指定すると、何もない状態から始められます（?instructions="" は指定しないでください。Instructions として二重引用符が2文字送信されます）。
• ?groqFilter=<URL-encoded> は、エンドポイントに保存されているフィルターの範囲を狭めます。2つのフィルターは && で結合されます。保存されたフィルターで許可される範囲を広げることはできません。

結果の保存はユーザーが Context アプリで行います。エンドポイントの設定を変更することはありません。

ツールの呼び出し。 エンドポイントが MCP サーバーとして接続されていない場合は、HTTP 経由で呼び出してください。クエリパラメーターを URL に指定します。

curl -X POST "$SANITY_CONTEXT_MCP_URL?instructions=" \
  -H "Authorization: Bearer $SANITY_ORGANIZATION_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"groq_query","arguments":{"query":"*[0...3]._type"}}}'

初期コンテキスト（スキーマと Instructions）を読むには、GET $SANITY_CONTEXT_MCP_URL/initial-context を実行します（同じ認証ヘッダーと同じクエリパラメーターを使用します）。

重要なルール

1. 純粋な差分だけにしてください。 スキーマから明らかな場合は、Instructions に記載しないでください。
2. 少数のサンプルから一般化しないでください。 ドキュメントを3件クエリして「フィールド X は常に null」と結論づけるのが、最もよくある失敗です。記載する内容はすべて、含める前にユーザーに確認してください。
3. データを知っているのはユーザーです。 スキーマについて対話することは、データを探索することより重要です。スキーマを提示し、質問し、話を聞いてください。
4. すべての主張を根拠で検証してください。 Instructions の草案に記載する各行について、その根拠となるクエリと結果を示してください。ユーザーに確認してもらうか、修正してもらってください。
5. 簡潔かつ事実に忠実にしてください。 調査結果を Instructions にまとめる過程で、情報が失われたり歪められたりしがちです。独自の解釈は加えず、短い断定文を使ってください。

ワークフロー

ステップ 1：接続とクリーンな状態の確保

目標： MCP アクセスを確立し、安全な作業環境を整えます。

ユーザーから MCP エンドポイント URL と組織トークンを取得します（前提条件を参照）。

ドラフトエンドポイントが必要かどうかを判断します。 ?groqFilter= では絞り込みしかできないため、エンドポイントに保存されている GROQ フィルターをユーザーに尋ねます（Context アプリのエンドポイントに表示されています）。

• 保存済みフィルターがない場合、または保存済みフィルターをさらに絞り込むだけでよい場合： URL パラメーターを使って既存のエンドポイントで作業します。それ以外の設定は不要です。
• 保存済みフィルターを広げる必要がある場合： Context アプリで、同じデータセットソースを使い、tuning-draft のような名前を付け、GROQ フィルターを設定しないドラフトエンドポイントを作成するようユーザーに依頼します（New MCP endpoint）。作成には、組織とデータセットのプロジェクトの両方で Administrator または Developer のロールが必要です（プロジェクトのロールは、ステップ 7 でフィルターを変更する際に必要なものと同じです）。セッションはドラフトの URL を使って実行します。本番エンドポイントには手を加えません。

スキーマだけでは何がうまくいかないのかを既存の指示が覆い隠さないよう、ドラフトの指示をテストするまでは、すべての呼び出しで空の ?instructions= を使用します。

エンドポイントに指示がすでに設定されているか確認します（Context アプリからコピーするようユーザーに依頼するか、instructions パラメーターなしで /initial-context を取得し、Context Instructions セクションを確認します）。

• 指示がある場合は、既存の指示をそのままユーザーに提示します
• 「この中で残したいものはありますか。それとも、最初から始めますか？」と尋ねます
• ユーザーに判断を委ねます。既存の指示が誤っていると決めつけないでください
• 前回のセッションから既存の指示がある場合は、最初からやり直すのではなく、各調査結果を検証して改善します

*[0...3]._type のような簡単な GROQ クエリを実行し、データセットにクエリできることを確認します。

出力： MCP アクセスを確認し、安全な作業環境（URL パラメーターと、必要な場合はドラフトエンドポイント）を確立して、既存の指示があればユーザーに提示します。

Step 2: スキーマについての対話

目標： 単に探索するのではなく、会話を通じてデータセットを理解します。

スキーマを取得します（MCP が提供します）。ドキュメントの種類をわかりやすいリストにしてユーザーに提示します。

データセット内のドキュメントの種類は次のとおりです。

• article（14 フィールド）
• author（8 フィールド）
• category（5 フィールド）
• ...

このうち、エージェントが扱う必要があるのはどれですか？

これは会話であり、独り言ではありません。ユーザーに次のことを尋ねます。

1. どの種類が重要ですか？「エージェントがクエリする必要があるのはどれですか？エージェントが無視すべき内部／システム用の種類はありますか？」
2. 誤解を招くものはありますか？「名前から想像する意味とは異なるフィールドはありますか？未使用または非推奨のフィールドはありますか？」
3. どのような関連がありますか？「これらの種類はどのようにつながっていますか？たとえば、記事は著者を参照していますか？どのように参照しますか？直接参照、参照の配列、その他の方法ですか？」
4. 必須のフィルターはありますか？「エージェントは常にロケール、編集ステータスフィールド、その他の条件でフィルターする必要がありますか？」
5. 主なコンテンツの言語は何ですか？ i18n が関係する場合は、そのパターンを確認します。

フィルターを提案します。 エンドポイントの GROQ フィルターは、エージェントがアクセスできるドキュメントの範囲を指定します。これは効果が大きく、ノイズを大幅に減らし、エージェントが無関係な種類をクエリするのを防ぎます。また、これは厳格な境界でもあります。サーバー側で適用されるため、会話の内容によって範囲が広がることはありません。

フィルターは GROQ のフィルター式（*[...] の中身）であり、単なる種類のリストではありません。そのため、必要なドキュメントの集合を正確に絞り込めます。

• 単純な種類のフィルター：_type in ["product", "support-article", "productFeature"]
• ロケールのフィルター：_type in ["product", "article"] && lang == "en-us"
• 複雑なフィルター：_type in ["product", "article"] && lang == "en-us" && defined(title)

完全なクエリ（*[...]）、プロジェクション（{ name, price }）、並べ替え／スライスは記述しないでください。これらは拒否されるか、何も一致せず、接続が壊れているように見えます。エンドポイントはデフォルトで公開済みのパースペクティブを読み取るため、ドラフトをフィルターする必要はありません。

会話に基づいて、フィルターを提案します。

お話しいただいた内容に基づくと、次のフィルターをおすすめします。

_type in ["article", "author", "category", "tag"]

これにより、エージェントには siteSettings、redirect、migration などが表示されません。これでよさそうですか？

フィルターをすぐに適用します。 ユーザーが同意したら、以降のすべての MCP 呼び出しに ?groqFilter=<URL-encoded expression> を追加します。

ここから先のすべての探索には、合意したフィルターを使用します。

出力： 重要な種類、既知の特記事項、関連、および有効なフィルターについての共通認識を得ます。本番環境のエージェントに表示されない種類を探索しても意味がありません。

Step 3: 想定される質問

目標： 本番環境のエージェントに実際に尋ねられる質問の具体例を集めます。

このコンテキストを使うエージェントに、どのような質問が寄せられるかをユーザーに尋ねます。

このコンテキストを使うエージェントには、どんな質問が寄せられますか？5～20 個の例を挙げてください。現実的な例ほど役立ちます。

例：

• 「Dolby Atmos に対応しているスピーカーはどれですか？」
• 「WiFi の接続問題を解決するにはどうすればよいですか？」
• 「再生品の返品ポリシーを教えてください。」
• 「製品 X と製品 Y の機能を比較してください。」

これらの質問をもとに、Step 4 で探索します。実際に重要となるクエリのパターンを把握できます。

シンプルなデータセットなら、質問は 5 つで十分です。複雑なデータセットの場合は、15～20 個を目指してもらいます。

出力： 想定される質問の番号付きリスト。

ステップ 4：調査と検証

目標： MCP を使って、想定される各質問に回答し、機能することと機能しないことを記録します。

ステップ 4～6 は順番に進めるのではなく、反復して進めます。 作業を進めながら、ユーザーと調査結果を検証してください。15 個の質問を調べてからすべてを下書きし、主張の半分が成り立たないと後で気づくような進め方は避けてください。

想定される質問に 1 つずつ（または関連するグループごとに）取り組みます。質問ごとに、次のことを行います。

1. 回答するための GROQ クエリを書く
2. MCP 経由でクエリを実行する
3. 結果を記録する — 期待どおりに機能しましたか？データは想定した内容でしたか？
4. 継続的に更新するリストに調査結果を記録する：
   • ✅ 期待どおりに機能した（指示は不要）
   • ⚠️ 機能したが、分かりにくいパターンが必要だった（指示が必要）
   • ❌ 失敗した、または予想外の結果が返された（調査し、ユーザーに確認）

重要：推測しないでください。 クエリの結果が空、または予想外のデータだった場合：

• 少数のサンプルだけを根拠に「このフィールドは常に空」と結論づけないでください
• 代わりに、すぐにユーザーに尋ねてください。null フィールドに関する調査結果をまとめて尋ねず、「X をクエリすると Y が返されます。これは想定どおりですか？データは実際に存在しますか？」と確認してください
• ユーザーが事実を確認するか、食い違いについて説明します

調査結果は次のようなシンプルな表に記録します。

#	質問	クエリ	結果	調査結果
1	「最近の記事」	*[_type == "article"] | order(publishedAt desc)[0..4]	✅ 5 件の結果	スキーマだけで機能する
2	「著者別の記事」	*[_type == "article" && references(authorId)]	⚠️ 空	著者は直接の参照ではなく、contributors[].person でリンクされている
3	「ガイドのみ」	*[_type == "article" && category == "guide"]	❌ 空	ユーザー確認：ガイドは articleType == "howto"

規模に応じて調整します。

• シンプルなデータセット（3～5 種類、質問 5 件）：このステップには 10 分ほどかかる場合があります
• 複雑なデータセット（50 種類、質問 20 件）：関連する質問をまとめて体系的に調査しますが、それでも調査結果は 1 つずつ検証してください

出力： 想定される各質問について、検証済みの結果をまとめた調査結果表。

ステップ 5：指示を作成する

目標： 調査結果を、簡潔で事実に基づいた Instructions の内容にまとめます。

ステップ 4 の調査結果表を確認します。分かりにくいパターンが必要だった項目、または明白な方法では失敗した項目、つまり ⚠️ または ❌ の項目だけを含めてください。

Instructions は、カテゴリごとに整理した短い宣言文として記述します。

### Rules

- Guides are `article` documents with `articleType == "howto"` — there is no `guide` category
- Always include `[_lang == "en"]` for localized content unless user specifies otherwise

### Schema notes

- `contributors` on `article` is an array of objects with a `person` reference to `author` — not a direct author reference
- `hero` on `article` is a reference to `mediaAsset`, not an image field
- `body` on `page` is a Portable Text array, not a string — use `pt::text(body)` for plain text search

### Query patterns

- Articles by author: `*[_type == "article" && contributors[].person._ref == $authorId]`
- Recent guides: `*[_type == "article" && articleType == "howto"] | order(publishedAt desc)`

### Known limitations

- `subtitle` field on `article` is unused — ignore it
- `relatedArticles` is manually curated and often empty for older content

簡潔にまとめてください。 各行について、次のテストを行います。「スキーマだけを与えられたエージェントなら、この点を間違えるだろうか？」判断がつかない場合はテストしてください。空の ?instructions= を使って 2～3 件の質問に回答させ、モデルが自力で何を間違えるかを確認します。それを、実際にここに記載する必要がある内容の実証的な基準とします。必要がなければ削除してください。

含めないでください：

• 一般的な GROQ の構文（チュートリアルで説明します）
• フィールド一覧や型の説明（スキーマで説明します）
• 応答の書式設定に関する指針（これはシステムプロンプトに含めます。shape-your-agent スキルを参照してください）
• エージェントが自力で把握できる内容

出力： データセットの複雑さに応じて、通常 10～40 行の Instructions の下書き。

ステップ 6：主張を検証する

目標： ドラフトのすべての記述が証拠に裏付けられていることを確認します。

ドラフトの Instructions を行ごとに確認します。各主張について、次の内容をユーザーに提示してください。

1. 主張： 例：「article の contributors は、人物への参照を含むオブジェクトの配列です」
2. 証拠： それを実証する GROQ クエリと結果
3. 確認を求める： 「これは正確ですか？追加や修正はありますか？」

例：

主張： 「Guide は article ドキュメントで、articleType == "howto" です。guide カテゴリはありません」

証拠： *[_type == "article" && category == "guide"][0...3] → 結果は 0 件。array::unique(*[_type == "article"].articleType) → ["howto", "news", "opinion"]。

これは正しいですか？

ユーザーが主張を訂正した場合は、直ちにドラフトを更新します。

ユーザーが新しい情報（「そういえば、これも知っておいてください……」など）を追加した場合は、ドラフトに加えて同じ方法で検証します。

出力： すべての主張がユーザーによって確認された、検証済みの Instructions ブロック。

ステップ 7：デプロイする

目標： Instructions とフィルターを安全に本番環境へ反映します。

最後にもう一度確認してもらうため、最終版の Instructions とフィルターをユーザーに提示します。

最終設定はこちらです：

フィルター（GROQ 式）：

_type in ["article", "author", "category", "tag"]

Instructions： ［最終版の Instructions ブロック］

デプロイしてよいですか？

ユーザーが Context アプリで設定を保存できるよう、貼り付ける内容をそのまま提示してください。

1. Sanity Dashboard で Context アプリを開き、production エンドポイントを選択します
2. Instructions フィールド：［最終版の Instructions ブロック］
3. GROQ filter フィールド：［最終版の GROQ 式］。新しい値は保存済みの値を置き換えます。すでにフィルターが設定されたエンドポイントで ?groqFilter= を使って調整した場合、テストされたフィルターは (<saved filter>) && (<your filter>) です。そのため、この結合済みの式を貼り付けてください。以前のフィルターを削除したい場合は、テストした範囲を超えて対象が広がります。保存する前にドラフトエンドポイントで再テストしてください（ステップ 1）
4. 保存します。変更は次回の接続時に反映され、エージェントの再デプロイは不要です。エージェントが /initial-context をキャッシュしている場合、Instructions の変更はキャッシュが更新された時点で反映されます

GROQ フィルターの変更には、接続されている各データセットのプロジェクトで Administrator または Developer のロールも必要です。保存時に 403 が発生した場合は、そのロールを持つユーザーが変更する必要があります。

エージェントの接続先をドラフトではなく本番エンドポイントにします。エンドポイント名は URL の一部であり、変更できないため、エンドポイントを切り替えるにはエージェントの設定を変更する必要があります。

保存後の確認： instructions パラメーターも groqFilter パラメーターも付けずに、本番エンドポイントから /initial-context を取得し、Context Instructions セクションが一致することを確認します。想定される質問のうち 1 つを実行し、フィルターが有効であることを確認します。tuning-draft エンドポイントを作成した場合は、Context アプリで削除できることをユーザーに伝えます。

出力： Instructions とフィルターが本番環境に反映され、正常に動作することを確認済み。

適応ガイドライン

データセットに合わせてワークフローの規模を調整します。小さく明確なスキーマなら、Instructions は 5 行、あるいは不要な場合もあります。それで問題ありません。大規模なスキーマ（50 種類以上）では、ステップ 2 でタイプをドメイン別にグループ化し、ステップ 3 で想定される質問を 15～20 件用意します。また、そのようなスキーマではフィルターが特に役立ちます。

セッション状態の追跡

セッション全体を通じて、次の項目の進捗状況を把握してください。

- [ ] MCP access verified
- [ ] Working environment set up (URL params, plus a draft endpoint if needed)
- [ ] Existing instructions reviewed (if any)
- [ ] Schema discussed with user
- [ ] Filter agreed and applied
- [ ] Expected questions collected
- [ ] Questions explored and findings tracked
- [ ] Draft instructions written
- [ ] Each claim verified with evidence
- [ ] Instructions and filter saved in the Context app
- [ ] Production deployment verified

このチェックリストで進捗を追跡します。プロセスのどこまで進んでいるかユーザーにわかるよう、定期的に共有してください。