@sellhapi/mcp 0.0.0-stage → 0.1.1

package/dist/resources/wireframe-schema.js

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

package/dist/server.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared MCP server factory.
+ *
+ * Both the stdio CLI entry point and the hosted HTTP entry point use this
+ * to create an identically-configured McpServer instance.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createMcpServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Shared MCP server factory.
+ *
+ * Both the stdio CLI entry point and the hosted HTTP entry point use this
+ * to create an identically-configured McpServer instance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpServer = createMcpServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+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 index_js_1 = require("./resources/index.js");
+function createMcpServer() {
+    const server = new mcp_js_1.McpServer({
+        name: "sellhapi",
+        version: "0.1.0",
+    });
+    (0, studio_js_1.registerStudioTools)(server);
+    (0, commerce_js_1.registerCommerceTools)(server);
+    (0, content_js_1.registerContentTools)(server);
+    (0, intelligence_js_1.registerIntelligenceTools)(server);
+    (0, index_js_1.registerResources)(server);
+    return server;
+}

package/dist/tools/commerce.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCommerceTools(server: McpServer): void;

package/dist/tools/commerce.js

@@ -0,0 +1,86 @@
+"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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCommerceTools = registerCommerceTools;
+const client_js_1 = require("../client.js");
+const util_js_1 = require("../util.js");
+function registerCommerceTools(server) {
+    // ── Products ───────────────────────────────────────────────────────────────
+    server.registerTool("list_products", {
+        title: "List Products",
+        description: "List all physical products for this vendor.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/products");
+        return JSON.stringify(data.products, null, 2);
+    }));
+    // ── Digital Products ───────────────────────────────────────────────────────
+    server.registerTool("list_digital_products", {
+        title: "List Digital Products",
+        description: "List all digital products (ebooks, courses, downloads) for this vendor.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/digital-products");
+        return JSON.stringify(data.products, null, 2);
+    }));
+    // ── Service Listings ───────────────────────────────────────────────────────
+    server.registerTool("list_service_listings", {
+        title: "List Service Listings",
+        description: "List all service listings for this vendor.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/service-listings");
+        return JSON.stringify(data.listings, null, 2);
+    }));
+    // ── Events ─────────────────────────────────────────────────────────────────
+    server.registerTool("list_events", {
+        title: "List Events",
+        description: "List all events for this vendor, including ticket types.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/events");
+        return JSON.stringify(data.events, null, 2);
+    }));
+    // ── Membership Tiers ───────────────────────────────────────────────────────
+    server.registerTool("list_membership_tiers", {
+        title: "List Membership Tiers",
+        description: "List all membership tiers for this vendor.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/memberships");
+        return JSON.stringify(data.tiers, null, 2);
+    }));
+    // ── Donation Campaigns ─────────────────────────────────────────────────────
+    server.registerTool("list_donation_campaigns", {
+        title: "List Donation Campaigns",
+        description: "List all donation campaigns for this vendor.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/donations/campaigns");
+        return JSON.stringify(data.campaigns, null, 2);
+    }));
+    // ── Appointments ───────────────────────────────────────────────────────────
+    server.registerTool("list_appointment_services", {
+        title: "List Appointment Services",
+        description: "List all bookable appointment services for this vendor.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/appointments/services");
+        return JSON.stringify(data.services, null, 2);
+    }));
+    // ── Capabilities ───────────────────────────────────────────────────────────
+    server.registerTool("list_capabilities", {
+        title: "List Capabilities",
+        description: "List all available capabilities and which ones are active for this vendor. Capabilities include: physical_products, digital_products, services, appointments, events, donations, memberships, content, listings, customer_accounts.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/capabilities");
+        return JSON.stringify(data.capabilities, null, 2);
+    }));
+}

package/dist/tools/content.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Content/CMS tools — read-only access to content items, forms, articles, collections.
+ *
+ * All URLs point to /api/mcp/* (API key auth). Write endpoints are not yet
+ * available on the MCP route layer.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerContentTools(server: McpServer): void;

package/dist/tools/content.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Content/CMS tools — read-only access to content items, forms, articles, collections.
+ *
+ * All URLs point to /api/mcp/* (API key auth). Write endpoints are not yet
+ * available on the MCP route layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerContentTools = registerContentTools;
+const client_js_1 = require("../client.js");
+const util_js_1 = require("../util.js");
+function registerContentTools(server) {
+    // ── Content Items ──────────────────────────────────────────────────────────
+    server.registerTool("list_content", {
+        title: "List Content",
+        description: "List all CMS content items (images, videos, testimonials, FAQs, etc.) for this vendor.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/content/items");
+        return JSON.stringify(data.items, null, 2);
+    }));
+    // ── Forms ──────────────────────────────────────────────────────────────────
+    server.registerTool("list_forms", {
+        title: "List Forms",
+        description: "List all forms (contact, order, survey, etc.) for this vendor.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/content/forms");
+        return JSON.stringify(data.forms, null, 2);
+    }));
+    // ── Collections ────────────────────────────────────────────────────────────
+    server.registerTool("list_collections", {
+        title: "List Collections",
+        description: "List all product collections for this vendor.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/collections");
+        return JSON.stringify(data.collections, null, 2);
+    }));
+    // ── Articles ───────────────────────────────────────────────────────────────
+    server.registerTool("list_articles", {
+        title: "List Articles",
+        description: "List all CMS articles/blog posts for this vendor.",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/content/articles");
+        return JSON.stringify(data.articles, null, 2);
+    }));
+}

package/dist/tools/intelligence.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Read-only intelligence tools — orders, wallet balance.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerIntelligenceTools(server: McpServer): void;

package/dist/tools/intelligence.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Read-only intelligence tools — orders, wallet balance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerIntelligenceTools = registerIntelligenceTools;
+const v4_1 = require("zod/v4");
+const client_js_1 = require("../client.js");
+const util_js_1 = require("../util.js");
+function registerIntelligenceTools(server) {
+    // ── Orders ─────────────────────────────────────────────────────────────────
+    server.registerTool("list_orders", {
+        title: "List Orders",
+        description: "List recent orders for this vendor. Returns order details, status, customer info, and products.",
+        inputSchema: {
+            status: v4_1.z.string().optional().describe("Filter by status: pending, confirmed, shipped, delivered, cancelled"),
+            limit: v4_1.z.number().optional().describe("Max orders to return (default 20, max 100)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ status, limit }) => (0, util_js_1.safeCall)(async () => {
+        const params = new URLSearchParams();
+        if (status)
+            params.set("status", status);
+        if (limit)
+            params.set("limit", String(limit));
+        const qs = params.toString();
+        const data = await (0, client_js_1.get)(`/api/mcp/orders${qs ? `?${qs}` : ""}`);
+        return JSON.stringify(data.orders, null, 2);
+    }));
+    // ── Wallet balance ─────────────────────────────────────────────────────────
+    server.registerTool("get_wallet_balance", {
+        title: "Get Wallet Balance",
+        description: "Get the vendor's current wallet balance (available funds and AI credits).",
+        annotations: { readOnlyHint: true },
+    }, async () => (0, util_js_1.safeCall)(async () => {
+        const data = await (0, client_js_1.get)("/api/mcp/wallet");
+        return JSON.stringify(data, null, 2);
+    }));
+}

package/dist/tools/studio.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Studio tools — website lifecycle management.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerStudioTools(server: McpServer): void;