solostack-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SoloStack Contributors
+
+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.

package/README.md

@@ -0,0 +1,213 @@
+# SoloStack
+
+Email marketing that your AI agent deploys and runs. No sign-ups, no dashboards, no SaaS subscriptions.
+
+You say: *"Set up email marketing for my site."*
+Your AI agent provisions a Cloudflare Worker, creates a database, verifies your sending domain, and hands you a working email stack. Then it runs it — subscribing users, sending broadcasts, tracking delivery — all through conversation.
+
+## The Demo
+
+```
+You:    Set up email marketing on zeroheadcount.com
+Claude: I'll provision your email stack now.
+
+        ✅ Worker deployed: solostack-zeroheadcount.ivy-audit.workers.dev
+        ✅ D1 database created with subscriber + email log tables
+        ✅ Secrets configured (API keys, bearer token)
+        ✅ Health check passing
+
+        Next: I need to verify your sending domain.
+        Add these DNS records to zeroheadcount.com:
+          CNAME  bounce  →  bounce.resend.net
+          TXT    ...     →  v=spf1 include:...
+          TXT    ...     →  v=DKIM1; p=...
+
+You:    Done, added them.
+Claude: Verifying... ✅ Domain verified. Webhook registered.
+
+You:    Send a welcome email to sarah@example.com
+Claude: ✅ Sent "Welcome to Zero Headcount" to sarah@example.com
+
+You:    How many subscribers do I have?
+Claude: 47 active subscribers. 3 unsubscribed this week.
+```
+
+No CLI commands. No config files. No dashboard tabs. Just conversation.
+
+## How It Works
+
+SoloStack is two things:
+
+1. **A provisioner** — a local MCP server that creates your email infrastructure via Cloudflare and Resend APIs
+2. **An email engine** — a Cloudflare Worker that handles subscribers, sends emails, and tracks delivery
+
+The provisioner runs locally (your AI agent connects via stdio). After setup, it acts as a gateway — proxying your email commands to the deployed worker.
+
+```
+Your AI Agent (Claude, Cursor, etc.)
+    │
+    │  stdio
+    │
+    ▼
+Local Provisioner (12 MCP tools)
+    │
+    ├── Provisioning tools → Cloudflare API + Resend API
+    │   (provision, upgrade, domain setup, migrate)
+    │
+    └── Gateway proxy → Deployed Worker /mcp
+        (subscribe, send_email, broadcast, etc.)
+            │
+            ├── D1 database (subscribers, email log)
+            ├── Resend API (email delivery)
+            └── Webhook endpoint (delivery tracking)
+```
+
+## Tools
+
+### Provisioning (runs locally)
+
+| Tool | What it does |
+|------|-------------|
+| `provision_solostack` | Creates Worker + D1 database + schema + secrets. One call, full stack. |
+| `check_status` | Health check — is the worker running, what version, subscriber count |
+| `setup_email_domain` | Adds your domain to Resend, returns DNS records to add |
+| `verify_email_domain` | Polls until domain is verified, then auto-registers webhook |
+| `migrate_subscribers` | Import subscribers from CSV (any provider — just needs an `email` column) |
+| `upgrade_solostack` | Upload new worker bundle with rollback on health failure |
+
+### Email operations (proxied to deployed worker)
+
+| Tool | What it does |
+|------|-------------|
+| `subscribe` | Add or re-activate a subscriber (idempotent) |
+| `unsubscribe` | Mark subscriber as unsubscribed |
+| `list_subscribers` | List subscribers with status/tag filtering + pagination |
+| `get_subscriber_count` | Count subscribers by status or tag |
+| `send_email` | Send a single email to one recipient |
+| `send_broadcast` | Send to all active subscribers (max 100, filterable by tag) |
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- A Cloudflare account ([free tier](https://dash.cloudflare.com) — 100K requests/day)
+- A Resend account ([free tier](https://resend.com) — 3,000 emails/month)
+
+### Let the AI do it
+
+Add SoloStack as an MCP server in your AI client:
+
+```json
+{
+  "mcpServers": {
+    "solostack": {
+      "command": "npx",
+      "args": ["-y", "solostack-mcp"]
+    }
+  }
+}
+```
+
+Then tell your AI: *"Set up email marketing on mydomain.com"* and provide your Cloudflare API token, account ID, and Resend API key when asked.
+
+The AI handles the rest — provisioning, domain verification, and all ongoing operations.
+
+<details>
+<summary>Running from source (development)</summary>
+
+```json
+{
+  "mcpServers": {
+    "solostack": {
+      "command": "npx",
+      "args": ["tsx", "src/provisioner/index.ts"],
+      "cwd": "/path/to/solostack"
+    }
+  }
+}
+```
+
+</details>
+
+### Self-hosted (manual path)
+
+<details>
+<summary>Traditional setup with wrangler CLI</summary>
+
+```bash
+npm install
+
+# Create D1 database
+npx wrangler d1 create solostack
+# Copy database_id into wrangler.toml
+
+# Set FROM_EMAIL in wrangler.toml [vars]
+
+# Local development
+cat > .dev.vars << 'EOF'
+SOLOSTACK_API_KEY=your-local-dev-key
+RESEND_API_KEY=re_your_resend_key
+RESEND_WEBHOOK_SECRET=whsec_your_webhook_secret
+EOF
+
+npm run db:local
+npm run dev
+
+# Deploy to production
+npx wrangler secret put SOLOSTACK_API_KEY
+npx wrangler secret put RESEND_API_KEY
+npm run db:remote
+npm run deploy
+```
+
+After deploying, add a Resend webhook pointing to `https://your-worker.workers.dev/webhook/resend` for delivery tracking.
+
+</details>
+
+## Tech Stack
+
+- **Runtime:** [Cloudflare Workers](https://workers.cloudflare.com) (serverless, free tier: 100K req/day)
+- **Database:** [Cloudflare D1](https://developers.cloudflare.com/d1/) (SQLite, free tier: 5GB)
+- **Email:** [Resend](https://resend.com) API (free tier: 3,000 emails/month)
+- **Protocol:** [MCP](https://modelcontextprotocol.io) Streamable HTTP transport
+- **Language:** TypeScript
+
+## Architecture
+
+```
+src/
+  index.ts              # Worker entry: routing, auth, MCP handler
+  tools/
+    subscribers.ts      # subscribe, unsubscribe, list, count
+    email.ts            # send_email, send_broadcast
+  webhooks/
+    resend.ts           # Delivery tracking (Svix signature verification)
+  db/
+    schema.sql          # D1 schema (subscribers + email_log)
+  lib/
+    types.ts            # Env interface
+    resend.ts           # Resend API client
+  provisioner/
+    index.ts            # Local MCP server (stdio transport)
+    gateway.ts          # Proxy pattern — forwards tool calls to worker
+    cf-api.ts           # Cloudflare API client
+    resend-api.ts       # Resend API client (domain setup)
+    config.ts           # ~/.solostack/config.json storage
+    tools/              # Provisioning tool implementations
+scripts/
+  build-bundle.ts       # esbuild pipeline for worker bundle
+  e2e-test.ts           # End-to-end provisioning test
+```
+
+## Current Limitations
+
+- **Broadcast cap:** 100 recipients per call (Resend free tier: 100 emails/day)
+- **No drip sequences yet** — subscribe + broadcast only (drip engine planned)
+- **No analytics dashboard** — query `email_log` via D1 for delivery stats
+- **Single sending domain** per worker instance
+- **Cloudflare-only** — Workers + D1 (multi-platform planned)
+
+## License
+
+MIT