one.socialai/website-mcp

Build, edit, stock, and publish Social AI websites and storefronts via AI chat.

Open source Open in the app JSON README (API)

About

Build, edit, stock, and publish Social AI websites and storefronts via AI chat.

Details

Kind: MCP servers
Topic: E-commerce & business
Publisher: one.socialai
Origin: official
Category: ferramentas
Transport: http
Version: 1.5.2
Added: 2026-08-29 04:01:50
Updated: 2026-08-29 04:01:50
Origin id: one.socialai/website-mcp

README

# @socialai/website-mcp

Model Context Protocol server for the Social AI Website Builder.

Use Social AI from Claude, OpenAI Codex, Cursor, Windsurf, VS Code, or any MCP-compatible client to create websites, edit pages, manage shops, upload media, configure payments, inspect analytics, and publish live sites.

## What Users Can Do

- Create a blank website or shop.
- Create a website from a Social AI template.
- Browse block types with reference links before adding headers, heroes, promo/ad sections, product rows, forms, and footers.
- Use setup presets for shop categories, variants, header menus, footer columns, contact pages, and product CSVs.
- Edit pages and blocks.
- Generate website copy, page sections, and themes with AI.
- Manage products, variants, categories, CSV import/export, discounts, and orders.
- Upload and host images.
- Configure country, currency, payment provider, and public site settings.
- Check preview, domain, analytics, leads, snapshots, and media limits.
- Publish a site when the account has an active package website slot.

## Choose the Right Connection

For Claude.ai, Claude Desktop, Cowork, and other remote OAuth clients, add this custom connector URL:

```text
https://socialai.one/api/mcp
```

Complete Social AI sign-in, approve access, enable Social AI in a new conversation, and ask the client to call `get_started`. No npm install, JSON edit, or API key is required for this path.

For local CLI and IDE clients, use the npm package below. This path requires Node.js 18 or newer and a Social AI API key from `Settings -> API Keys`. Put the live key directly in the local config or secret store; never paste it into chat.

## Local Package Quick Start

Add this MCP server to a local AI client:

```json
{
"mcpServers": {
"socialai-websites": {
"command": "npx",
"args": ["-y", "@socialai/website-mcp"],
"env": {
"SOCIALAI_API_KEY": "sai_user_xxxxx",
"SOCIALAI_API_URL": "https://socialai.one"
}
}
}
}
```

Then restart your AI client and try:

```text
Help me create a Social AI website. Ask me one question at a time.
```

The MCP includes `get_started`, `get_proactive_next_steps`, `get_store_setup_preset`, `get_intake_questions`, `quick_build`, `product_csv(action="template")`, and a `socialai_start_website` prompt. Good AI clients can use those to guide the user through a friendly setup flow instead of dumping raw JSON.

For template browsing, ask for a small shortlist:

```text
Show me 5 shop templates with preview links for a South African fashion store.
```

For block browsing, ask for focused options:

```text
Show me 8 hero and header blocks with reference links.
```

## Claude Code

Add to `~/.claude/settings.json`:

## OpenAI Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.socialai_websites]
command = "npx"
args = ["-y", "@socialai/website-mcp"]

[mcp_servers.socialai_websites.env]
SOCIALAI_API_KEY = "sai_user_xxxxx"
SOCIALAI_API_URL = "https://socialai.one"
```

## Cursor or Windsurf

Add to `.cursor/mcp.json` or the Windsurf MCP settings:

## VS Code

Add to `.vscode/settings.json`:

```json
{
"mcp": {
"servers": {
"socialai-websites": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@socialai/website-mcp"],
"env": {
"SOCIALAI_API_KEY": "sai_user_xxxxx",
"SOCIALAI_API_URL": "https://socialai.one"
}
}
}
}
}
```

## Tool Groups

### Getting Started

- `get_started`
- `get_proactive_next_steps`
- `get_intake_questions`
- `get_store_setup_preset`
- `quick_build`
- `product_csv` with `action: "template"`
- `list_blocks`
- `list_block_types`
- Prompt: `socialai_start_website`
- Resources: `socialai://mcp/getting-started`, `socialai://mcp/workflows/create-website`

### Websites

- `list_templates`
- `create_website_from_template`
- `transfer_website_to_template`
- `manage_websites`
- `export_site`
- `apply_site`
- `publish_website`
- `get_preview_url`
- `manage_domain`
- `manage_snapshots`

### Pages and Navigation

- `update_page_blocks`
- `manage_pages`
- `manage_navigation`
- `manage_posts`

### Block Catalog

- `list_blocks`
- `list_block_types`

Use this before adding sections when the user wants to choose a block visually or by name. Each result includes `type`, `label`, `group`, `keywords`, and `referenceUrl`.

### AI and Theme

- `generate_content`
- `manage_theme`

### Store, Products, Orders, and Discounts

- `manage_products`
- `manage_variants`
- `manage_categories`
- `product_csv`
- `manage_orders`
- `manage_discounts`

### Media

- `manage_media`

### Payments and Settings

- `manage_store_settings`

### Analytics, Leads, Snapshots, and Support

- `get_traffic_summary`
- `list_leads`
- `report_issue`

### Marketplace sellers

- `manage_shop_seller` — run a third-party seller account on the main Social AI Shop marketplace. This is a different shop from the website-builder store: `manage_products` and the other store tools are scoped to a website project, while most marketplace listings have none, so a marketplace seller cannot reach their own catalogue through them. Covers products (list/get/update/delete, plus `set_offer` for shared listings where the price lives on the offer rather than the product), image upload from the local machine or an https URL, CSV export/preview/import matched on SKU, dispatch and collection addresses with the courier prices the customer is charged, orders and shipment marking, returns decisions, balance and payout requests. A new product is submitted for Social AI approval rather than published; `delete_product`, `delete_location`, `import_products` and `request_payout` require `confirm=true`; payouts go only to the bank account saved in the seller portal and cannot be redirected from MCP; an order shows only the calling seller's own lines. Every write is recorded against the acting agent. Intentionally excluded from the OpenAI review profile.

### Team & Partners

- `manage_team` — durable team inbox (`my_inbox`), assigned-task acknowledgement, submission with artifact URLs, owner approval/change requests, day/week/month work logs, and authorised team channels. Open Team pages receive live channel updates; assignments/submissions also send in-app notifications and email, while MCP clients retrieve state with `my_inbox` or `my_tasks`. Channel posts can optionally email recipients, and `@sai` answers with live team stats. Reports are filed to the owner and mirrored into `#bugs`.
- `manage_business_teams` — full-client multi-business administration: create/list businesses, select country/currency/accounting books, manage role-based members, choose Stripe/PayStack/PayFast and sandbox mode, narrow Team/MCP switches, and inspect accounting-linked customers/debtors. It never accepts or returns gateway secrets and is intentionally excluded from the OpenAI review profile.
- `manage_team_invoices` — full-client Team invoice CRUD, secure customer links, and confirmed email delivery. It can select Stripe, PayStack, or PayFast for the customer portal but cannot execute or mark a payment; signed provider webhooks do that. Delete and email actions require explicit confirmation. Administrators can disable Team invoicing, gateways, email, or the MCP invoice surface independently. This finance-adjacent tool is intentionally excluded from the OpenAI review profile.
- `manage_feedback_surveys` — full-client Team feedback survey CRUD, email preview, satisfaction/matrix/NPS/text questions, selected or all-Team delivery, invitation metrics, and response analysis. Delete and email actions require explicit confirmation. Team permissions and administrator switches are enforced, and the tool is intentionally excluded from the OpenAI review profile.
- `manage_feedback_surveys` — full-client Team feedback survey CRUD, email preview, satisfaction/matrix/NPS/text questions, selected or all-Team delivery, invitation metrics, and response analysis. Delete and email actions require explicit confirmation. Team permissions and administrator switches are enforced, and the tool is intentionally excluded from the OpenAI review profile.

## Example Prompts

```text
Help me create a Social AI website. Ask me one question at a time, then recommend templates.
```

```text
Show me 5 premium shop templates with preview links for a South African fashion store.
```

```text
Create a website from the best template for a premium dental clinic in Johannesburg.
```

```text
List my websites, make the newest one the active package-slot website, and show me the preview URL.
```

```text
Import this product CSV, upload the image URLs, create categories, and configure South African payments.
```

```text
Export only the demo products with source columns, then replace the demo products with my real CSV.
```

```text
Check my store orders, list open leads, and summarize the last 30 days of traffic.
```

```text
Duplicate the About page, rename it Our Story, update the navigation, and publish when I confirm.
```

```text
Show me promo/ad style blocks with reference links, then add the one I choose to the homepage.
```

## Template Browsing Without Huge Output

`list_templates` supports filters so AI clients do not need to load every template:

- `limit` and `offset` for pagination.
- `q` for natural search text such as `fashion`, `coffee`, `law`, or `skincare`.
- `projectType` as `website` or `shop`.
- `category` for category/tag filtering.
- `premium` for premium/free filtering.
- `includePages=false` and `summaryOnly=true` for short chat output.

Each result includes a `previewUrl` so the user can click and inspect the template before choosing it.

## Product CSV and Demo Products

Template shops can include demo products so the store looks complete before the seller adds their own catalog. Those demo rows are tagged separately from seller-imported rows.

- Use `product_csv` with `action: "template"` to create a fillable product CSV for the chosen store type.
- Use `product_csv` with `action: "export"` and `scope: "demo"` to download only template demo products.
- Use `product_csv` with `action: "export"` and `scope: "user"` to download only seller/imported products.
- Use `includeSource: true` when the AI or admin needs to see whether a row is demo or user-owned.
- Use `product_csv` with `action: "import"` and `replaceDemoProducts: true` when the seller confirms they want to delete the demo catalog and replace it with their real products.
- For a storefront URL migration, use Import Studio for the design direction and `import_products_from_url` for Shopify or WooCommerce/WordPress product feeds. Public WooCommerce works through the Store API; pass `wooConsumerKey` and `wooConsumerSecret` for private Woo catalogs and richer variation imports. The seller admin **Products -> Import products from a store URL** flow uses the same importer. URL imports create draft products first so the seller can review, edit, bulk-activate, mirror product images into Social AI storage, and publish intentionally.

The import endpoint imports core product fields plus supported variant/detail/spec columns. Follow-up MCP actions such as `manage_variants`, `manage_categories`, and `manage_products(action: "mirror_images")` can refine anything that needs custom handling after import.

## Safeguards and Entitlements

The MCP respects Social AI plan rules:

- API keys must have the right scopes.
- Paid package slots control publishing, commerce, payments, and custom-domain power.
- Draft sites can exist without being assigned to a paid package slot.
- Media uploads are checked against storage, monthly upload count, file size, dimensions, and image type limits.
- AI generation checks plan access, rate limits, and credit billing.
- Expired/free accounts can read where allowed, but write, publish, commerce, AI, and custom-domain tools can be blocked by plan state.
- Project-scoped keys can only access their pinned project.

When a tool is blocked, the server returns an error code such as:

- `mcp_access_denied`
- `website_edit_mode_denied`
- `inactive_package_slot`
- `active_package_slot_limit`
- `published_site_limit`
- `media_storage_limit`
- `monthly_media_upload_limit`
- `ai_provider_failed`

## Country-Aware Payments

Use `manage_store_settings` with `action: "set_payments"` and a country code:

```text
Configure this shop for South Africa.
```

The tool can set `country=ZA`, `currency=ZAR`, and recommend providers such as Paystack, PayFast, and Ozow. Payment provider secret keys are not accepted through MCP; they must be entered in the Social AI dashboard.

## Local Testing

PowerShell:

```powershell
cd C:\sai\SaiApp\mcp
$env:SOCIALAI_API_URL = "http://localhost:3000"
$env:SOCIALAI_API_KEY = "sai_user_xxxxx"
node test-local.mjs
```

Do not paste the `PS C:\...>` prompt itself. Only paste the commands.

## Publishing a New npm Version

The repository release contract is `mcp/compatibility.json`. The full OAuth endpoint is `https://socialai.one/api/mcp`; the OpenAI submission endpoint is the review-stable `https://socialai.one/api/mcp/openai`. Existing SocialAI entitlements apply on both endpoints, but the OpenAI profile does not expose checkout, subscription purchase, credit purchase, money transfer, or payment execution. `lib/mcpOpenAiPolicy.json` is the canonical OpenAI hint/payment policy; run `npm run generate:chatgpt-submission` and `npm run check:chatgpt-submission` whenever tools or hints change. Update the contract together with `mcp/package.json`, `mcp/package-lock.json`, the runtime version in `mcp/src/server.ts`, the public `/mcp` page, `public/llms.txt`, `mcp/SETUP.md`, and the admin MCP manual.

```powershell
cd C:\sai\SaiApp\mcp
npm login
npm version patch --no-git-tag-version
npm run build
npm pack --dry-run
npm publish --access public
cd ..
npm run check:mcp-registry
```

The npm package only updates the local stdio server. Deploy the Social AI web app so the matching `/api/mcp-api/*` routes, `https://socialai.one/api/mcp`, and `/mcp` instructions are current. Then complete a clean hosted OAuth test with any local stdio Social AI server disabled.

## Environment Variables

| Variable | Required | Description |
| --- | --- | --- |
| `SOCIALAI_API_KEY` | Yes | User or project API key from Social AI. |
| `SOCIALAI_API_URL` | No | Social AI API base URL. Defaults to `https://socialai.one`. |

## License

MIT

one.socialai/website-mcp

About

Details

README

More