# RevCent MCP Guide: `CreateSite` This guide is written for AI/MCP clients that need to create RevCent Sites correctly, safely, and with useful long-term ecommerce organization. --- ## Primary Operation ```text CreateSite ``` **Title:** Create A Site **Purpose:** Create a RevCent Site and receive a unique 20-character `site_id`. A RevCent Site is an AI-developed, RevCent-hosted ecommerce storefront, cart, or lander connected to RevCent Products, Product Groups, Payment Profiles, optional PayPal Accounts, and live routing. At this time, the RevCent Sites feature is in beta. Users and merchants are responsible for developing, testing, reviewing, and approving Site changes before relying on them for live customer traffic. --- ## When to Use Use `CreateSite` when the user wants to create a new ecommerce Site connected to RevCent. Good uses: - create a new storefront for a Product Group, - create a campaign-specific lander or cart, - create a Site that AI can help customize, - create a dev/live ecommerce experience tied to a Payment Profile, - prepare a Site that can later receive a Tracking Domain. Do not use `CreateSite` to edit an existing Site, attach a Tracking Domain, inspect status, or retrieve logs. --- ## Required Preparation Before calling `CreateSite`, identify: | Value | Required | How to Choose | |---|---:|---| | `name` | Yes | Use a clear, unique Site name. | | `payment_profile` | Yes | Use the Payment Profile that should process Site credit card payments. | | `product_group` | Yes | Use the Product Group that should power the Site catalog. | | `collaborators` | Yes | Provide at least one valid GitHub username that should be invited to the Site repository. | | `description` | No | Add context that helps humans and AI understand the Site purpose. | | `paypal_account` | No | Include only when PayPal checkout should be available for the Site. | Never guess IDs. Use relevant list/get operations first when IDs are not known. ## Product Metadata for Site Catalogs Before creating a Site, review the Products in the Product Group that will power the Site catalog. Each Product intended for the Site catalog may include Site catalog metadata in the Product's `metadata` array: ```json [ { "name": "slug", "value": "organic-coffee-beans" }, { "name": "site_categories", "value": "[\"coffee/beans\",\"subscriptions\"]" } ] ``` Use `slug` for a clear, URL-friendly Product slug that is unique within the Site catalog. Use `site_categories` as a JSON array string of slash-delimited category paths. A Product can be assigned to more than one category path, and nested categories are represented with slashes, such as `apparel/mens/shirts`. Paths with more than three levels are ignored. This metadata helps AI and the Site storefront organize product URLs, category pages, collection filters, landing pages, and product presentation. It does not replace Product Group membership, Product ID, price, shipping, subscription, or other authoritative Product fields. --- ## Input Schema `CreateSite` accepts the following request body. ```json { "name": "string", "description": "string", "paypal_account": "XXXXXXXXXXXXXXXXXXXX", "payment_profile": "XXXXXXXXXXXXXXXXXXXX", "product_group": "XXXXXXXXXXXXXXXXXXXX", "collaborators": [ "github-username" ] } ``` ### Required Fields | Field | Type | Required | Description | |---|---:|---:|---| | `name` | `string` | Yes | The Site name. Must be unique from other Site names. | | `payment_profile` | `string` | Yes | A 20-character Payment Profile ID used for credit card sales on the Site. | | `product_group` | `string` | Yes | A 20-character Product Group ID used as the Site catalog source. | | `collaborators` | `array` | Yes | Valid GitHub usernames allowed as collaborators. At least one collaborator is required. | ### Optional Fields | Field | Type | Required | Description | |---|---:|---:|---| | `description` | `string` | No | Human-readable Site description. | | `paypal_account` | `string` | No | A 20-character PayPal Account ID. Only include when the Site accepts PayPal payments. | ### Important Schema Rules - Do not include unknown properties. - `payment_profile`, `product_group`, and `paypal_account` values must be 20-character RevCent IDs when provided. - `collaborators` must contain at least one GitHub username. - Collaborators are invited through GitHub. Repository access is not available until the collaborator accepts the GitHub invite. - A Site name must be unique. - Creating a Site does not attach a Tracking Domain. Use `AddTrackingDomainToSite` later when the custom domain is ready. --- ## Collaborator Invite and AI Customization Workflow `CreateSite` invites the provided collaborators to the Site's GitHub repository. Collaborators must accept the GitHub repository invitation before they can access, clone, or edit the Site source. After accepting the invite, a collaborator can clone the repository locally and use an AI coding tool, AI IDE, copilot, agent, or MCP-enabled workflow to customize and update the ecommerce store. The Site repository includes detailed documentation for developing, customizing, testing, and maintaining that specific Site. After cloning the repository locally, AI should read the repository documentation before making source-code, design, page behavior, cart behavior, checkout logic, offer flow, or custom business-logic changes. These public RevCent markdown files intentionally do not include the full repository-level documentation. They describe the RevCent-facing operation and workflow; the issued Site repository contains the detailed local development guidance. Recommended user-facing explanation: ```text RevCent hosts the Site. AI is the intended developer for the Site. Collaborators receive GitHub repository invites, accept those invites, clone the repository locally, read the repository documentation, then use AI tools to customize the storefront. ``` AI/MCP clients should not tell the user to customize the Site in a RevCent web-app site builder. RevCent Sites are intended to be created and updated through AI-assisted repository development while RevCent hosts the resulting ecommerce Site. After creation, use `EditSite` only for supported Site configuration changes. Actual Site code, design, page behavior, cart behavior, checkout business logic, offer flow, and custom ecommerce logic are edited through the Site repository. --- ## Beta Feature and Repository Responsibility RevCent Sites intentionally provide full access to the Site repository for users, collaborators, and AI-assisted development workflows. This gives the user or merchant a high degree of flexibility. AI can modify the storefront, cart, lander, presentation, and supporting ecommerce behavior at the source level instead of being constrained by a closed visual builder or walled-garden SaaS platform. That flexibility comes with responsibility. Before creating a Site, AI/MCP clients should make sure the user understands: - The RevCent Sites feature is currently in beta. - RevCent hosts the Site, but the user or merchant is responsible for development and testing. - Collaborators and AI tools with repository access can make meaningful changes to the ecommerce experience. - Changes should be reviewed and tested carefully before being treated as live-ready. - The dev branch should be used for testing and review before relying on main/live behavior. Recommended user-facing explanation: ```text The RevCent Sites feature gives you full AI-editable repository access while RevCent hosts the ecommerce Site. That flexibility is powerful, but during beta you are responsible for carefully developing, testing, and approving changes before sending customers to the Site. ``` --- ## Output Schema A successful `CreateSite` response includes the new Site ID. ```json { "api_call_id": "XXXXXXXXXXXXXXXXXXXX", "api_call_unix": 1710000000, "code": 1, "site_id": "XXXXXXXXXXXXXXXXXXXX", "result": "string" } ``` ### Output Fields | Field | Type | Description | |---|---:|---| | `api_call_id` | `string` | A 20-character API call ID. | | `api_call_unix` | `integer` | Unix timestamp of when the API call was initiated. | | `code` | `integer` | API response code. `1` means success. | | `site_id` | `string` | The 20-character Site ID that was created. | | `result` | `string` | Human-readable operation result. | --- ## Minimal Request Example ```json { "name": "Acme Summer Store", "description": "Customer-facing ecommerce Site for the Acme summer product collection.", "payment_profile": "XXXXXXXXXXXXXXXXXXXX", "product_group": "YYYYYYYYYYYYYYYYYYYY", "collaborators": [ "acme-developer" ] } ``` --- ## Request Example With PayPal Use this when PayPal should be available on the Site. ```json { "name": "Acme Summer Store", "description": "Customer-facing ecommerce Site for the Acme summer product collection with credit card and PayPal checkout.", "payment_profile": "XXXXXXXXXXXXXXXXXXXX", "product_group": "YYYYYYYYYYYYYYYYYYYY", "paypal_account": "ZZZZZZZZZZZZZZZZZZZZ", "collaborators": [ "acme-developer", "acme-designer" ] } ``` --- ## Recommended Follow-Up After a successful `CreateSite` call: 1. Save the returned `site_id` in the conversation context. 2. Call `GetSite` with that `site_id`. 3. Inspect `deployment.status`, `deployment.health`, `deployment.branches`, and `catalog`. 4. Tell the user whether the Site is still being created, ready, degraded, unavailable, or needs attention. 5. Remind collaborators to accept the GitHub invite before trying to access or clone the repository. 6. Once repository access is accepted, guide the collaborator to clone the repository locally for AI-assisted customization. 7. Have AI read the repository documentation before making Site code, design, or business-logic changes. 8. Remind the user that the RevCent Sites feature is in beta and that they are responsible for testing and approving Site changes. 9. Explain that `EditSite` is for configuration only and repository edits are required for code or business-logic changes. 10. Use `GetSiteEvents` if the user wants recent activity details. --- ## Best Practices 1. Confirm the Product Group before creating the Site. 2. Confirm the Payment Profile before creating the Site. 3. Include PayPal only when needed. 4. Use clear Site names, such as `{Brand} Store`, `{Campaign} Lander`, or `{Product Line} Cart`. 5. Include a useful description so future AI workflows understand the Site's purpose. 6. Confirm collaborator usernames with the user before submitting. 7. Review Products in the Product Group and add `metadata` entries with `name` = `slug` and `name` = `site_categories` when the Site catalog should use stable slugs or category organization. 8. Explain that collaborators must accept the GitHub invite before cloning or editing the Site source. 9. Tell AI to read the Site repository documentation after local clone. 10. Position AI as the developer/customization method for the Site. 11. Explain that full repository access is intentional and should be used carefully. 12. Encourage dev-branch testing before main/live usage. 13. Do not describe the custom domain as live until a Tracking Domain has been attached and routing/DNS are ready. --- ## Final MCP Instruction Use `CreateSite` only when the user explicitly wants a new RevCent Site and the required Product Group, Payment Profile, and collaborator values are known or have been confirmed. --- Document Parent Directory * [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.