feat: add register_paid_tool for Python MCP servers

[mvanhorn]

The TypeScript toolkit has registerPaidTool for wrapping MCP tools with Stripe Checkout payment gating. Python has no equivalent.

This adds register_paid_tool to the Python toolkit, bringing parity with the TS implementation.

from stripe_agent_toolkit.mcp import register_paid_tool

register_paid_tool(
    mcp_server=server,
    tool_name="premium_analysis",
    tool_description="Run premium data analysis",
    params_schema={"type": "object"},
    callback=analyze_data,
    options={
        "payment_reason": "Access to premium analysis",
        "stripe_secret_key": os.environ["STRIPE_SECRET_KEY"],
        "user_email": user_email,
        "checkout": {
            "line_items": [{"price": "price_xxx", "quantity": 1}],
            "mode": "payment",
            "success_url": "https://example.com/success",
            "cancel_url": "https://example.com/cancel",
        },
    },
)

Supports all three payment modes from the TS version:

• One-time payments via Checkout
• Subscription-based access
• Usage-based metering via Stripe Billing meter events

The implementation mirrors the TS flow: get-or-create customer by email, check for existing paid session (with subscription verification), create Checkout session if unpaid, record meter events for usage-based billing, then call the original tool callback.

New files:

• tools/python/stripe_agent_toolkit/mcp/register_paid_tool.py - core implementation
• tools/python/stripe_agent_toolkit/mcp/__init__.py - module exports
• tools/python/tests/test_register_paid_tool.py - tests covering all payment modes + error cases

New optional dependency: stripe-agent-toolkit[mcp-payments] (adds stripe>=7.0.0)

Reference: registerPaidTool (TypeScript)

This contribution was developed with AI assistance (Codex).