diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index 49f6d8ec..48730643 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -72,6 +72,11 @@ "name": "pstack", "source": "pstack", "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence." + }, + { + "name": "yolfi", + "source": "yolfi", + "description": "Add crypto checkout, payment links, signed webhooks, and payment verification with Yolfi." } ] } diff --git a/yolfi/.cursor-plugin/plugin.json b/yolfi/.cursor-plugin/plugin.json new file mode 100644 index 00000000..afb4ffa0 --- /dev/null +++ b/yolfi/.cursor-plugin/plugin.json @@ -0,0 +1,34 @@ +{ + "name": "yolfi", + "displayName": "Yolfi Payments", + "version": "0.2.0", + "description": "Add crypto checkout, payment links, signed webhooks, and payment verification with Yolfi.", + "author": { + "name": "Yolfi" + }, + "homepage": "https://yolfi.com/ai-agent-kit", + "repository": "https://github.com/yolfinance/yolfi-agent", + "license": "MIT", + "logo": "./assets/favicon.ico", + "keywords": [ + "payments", + "crypto", + "stablecoins", + "checkout", + "webhooks", + "mcp" + ], + "category": "payments", + "tags": [ + "payments", + "crypto", + "checkout", + "mcp" + ], + "skills": "./skills/", + "mcpServers": { + "yolfi": { + "url": "https://app.yolfi.com/mcp" + } + } +} diff --git a/yolfi/LICENSE b/yolfi/LICENSE new file mode 100644 index 00000000..4466f570 --- /dev/null +++ b/yolfi/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Yolfi + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/yolfi/README.md b/yolfi/README.md new file mode 100644 index 00000000..41fa0732 --- /dev/null +++ b/yolfi/README.md @@ -0,0 +1,15 @@ +# Yolfi Payments + +Add non-custodial crypto checkout flows to applications from Cursor. The plugin combines Yolfi's hosted OAuth MCP server with an integration skill for creating payment links and checkout sessions, configuring signed webhooks, and verifying payment status. + +## Connect + +Install the plugin from Cursor's marketplace and invoke a Yolfi tool. Cursor opens the Yolfi authorization flow in your browser; no API key needs to be pasted into the MCP configuration. + +The server is also available locally with: + +```bash +npx -y @yolfi/agent mcp +``` + +Documentation: https://yolfi.com/ai-agent-kit diff --git a/yolfi/assets/favicon.ico b/yolfi/assets/favicon.ico new file mode 100644 index 00000000..2f5a8c81 Binary files /dev/null and b/yolfi/assets/favicon.ico differ diff --git a/yolfi/skills/yolfi-payments/SKILL.md b/yolfi/skills/yolfi-payments/SKILL.md new file mode 100644 index 00000000..9b4b9cde --- /dev/null +++ b/yolfi/skills/yolfi-payments/SKILL.md @@ -0,0 +1,51 @@ +--- +name: yolfi-payments +description: Add Yolfi crypto checkout, payment links, and webhook handling to an app through the hosted Yolfi MCP server. +--- + +# Yolfi Payments Skill + +Use this when the user asks to add crypto payments, payment links, checkout, subscriptions, donations, or webhook-based entitlements with Yolfi. + +## Workflow + +1. Inspect the target app first. +2. Identify the framework, env system, server routes, existing checkout code, existing webhook handlers, and entitlement logic. +3. This marketplace plugin uses the hosted MCP transport. Complete Cursor's host-managed OAuth flow, then call `yolfi_auth_status`. Do not run local CLI setup, check-in, or signup commands; they are not part of this plugin transport. +4. Call `yolfi_organization_get`, `yolfi_webhooks_list`, and `yolfi_paylinks_list` before proposing mutations. +5. Ask the user for the exact settlement account ids, wallet addresses, and enabled token ids. Never invent them. Configure only approved values with `yolfi_settlement_configure`. +6. Ask the user for product name, price, currency, payment type, and recurring interval. +7. Before creating a webhook, ask for its publicly reachable HTTPS callback URL, the adapter that matches the app's existing handler (`NONE`, `STRIPE`, or `LEMON_SQUEEZY`), and any `metadataFilters` needed for routing. Never guess these values. Compare the URL, adapter, and complete filter map with `yolfi_webhooks_list`: reuse an exact match; update a specifically user-approved endpoint with `yolfi_webhooks_update`; otherwise create a distinct endpoint with `yolfi_webhooks_configure`. +8. Treat a signing secret returned by webhook creation or rotation as one-time secret material. Never repeat it in chat, commit it, or put it in ordinary source/config. Store it only through a user-approved deployment secret mechanism; if none is available, stop and ask the user to store it. +9. Reuse a matching result from `yolfi_paylinks_list`; otherwise create an approved paylink with `yolfi_paylinks_create`. +10. Store paylink ids in env/config, not hard-coded source when avoidable. +11. Add checkout UI or a server route that calls `POST /api/public/payments`. Pass a stable merchant-side customer/user id as `clientReferenceId` whenever webhook-driven attribution or subscription lifecycle updates must resolve that customer. +12. Add webhook signature verification for `X-Yolfi-Signature`. In native (`NONE`) payloads read `data.customer.clientReferenceId`; Stripe-compatible Checkout Session uses `data.object.client_reference_id`, while Stripe-compatible Invoice and Subscription objects use `data.object.metadata.client_reference_id`; Lemon Squeezy-compatible payloads use `meta.custom_data.client_reference_id`. +13. Connect webhook events to the app's existing entitlement/business logic when possible. +14. Verify payment status with `yolfi_payments_status`; a frontend redirect is not proof of payment. +15. Report changed files and exact verification commands. + +## Webhook Contract + +- Publicly supported endpoint adapters are `NONE`, `STRIPE`, and `LEMON_SQUEEZY`. Treat `NONE` as native Yolfi payload format, not as the absence of a provider. +- Create and manage independent endpoints with `yolfi_webhooks_configure`, `yolfi_webhooks_update`, `yolfi_webhooks_rotate_secret`, and `yolfi_webhooks_delete`; the removed organization-level `webhookUrl` and `webhookAdapter` fields are not supported. +- Each endpoint has its own signing secret. The hosted MCP returns it once on create or rotation, so provision it through the target deployment's secret manager immediately and never expose it in normal output. +- `YOLFI_API_KEY` authorizes Yolfi API calls and must never be used to verify webhook signatures. Verify `X-Yolfi-Signature` with that endpoint's signing secret only. +- Endpoint create/update accepts optional flat `metadataFilters` string maps (at most 10 entries; keys at most 100 characters; values at most 255 characters); a delivery must match every configured key/value. +- Cursor owns OAuth for this hosted MCP connection. Local `yolfi_agent_*` setup, check-in, and signup flows are not exposed by this plugin transport. +- Analytics routing uses `website_id`. Provision an adapter `NONE` endpoint with `metadataFilters: { "website_id": "" }`. + +## Do Not + +- Do not invent wallet addresses. +- Do not invent webhook callback URLs or adapters. +- Do not invent prices, plans, currencies, or recurring intervals. +- Do not commit API keys or webhook secrets. +- Do not call local setup, check-in, or signup tools from this hosted plugin. +- Do not pass webhook signing secrets as MCP arguments or ordinary CLI flags. +- Do not bypass available MCP tools with private REST endpoints. +- Do not replace existing billing logic unnecessarily. +- Do not use frontend redirect as proof of payment. +- Do not disable paylinks without explicit user approval. +- Do not duplicate webhook business handlers when an existing handler can be reused. +- Do not use email as the primary subscription identity when `clientReferenceId` can be supplied.