Real-World Testing Guide¶

Version: 1.1
Date: January 20, 2026
Status: Active

This guide walks you through setting up a complete real-world testing environment for Forma3D.Connect, connecting all external services to test the full order-to-shipment flow.

Table of Contents¶

1. Overview
2. Prerequisites
3. Part 1: Shopify Development Store
4. Part 2: SimplyPrint Setup
5. Part 3: Sendcloud Sandbox
6. Part 4: Product Configuration (Benchy)
7. Part 4b: Multi-Color Printing (Bambu Lab AMS)
8. Part 5: Forma3D.Connect Configuration
9. Part 6: End-to-End Testing
10. Troubleshooting
11. Part 7: AI-Assisted Development with MCP Servers and CLIs

Overview¶

The real-world testing setup connects:

Test Flow: 1. Customer purchases a Benchy (green/white/grey) on Shopify test store 2. Shopify sends webhook to Forma3D.Connect 3. Forma3D.Connect creates print job in SimplyPrint with correct color/file 4. When print completes, Forma3D.Connect creates shipping label via Sendcloud 5. Order is fulfilled in Shopify with tracking number

Prerequisites¶

You'll also need: - Forma3D.Connect staging environment deployed - Access to Azure DevOps variable groups - 3D printer connected to SimplyPrint (or SimplyPrint virtual printer for testing)

Part 1: Shopify Development Store¶

1.1 Create a Shopify Partners Account¶

1. Go to partners.shopify.com
2. Sign up for a free Shopify Partners account
3. Complete the partner registration

1.2 Create a Development Store¶

1. In the Partners Dashboard, click Stores → Add store
2. Select Development store
3. Configure:
4. Store name: forma3d-test (or similar)
5. Store purpose: Select Create a store to test and build
6. Development store login: Your email and password
7. Click Save

Your store URL will be: forma3d-test.myshopify.com

1.3 Create a Custom App (for API Access)¶

1. In your development store admin, go to Settings → Apps and sales channels
2. Click Develop apps → Allow custom app development → Allow
3. Click Create an app
4. Name it: Forma3D Connect
5. Click Configure Admin API scopes and enable:
6. read_orders
7. write_orders
8. read_products
9. write_products
10. read_fulfillments
11. write_fulfillments
12. read_inventory
13. Click Save → Install app
14. Note down:
15. Admin API access token (starts with shpat_)
16. API key
17. API secret key

1.4 Configure Webhooks¶

1. Go to Settings → Notifications → Webhooks
2. Click Create webhook for each:

1. Set webhook format to JSON
2. Note the webhook signing secret (for verification)

1.5 Enable Test Mode / Bogus Gateway¶

For test purchases without real credit cards:

1. Go to Settings → Payments
2. Scroll to Shopify Payments → Manage
3. Enable Test mode (toggle at the top)

Test Credit Card Numbers: | Card Type | Number | Expiry | CVV | |-----------|--------|--------|-----| | Visa (success) | 4242 4242 4242 4242 | Any future date | Any 3 digits | | Visa (decline) | 4000 0000 0000 0002 | Any future date | Any 3 digits | | Mastercard | 5555 5555 5555 4444 | Any future date | Any 3 digits |

Note: You can also use Shopify Payments test mode or Bogus Gateway (1 for success in credit card fields).

Part 2: SimplyPrint Setup¶

2.1 Create/Access SimplyPrint Account¶

1. Go to simplyprint.io
2. Create an account or log in to your existing account
3. Ensure you have a Pro or Team plan for API access

2.2 Get API Credentials¶

1. Go to Settings → API (or Developer Settings)
2. Generate an API Key
3. Note your Company ID (format: S123456 or numeric)

2.3 Connect Your Printer(s)¶

If you don't have a physical printer for testing:

1. You can use SimplyPrint's Virtual Printer feature for testing
2. Go to Printers → Add Printer → Virtual Printer

For real printers: 1. Install SimplyPrint on your printer (OctoPrint plugin, Klipper, etc.) 2. Follow SimplyPrint's setup wizard

2.4 Upload Benchy Files¶

You need to upload 3 versions of the Benchy STL (one for each color):

1. Download the Benchy model from MakerWorld
2. Go to Files in SimplyPrint
3. Create a folder: benchy-variants
4. Upload the STL file 3 times with distinct names:
5. benchy-green.stl (or pre-sliced .gcode/.3mf)
6. benchy-white.stl

7. benchy-grey.stl

8. Note down the File ID for each file:

9. Click on each file → look at the URL or file details
10. File IDs are used in product mappings

Tip: If using pre-sliced files, ensure each uses the correct filament color profile.

2.5 Configure Webhooks (Optional but Recommended)¶

For real-time print status updates:

1. Go to Settings → Webhooks
2. Add webhook URL: https://staging-connect-api.forma3d.be/simplyprint/webhooks
3. Select events:
4. Job Started
5. Job Done
6. Job Failed
7. Job Cancelled
8. Note the webhook secret for verification

Part 3: Sendcloud Sandbox¶

3.1 Create Sendcloud Account¶

1. Go to panel.sendcloud.sc/register
2. Sign up for a free trial account
3. Complete the registration and email verification

3.2 Enable Test Mode¶

Sendcloud operates in test mode by default for new accounts. To verify:

1. Go to Settings → Integrations
2. Look for Test Mode indicator (usually shown in the dashboard header)

In test mode: - Labels are generated with "TEST" watermark - No real shipping charges apply - Tracking numbers are simulated

3.3 Get API Credentials¶

1. Go to Settings → Integrations → Sendcloud API
2. Click Create new integration (or view existing)
3. Note down:
4. Public Key
5. Secret Key

3.4 Configure Sender Address¶

1. Go to Settings → Addresses → Sender addresses
2. Add your test sender address:
3. Company: Forma3D Test
4. Address: Your test address
5. City, Postal Code, Country
6. Note the Sender Address ID (visible in URL or settings)

3.5 Select Default Shipping Method¶

1. Go to Shipping → Shipping methods
2. Browse available carriers for your country
3. Select a test-friendly carrier (e.g., PostNL, DHL, bpost)
4. Note the Shipping Method ID (visible when you click on the method)

Common shipping method IDs: | Carrier | Method | ID (example) | |---------|--------|--------------| | PostNL | Standard | 8 | | DHL | Parcel | 2001 | | bpost | Domestic | 3001 |

Note: Exact IDs depend on your account and country. Check your Sendcloud dashboard.

Part 4: Product Configuration (Benchy)¶

4.1 Create Shopify Products¶

In your Shopify development store:

1. Go to Products → Add product
2. Create the Benchy product:

Product Details: - Title: 3D Benchy Test Boat - Description: The classic 3D printing benchmark model - Product type: 3D Print - Price: €9.99 (or any test price)

Add Variants: 1. Click Add options like size or color → Add option: Color 2. Add variant values: Green, White, Grey 3. For each variant, set a unique SKU:

1. Add product images (optional but helpful for testing)
2. Click Save

4.2 Note Product and Variant IDs¶

After saving, you can find IDs in the Shopify URL or via API:

Product URL: /admin/products/1234567890
Product ID: 1234567890 (or gid://shopify/Product/1234567890)

Variant URL: /admin/products/1234567890/variants/9876543210
Variant ID: 9876543210 (or gid://shopify/ProductVariant/9876543210)

4.3 Product Mapping: Linking Shopify to SimplyPrint¶

This is the critical step that tells Forma3D.Connect which 3D file to print for each product variant.

Understanding Product Mappings:

Create mappings for each color variant:

You need to create 3 product mappings (one per color variant), each pointing to a different SimplyPrint file.

Part 4b: Multi-Color Printing (Bambu Lab AMS)¶

If you have Bambu Lab printers with AMS (like the A1 Combo), you can offer multi-color prints. There are several approaches depending on your use case.

Approach 1: Pre-sliced Multi-Color Files (Recommended)¶

For true multi-color prints using AMS, upload pre-sliced .3mf files from Bambu Studio that have color/filament assignments baked in.

Setup Steps:

1. In Bambu Studio:
2. Import your model (STL/OBJ/3MF)
3. Paint or assign colors to different parts using the color painting tool
4. Configure filament types for each AMS slot

5. Slice and export as .3mf

6. In SimplyPrint:

7. Upload the .3mf file (preserves color assignments)
8. Ensure your Bambu printer is connected via SimplyPrint

9. AMS slot assignments are read from the .3mf file

10. In Shopify:

11. Create a variant for the multi-color option (e.g., "Rainbow")

12. SKU: BENCHY-RAINBOW-001

13. Product Mapping:

    {
      "sku": "BENCHY-RAINBOW-001",
      "productName": "3D Benchy - Rainbow",
      "assemblyParts": [{
        "partName": "Multi-color Benchy",
        "simplyPrintFileId": "YOUR_MULTICOLOR_3MF_FILE_ID",
        "simplyPrintFileName": "benchy-multicolor.3mf"
      }]
    }
    

Approach 2: Multiple Color Combinations as Variants¶

If you want to offer different multi-color combinations, create separate pre-sliced files for each:

Each file contains the same model but with different color assignments in the .3mf.

Approach 3: Assembly Mode (Multi-Part, Single Color Each)¶

For products made of multiple separately-printed parts (each in one color), use the existing assembly feature:

This creates separate print jobs for each part, which can be printed on different printers or sequentially.

AMS Slot Configuration¶

For consistent multi-color prints, standardize your AMS slot assignments:

Important: Your .3mf files must be sliced with the same slot assignments as your physical AMS configuration.

Understanding AMS Slot vs Color Assignment¶

Key concept: Bambu Studio slices for slots, not colors. The gcode says "use filament from Slot 1", not "use blue filament".

Two behaviors depending on filament type:

Production Print Farm Strategy¶

For automated, unattended printing (recommended for Forma3D.Connect):

Strategy: Standardize all printers identically

Printer 1 (A1 Combo):          Printer 2 (A1 Combo):
├── Slot 1: White PLA          ├── Slot 1: White PLA
├── Slot 2: Black PLA          ├── Slot 2: Black PLA
├── Slot 3: Green PLA          ├── Slot 3: Green PLA
└── Slot 4: Grey PLA           └── Slot 4: Grey PLA

Then slice ALL your multi-color files with this exact configuration. Any print can go to any printer.

For single-color products (like the Benchy color variants):

You don't need multi-color slicing. Instead: - Upload 3 identical .stl files (or the same file 3 times) - Each sliced with a single color from Slot 1 - Physically load the appropriate color in Slot 1 when that color's jobs are queued

Or use printer groups in SimplyPrint: - "Green Printer Group" → Printers loaded with green in Slot 1 - "White Printer Group" → Printers loaded with white in Slot 1 - Route jobs to the appropriate group based on the ordered color

Offline Slicing Workflow¶

You can slice without a connected printer:

1. Open Bambu Studio (no printer connection needed)
2. Select printer profile: A1 Combo
3. Configure AMS slots in the filament panel (virtual configuration)
4. Import and paint your model with colors
5. Slice → Generates gcode with slot assignments
6. Export as .3mf (preserves project + gcode + plate info)
7. Upload to SimplyPrint for later printing

The exported .3mf contains everything needed. When SimplyPrint sends it to your printer, it will use the slot assignments from your slice.

SimplyPrint + Bambu Lab Integration¶

SimplyPrint connects to Bambu printers via:

1. Bambu Cloud - Remote connection through Bambu's servers
2. Local Network - Direct LAN connection (faster, requires same network)

To set up in SimplyPrint: 1. Go to Printers → Add Printer 2. Select Bambu Lab 3. Enter your Bambu Cloud credentials or local IP 4. SimplyPrint will detect your A1 Combo and AMS configuration

Print Profile for Multi-Color¶

The defaultPrintProfile in ProductMapping can include AMS-specific settings:

{
  "defaultPrintProfile": {
    "material": "PLA",
    "qualityPreset": "0.20mm Standard",
    "infillPercentage": 15,
    "supportEnabled": false,
    "additionalSettings": {
      "amsEnabled": true,
      "flushingVolume": "medium",
      "primeWaste": "chute"
    }
  }
}

Note: Some settings depend on SimplyPrint's Bambu integration capabilities. Check SimplyPrint documentation for supported parameters.

Part 5: Forma3D.Connect Configuration¶

5.1 Update Azure DevOps Variable Group¶

Update the forma3d-staging variable group with your test credentials:

5.2 Deploy Configuration¶

After updating the variable group, trigger a deployment:

# Push a small change to develop branch, or trigger manually in Azure DevOps
git checkout develop
git commit --allow-empty -m "Trigger deployment for config update"
git push

5.3 Verify Connections¶

After deployment, check the health endpoints:

# Check API health (includes integration status)
curl https://staging-connect-api.forma3d.be/health

# Expected response includes:
# - database: connected
# - simplyprint: connected (if configured correctly)

# Check dependencies specifically
curl https://staging-connect-api.forma3d.be/health/dependencies

5.4 Create Product Mappings via API¶

Use the Forma3D.Connect API to create product mappings:

# Get your INTERNAL_API_KEY from the variable group
API_KEY="your-internal-api-key"
API_URL="https://staging-connect-api.forma3d.be"

# Create mapping for Green Benchy
curl -X POST "$API_URL/api/v1/product-mappings" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shopifyProductId": "1234567890",
    "shopifyVariantId": "9876543210001",
    "sku": "BENCHY-GREEN-001",
    "productName": "3D Benchy - Green",
    "description": "Green PLA Benchy test print",
    "defaultPrintProfile": {
      "material": "PLA",
      "infillPercentage": 20,
      "layerHeight": 0.2,
      "supportEnabled": false
    }
  }'

# Note the returned mapping ID, then add the assembly part (file reference)
MAPPING_ID="returned-mapping-id"

curl -X POST "$API_URL/api/v1/product-mappings/$MAPPING_ID/parts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partName": "Benchy Model",
    "partNumber": 1,
    "simplyPrintFileId": "YOUR_GREEN_FILE_ID",
    "simplyPrintFileName": "benchy-green.stl",
    "quantityPerProduct": 1
  }'

Repeat for White and Grey variants with their respective: - shopifyVariantId - sku - simplyPrintFileId

5.5 Alternative: Create Mappings via Dashboard¶

If the web dashboard is available:

1. Go to https://staging-connect.forma3d.be
2. Navigate to Mappings → New Mapping
3. Fill in the form for each color variant
4. Add the SimplyPrint file reference in the assembly parts section

Part 6: End-to-End Testing¶

6.1 Test Flow Checklist¶

• All product mappings created
• SimplyPrint files uploaded and IDs noted
• Webhooks configured and verified
• Health endpoints showing connected status

6.2 Place a Test Order¶

1. Open your Shopify test store: https://forma3d-test.myshopify.com
2. Add the 3D Benchy Test Boat - Green to cart
3. Proceed to checkout
4. Fill in a test shipping address
5. Use test credit card: 4242 4242 4242 4242
6. Complete the purchase

6.3 Verify Order Processing¶

1. Check Forma3D.Connect Dashboard:

   curl https://staging-connect-api.forma3d.be/api/v1/orders \
     -H "Authorization: Bearer $API_KEY"
   

2. Check Order Status:

3. Status should be PENDING → PROCESSING

4. Line item should show the correct product

5. Check Print Job:

6. A print job should be created in SimplyPrint
7. Verify the correct file was queued (green Benchy)

6.4 Simulate Print Completion¶

If using a virtual printer or want to simulate completion:

1. In SimplyPrint, manually mark the job as Completed
2. Or wait for the actual print to finish (if using real printer)

The webhook will notify Forma3D.Connect of completion.

6.5 Verify Shipping Label Creation¶

After all print jobs complete:

1. Check the order status changed to COMPLETED
2. Verify shipment was created:

   curl https://staging-connect-api.forma3d.be/api/v1/orders/ORDER_ID \
     -H "Authorization: Bearer $API_KEY"
   

3. Check for trackingNumber and trackingUrl in the response

4. In Sendcloud dashboard, verify the test label was created

6.6 Verify Shopify Fulfillment¶

1. Go to Shopify admin → Orders
2. The order should show as Fulfilled
3. Tracking information should be visible

Flow Diagram: How Color Selection Works¶

Troubleshooting¶

Order Not Appearing in Forma3D.Connect¶

1. Check webhook delivery in Shopify:

2. Settings → Notifications → Webhooks → Check response codes

3. Check API logs:

   ssh root@167.172.45.47
   docker logs forma3d-api | grep webhook
   

4. Verify webhook URL is correct (includes /shopify/webhooks)

Print Job Not Created¶

1. Check product mapping exists:

   curl https://staging-connect-api.forma3d.be/api/v1/product-mappings \
     -H "Authorization: Bearer $API_KEY" | jq '.[] | select(.sku == "BENCHY-GREEN-001")'
   

2. Check assembly part has SimplyPrint file ID:

3. The simplyPrintFileId must match an actual file in SimplyPrint

4. Check event logs:

   curl https://staging-connect-api.forma3d.be/api/v1/event-logs?orderId=ORDER_ID \
     -H "Authorization: Bearer $API_KEY"
   

   Look for product.unmapped events.

SimplyPrint Job Not Created¶

1. Verify SimplyPrint connection:

   curl https://staging-connect-api.forma3d.be/health/dependencies
   

2. Check SimplyPrint API key and company ID in variable group

3. Verify file exists in SimplyPrint:

4. Log into SimplyPrint dashboard
5. Check Files section for the referenced file ID

Shipping Label Not Created¶

1. Verify shipping is enabled:

2. SHIPPING_ENABLED must be true in variable group

3. Check Sendcloud credentials:

4. Public key and secret key must be correct

5. Check order has valid shipping address:

6. Country code must be valid ISO format (e.g., BE, NL, DE)

7. Check event logs for shipment errors

Wrong File Being Printed¶

1. Verify SKU matches exactly:
2. SKU in Shopify variant must match SKU in ProductMapping exactly

3. SKUs are case-sensitive

4. Check you have separate mappings for each color:

5. Each color variant needs its own ProductMapping with its own file ID

Push Notifications Not Working¶

Server says "Push notifications not configured"¶

1. Check VAPID environment variables are set:

   ssh root@167.172.45.47
   grep VAPID /opt/forma3d/.env
   

   You should see VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, and VAPID_SUBJECT.

2. Verify docker-compose passes VAPID vars:

   grep VAPID /opt/forma3d/docker-compose.yml
   

3. Recreate API container after adding VAPID:

   cd /opt/forma3d && docker compose up -d --force-recreate api
   

4. Test the VAPID endpoint:

   curl https://staging-connect-api.forma3d.be/api/v1/push/vapid-public-key
   

   Should return {"publicKey":"BGAS6q-..."}, not {"publicKey":null}.

Notifications sent but not received (macOS/Chrome)¶

1. Check macOS System Notifications:
2. Open System Settings → Notifications → Google Chrome
3. Ensure notifications are allowed

4. Check "Allow notifications" is enabled

5. Check Focus Mode / Do Not Disturb:

6. Look for moon icon in menu bar

7. Disable Focus mode if enabled

8. Check Chrome site permissions:

9. Go to chrome://settings/content/notifications

10. Verify staging-connect.forma3d.be is in "Allowed" list

11. Update the Service Worker:

12. Open the PWA or site in Chrome
13. Press Cmd+Option+I → Application tab → Service Workers
14. If there's a "waiting" worker, click skipWaiting

15. Or click Update to force update

16. Verify Service Worker has push handler: In DevTools Console, run:

    navigator.serviceWorker.ready.then(reg => console.log('SW:', reg.active?.scriptURL))
    

    Should show the sw.js URL.

Notifications work on mobile but not desktop¶

1. Check if PWA needs update:
2. The desktop PWA may have an old service worker without push handling

3. Uninstall and reinstall the PWA, or force update via DevTools

4. Clear service worker and reinstall:

5. Go to chrome://serviceworker-internals
6. Find staging-connect.forma3d.be and click Unregister
7. Reinstall the PWA from the browser

Stale subscriptions (sent count higher than devices receiving)¶

Old/invalid push subscriptions are automatically removed when they fail with a 410 Gone status. However, some stale subscriptions may linger if the push service hasn't invalidated them yet.

To manually check/clean subscriptions:

# Connect to database and list subscriptions
docker compose exec api npx prisma db execute --stdin <<< "SELECT id, \"userAgent\", \"createdAt\" FROM \"PushSubscription\" ORDER BY \"createdAt\" DESC;"

Part 7: AI-Assisted Development with MCP Servers and CLIs¶

This section documents how to configure MCP (Model Context Protocol) servers and CLI tools for Shopify, Sendcloud, and SimplyPrint to enable AI-assisted development, testing, and maintenance in Cursor.

7.1 Overview of MCP and CLI Integration¶

7.2 Shopify: Official MCP Server and CLI¶

Shopify provides official MCP servers and a comprehensive CLI tool.

7.2.1 Shopify Dev MCP Server¶

The Shopify Dev MCP server gives AI agents direct access to Shopify's development resources including API schemas, documentation, and Liquid validation tools.

Features: - Exposes Shopify's Admin GraphQL, Functions, Partner API, Storefront API schemas - Theme/Liquid validation (syntax checks, missing references) - Documentation search and retrieval - Polaris component information

Prerequisites: - Node.js 18+ (recommended: Node.js 20.10+)

Installation & Configuration:

1. Add to Cursor MCP configuration (.cursor/mcp.json or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    }
  }
}

1. Restart Cursor to load the MCP server

2. Verify by asking Cursor: "What fields are available on the Order type in Shopify Admin GraphQL?"

Use Cases for Forma3D.Connect: - Get accurate Shopify GraphQL schemas for order/fulfillment operations - Validate webhook payload structures - Look up correct API endpoints and authentication methods - Generate schema-correct code for Shopify integration

Additional Shopify MCP Servers:

Resources: - GitHub: https://github.com/Shopify/dev-mcp - Docs: https://shopify.dev/apps/build/devmcp

7.2.3 Shopify Admin MCP Servers (Community)¶

In addition to the official Dev MCP, there are community-built Admin MCP servers that can perform actual CRUD operations on your Shopify store (products, orders, customers, inventory, etc.).

Popular Options:

Installation & Configuration:

# Install globally
npm install -g @ajackus/shopify-mcp-server

# Or use npx
npx @ajackus/shopify-mcp-server

Add to Cursor MCP configuration:

{
  "mcpServers": {
    "shopify-admin": {
      "command": "npx",
      "args": ["-y", "@ajackus/shopify-mcp-server"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx",
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

Available Operations:

Required Shopify App Scopes:

For Forma3D.Connect operations, ensure your custom app has: - read_orders, write_orders - read_products, write_products - read_fulfillments, write_fulfillments - read_inventory, write_inventory

Use Cases for Forma3D.Connect: - Test order creation and fulfillment flows via AI - Debug webhook payloads by fetching actual order data - Verify product/variant configurations - Test fulfillment tracking updates

Security Considerations: - Never commit access tokens to version control - Use minimal required scopes - Consider using a separate test store for AI operations - Be cautious with write operations on production data

Resources: - @ajackus/shopify-mcp-server: https://www.npmjs.com/package/@ajackus/shopify-mcp-server - @tzenderman/shopify-mcp: https://github.com/tzenderman/shopify-mcp

7.2.2 Shopify CLI¶

The Shopify CLI is a comprehensive command-line tool for app and theme development.

Installation:

# npm
npm install -g @shopify/cli@latest

# pnpm (recommended for this project)
pnpm install -g @shopify/cli@latest

# Homebrew (macOS)
brew tap shopify/shopify
brew install shopify-cli

Key Commands:

# Authentication
shopify auth login                    # Log in to Shopify Partners
shopify auth logout                   # Log out

# App Development
shopify app init                      # Create new app
shopify app dev                       # Start development server
shopify app deploy                    # Deploy app changes

# Theme Development  
shopify theme dev                     # Start theme dev server
shopify theme pull                    # Download theme from store
shopify theme push                    # Upload theme to store
shopify theme console                 # Headless Liquid REPL

# Information
shopify version                       # Check CLI version

Configuration for Forma3D.Connect:

Create a .shopify-cli.json in the project root if needed:

{
  "project_type": "custom_app",
  "organization_id": "YOUR_PARTNER_ORG_ID"
}

Use Cases: - Test webhook configurations locally with shopify app dev - Validate Shopify app configurations - Manage development store connections

7.3 Sendcloud: Custom MCP Server (No Official Support)¶

Sendcloud does not have an official MCP server or CLI tool. However, you can create a custom MCP server that wraps their REST API.

7.3.1 Sendcloud API Overview¶

Sendcloud provides REST APIs for: - Shipping API: Create parcels, generate labels, compare rates - Service Points API: Retrieve pickup locations - Returns API (V3): Handle return shipments - Tracking API: Track shipment status - Dynamic Checkout API: Service options based on zones/time

Authentication: Basic Auth with public/secret keys or OAuth2 (beta)

7.3.2 Building a Custom Sendcloud MCP Server¶

You can create a custom MCP server to expose Sendcloud operations to Cursor AI.

Create tools/sendcloud-mcp/server.ts:

import { MCPServer, Tool } from '@modelcontextprotocol/sdk';

const SENDCLOUD_PUBLIC = process.env.SENDCLOUD_PUBLIC_KEY;
const SENDCLOUD_SECRET = process.env.SENDCLOUD_SECRET_KEY;
const AUTH = Buffer.from(`${SENDCLOUD_PUBLIC}:${SENDCLOUD_SECRET}`).toString('base64');

const BASE_URL = 'https://panel.sendcloud.sc/api/v2';

async function fetchSendcloud(endpoint: string, options: RequestInit = {}) {
  const response = await fetch(`${BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Basic ${AUTH}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });
  return response.json();
}

const server = new MCPServer();

// Tool: Get shipping methods
server.tool({
  name: 'sendcloud_get_shipping_methods',
  description: 'List available shipping methods/carriers for the account',
  parameters: {
    type: 'object',
    properties: {
      sender_country: { type: 'string', description: 'ISO country code of sender' },
      to_country: { type: 'string', description: 'ISO country code of destination' },
    },
  },
  handler: async (params) => {
    const result = await fetchSendcloud('/shipping_methods');
    return result;
  },
});

// Tool: Create parcel/label
server.tool({
  name: 'sendcloud_create_parcel',
  description: 'Create a parcel and generate shipping label',
  parameters: {
    type: 'object',
    properties: {
      name: { type: 'string', description: 'Recipient name' },
      address: { type: 'string', description: 'Street address' },
      city: { type: 'string', description: 'City' },
      postal_code: { type: 'string', description: 'Postal code' },
      country: { type: 'string', description: 'ISO country code' },
      shipment_id: { type: 'number', description: 'Shipping method ID' },
      weight: { type: 'number', description: 'Weight in grams' },
    },
    required: ['name', 'address', 'city', 'postal_code', 'country', 'shipment_id'],
  },
  handler: async (params) => {
    const result = await fetchSendcloud('/parcels', {
      method: 'POST',
      body: JSON.stringify({ parcel: params }),
    });
    return result;
  },
});

// Tool: Track parcel
server.tool({
  name: 'sendcloud_track_parcel',
  description: 'Get tracking information for a parcel',
  parameters: {
    type: 'object',
    properties: {
      parcel_id: { type: 'number', description: 'Sendcloud parcel ID' },
    },
    required: ['parcel_id'],
  },
  handler: async (params) => {
    const result = await fetchSendcloud(`/parcels/${params.parcel_id}`);
    return result;
  },
});

// Run server
server.run({ transport: 'stdio' });

Add to Cursor MCP configuration:

{
  "mcpServers": {
    "sendcloud": {
      "command": "npx",
      "args": ["ts-node", "tools/sendcloud-mcp/server.ts"],
      "env": {
        "SENDCLOUD_PUBLIC_KEY": "your-public-key",
        "SENDCLOUD_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

Alternative: Use MCP SDK directly

npm install @modelcontextprotocol/sdk

7.3.3 Sendcloud API Reference¶

For building MCP tools, reference these key endpoints:

API Documentation: https://www.sendcloud.dev/docs/

7.4 SimplyPrint: Community MCP Server + API¶

SimplyPrint does not have an official MCP server or CLI tool. However, there are community solutions and their comprehensive API can be wrapped.

7.4.1 Community 3D Printer MCP Server¶

The mcp-3d-printer-server by DMontgomery40 supports multiple 3D printer backends including connections compatible with SimplyPrint workflows.

Features: - Printer status queries (temps, progress) - File management (upload, list, delete) - Print job control (start, cancel) - STL manipulation (scale, rotate, slice) - Supports: OctoPrint, Klipper/Moonraker, Duet, Repetier, Bambu Labs, Prusa Connect, Creality

Installation:

# Global install
npm install -g mcp-3d-printer-server

# Or from source
git clone https://github.com/dmontgomery40/mcp-3d-printer-server.git
cd mcp-3d-printer-server
npm install
npm link

Configuration (.env):

# Printer connection
PRINTER_HOST=192.168.1.100
PRINTER_PORT=80
PRINTER_TYPE=octoprint    # octoprint, klipper, bambu, prusa, creality
API_KEY=your_printer_api_key

# Temporary file storage
TEMP_DIR=/tmp/mcp-3d-temp

# For Bambu Lab printers
BAMBU_SERIAL=YOUR_PRINTER_SERIAL
BAMBU_TOKEN=YOUR_ACCESS_TOKEN

# Slicer settings (optional)
SLICER_TYPE=prusaslicer
SLICER_PATH=/usr/local/bin/prusaslicer
SLICER_PROFILE=/path/to/profile.ini

Add to Cursor MCP configuration:

{
  "mcpServers": {
    "3d-printer": {
      "command": "mcp-3d-printer-server",
      "env": {
        "PRINTER_HOST": "192.168.1.100",
        "PRINTER_TYPE": "octoprint",
        "API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools:

Resources: - GitHub: https://github.com/DMontgomery40/mcp-3d-printer-server - MCP Hub: https://mcphub.tools/detail/DMontgomery40/mcp-3D-printer-server

7.4.2 SimplyPrint API Overview¶

SimplyPrint provides a comprehensive REST API for print farm management.

Base URL: https://api.simplyprint.io/{company_id}/

Authentication: - Header: X-API-KEY: {API_KEY} - Requires Pro or Team plan

Key Endpoints:

Webhook Events: - job.started, job.done, job.failed, job.cancelled - printer.material_changed, printer.status_changed

7.4.3 Building a Custom SimplyPrint MCP Server¶

Create a custom MCP server for SimplyPrint operations:

Create tools/simplyprint-mcp/server.ts:

import { MCPServer } from '@modelcontextprotocol/sdk';

const SIMPLYPRINT_API_KEY = process.env.SIMPLYPRINT_API_KEY;
const SIMPLYPRINT_COMPANY_ID = process.env.SIMPLYPRINT_COMPANY_ID;
const BASE_URL = `https://api.simplyprint.io/${SIMPLYPRINT_COMPANY_ID}`;

async function fetchSimplyPrint(endpoint: string, options: RequestInit = {}) {
  const response = await fetch(`${BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'X-API-KEY': SIMPLYPRINT_API_KEY!,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });
  return response.json();
}

const server = new MCPServer();

// Tool: Get printers
server.tool({
  name: 'simplyprint_get_printers',
  description: 'List all printers and their current status',
  parameters: { type: 'object', properties: {} },
  handler: async () => {
    return await fetchSimplyPrint('/printers');
  },
});

// Tool: Get print queue
server.tool({
  name: 'simplyprint_get_queue',
  description: 'Get the current print queue',
  parameters: { type: 'object', properties: {} },
  handler: async () => {
    return await fetchSimplyPrint('/queue');
  },
});

// Tool: Add to queue
server.tool({
  name: 'simplyprint_add_to_queue',
  description: 'Add a file to the print queue',
  parameters: {
    type: 'object',
    properties: {
      file_id: { type: 'string', description: 'SimplyPrint file ID' },
      printer_id: { type: 'string', description: 'Target printer ID (optional)' },
      copies: { type: 'number', description: 'Number of copies', default: 1 },
    },
    required: ['file_id'],
  },
  handler: async (params) => {
    return await fetchSimplyPrint('/queue/AddItem', {
      method: 'POST',
      body: JSON.stringify(params),
    });
  },
});

// Tool: Get job status
server.tool({
  name: 'simplyprint_get_job',
  description: 'Get status of a specific print job',
  parameters: {
    type: 'object',
    properties: {
      job_id: { type: 'string', description: 'Job ID' },
    },
    required: ['job_id'],
  },
  handler: async (params) => {
    return await fetchSimplyPrint(`/jobs/${params.job_id}`);
  },
});

server.run({ transport: 'stdio' });

Add to Cursor MCP configuration:

{
  "mcpServers": {
    "simplyprint": {
      "command": "npx",
      "args": ["ts-node", "tools/simplyprint-mcp/server.ts"],
      "env": {
        "SIMPLYPRINT_API_KEY": "your-api-key",
        "SIMPLYPRINT_COMPANY_ID": "your-company-id"
      }
    }
  }
}

API Documentation: https://apidocs.simplyprint.io/

7.5 Complete Cursor MCP Configuration¶

Here's a complete .cursor/mcp.json configuration for all integrations:

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    },
    "shopify-admin": {
      "command": "npx",
      "args": ["-y", "@ajackus/shopify-mcp-server"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx",
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com"
      }
    },
    "3d-printer": {
      "command": "mcp-3d-printer-server",
      "env": {
        "PRINTER_HOST": "192.168.1.100",
        "PRINTER_TYPE": "bambu",
        "BAMBU_SERIAL": "YOUR_SERIAL",
        "BAMBU_TOKEN": "YOUR_TOKEN"
      }
    },
    "simplyprint": {
      "command": "npx",
      "args": ["ts-node", "tools/simplyprint-mcp/server.ts"],
      "env": {
        "SIMPLYPRINT_API_KEY": "${SIMPLYPRINT_API_KEY}",
        "SIMPLYPRINT_COMPANY_ID": "${SIMPLYPRINT_COMPANY_ID}"
      }
    },
    "sendcloud": {
      "command": "npx", 
      "args": ["ts-node", "tools/sendcloud-mcp/server.ts"],
      "env": {
        "SENDCLOUD_PUBLIC_KEY": "${SENDCLOUD_PUBLIC_KEY}",
        "SENDCLOUD_SECRET_KEY": "${SENDCLOUD_SECRET_KEY}"
      }
    }
  }
}

Note: Replace ${VAR} placeholders with actual values or use environment variable references.

7.6 Summary: Integration Status¶

7.7 Recommended Setup for Forma3D.Connect¶

For optimal AI-assisted development:

1. Always install Shopify Dev MCP - Provides schema-accurate code generation for orders, fulfillments, webhooks

2. Consider Shopify Admin MCP (@ajackus/shopify-mcp-server) - Allows AI to perform actual operations on your test store (fetch orders, create fulfillments, etc.)

3. Install Shopify CLI globally - Useful for testing webhooks and app configurations

4. Consider building custom MCP servers for Sendcloud and SimplyPrint if you frequently need AI assistance with:

5. Debugging shipping label creation
6. Testing print queue operations

7. Understanding API response structures

8. For 3D printer debugging, the community mcp-3d-printer-server can connect directly to your printers for status queries during development

Minimum recommended configuration:

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    }
  }
}

Full recommended configuration for development/testing:

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    },
    "shopify-admin": {
      "command": "npx",
      "args": ["-y", "@ajackus/shopify-mcp-server"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx",
        "SHOPIFY_STORE_DOMAIN": "forma3d-test.myshopify.com"
      }
    }
  }
}

This gives Cursor AI: - Dev MCP: Accurate Shopify API schemas and documentation - Admin MCP: Ability to fetch/manipulate actual store data for debugging and testing

Quick Reference¶

URLs¶

Test Credit Cards¶

API Endpoints¶

Revision History: