@sellhapi/mcp 0.1.2 → 0.1.4

package/dist/resources/capability-patterns.js

@@ -305,6 +305,63 @@ Anti-patterns:
 
 ---
 
+## ENTITY LAYOUT PHILOSOPHY
+
+Entities DO NOT have to be displayed as uniform rectangle cards in a grid.
+Choose the layout that fits the business type, visual direction, and the entity's purpose.
+The wireframe is your opportunity to propose the right layout — the user can approve or change it.
+
+Layout options by entity type:
+
+MEMBERSHIPS — premium tiers deserve premium presentation:
+  - Large image tile (full-width image, title + price + CTA below) — ideal for lifestyle/luxury brands
+  - Horizontal comparison table — ideal for SaaS-style or tiered feature sets
+  - Feature-rich card with expanded benefits checklist — ideal when benefits are the selling point
+  - Avoid generic equal-height rectangle cards unless the business explicitly has many tiers
+
+SERVICES — editorial presentation conveys quality better than a card grid:
+  - Alternating split sections (image left / text + CTA right, alternates per service)
+  - Full-width editorial rows with large background image + text overlay
+  - Icon + heading + description list for minimalist service studios
+  - Grid cards are acceptable only when services are many and uniform (e.g. a menu)
+
+EVENTS — presentation should match the energy of the event:
+  - Poster-style: large image, event name as headline, date + location below — theatrical feel
+  - Horizontal scroll strip: compact cards in a row — good for many events
+  - Featured hero card (first event large, rest smaller) — highlights the primary event
+  - Calendar or timeline view when date ordering matters most
+
+DONATIONS — campaigns are stories, not products:
+  - Hero campaign section: full-width image, campaign name, progress bar, donate CTA
+  - Stacked editorial rows: image + story side-by-side, alternating
+  - Card grid is acceptable when there are multiple parallel campaigns of equal importance
+
+APPOINTMENTS — scheduling flows need clarity, not decoration:
+  - Service list → select → calendar → time slot: linear step-by-step (most common, best UX)
+  - Service cards with inline "Book now" that opens a side panel
+  - Minimal: service name + duration + price in a clean list, not a card grid
+
+PRODUCTS (homepage teaser) — this is an editorial/marketing section:
+  - 2-col editorial layout: large image takes 60% width, product name + price + CTA in remaining 40%
+  - 4-col editorial grid with large images and minimal text overlay
+  - Featured product hero (one product at full width) + 3 supporting products below
+  - NOT the same component or layout as the /products page — it must look visually distinct
+
+PRODUCTS (grid/browse page) — standard grid is correct here:
+  - 3-col or 4-col responsive grid with image, name, price, Add to Cart
+  - Consistent card height, pagination or Load More at bottom
+  - This is the browsing context — uniformity and scannability are correct here
+
+Key rules:
+  - Match layout to visualDirection.layoutPattern if set — it explicitly describes the intended pattern
+  - "glassmorphism" or "soft-shadow" cardStyle + premium business → prefer large image tiles, not small cards
+  - The wireframe section names you choose (e.g. "featured-membership-tiles", "editorial-services", "campaign-hero")
+    signal your layout intent — use descriptive names, not generic ones like "section1"
+  - BuildGuard does NOT enforce layout — only data-region attributes and banned JS APIs are checked
+  - The visual representation is yours to decide based on brand and context
+
+---
+
 ## UNIVERSAL RULES
 
 1. Price display: always (priceKobo / 100).toLocaleString() — prefix with ₦

package/dist/resources/wireframe-schema.d.ts

@@ -5,4 +5,4 @@
  * apply_wireframe. The AI client generates mid-fidelity wireframes per page,
  * presents each one to the user for review, then submits the approved set.
  */
-export declare const WIREFRAME_SCHEMA = "\n# SellHapi Wireframe Schema\n\nWireframes are mid-fidelity HTML page layouts \u2014 one per storefront page.\nThey are the USER'S checkpoint before code is written: present each page\nwireframe in the conversation, collect feedback, revise if needed, then\ncall apply_wireframe only after the user approves the full set.\n\n---\n\n## Data shape\n\n```\n{ [pageSlug: string]: htmlString }\n```\n\n- Each key is a page slug that MUST match one of the slugs in designDirection.pages\n- Each value is a valid HTML string for that page's mid-fidelity wireframe\n- All pages from designDirection.pages should be included (missing pages means no wireframe guidance for code generation on that page)\n\n---\n\n## What a wireframe IS\n\nMid-fidelity structural HTML. It communicates:\n- Which sections appear on the page and in what order\n- What content each section contains (headings, CTAs, placeholder data)\n- Navigation structure (links, cart icon, CTA button)\n- Footer structure (columns, links)\n- Which runtime hook each section will use\n\nIt does NOT include:\n- Real CSS (use only inline style for basic layout structure if needed)\n- JavaScript or React\n- Actual product/service data (use descriptive placeholders)\n- Final colour values or fonts (those come from designDirection.visualDirection)\n\n---\n\n## Structure rules\n\n### Navigation \u2014 MANDATORY on every page\n```html\n<nav>\n  <div class=\"nav-logo\">[Business Name]</div>\n  <ul class=\"nav-links\">\n    <li><a href=\"#/home\">Home</a></li>\n    <li><a href=\"#/shop\">Shop</a></li>\n    <!-- one <li> per page in designDirection.pages -->\n  </ul>\n  <!-- If physical_products or digital_products in capabilityIds: -->\n  <button class=\"nav-cart\">Cart (0)</button>\n  <button class=\"nav-cta\">[Primary CTA]</button>\n</nav>\n```\n\n- Navigation HTML must be **identical across all pages** \u2014 copy verbatim after the first page\n- Highlight the current page's link as active (add class=\"active\" to that <li>)\n- Cart icon only when capability includes physical_products or digital_products\n\n### Footer \u2014 MANDATORY on every page\n```html\n<footer>\n  <div class=\"footer-col\">\n    <div class=\"footer-logo\">[Business Name]</div>\n    <p>[tagline]</p>\n  </div>\n  <div class=\"footer-col\">\n    <h4>NAVIGATE</h4>\n    <ul><!-- one <li> per page --></ul>\n  </div>\n  <div class=\"footer-col\">\n    <h4>RESOURCES</h4>\n    <ul><!-- relevant links for this business type --></ul>\n  </div>\n  <div class=\"footer-col\">\n    <h4>CONNECT</h4>\n    <!-- social platform links -->\n  </div>\n  <div class=\"footer-bottom\">\u00A9 [year] [Business Name]. All rights reserved.</div>\n</footer>\n```\n\n- Footer HTML must be **identical across all pages** \u2014 copy verbatim after the first page\n\n### Sections\nEach section gets a wrapper with a comment and data-hook attribute:\n\n```html\n<!-- Hero Section -->\n<section data-section=\"hero\" data-hook=\"none\">\n  <h1>[Headline \u2014 use the business tagline]</h1>\n  <p>[Supporting copy]</p>\n  <button>[Primary CTA]</button>\n  <div class=\"hero-image\">[Hero image placeholder]</div>\n</section>\n\n<!-- Product Grid Section -->\n<section data-section=\"product-grid\" data-hook=\"useProducts\">\n  <h2>Our Products</h2>\n  <div class=\"product-grid\">\n    <div class=\"product-card\">\n      <div class=\"product-image\">[Product image]</div>\n      <h3>[Product name]</h3>\n      <p>[Price in \u20A6]</p>\n      <button>Add to Cart</button>\n    </div>\n    <!-- repeat 2 more placeholder cards -->\n  </div>\n</section>\n\n<!-- Testimonials Section -->\n<section data-section=\"testimonials\" data-hook=\"useContentTestimonials\">\n  <h2>What Customers Say</h2>\n  <div class=\"testimonials-grid\">\n    <blockquote>[Testimonial 1]</blockquote>\n    <blockquote>[Testimonial 2]</blockquote>\n    <blockquote>[Testimonial 3]</blockquote>\n  </div>\n</section>\n```\n\n---\n\n## data-hook values by capability\n\nUse these exact hook names in data-hook attributes so code generation\nmatches the correct runtime hook:\n\n| Section type                  | data-hook                       |\n|-------------------------------|---------------------------------|\n| Product listing / grid        | useProducts                     |\n| Product collections           | useProductCollections           |\n| Single collection             | useCollection                   |\n| Category sections             | useSections                     |\n| Service listings              | useServiceListings              |\n| Appointment booking           | useBookAppointment              |\n| Available dates               | useAvailableDates               |\n| Events listing                | useEvents                       |\n| Donation campaigns            | useDonationCampaigns            |\n| Membership tiers              | useMemberships                  |\n| Content images                | useContentImages                |\n| Testimonials                  | useContentTestimonials          |\n| FAQs                          | useContentFaqs                  |\n| Team members                  | useContentTeam                  |\n| Stats / social proof          | useContentStats                 |\n| Feature highlights            | useContentFeatures              |\n| Contact / enquiry form        | useSubmitForm                   |\n| Listings (classifieds/jobs)   | useListings                     |\n| Non-data sections (hero, about, footer, nav) | none          |\n\n---\n\n## Presenting wireframes to the user\n\nBefore calling apply_wireframe, show each page to the user like this:\n\n```\n\uD83D\uDCC4 HOME PAGE\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n[NAV] Logo | Home \u00B7 Shop \u00B7 About \u00B7 Contact  [Cart] [Shop Now]\n\n[HERO]\n  \"Authentic Nigerian fashion for the bold\"\n  Subheading + CTA button\n  Full-width hero image\n\n[FEATURED PRODUCTS] (useProducts)\n  3-column product grid \u2014 6 products\n  Each card: image, name, price, Add to Cart\n\n[COLLECTIONS] (useProductCollections)\n  4 collection tiles with cover images\n\n[TESTIMONIALS] (useContentTestimonials)\n  3 customer quotes in a row\n\n[NEWSLETTER]\n  Email capture form\n\n[FOOTER] 4-column footer\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\nDoes this structure look right? Any sections to add, remove, or reorder?\n```\n\nWait for explicit user approval before proceeding to apply_wireframe.\nIf the user requests changes, update the affected page(s) and show again.\n\n---\n\n## Submission\n\nOnce ALL pages are approved by the user:\n\n```\napply_wireframe(projectId, {\n  \"home\":    \"<nav>...</nav><main>...</main><footer>...</footer>\",\n  \"shop\":    \"<nav>...</nav><main>...</main><footer>...</footer>\",\n  \"about\":   \"<nav>...</nav><main>...</main><footer>...</footer>\",\n  \"contact\": \"<nav>...</nav><main>...</main><footer>...</footer>\"\n})\n```\n\nReturns: `{ pageCount: 4, slugs: [\"home\", \"shop\", \"about\", \"contact\"] }`\n\nAfter this, proceed to generate React code using the wireframe as your\nstructural reference. The wireframe defines WHAT to build \u2014 runtime-hooks\nand build-rules define HOW to build it in React.\n";
+export declare const WIREFRAME_SCHEMA = "\n# SellHapi Wireframe Schema\n\nWireframes are mid-fidelity HTML page layouts \u2014 one per storefront page.\nThey are the USER'S checkpoint before code is written: present each page\nwireframe in the conversation, collect feedback, revise if needed, then\ncall apply_wireframe only after the user approves the full set.\n\n---\n\n## Data shape\n\n```\n{ [pageSlug: string]: htmlString }\n```\n\n- Each key is a page slug that MUST match one of the slugs in designDirection.pages\n- Each value is a valid HTML string for that page's mid-fidelity wireframe\n- All pages from designDirection.pages should be included (missing pages means no wireframe guidance for code generation on that page)\n\n---\n\n## What a wireframe IS\n\nMid-fidelity structural HTML. It communicates:\n- Which sections appear on the page and in what order\n- What content each section contains (headings, CTAs, placeholder data)\n- Navigation structure (links, cart icon, CTA button)\n- Footer structure (columns, links)\n- Which runtime hook each section will use\n\nIt does NOT include:\n- Real CSS (use only inline style for basic layout structure if needed)\n- JavaScript or React\n- Actual product/service data (use descriptive placeholders)\n- Final colour values or fonts (those come from designDirection.visualDirection)\n\n---\n\n## Structure rules\n\n### Navigation \u2014 MANDATORY on every page\n```html\n<nav>\n  <div class=\"nav-logo\">[Business Name]</div>\n  <ul class=\"nav-links\">\n    <li><a href=\"#/home\">Home</a></li>\n    <li><a href=\"#/shop\">Shop</a></li>\n    <!-- one <li> per page in designDirection.pages -->\n  </ul>\n  <!-- If physical_products or digital_products in capabilityIds: -->\n  <button class=\"nav-cart\">Cart (0)</button>\n  <button class=\"nav-cta\">[Primary CTA]</button>\n</nav>\n```\n\n- Navigation HTML must be **identical across all pages** \u2014 copy verbatim after the first page\n- Highlight the current page's link as active (add class=\"active\" to that <li>)\n- Cart icon only when capability includes physical_products or digital_products\n\n### Footer \u2014 MANDATORY on every page\n```html\n<footer>\n  <div class=\"footer-col\">\n    <div class=\"footer-logo\">[Business Name]</div>\n    <p>[tagline]</p>\n  </div>\n  <div class=\"footer-col\">\n    <h4>NAVIGATE</h4>\n    <ul><!-- one <li> per page --></ul>\n  </div>\n  <div class=\"footer-col\">\n    <h4>RESOURCES</h4>\n    <ul><!-- relevant links for this business type --></ul>\n  </div>\n  <div class=\"footer-col\">\n    <h4>CONNECT</h4>\n    <!-- social platform links -->\n  </div>\n  <div class=\"footer-bottom\">\u00A9 [year] [Business Name]. All rights reserved.</div>\n</footer>\n```\n\n- Footer HTML must be **identical across all pages** \u2014 copy verbatim after the first page\n\n### Sections\nEach section gets a wrapper with a comment and data-hook attribute:\n\n```html\n<!-- Hero Section -->\n<section data-section=\"hero\" data-hook=\"none\">\n  <h1>[Headline \u2014 use the business tagline]</h1>\n  <p>[Supporting copy]</p>\n  <button>[Primary CTA]</button>\n  <div class=\"hero-image\">[Hero image placeholder]</div>\n</section>\n\n<!-- Product Grid Section -->\n<section data-section=\"product-grid\" data-hook=\"useProducts\">\n  <h2>Our Products</h2>\n  <div class=\"product-grid\">\n    <div class=\"product-card\">\n      <div class=\"product-image\">[Product image]</div>\n      <h3>[Product name]</h3>\n      <p>[Price in \u20A6]</p>\n      <button>Add to Cart</button>\n    </div>\n    <!-- repeat 2 more placeholder cards -->\n  </div>\n</section>\n\n<!-- Testimonials Section -->\n<section data-section=\"testimonials\" data-hook=\"useContentTestimonials\">\n  <h2>What Customers Say</h2>\n  <div class=\"testimonials-grid\">\n    <blockquote>[Testimonial 1]</blockquote>\n    <blockquote>[Testimonial 2]</blockquote>\n    <blockquote>[Testimonial 3]</blockquote>\n  </div>\n</section>\n```\n\n---\n\n## data-hook values by capability\n\nUse these exact hook names in data-hook attributes so code generation\nmatches the correct runtime hook:\n\n| Section type                  | data-hook                       |\n|-------------------------------|---------------------------------|\n| Product listing / grid        | useProducts                     |\n| Product collections           | useProductCollections           |\n| Single collection             | useCollection                   |\n| Category sections             | useSections                     |\n| Service listings              | useServiceListings              |\n| Appointment booking           | useBookAppointment              |\n| Available dates               | useAvailableDates               |\n| Events listing                | useEvents                       |\n| Donation campaigns            | useDonationCampaigns            |\n| Membership tiers              | useMemberships                  |\n| Content images                | useContentImages                |\n| Testimonials                  | useContentTestimonials          |\n| FAQs                          | useContentFaqs                  |\n| Team members                  | useContentTeamMembers           |\n| Stats / social proof          | useContentStats                 |\n| Feature highlights            | useContentFeatures              |\n| Contact / enquiry form        | useSubmitForm                   |\n| Listings (classifieds/jobs)   | useListings                     |\n| Non-data sections (hero, about, footer, nav) | none          |\n\n---\n\n## Presenting wireframes to the user\n\nBefore calling apply_wireframe, show each page to the user like this:\n\n```\n\uD83D\uDCC4 HOME PAGE\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n[NAV] Logo | Home \u00B7 Shop \u00B7 About \u00B7 Contact  [Cart] [Shop Now]\n\n[HERO]\n  \"Authentic Nigerian fashion for the bold\"\n  Subheading + CTA button\n  Full-width hero image\n\n[FEATURED PRODUCTS] (useProducts)\n  3-column product grid \u2014 6 products\n  Each card: image, name, price, Add to Cart\n\n[COLLECTIONS] (useProductCollections)\n  4 collection tiles with cover images\n\n[TESTIMONIALS] (useContentTestimonials)\n  3 customer quotes in a row\n\n[NEWSLETTER]\n  Email capture form\n\n[FOOTER] 4-column footer\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\nDoes this structure look right? Any sections to add, remove, or reorder?\n```\n\nWait for explicit user approval before proceeding to apply_wireframe.\nIf the user requests changes, update the affected page(s) and show again.\n\n---\n\n## Submission\n\nOnce ALL pages are approved by the user:\n\n```\napply_wireframe(projectId, {\n  \"home\":    \"<nav>...</nav><main>...</main><footer>...</footer>\",\n  \"shop\":    \"<nav>...</nav><main>...</main><footer>...</footer>\",\n  \"about\":   \"<nav>...</nav><main>...</main><footer>...</footer>\",\n  \"contact\": \"<nav>...</nav><main>...</main><footer>...</footer>\"\n})\n```\n\nReturns: `{ pageCount: 4, slugs: [\"home\", \"shop\", \"about\", \"contact\"] }`\n\nAfter this, proceed to generate React code using the wireframe as your\nstructural reference. The wireframe defines WHAT to build \u2014 runtime-hooks\nand build-rules define HOW to build it in React.\n";

package/dist/resources/wireframe-schema.js

@@ -152,7 +152,7 @@ matches the correct runtime hook:
 | Content images                | useContentImages                |
 | Testimonials                  | useContentTestimonials          |
 | FAQs                          | useContentFaqs                  |
-| Team members                  | useContentTeam                  |
+| Team members                  | useContentTeamMembers           |
 | Stats / social proof          | useContentStats                 |
 | Feature highlights            | useContentFeatures              |
 | Contact / enquiry form        | useSubmitForm                   |

package/dist/server.js

@@ -12,6 +12,7 @@ const studio_js_1 = require("./tools/studio.js");
 const commerce_js_1 = require("./tools/commerce.js");
 const content_js_1 = require("./tools/content.js");
 const intelligence_js_1 = require("./tools/intelligence.js");
+const analytics_js_1 = require("./tools/analytics.js");
 const index_js_1 = require("./resources/index.js");
 function createMcpServer() {
     const server = new mcp_js_1.McpServer({
@@ -22,6 +23,7 @@ function createMcpServer() {
     (0, commerce_js_1.registerCommerceTools)(server);
     (0, content_js_1.registerContentTools)(server);
     (0, intelligence_js_1.registerIntelligenceTools)(server);
+    (0, analytics_js_1.registerAnalyticsTools)(server);
     (0, index_js_1.registerResources)(server);
     return server;
 }

package/dist/tools/analytics.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Analytics tools — read-only access to pre-computed capability metrics.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAnalyticsTools(server: McpServer): void;

package/dist/tools/analytics.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Analytics tools — read-only access to pre-computed capability metrics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAnalyticsTools = registerAnalyticsTools;
+const v4_1 = require("zod/v4");
+const client_js_1 = require("../client.js");
+const util_js_1 = require("../util.js");
+function registerAnalyticsTools(server) {
+    server.registerTool("get_analytics", {
+        title: "Get Analytics",
+        description: "Get pre-computed analytics for this vendor. Returns revenue, transaction counts, and other metrics per capability for a given period. Use this to answer questions like 'what's my revenue this month', 'which capability earns the most', or 'how many orders have I had'. Metrics are computed on a schedule — call this before making business recommendations.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            period: v4_1.z.enum(["7d", "30d", "90d"]).optional().default("30d").describe("Time period for metrics (default: 30d)"),
+        },
+    }, async ({ period }) => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)(`/api/mcp/analytics?period=${period}`);
+        return JSON.stringify(data, null, 2);
+    }));
+}

package/dist/tools/commerce.d.ts

@@ -1,9 +1,6 @@
 /**
- * Commerce tools — read-only access to products, services, events, memberships, donations, appointments.
- *
- * All URLs point to /api/mcp/* (API key auth). Write endpoints are not yet
- * available on the MCP route layer — create tools will be added when backend
- * write proxies are shipped.
+ * Commerce tools — read and write access to products, services, events,
+ * memberships, donations, appointments, and forms.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function registerCommerceTools(server: McpServer): void;

package/dist/tools/commerce.js

@@ -1,13 +1,11 @@
 "use strict";
 /**
- * Commerce tools — read-only access to products, services, events, memberships, donations, appointments.
- *
- * All URLs point to /api/mcp/* (API key auth). Write endpoints are not yet
- * available on the MCP route layer — create tools will be added when backend
- * write proxies are shipped.
+ * Commerce tools — read and write access to products, services, events,
+ * memberships, donations, appointments, and forms.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerCommerceTools = registerCommerceTools;
+const v4_1 = require("zod/v4");
 const client_js_1 = require("../client.js");
 const util_js_1 = require("../util.js");
 function registerCommerceTools(server) {
@@ -74,6 +72,170 @@ function registerCommerceTools(server) {
         const data = await (0, client_js_1.get)("/api/mcp/appointments/services");
         return JSON.stringify(data.services, null, 2);
     }));
+    // ── Categories ────────────────────────────────────────────────────────────
+    server.registerTool("list_categories", {
+        title: "List Categories",
+        description: "List all product categories for this vendor. Call this before create_product or update_product to get valid categoryId values. Returns id, name, description for each category.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/categories");
+        return JSON.stringify(data.categories, null, 2);
+    }));
+    server.registerTool("create_category", {
+        title: "Create Category",
+        description: "Create a product category. Returns the new category id — use it immediately in create_product or update_product. Returns a 409 conflict (with the existing id) if a category with the same name already exists — use that id instead of creating a duplicate.",
+        inputSchema: {
+            name: v4_1.z.string().describe("Category name e.g. 'Clothing', 'Baked Goods'"),
+            description: v4_1.z.string().optional().describe("Optional description"),
+        },
+    }, async (input) => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.post)("/api/mcp/categories", input);
+        return JSON.stringify(data, null, 2);
+    }));
+    // ── Write: Create product ─────────────────────────────────────────────────
+    server.registerTool("create_product", {
+        title: "Create Product",
+        description: "Create a physical or digital product. Call list_capabilities first to confirm the relevant capability (physical_products or digital_products) is active. Call list_categories first to get a valid categoryId — supplying an invalid categoryId returns a 400 error. Prices must be in kobo (₦1 = 100 kobo). imageUrl is optional.",
+        inputSchema: {
+            name: v4_1.z.string().describe("Product name"),
+            description: v4_1.z.string().optional().describe("Product description"),
+            priceKobo: v4_1.z.number().int().min(0).describe("Price in kobo (₦1 = 100 kobo)"),
+            type: v4_1.z.enum(["physical", "digital"]).optional().default("physical").describe("Product type — physical (default) or digital"),
+            stock: v4_1.z.number().int().min(0).optional().describe("Initial stock quantity (0 = out of stock). Omit for untracked stock."),
+            imageUrl: v4_1.z.string().optional().describe("External image URL for the product"),
+            categoryId: v4_1.z.string().uuid().optional().describe("Category ID from list_categories. Omit if no category applies."),
+        },
+    }, async (input) => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.post)("/api/mcp/products", input);
+        return JSON.stringify(data, null, 2);
+    }));
+    // ── Write: Update product ─────────────────────────────────────────────────
+    server.registerTool("update_product", {
+        title: "Update Product",
+        description: "Update an existing product's name, description, category, or image. Call list_products to get the productId, list_categories to get a valid categoryId. Only fields provided are updated — omitted fields stay unchanged. Pass categoryId: null to remove the category.",
+        inputSchema: {
+            productId: v4_1.z.string().uuid().describe("Product ID from list_products"),
+            name: v4_1.z.string().optional().describe("New product name"),
+            description: v4_1.z.string().optional().describe("New product description"),
+            categoryId: v4_1.z.string().uuid().nullable().optional().describe("Category ID from list_categories, or null to remove category"),
+            imageUrl: v4_1.z.string().nullable().optional().describe("New image URL, or null to clear"),
+        },
+    }, async ({ productId, ...rest }) => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.patch)(`/api/mcp/products/${productId}`, rest);
+        return JSON.stringify(data, null, 2);
+    }));
+    // ── Write: Create event ───────────────────────────────────────────────────
+    server.registerTool("create_event", {
+        title: "Create Event",
+        description: "Create an event with optional ticket types in a single call. Events are created as draft — they become visible on the storefront when published from the dashboard. Call list_capabilities first to confirm events capability is active.",
+        inputSchema: {
+            title: v4_1.z.string().describe("Event title"),
+            description: v4_1.z.string().optional().describe("Event description"),
+            startsAt: v4_1.z.string().describe("Start datetime — ISO 8601 string e.g. '2025-03-15T10:00:00'"),
+            endsAt: v4_1.z.string().describe("End datetime — ISO 8601 string"),
+            location: v4_1.z.string().optional().describe("Venue or location name"),
+            imageUrl: v4_1.z.string().optional().describe("Event cover image URL"),
+            tickets: v4_1.z.array(v4_1.z.object({
+                name: v4_1.z.string().describe("Ticket type name e.g. 'General Admission'"),
+                priceKobo: v4_1.z.number().int().min(0).describe("Ticket price in kobo (0 = free)"),
+                capacity: v4_1.z.number().int().min(1).describe("Total number of tickets available"),
+                maxPerOrder: v4_1.z.number().int().optional().describe("Max tickets per order"),
+                description: v4_1.z.string().optional(),
+            })).optional().default([]).describe("Ticket types to create inline with the event"),
+        },
+    }, async (input) => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.post)("/api/mcp/events", input);
+        return JSON.stringify(data, null, 2);
+    }));
+    // ── Write: Create membership tier ─────────────────────────────────────────
+    server.registerTool("create_membership_tier", {
+        title: "Create Membership Tier",
+        description: "Create a membership tier with benefits list and billing period. Call list_capabilities first to confirm memberships capability is active. Prices in kobo.",
+        inputSchema: {
+            name: v4_1.z.string().describe("Tier name e.g. 'Gold Member'"),
+            description: v4_1.z.string().optional().describe("Tier description"),
+            priceKobo: v4_1.z.number().int().min(0).describe("Price in kobo per billing period"),
+            billingPeriod: v4_1.z.enum(["monthly", "yearly", "one_time"]).optional().default("monthly"),
+            benefits: v4_1.z.array(v4_1.z.string()).optional().describe("List of benefits e.g. ['Free delivery', 'Early access to drops']"),
+            imageUrl: v4_1.z.string().optional().describe("Tier cover image URL"),
+            maxMembers: v4_1.z.number().int().optional().describe("Maximum members for this tier (null = unlimited)"),
+        },
+    }, async (input) => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.post)("/api/mcp/memberships/tiers", input);
+        return JSON.stringify(data, null, 2);
+    }));
+    // ── Write: Create donation campaign ───────────────────────────────────────
+    server.registerTool("create_donation_campaign", {
+        title: "Create Donation Campaign",
+        description: "Create a fundraising campaign. Campaigns are live immediately after creation. Call list_capabilities first to confirm donations capability is active.",
+        inputSchema: {
+            title: v4_1.z.string().describe("Campaign title"),
+            description: v4_1.z.string().optional().describe("Campaign story / description"),
+            goalAmountKobo: v4_1.z.number().int().optional().describe("Fundraising goal in kobo (omit for open-ended campaigns)"),
+            imageUrl: v4_1.z.string().optional().describe("Campaign cover image URL"),
+            endsAt: v4_1.z.string().optional().describe("Campaign end date — ISO 8601 string (omit for no end date)"),
+            presetAmounts: v4_1.z.array(v4_1.z.number().int().min(0)).optional().describe("Preset donation amount options in kobo e.g. [500000, 1000000, 2000000]"),
+        },
+    }, async (input) => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.post)("/api/mcp/donations/campaigns", input);
+        return JSON.stringify(data, null, 2);
+    }));
+    // ── Write: Create appointment service ────────────────────────────────────
+    server.registerTool("create_appointment_service", {
+        title: "Create Appointment Service",
+        description: "Create a bookable appointment service. Note: staff members and their weekly schedules must be set up in the Appointments dashboard before customers can book. Call list_capabilities first to confirm appointments capability is active.",
+        inputSchema: {
+            name: v4_1.z.string().describe("Service name e.g. 'Hair Consultation'"),
+            description: v4_1.z.string().optional(),
+            durationMinutes: v4_1.z.number().int().min(1).describe("Service duration in minutes"),
+            priceKobo: v4_1.z.number().int().min(0).describe("Price in kobo"),
+            imageUrl: v4_1.z.string().optional(),
+            bufferMinutes: v4_1.z.number().int().min(0).optional().describe("Buffer time between bookings in minutes (default 0)"),
+            maxConcurrentBookings: v4_1.z.number().int().min(1).optional().describe("Max simultaneous bookings for this service (default 1)"),
+        },
+    }, async (input) => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.post)("/api/mcp/appointments/services", input);
+        return JSON.stringify(data, null, 2);
+    }));
+    // ── Write: Create service listing ────────────────────────────────────────
+    server.registerTool("create_service_listing", {
+        title: "Create Service Listing",
+        description: "Create a service listing (freelance/agency-style services with a coverImage, description, and purchase flow). Different from appointment services — service listings are for deliverable-based work like design, photography, consulting. Call list_capabilities first to confirm services capability is active.",
+        inputSchema: {
+            title: v4_1.z.string().describe("Listing title e.g. 'Brand Identity Package'"),
+            description: v4_1.z.string().optional(),
+            priceKobo: v4_1.z.number().int().min(0).describe("Price in kobo"),
+            category: v4_1.z.string().optional().describe("Service category e.g. 'Design', 'Photography'"),
+            coverImageUrl: v4_1.z.string().optional(),
+            duration: v4_1.z.string().optional().describe("Delivery timeframe label e.g. '3–5 days'"),
+            deliveryTime: v4_1.z.string().optional().describe("Delivery time e.g. '7 days'"),
+        },
+    }, async (input) => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.post)("/api/mcp/service-listings", input);
+        return JSON.stringify(data, null, 2);
+    }));
+    // ── Write: Create form ───────────────────────────────────────────────────
+    server.registerTool("create_form", {
+        title: "Create Form",
+        description: "Create a published storefront form. Returns the form ID — use it in useContentForm(formId) and useSubmitForm(formId) in storefront code. Call list_capabilities first to confirm content capability is active. Field types: text, email, phone, textarea, select, radio, checkbox, date, number, file.",
+        inputSchema: {
+            title: v4_1.z.string().describe("Form name e.g. 'Contact Us'"),
+            description: v4_1.z.string().optional(),
+            fields: v4_1.z.array(v4_1.z.object({
+                label: v4_1.z.string().describe("Field label shown to the user"),
+                type: v4_1.z.enum(["text", "email", "phone", "textarea", "select", "radio", "checkbox", "date", "number", "file"]).describe("Field input type"),
+                required: v4_1.z.boolean().optional().default(false),
+                placeholder: v4_1.z.string().optional(),
+                options: v4_1.z.array(v4_1.z.string()).optional().describe("Options for select fields"),
+            })).describe("Form fields in order"),
+            submitButtonText: v4_1.z.string().optional().describe("Submit button label (default: 'Submit')"),
+            successMessage: v4_1.z.string().optional().describe("Message shown after successful submission"),
+            storefrontPurpose: v4_1.z.enum(["contact", "waitlist", "enquiry", "feedback", "application"]).optional().describe("Semantic purpose — helps the storefront and Studio identify this form"),
+        },
+    }, async (input) => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.post)("/api/mcp/content/forms", input);
+        return JSON.stringify(data, null, 2);
+    }));
     // ── Capabilities ───────────────────────────────────────────────────────────
     server.registerTool("list_capabilities", {
         title: "List Capabilities",

package/dist/tools/studio.js

@@ -9,6 +9,8 @@ const client_js_1 = require("../client.js");
 const util_js_1 = require("../util.js");
 const runtime_hooks_js_1 = require("../resources/runtime-hooks.js");
 const build_rules_js_1 = require("../resources/build-rules.js");
+const design_direction_schema_js_1 = require("../resources/design-direction-schema.js");
+const wireframe_schema_js_1 = require("../resources/wireframe-schema.js");
 function registerStudioTools(server) {
     // ── List projects ──────────────────────────────────────────────────────────
     server.registerTool("list_projects", {
@@ -52,13 +54,13 @@ function registerStudioTools(server) {
                         step: 1,
                         tool: "apply_design_direction",
                         required: true,
-                        description: "Generate and store a full DesignDirection — colors, fonts, pages, business context. Do this NOW before anything else. Read sellhapi://design-direction-schema for the exact shape. Present the direction summary to the user (palette, pages, mood) and get confirmation before calling apply_design_direction. Alternatively use set_design_direction to let SellHapi's Claude generate it (costs credits).",
+                        description: "BEFORE generating any direction JSON, have a SHORT design conversation with the user. Ask: (1) preferred brand colors — or let the AI suggest based on the business type; (2) font style — modern/minimal, editorial/serif, warm/handcrafted, bold/display, playful; (3) if physical_products is active: which display modes to use (product grid / collections / bundles / category sections); (4) overall mood / reference brands they like. Then generate the DesignDirection JSON and present a summary (palette, fonts, pages, mood) for user confirmation before calling apply_design_direction. The design_direction_schema in required_reading has the full shape. Alternatively use set_design_direction to let SellHapi's Claude generate it (costs credits).",
                     },
                     {
                         step: 2,
                         tool: "apply_wireframe",
                         required: false,
-                        description: "Optional but recommended. Generate mid-fidelity HTML wireframes for each page, present them section-by-section to the user, collect feedback, then store the approved wireframes. Read sellhapi://wireframe-schema first.",
+                        description: "Optional but recommended. Generate mid-fidelity HTML wireframes for each page, present them section-by-section to the user, collect feedback, then store the approved wireframes. The wireframe_schema in required_reading has full conventions and data-hook reference.",
                     },
                     {
                         step: 3,
@@ -75,7 +77,9 @@ function registerStudioTools(server) {
                 ],
             },
             required_reading: {
-                instruction: "Read build_rules and runtime_hooks in full before generating any storefront code. Violating build_rules causes push_code to fail with a BuildGuard error.",
+                instruction: "Read ALL four documents below before generating any storefront code. design_direction_schema and wireframe_schema must be read before Step 1. build_rules and runtime_hooks must be read before Step 3 (push_code). Violating build_rules causes push_code to fail with a BuildGuard error.",
+                design_direction_schema: design_direction_schema_js_1.DESIGN_DIRECTION_SCHEMA,
+                wireframe_schema: wireframe_schema_js_1.WIREFRAME_SCHEMA,
                 build_rules: build_rules_js_1.BUILD_RULES,
                 runtime_hooks: runtime_hooks_js_1.RUNTIME_HOOKS,
             },
@@ -120,7 +124,7 @@ function registerStudioTools(server) {
     // ── Push code (zero credits) ───────────────────────────────────────────────
     server.registerTool("push_code", {
         title: "Push Code",
-        description: "Push client-generated React code to a project. Runs BuildGuard validation + esbuild bundling and returns a preview URL. ZERO AI credit cost — you generate the code, SellHapi only builds it. CRITICAL RULES: (1) import ONLY from @sellhapi/studio-runtime and react — NO external packages; (2) every top-level JSX section must have data-region, data-label, data-scope attributes; (3) NO inline style={{}} — use Tailwind only; (4) NO localStorage/sessionStorage for state management — EXCEPTION: window.location.href IS required and allowed for payment redirects (all commerce hooks return { paymentLink } — redirect with window.location.href = result.paymentLink); (5) prices via priceKobo / 100 — never hardcode currency. Call get_build_rules or get_runtime_hooks for full reference.",
+        description: "Push client-generated React code to a project. Runs BuildGuard validation + esbuild bundling and returns a preview URL. ZERO AI credit cost — you generate the code, SellHapi only builds it. CRITICAL RULES: (1) import ONLY from @sellhapi/studio-runtime and react — NO external packages; (2) every top-level JSX section must have data-region, data-label, data-scope attributes; (3) use inline React style objects for ALL styling — Tailwind is NOT available; (4) NO localStorage/sessionStorage for state management — EXCEPTION: window.location.href IS required and allowed for payment redirects (all commerce hooks return { paymentLink } — redirect with window.location.href = result.paymentLink); (5) prices via priceKobo / 100 — never hardcode currency. Call get_build_rules or get_runtime_hooks for full reference.",
         inputSchema: {
             projectId: v4_1.z.string().describe("Studio project ID"),
             files: v4_1.z.record(v4_1.z.string(), v4_1.z.string()).describe("Map of filename → code content. Must include App.tsx as entry point."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellhapi/mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "SellHapi MCP server — build and manage SellHapi storefronts from AI tools",
   "bin": {
     "sellhapi-mcp": "./dist/index.js"