salla-mcp-server / rules
Cursor rule7 starsChanged 18 months agoMITView on GitHub
This rule explains how to create a remote MCP server on Cloudflare with both free and paid tools (using Stripe).
- Reads credentials
Where files are headingNew Cursor rule files have more rules about planning and tracking tasks, and fewer about code style.
Of the Cursor rule files we read, the 4,243 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
The file
We split this mcp-server.mdc into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 38
Use REUSABLE_PAYMENT_REASON from @src/helpers/constants.ts for payment prompts.
- Very specific: line 42
Use a specific paymentReason (often combining a custom message with METERED_TOOL_PAYMENT_REASON from @src/helpers/constants.ts) to inform …
- Very specific: line 66
Payment Flow: When a user attempts to use a paid tool without prior payment, the PaidMcpAgent initiates a Stripe Checkout session.
≈ “Common” is an estimate: at least 1 in 5 of the 6,809 Cursor rule files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
---
description: This rule explains how to create a remote MCP server on Cloudflare with both free and paid tools (using Stripe).
globs:
alwaysApply: false
---
# MCP Boilerplate Project Overview
This rule provides a guide to understanding the structure and core functionalities of the MCP Boilerplate project. It's designed to help you navigate and extend the boilerplate effectively.
## Core Architecture
The project is a Cloudflare Worker that implements an MCP (Model Context Protocol) server with built-in support for user authentication and Stripe payments.
- **Main Entry Point**: `src/index.ts`
- Initializes the `BoilerplateMCP` agent, which extends `PaidMcpAgent` from `@stripe/agent-toolkit/cloudflare`.
- Sets up routing using Hono, handling the homepage (`@src/pages/index.html`), payment success page (`@src/pages/payment-success.html`), and Stripe webhooks (`@src/webhooks/stripe.ts`).
- Configures the `OAuthProvider` for handling authentication flows, defaulting to Google (`@src/auth/google-handler.ts`) but switchable to GitHub (`@src/auth/github-handler.ts`).
- **Configuration**:
- `wrangler.jsonc`: Defines Cloudflare Worker settings, including Durable Objects (`BoilerplateMCP`), KV namespaces (`OAUTH_KV` for storing OAuth related data), and compatibility flags.
- `package.json`: Lists project dependencies like `@modelcontextprotocol/sdk`, `@stripe/agent-toolkit/cloudflare`, `hono`, `zod`, and OAuth providers. It also contains scripts for development (`dev`) and deployment (`deploy`).
- `.dev.vars` (from `@.dev.vars.example`): Stores local development secrets and environment variables such as API keys for Google, GitHub, Stripe, and `BASE_URL`.
## Tool Creation
MCP tools are defined in the `src/tools/` directory. Each tool is typically in its own file and then exported via `src/tools/index.ts` to be registered in `src/index.ts` within the `BoilerplateMCP.init()` method.
- **Free Tools**:
- Defined using `agent.server.tool()`.
- Example: `@src/tools/add.ts` (simple addition) and `@src/tools/calculate.ts` (more complex calculations).
- Input parameters are validated using `zod`.
- **Paid Tools**:
- Defined using `agent.paidTool()`. Tools can be subscription-based or metered.
- Both types require `BASE_URL` to be passed from environment variables.
- **Subscription Tools**:
- Require `STRIPE_SUBSCRIPTION_PRICE_ID` (for a recurring subscription product).
- Use `REUSABLE_PAYMENT_REASON` from `@src/helpers/constants.ts` for payment prompts.
- Example: `@src/tools/subscriptionAdd.ts`.
- **Metered Tools**:
- Require `STRIPE_METERED_PRICE_ID` (for a metered usage product).
- Use a specific `paymentReason` (often combining a custom message with `METERED_TOOL_PAYMENT_REASON` from `@src/helpers/constants.ts`) to inform users about metered billing.
- Require a `meterEvent` string in the tool definition, which must match an event name configured in your Stripe meter for that product/price. This event is used to report usage to Stripe.
- Example: `@src/tools/meteredAdd.ts`.
- The `successUrl` (e.g., `${baseUrl}/payment/success`) redirects users after successful payment for both types, leading to `@src/pages/payment-success.html`.
## Authentication
Authentication is handled by `@cloudflare/workers-oauth-provider`, with specific implementations for Google and GitHub.
- **Handlers**:
- `@src/auth/google-handler.ts`: Manages the Google OAuth2 flow.
- `@src/auth/github-handler.ts`: Manages the GitHub OAuth flow.
- **Utilities**:
- `@src/auth/oauth.ts`: Contains helper functions like `getUpstreamAuthorizeUrl` and `fetchUpstreamAuthToken` for interacting with OAuth providers.
- `@src/auth/workers-oauth-utils.ts`: Provides utilities for rendering an approval dialog (`renderApprovalDialog`) and managing client approval status via cookies (`clientIdAlreadyApproved`, `parseRedirectApproval`). This uses a `COOKIE_ENCRYPTION_KEY` from `.dev.vars`.
- **Storage**: The `OAUTH_KV` namespace (configured in `wrangler.jsonc`) is used by the OAuth provider, likely for storing state or tokens related to the OAuth process.
## Payment Integration (Stripe)
Payments for paid tools are managed through Stripe integration, supporting both subscription and metered billing.
- **Core Component**: `experimental_PaidMcpAgent` from `@stripe/agent-toolkit/cloudflare` is the base for `BoilerplateMCP`, enabling paid tool functionality.
- **Configuration**: Requires `STRIPE_SECRET_KEY` in `.dev.vars`. For subscription tools, `STRIPE_SUBSCRIPTION_PRICE_ID` is needed. For metered tools, `STRIPE_METERED_PRICE_ID` is needed.
- **Webhook (Optional)**: `@src/webhooks/stripe.ts` handles incoming Stripe webhooks (e.g., `checkout.session.completed`) if configured. This requires `STRIPE_WEBHOOK_SECRET`.
- **Payment Flow**: When a user attempts to use a paid tool without prior payment, the `PaidMcpAgent` initiates a Stripe Checkout session. The `paymentReason` informs the user. For metered tools, usage is reported via a `meterEvent` defined in the tool, which corresponds to a Stripe meter.
## Frontend Pages
Simple HTML pages are served for basic interactions:
- `@src/pages/index.html`: A basic welcome page.
- `@src/pages/payment-success.html`: Shown after a user successfully completes a Stripe payment.
## Setup and Development
Refer to `@README.md` for detailed step-by-step instructions on setting up the project, including installing dependencies, configuring Cloudflare KV and secrets, and setting up OAuth applications and Stripe products.
Key commands from `package.json`:
- `npm run dev` (via `wrangler dev`): Starts the local development server.
- `npm run deploy` (via `wrangler deploy`): Deploys the worker to Cloudflare.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

