# Developer Kit
## What You Get
The Shopify Agentic MCP Gateway Developer Kit is a complete, production-ready codebase for adding autonomous AI commerce capabilities to any Shopify store. Every component is built, tested, and documented.
### Included Components
| Component | Description |
|-----------|-------------|
| **MCP Server** | 5 registered tools with Zod-validated schemas for scout_inventory, manage_cart, negotiate_terms, execute_checkout, track_order |
| **UCP Layer** | Profile publisher (`/.well-known/ucp`), capability negotiation engine, checkout state machine, catalog discovery facade |
| **AP2 Layer** | ES256 mandate signer, chain verifier (Intent/Cart/Payment), mandate store with DynamoDB migration path |
| **Guardrail Engine** | AI hallucination guard -- validates prices, inventory, mandate amounts, and checkout state transitions against real Shopify data |
| **Fee Collector** | Configurable platform fee calculation and ledger tracking |
| **Shopify Integration** | Storefront API (GraphQL) and Admin API (REST) client wrappers |
| **Serverless Config** | Production-ready `serverless.yml` with Lambda, API Gateway, and DynamoDB resources |
| **TypeScript Source** | Full source code with strict TypeScript, ESM modules, and comprehensive type definitions |
| **Test Suite** | Vitest test suite with MSW (Mock Service Worker) for API mocking |
| **Documentation** | Architecture guide, protocol references, deployment instructions, and code examples |
### Source Code Structure
```
shopify-agentic-mcp/
src/
index.ts Dual-mode entry point (Lambda + stdio)
server.ts MCP tool registrations
types.ts Shared type definitions (~300 lines)
tools/ 5 MCP tool implementations
ucp/ UCP protocol layer (5 modules)
ap2/ AP2 protocol layer (4 modules)
middleware/ Guardrail, fees, rate limiter, auth
shopify/ Shopify API client layer
utils/ Logger, errors, crypto utilities
tests/ Test suite
docs/ Documentation
examples/ Usage examples
serverless.yml AWS deployment config
tsconfig.json TypeScript config
package.json Dependencies and scripts
.env.example Environment variable template
```
---
## Pricing
### Starter (Free)
For evaluation and personal projects.
- Full source code access
- Community support via GitHub Issues
- MIT License
- Self-hosted only
- No SLA
### Pro ($49/month)
For production stores and professional developers.
- Everything in Starter, plus:
- Priority email support (48-hour response)
- Monthly updates and security patches
- Access to private Discord channel
- Pre-built CloudFormation templates
- Monitoring dashboards (CloudWatch templates)
### Enterprise ($199/month)
For agencies and high-volume merchants.
- Everything in Pro, plus:
- Dedicated Slack channel
- 4-hour response SLA
- Custom capability extensions
- Multi-store deployment support
- Architecture review sessions (monthly)
- Early access to new protocol versions
- White-label license
### Developer Kit (One-Time Purchase)
For developers building their own agentic commerce products.
| Tier | Price | Includes |
|------|-------|----------|
| **Kit Basic** | $99 | Source code + documentation + 30 days email support |
| **Kit Pro** | $199 | Kit Basic + 90 days support + 6 months updates + CloudFormation templates |
| **Kit Enterprise** | $299 | Kit Pro + 12 months updates + architecture consultation (2 hours) + multi-tenant license |
---
## Support and Updates
### Support Channels
| Channel | Availability | Tiers |
|---------|-------------|-------|
| GitHub Issues | Public, best-effort | All |
| Email Support | 48h response | Pro, Enterprise, Kit Pro+ |
| Discord (Private) | Community + team | Pro, Enterprise |
| Slack (Dedicated) | Direct access | Enterprise |
### Update Policy
- **Security patches**: Immediate release for all tiers
- **Bug fixes**: Monthly release cycle
- **Feature updates**: Quarterly release cycle
- **Protocol upgrades**: Released within 30 days of UCP/AP2/MCP specification updates
### Versioning
The gateway follows semantic versioning:
- **Major**: Breaking protocol changes (UCP version bump, MCP SDK major update)
- **Minor**: New features, new tools, new capabilities
- **Patch**: Bug fixes, security patches, dependency updates
---
## Getting Started for Kit Purchasers
### Step 1: Set Up Your Shopify App
1. Go to your [Shopify Partner Dashboard](https://partners.shopify.com/).
2. Create a new app (or use an existing one).
3. Enable the following API scopes:
- **Storefront API**: `unauthenticated_read_product_listings`, `unauthenticated_write_checkouts`, `unauthenticated_read_checkouts`
- **Admin API**: `read_orders`, `read_products`, `read_inventory`
4. Note your API key, API secret, and access tokens.
### Step 2: Install and Configure
```bash
# Install dependencies
npm install
# Copy environment template
cp .env.example .env
# Edit .env with your Shopify credentials
# (See docs/deployment.md for the full variable reference)
```
### Step 3: Test Locally
```bash
# Build
npm run build
# Run tests
npm test
# Start in stdio mode (for Claude Desktop)
npm start
```
### Step 4: Connect Claude Desktop
Add to your Claude Desktop config:
```json
{
"mcpServers": {
"shopify-agentic": {
"command": "node",
"args": ["/path/to/shopify-agentic-mcp/dist/index.js"],
"env": {
"SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com",
"SHOPIFY_STOREFRONT_TOKEN": "your_token"
}
}
}
}
```
### Step 5: Try It
Open Claude Desktop and try these prompts:
- *"Search for wireless headphones under $50"*
- *"Create a cart and add the cheapest headphones"*
- *"What shipping options are available?"*
- *"Track order #12345"*
### Step 6: Deploy to Production
See [docs/deployment.md](deployment.md) for the full AWS Lambda deployment guide.
---
## Customization Guide
### Adding Custom MCP Tools
Register new tools in `src/server.ts`:
```typescript
server.tool(
'your_custom_tool',
'Description of what this tool does.',
{
param1: z.string().describe('Parameter description'),
},
async (params) => {
// Your implementation here
return {
content: [{
type: 'text' as const,
text: JSON.stringify({ result: 'your data' }),
}],
};
},
);
```
### Extending UCP Capabilities
Add new capabilities in `src/ucp/profile.ts`:
```typescript
const DEFAULT_CAPABILITIES: UCPCapability[] = [
// ... existing capabilities
{ name: 'dev.ucp.shopping.checkout.loyalty', version: UCP_VERSION },
{ name: 'dev.ucp.shopping.catalog.recommendations', version: UCP_VERSION },
];
```
### Customizing Fee Logic
Modify `src/middleware/fee-collector.ts` to implement tiered fees, volume discounts, or alternative collection methods.
### Switching from In-Memory to DynamoDB
Every in-memory store (`MandateStore`, `CheckoutSessionManager`, cart store) includes annotated comments showing the DynamoDB equivalent operations. Replace the in-memory calls with AWS SDK DynamoDB calls following the comments.
---
## Frequently Asked Questions
**Q: Does this work with Shopify Plus?**
A: Yes. The gateway uses standard Storefront and Admin APIs, which are available on all Shopify plans. Shopify Plus provides higher API rate limits, which benefits high-volume deployments.
**Q: Can I use this with agents other than Claude?**
A: Yes. Any MCP-compatible agent can use the stdio or HTTP transport. The MCP SDK is protocol-level compatible -- it works with any LLM that implements MCP tool calling.
**Q: Is the AP2 mandate chain required?**
A: For `execute_checkout`, yes. The mandate chain is the security mechanism that prevents unauthorized purchases. For browsing (`scout_inventory`), cart management (`manage_cart`), and order tracking (`track_order`), no mandates are needed.
**Q: Can I run this on something other than AWS?**
A: The core MCP server runs anywhere Node.js runs. Only the serverless deployment config is AWS-specific. You can deploy to any platform that supports Node.js 22+ (Vercel, Railway, Docker, bare metal) by using the stdio or HTTP entry points.
**Q: How do I handle multi-currency stores?**
A: All amounts are in minor units with an explicit currency code. The checkout session and mandate chain enforce consistent currency throughout. Configure currency per checkout session when creating it.
