# siteforge-mcp

An MCP server that takes payment for a website and publishes it — but only after
Stripe confirms the money arrived.

Standalone. No shared code, imports, or infrastructure with any other project.

## Tools

| Tool | In | Out |
|---|---|---|
| `service_status` | — | which halves are configured (no secrets echoed) |
| `create_checkout_session` | `product_name`, `amount_usd`, `success_url`, `cancel_url`, `recurring` | `{checkout_url, session_id}` |
| `check_session_status` | `session_id` | `{payment_status, paid, customer_email, published_url}` |
| `publish_site` | `session_id`, `html`, `business_name` | `{url, claim_url, site_id, deploy_id, deploy_state}` |
| `check_deploy` | `deploy_id` | `{state, live, url}` |

## The one rule this server exists to enforce

`publish_site` is the paywall. The caller is a browser artifact — it can be
edited by anyone with devtools, so it is never believed. The only thing it can
send is a `session_id`, and the server asks Stripe directly whether that session
is paid. There is no parameter that lets a caller assert payment.

Second-order protections:

- A paid session maps to exactly one Netlify site, recorded in that session's
  Stripe metadata. Republishing with the same session updates the same site, so
  one payment cannot mint unlimited sites. Metadata also means no database.
- No card number ever touches this server. Customers pay on Stripe's hosted
  page, which keeps the whole thing out of PCI scope.
- Secrets live only in this process's environment.

## Site ownership

Sites are created under your umbrella Netlify team, then handed over. Each
response includes a `claim_url` — a signed link that transfers the site into the
customer's own Netlify account. You keep deploy access afterward, so paid edits
still work, but their hosting is on their account. Set the OAuth vars below to
enable it; without them `claim_url` is `null` and sites stay yours.

## Setup

1. **Stripe key** — dashboard.stripe.com/apikeys. Start with `sk_test_`.
2. **Netlify token** — app.netlify.com/user/applications → personal access tokens.
3. **Team slug** — Netlify team settings → general. Use a team dedicated to
   customer sites, not your personal one.
4. **OAuth app** (for claiming) — app.netlify.com/user/applications → OAuth
   applications → Create new. No redirect URI needed for deploy-and-claim.
   Copy the client ID and secret.

Copy `.env.example` to `.env` for local runs. On Render, set the same keys under
Environment. `render.yaml` is included — deploy from repo, free plan is fine.

```bash
pip install -r requirements.txt
python server.py            # serves on http://localhost:8000/mcp
```

## Tests

```bash
pip install -r requirements-dev.txt
pytest -q                   # 66 tests, no network or credentials needed
```

Stripe and Netlify are both stubbed. Stripe responses are built with
`construct_from`, so tests see the same object types a live call returns —
that is what catches the version issue described below.

## Verified

- Server boots; `initialize`, `tools/list` and `tools/call` answer correctly
  over streamable HTTP.
- `publish_site` refuses every non-`paid` payment status and never touches
  Netlify for one. It takes no argument through which a caller could assert
  payment — the artifact can only hand over a `session_id`.
- One paid session maps to one site: republishing redeploys the recorded
  `site_id` instead of creating a second site.
- Once a deploy succeeds the URL always comes back. No Stripe failure on the
  bookkeeping write afterward can turn a live, paid-for site into a failed call;
  it degrades to a `warning` field.
- Every Stripe and Netlify failure returns `{ok, error, how_to_fix}` rather than
  a raw exception, and Stripe's partially-masked API key is never echoed back.
- Misconfiguration names the missing variable.
- HTML fragments and oversized documents are rejected before Stripe is called.
- Claim link JWT signs and verifies with the expected `client_id` / `session_id`,
  and a broken OAuth secret yields `claim_url: null` instead of failing a publish.

## Not yet verified

- A real payment moving `unpaid` → `paid`, and a real Netlify deploy. Both need
  live credentials. That is the first thing to run once this is on Render.
- Subscription (`recurring=true`) checkout has not been exercised end to end;
  the session is constructed correctly but no real subscription has been billed.

## A note on the Stripe version

`stripe-python` 12 stopped making `StripeObject` a `dict` subclass. On 12+,
`session.metadata` is not a mapping: `.get()` raises `AttributeError`, `{**...}`
raises `TypeError`, and an empty one is truthy so `or {}` never falls back. Since
this server keeps its payment→site mapping in Stripe metadata, every read goes
through `_stripe_dict()`, which normalizes all of those shapes — plus absent and
null fields — to a plain dict. It works on 11 and 12+ alike. Don't reach for
`session.metadata` directly when adding code.

## v1 scope

No refunds, no webhooks, no custom domains, no multi-page sites. Add them when a
customer asks, not before.