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

package/data/static/schemas.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "description": "@valets/schema \u2014 consolidated schema bundle",
-  "generated": "2026-05-27T14:03:20.868899+00:00",
+  "generated": "2026-05-27T15:51:06.117627+00:00",
   "schemas": {
     "allowed-user": {
       "type": "object",
@@ -3477,6 +3477,263 @@
         "month": "month"
       }
     },
+    "notification-channel": {
+      "type": "string",
+      "enum": [
+        "email",
+        "whatsapp",
+        "sms",
+        "push"
+      ],
+      "description": "Delivery channel of a NotificationRecord (GH#48)."
+    },
+    "notification-entity-type": {
+      "type": "string",
+      "enum": [
+        "order",
+        "booking",
+        "customer",
+        "digest",
+        "magic_link",
+        "other"
+      ],
+      "description": "Type of entity a NotificationRecord relates to. When `order`, the record is dual-written to the order-scoped subcollection (GH#48)."
+    },
+    "notification-record": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID, auto-generated. Same ID is used in both the company-wide and order-scoped copies.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "$ref": "#/definitions/notification-channel",
+          "description": "(Read-only) Delivery channel.",
+          "readOnly": true
+        },
+        "status": {
+          "$ref": "#/definitions/notification-status",
+          "description": "(Read-only) Delivery status after the send attempt.",
+          "readOnly": true
+        },
+        "subject": {
+          "readOnly": true,
+          "description": "(Read-only) Subject line. Present for email notifications only.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "recipients": {
+          "type": "object",
+          "properties": {
+            "to": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "email": {
+                    "description": "Recipient email address. Present for email notifications.",
+                    "type": "string"
+                  },
+                  "phone": {
+                    "description": "Recipient phone number (E.164). Present for whatsapp/sms notifications.",
+                    "type": "string"
+                  },
+                  "name": {
+                    "description": "Recipient display name.",
+                    "type": "string"
+                  },
+                  "role": {
+                    "description": "Recipient role (e.g. organizer, customer).",
+                    "type": "string"
+                  }
+                },
+                "additionalProperties": false,
+                "description": "A notification recipient (GH#48)."
+              },
+              "description": "Primary recipients."
+            },
+            "cc": {
+              "description": "CC recipients (email).",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "email": {
+                    "description": "Recipient email address. Present for email notifications.",
+                    "type": "string"
+                  },
+                  "phone": {
+                    "description": "Recipient phone number (E.164). Present for whatsapp/sms notifications.",
+                    "type": "string"
+                  },
+                  "name": {
+                    "description": "Recipient display name.",
+                    "type": "string"
+                  },
+                  "role": {
+                    "description": "Recipient role (e.g. organizer, customer).",
+                    "type": "string"
+                  }
+                },
+                "additionalProperties": false,
+                "description": "A notification recipient (GH#48)."
+              }
+            },
+            "bcc": {
+              "description": "BCC recipients (email).",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "email": {
+                    "description": "Recipient email address. Present for email notifications.",
+                    "type": "string"
+                  },
+                  "phone": {
+                    "description": "Recipient phone number (E.164). Present for whatsapp/sms notifications.",
+                    "type": "string"
+                  },
+                  "name": {
+                    "description": "Recipient display name.",
+                    "type": "string"
+                  },
+                  "role": {
+                    "description": "Recipient role (e.g. organizer, customer).",
+                    "type": "string"
+                  }
+                },
+                "additionalProperties": false,
+                "description": "A notification recipient (GH#48)."
+              }
+            }
+          },
+          "required": [
+            "to"
+          ],
+          "additionalProperties": false,
+          "readOnly": true,
+          "description": "(Read-only) Recipients of the notification."
+        },
+        "relatedEntity": {
+          "type": "object",
+          "properties": {
+            "type": {
+              "$ref": "#/definitions/notification-entity-type",
+              "description": "Entity type this notification relates to."
+            },
+            "id": {
+              "type": "string",
+              "description": "Entity document ID (e.g. orderId when type=order)."
+            }
+          },
+          "required": [
+            "type",
+            "id"
+          ],
+          "additionalProperties": false,
+          "readOnly": true,
+          "description": "(Read-only) Entity that triggered the notification. type=order triggers the dual-write to the order subcollection."
+        },
+        "wamid": {
+          "readOnly": true,
+          "description": "(Read-only) WhatsApp message ID from the Meta API response. Present on successful whatsapp sends only.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "templateParams": {
+          "readOnly": true,
+          "description": "(Read-only) Filled-in template variable values at send time. Allows reconstructing the sent message without fetching from Meta.",
+          "type": [
+            "object",
+            "null"
+          ],
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "metadata": {
+          "readOnly": true,
+          "description": "(Read-only) Channel-specific extras (e.g. senderPhoneId, templateName, orderNumber).",
+          "type": [
+            "object",
+            "null"
+          ],
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {}
+        },
+        "error": {
+          "readOnly": true,
+          "description": "(Read-only) Failure reason. Present on status=failed.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "sentAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "(Read-only) When the send was attempted.",
+          "readOnly": true
+        },
+        "createdAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "(Read-only) When the record was created.",
+          "readOnly": true
+        }
+      },
+      "required": [
+        "type",
+        "status",
+        "recipients",
+        "relatedEntity",
+        "sentAt",
+        "createdAt"
+      ],
+      "additionalProperties": false,
+      "description": "NotificationRecord \u2014 backend-written, multi-channel notification audit log (GH#48). Paths: companies/{cid}/notifications/{id} (always) and companies/{cid}/orders/{oid}/notifications/{id} (dual-write when relatedEntity.type=order). Consumers read only. Distinct from WhatsappOutboundMessage (GH#43).",
+      "example": {
+        "id": null,
+        "type": "phone",
+        "status": "status",
+        "subject": null,
+        "recipients": {
+          "to": [
+            {}
+          ]
+        },
+        "relatedEntity": {
+          "type": "phone",
+          "id": "bk_abc123def456"
+        },
+        "wamid": null,
+        "templateParams": null,
+        "metadata": null,
+        "error": null,
+        "sentAt": "sentAt",
+        "createdAt": "createdAt"
+      }
+    },
+    "notification-status": {
+      "type": "string",
+      "enum": [
+        "sent",
+        "failed",
+        "pending"
+      ],
+      "description": "Delivery status of a NotificationRecord, set by the Cloud Function after a send attempt (GH#48)."
+    },
     "order": {
       "type": "object",
       "properties": {

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.2",
+  "version": "0.2.4",
   "description": "MCP server exposing @valets/schema documentation to AI agents",
   "type": "module",
   "main": "index.js",