mcp-boilerplate — Cursor Rules

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.

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.

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 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.