@ingenx-io/valets-schema-mcp-server 0.2.3 → 0.2.4

package/README.md

@@ -45,6 +45,32 @@ claude mcp add valets-schema -- npx -y @ingenx-io/valets-schema-mcp-server
 | `list_decisions` | All data model decisions (D00–D37+) with status and summary |
 | `get_decision` | Full details for a specific decision by ID (e.g. `D12`) |
 | `get_openapi` | OpenAPI 3.1 spec — full or filtered to a single component (e.g. `Order`, `OrderCreate`) |
+| `get_guidance` | Use-case recipes: tool call sequences, field constraint cheatsheets, and workaround notes. Call with no args for the index, or pass a `slug` for the full recipe. |
+
+## Cookbook
+
+`get_guidance` exposes a set of use-case recipes — each one describes the right sequence of MCP tool calls for a specific task.
+
+### Available recipes
+
+| Slug | When to use |
+|------|-------------|
+| `write-model-code` | You need to read or write a Firestore document and want to know which fields are server-set, immutable, or deprecated. |
+| `field-history` | You found a field and want to understand why it exists, what decision drove it, and whether it's been migrated. |
+| `whatsapp-conversation-display` | You need to render a per-order WhatsApp message thread. Uses `NotificationRecord` as a workaround (outbound only). |
+
+### Example usage
+
+```
+# Get the index
+get_guidance()
+
+# Get a specific recipe
+get_guidance(slug="write-model-code")
+get_guidance(slug="whatsapp-conversation-display")
+```
+
+Each recipe returns JSON with ordered `steps` (tool + args + note), tips, and any relevant caveats or cheatsheets.
 
 ## Resources
 

package/data/static/cookbook.json

@@ -0,0 +1,150 @@
+{
+  "version": "1",
+  "recipes": [
+    {
+      "slug": "write-model-code",
+      "title": "Writing code that touches a model",
+      "summary": "How to look up a model's schema, identify field constraints, and avoid writing to server-set or immutable fields.",
+      "steps": [
+        {
+          "step": 1,
+          "tool": "schema_overview",
+          "args": {},
+          "note": "Start here to see all available models and enums. Identify the model(s) your code will read or write."
+        },
+        {
+          "step": 2,
+          "tool": "get_schema",
+          "args": { "name": "<model-name>" },
+          "note": "Fetch the full JSON Schema for the model. Inspect each field for constraint extensions: readOnly, x-immutable, deprecated, x-note, x-when."
+        },
+        {
+          "step": 3,
+          "tool": "get_openapi",
+          "args": { "component": "<ModelCreate>" },
+          "note": "Use the Create variant (PascalCase + 'Create', e.g. 'OrderCreate') to determine the correct write shape. readOnly and deprecated fields are excluded from required[] here."
+        },
+        {
+          "step": 4,
+          "tool": "get_openapi",
+          "args": { "component": "<ModelUpdate>" },
+          "note": "For PATCH operations use the Update variant. All fields become optional and readOnly / x-immutable fields are excluded entirely."
+        },
+        {
+          "step": 5,
+          "tool": "get_doc",
+          "args": { "slug": "models/<model-name>" },
+          "note": "Read the human-readable doc page for callout blocks: server-set warnings, immutable notices, deprecation alerts, and implementation tips."
+        }
+      ],
+      "field_constraint_cheatsheet": {
+        "readOnly: true": "Set by Firestore trigger or Admin SDK only — never write from client or backend application code.",
+        "x-immutable: true": "Set exactly once at document creation. Any subsequent write to this field is a bug.",
+        "deprecated: true": "Do not write in new code. Check x-replaced-by for the replacement field.",
+        "x-internal: true": "Backend-only collection — consumers must not depend on this model's shape."
+      },
+      "tips": [
+        "Field descriptions often contain '(GH#N)' or '(D-id)' references — use get_decision to trace rationale.",
+        "If a field is absent from ModelCreate, it is either readOnly (server-sets it) or deprecated.",
+        "Run get_schema on related enums (e.g. 'payment-status') to understand the allowed values for enum fields."
+      ]
+    },
+    {
+      "slug": "field-history",
+      "title": "Understanding a field's history or rationale",
+      "summary": "How to trace why a field exists, what decision or issue drove it, and whether it has been migrated or superseded.",
+      "steps": [
+        {
+          "step": 1,
+          "tool": "search_docs",
+          "args": { "query": "<fieldName>" },
+          "note": "Find every doc page that mentions the field. This surfaces the model page, any decision pages, and migration docs."
+        },
+        {
+          "step": 2,
+          "tool": "get_schema",
+          "args": { "name": "<model-name>" },
+          "note": "Read the field's 'description' value directly. It typically includes a GH# issue reference or a D-id decision reference."
+        },
+        {
+          "step": 3,
+          "tool": "list_decisions",
+          "args": {},
+          "note": "Scan all decisions for ones related to the model or field. Look at 'status': accepted decisions are live; superseded ones have been replaced."
+        },
+        {
+          "step": 4,
+          "tool": "get_decision",
+          "args": { "id": "<D-id>" },
+          "note": "Get full context: rationale, migration path, affected models, and implementation status."
+        },
+        {
+          "step": 5,
+          "tool": "get_doc",
+          "args": { "slug": "decisions/migrations" },
+          "note": "Check the migrations page for a changelog of field-level changes and the order in which they must be applied."
+        }
+      ],
+      "tips": [
+        "If a field has 'x-replaced-by', check that replacement field's schema and the decision that drove the change.",
+        "A decision with status 'pending' means the change is not yet live — do not depend on the new shape yet.",
+        "search_docs with the GH# (e.g. 'GH#48') will surface all docs that reference that issue."
+      ]
+    },
+    {
+      "slug": "whatsapp-conversation-display",
+      "title": "Displaying WhatsApp conversation history for an order",
+      "summary": "Current workaround for rendering a per-order WhatsApp thread using NotificationRecord documents. There is no dedicated WhatsApp conversation model yet; outbound messages are reconstructed from the notification audit log.",
+      "workaround_notice": "This is a temporary workaround (GH#48). NotificationRecord captures outbound messages only. Inbound customer replies are not stored in Firestore. A proper WhatsApp conversation model is a future concern.",
+      "steps": [
+        {
+          "step": 1,
+          "tool": "get_schema",
+          "args": { "name": "notification-record" },
+          "note": "Understand the full NotificationRecord shape. Note: every field is readOnly — this is a backend-written audit log, consumers read only."
+        },
+        {
+          "step": 2,
+          "tool": "get_doc",
+          "args": { "slug": "collections/firestore-paths" },
+          "note": "Review the two notification collection paths: company-wide (always written) and order-scoped (dual-write when relatedEntity.type === 'order')."
+        },
+        {
+          "step": 3,
+          "action": "query",
+          "collection": "companies/{companyId}/orders/{orderId}/notifications",
+          "filter": "type == 'whatsapp'",
+          "sort": "sentAt ASC",
+          "note": "Use the order-scoped subcollection for O(1) per-order lookup. Filter to type='whatsapp' to exclude email/sms/push records."
+        },
+        {
+          "step": 4,
+          "action": "render",
+          "fields": {
+            "message_content": "templateParams — filled-in template variable values at send time; reconstruct the message text without calling the Meta API.",
+            "delivery_status": "status — 'sent' | 'failed' | 'pending'",
+            "failure_reason": "error — present only when status === 'failed'",
+            "timestamp": "sentAt — Firestore Timestamp; convert to local time for display",
+            "meta_message_id": "wamid — WhatsApp message ID from Meta; use for deduplication if querying both collection paths"
+          },
+          "note": "All display fields are reconstructable from the NotificationRecord alone — no Meta API call needed."
+        },
+        {
+          "step": 5,
+          "action": "deduplicate",
+          "note": "If you query both companies/{cid}/notifications (filtered by relatedEntity.id === orderId) AND the order-scoped subcollection, deduplicate by 'id' — both paths write the same document ID."
+        }
+      ],
+      "related_models": {
+        "notification-record": "GH#48 — the model used in this workaround",
+        "whatsapp-outbound-message": "GH#43 — dashboard-initiated WhatsApp sends. Separate from backend-automated NotificationRecords but both appear in the conversation thread. Query this collection too for a complete view."
+      },
+      "tips": [
+        "notification-record covers ALL channels (email, whatsapp, sms, push). Always filter by type='whatsapp'.",
+        "metadata field may contain 'templateName', 'senderPhoneId', 'orderNumber' — useful for display headers.",
+        "The order-scoped subcollection only exists if at least one notification with relatedEntity.type='order' was sent. Check for its absence gracefully.",
+        "For a company-wide WhatsApp audit (not order-scoped), query companies/{cid}/notifications filtered by type='whatsapp'."
+      ]
+    }
+  ]
+}

package/index.js

@@ -19,6 +19,7 @@
  *   - list_decisions     → all data model decisions with status
  *   - get_decision       → single decision detail
  *   - get_openapi        → OpenAPI 3.1 spec (full or single component)
+ *   - get_guidance       → use-case recipes (call sequences, field cheatsheets, workaround notes)
  *
  * Resources:
  *   - valets://schemas.json    → full schema bundle
@@ -103,6 +104,11 @@ async function loadOpenapi() {
   return fetchOrRead("/openapi.yaml", join(BUNDLED_STATIC, "openapi.yaml"));
 }
 
+async function loadCookbook() {
+  const raw = await fetchOrRead("/cookbook.json", join(BUNDLED_STATIC, "cookbook.json"));
+  return JSON.parse(raw);
+}
+
 // ---------------------------------------------------------------------------
 // Doc page loading (Markdown)
 // ---------------------------------------------------------------------------
@@ -319,6 +325,32 @@ server.tool(
   }
 );
 
+server.tool(
+  "get_guidance",
+  "Get use-case recipes showing which MCP tools to call and in what order. Call with no arguments for an index of all recipes, or pass a slug to get the full recipe detail.",
+  { slug: z.string().optional().describe("Recipe slug (e.g. 'write-model-code', 'field-history', 'whatsapp-conversation-display'). Omit to list all recipes.") },
+  async ({ slug } = {}) => {
+    const cookbook = await loadCookbook();
+    if (!slug) {
+      const index = cookbook.recipes.map((r) => `- **${r.slug}**: ${r.summary}`).join("\n");
+      return {
+        content: [{ type: "text", text: `Available recipes (${cookbook.recipes.length}):\n\n${index}\n\nCall get_guidance with a slug to get the full recipe.` }],
+      };
+    }
+    const recipe = cookbook.recipes.find((r) => r.slug === slug);
+    if (!recipe) {
+      const available = cookbook.recipes.map((r) => r.slug);
+      return {
+        content: [{ type: "text", text: `Recipe "${slug}" not found.\n\nAvailable slugs:\n${available.map((s) => `  - ${s}`).join("\n")}` }],
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }],
+    };
+  }
+);
+
 // ---------------------------------------------------------------------------
 // Resources
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingenx-io/valets-schema-mcp-server",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "MCP server exposing @valets/schema documentation to AI agents",
   "type": "module",
   "main": "index.js",