mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-23 09:07:46 +02:00
Dotta
a560b48d6d
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Apps give those agents governed access to external tools. > - Provider catalogs must match each provider's current protocol and credential contract. > - Postman method labels and API-key placement were outdated. > - Shopify now offers a UCP commerce endpoint that needs a managed agent-profile argument. > - This pull request updates both providers and documents the complete connection-authoring workflow. > - The benefit is accurate setup, safer runtime defaults, and a repeatable provider review process. ## Linked Issues or Issue Description Refs #11965 This is stack 10 of 11. It depends on stack 9 and preserves the final catalog work recovered from #11965. Related: #5904 covers Shopify skill routing. This pull request covers the Apps connection contract instead. ## What Changed - Update Postman hosted MCP methods, capability choices, default selection, and bearer-token placement. - Add Shopify UCP commerce and Storefront compatibility methods with public-store prerequisites. - Inject the reviewed Shopify UCP agent profile at runtime and remove that managed field from user input schemas. - Classify Shopify checkout completion and cancellation as destructive actions. - Expand the connection authoring runbook from provider research through verification and pull request handoff. - Add focused shared, server, and UI coverage. - Make the approved-execution waiter phase-aware so slow preparation cannot consume the provider execution timeout and grace period. - Settle legacy pre-execute-on-approve requests and invocations as failed, clear their stale idempotency key, and allow a fresh governed approval instead of leaving work stuck in `executing`. ## Verification - `pnpm exec vitest run packages/shared/src/app-definitions.test.ts server/src/__tests__/tool-access-service.test.ts ui/src/pages/apps/AppsConnect.test.tsx -t "Postman|Shopify|normalizeConnectionMethodConfig|classifyRisk"` (16 passed) - `pnpm exec vitest run server/src/services/approved-execution-wait.test.ts` (4 passed) - `pnpm exec vitest run server/src/__tests__/tool-gateway.test.ts -t "enforces policy, approvals, retries, rate limits, and company boundaries for connected remote MCP calls"` (1 passed) - `pnpm exec vitest run server/src/__tests__/tool-gateway-service.test.ts` (21 passed; includes legacy approval settlement and fresh-approval recovery) - `pnpm --filter @paperclipai/server typecheck` - `pnpm check:token-gates` - `pnpm -r typecheck` - `pnpm build` ## Risks - Shopify UCP calls now include a Paperclip-managed agent profile that overrides caller input at the same path. - Postman EU credentials now use the hosted MCP server's bearer-token contract instead of the general REST API header. - The catalog generator and checked-in definitions change together to prevent regeneration drift. - Approved execution preparation has an explicit two-minute bound; provider execution retains its own 65-second timeout and persistence grace starting from durable provider start. - Legacy approvals created before execute-on-approve are intentionally terminalized and must be requested again under the current signed contract. > I checked `ROADMAP.md`. This provider update does not duplicate planned core work. The related open Shopify PR addresses skill routing, not Apps connections. ## Model Used OpenAI Codex, GPT-5. The runtime exact model ID and context window were not exposed. The model used reasoning, tool use, and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge
118 lines
4.6 KiB
JSON
118 lines
4.6 KiB
JSON
{
|
|
"schemaVersion": 1,
|
|
"slug": "shopify",
|
|
"name": "Shopify",
|
|
"description": "Search a store's products and policies, and manage shopping carts.",
|
|
"categories": [
|
|
"commerce"
|
|
],
|
|
"featured": false,
|
|
"branding": {
|
|
"logoUrl": "/brands/apps/shopify.svg"
|
|
},
|
|
"urlPatterns": [
|
|
"https://*.myshopify.com/api/ucp/mcp",
|
|
"https://*.myshopify.com/api/mcp"
|
|
],
|
|
"methods": [
|
|
{
|
|
"key": "ucp-commerce",
|
|
"transport": "mcp_remote",
|
|
"auth": "none",
|
|
"ownershipModes": [
|
|
"customer"
|
|
],
|
|
"whenToUse": "Recommended for Shopify's current UCP catalog, cart, and checkout tools.",
|
|
"defaults": {
|
|
"serverUrlTemplate": "https://{storeDomain}/api/ucp/mcp",
|
|
"toolArgumentDefaults": {
|
|
"meta": {
|
|
"ucp-agent": {
|
|
"profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-04-08/valid-with-capabilities.json"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"guidanceMd": "Connect Shopify's current UCP server for shopper-facing catalog and commerce tools. Paperclip supplies the required agent profile automatically.",
|
|
"riskTier": "S3",
|
|
"label": "Shopify UCP commerce",
|
|
"tenantFields": [
|
|
{
|
|
"key": "storeDomain",
|
|
"label": "Store domain",
|
|
"type": "text",
|
|
"required": true,
|
|
"placeholder": "your-store.myshopify.com",
|
|
"helperMd": "Enter the permanent myshopify.com domain without https://. Custom storefront domains are not the MCP endpoint.",
|
|
"validation": {
|
|
"pattern": "^[A-Za-z0-9][A-Za-z0-9-]*\\.myshopify\\.com$",
|
|
"maxLength": 255
|
|
}
|
|
}
|
|
],
|
|
"consoleLinks": {
|
|
"docs": "https://shopify.dev/docs/agents/catalog/storefront-catalog"
|
|
},
|
|
"warnings": [
|
|
"This is Shopify's shopper-facing UCP server, not Admin API access. It does not manage merchant products or customers.",
|
|
"The storefront must be public. A private or password-protected storefront returns HTTP 401 even when the merchant is signed in to Shopify Admin.",
|
|
"Paperclip currently uses Shopify's documented hosted agent-profile fixture while Paperclip's production UCP profile is being established."
|
|
],
|
|
"requiredResourceFilters": [
|
|
"store"
|
|
]
|
|
},
|
|
{
|
|
"key": "storefront-mcp",
|
|
"transport": "mcp_remote",
|
|
"auth": "none",
|
|
"ownershipModes": [
|
|
"customer"
|
|
],
|
|
"whenToUse": "Use Shopify's compatibility server when agents need storefront policy and FAQ search.",
|
|
"defaults": {
|
|
"serverUrlTemplate": "https://{storeDomain}/api/mcp"
|
|
},
|
|
"guidanceMd": "Connect Shopify's official Storefront MCP server for shopper-facing catalog, policy, and cart tools.",
|
|
"riskTier": "S3",
|
|
"label": "Storefront policies and compatibility tools",
|
|
"tenantFields": [
|
|
{
|
|
"key": "storeDomain",
|
|
"label": "Store domain",
|
|
"type": "text",
|
|
"required": true,
|
|
"placeholder": "your-store.myshopify.com",
|
|
"helperMd": "Enter the permanent myshopify.com domain without https://. Custom storefront domains are not the MCP endpoint.",
|
|
"validation": {
|
|
"pattern": "^[A-Za-z0-9][A-Za-z0-9-]*\\.myshopify\\.com$",
|
|
"maxLength": 255
|
|
}
|
|
}
|
|
],
|
|
"consoleLinks": {
|
|
"docs": "https://shopify.dev/docs/apps/build/storefront-mcp/servers/storefront"
|
|
},
|
|
"warnings": [
|
|
"This is Shopify's Storefront MCP, not Admin API access. It does not manage merchant products, orders, or customers.",
|
|
"The storefront must be public. A private or password-protected storefront returns HTTP 401 even when the merchant is signed in to Shopify Admin."
|
|
],
|
|
"requiredResourceFilters": [
|
|
"store"
|
|
]
|
|
}
|
|
],
|
|
"docsUrl": "https://shopify.dev/docs/apps/build/storefront-mcp/servers/storefront",
|
|
"setupPrerequisite": {
|
|
"title": "Launch the storefront before connecting",
|
|
"description": "Shopify's Storefront MCP is a public, no-auth endpoint. Paperclip cannot use the merchant's Shopify Admin session to bypass a private storefront.",
|
|
"steps": [
|
|
"Select a Shopify plan; Shopify keeps trial storefronts private until a plan is selected.",
|
|
"In Shopify Admin, open Online Store → Preferences and set Storefront visibility to Public (remove password protection).",
|
|
"Use the permanent <store>.myshopify.com domain in Paperclip, even if the store also has a custom domain."
|
|
],
|
|
"actionLabel": "Open Shopify Admin",
|
|
"actionUrl": "https://admin.shopify.com/"
|
|
}
|
|
}
|