stackapps-suite-mcp 0.1.5__tar.gz

stackapps_suite_mcp-0.1.5/.dockerignore

@@ -0,0 +1,4 @@
+dist/
+__pycache__/
+*.pyc
+.venv/

stackapps_suite_mcp-0.1.5/.gitignore

@@ -0,0 +1,24 @@
+node_modules
+dist
+functions/lib
+.DS_Store
+server/public
+vite.config.ts.*
+*.tar.gz
+.env
+.env.local
+*.key
+*.pem
+client/.env
+client/.env.local
+__pycache__
+*.pyc
+.venv
+.firebase
+**/node_modules/**
+**/dist/**
+**/__pycache__/**
+**/*.firebase.json
+**/*firebase-adminsdk*.json
+**/*service-account*.json
+**/*serviceAccount*.jsonfirebase-debug.log

stackapps_suite_mcp-0.1.5/Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock ./
+COPY stackapps_mcp ./stackapps_mcp
+
+RUN pip install --no-cache-dir uv \
+ && uv sync --frozen --no-dev
+
+ENV PORT=8080
+EXPOSE 8080
+
+CMD ["uv", "run", "python", "-m", "stackapps_mcp.http_main"]

stackapps_suite_mcp-0.1.5/JOINING-THE-GATEWAY.md

@@ -0,0 +1,154 @@
+# Joining the Gateway — Playbook for Adding a Member App
+
+This is the authoritative checklist for adding a new StackApps member app's paid
+tools to the stackapps-suite-mcp gateway. Follow it exactly — do not improvise
+from other apps' code. When this document and existing code disagree, this
+document wins; flag the discrepancy to Abe.
+
+**Architecture recap:** There is exactly ONE MCP server for the whole suite
+(this package). Member apps never get their own MCP server. Each member app
+hosts its own x402 paid HTTP routes on its own backend; the gateway's tools
+relay to those routes and handle payment. Cloud Run (`mcp.stackapps.app`)
+serves blueprint discovery ONLY — paid tools run locally over stdio.
+
+---
+
+## Invariants — never change these
+
+- `SUITE_PAY_TO` in `stackapps_mcp/x402_http.py` (`0x1f2A484ef654d49c58c625b09e78B538501D652D`).
+  Every member app's x402 middleware must pay to this exact address. The client
+  refuses to sign payments to any other address. If Abe ever rotates the wallet,
+  it changes in BOTH places (all app backends + this constant) in one release.
+- Network `eip155:8453` (Base mainnet), asset USDC
+  (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`).
+- The payment guards in `SuiteX402Http` (pay-to pin + per-call amount cap).
+  Never bypass them "temporarily". If a new tool must cost more than $0.50,
+  raise `_DEFAULT_MAX_USD_PER_CALL` deliberately and update the `client-safety`
+  note in `blueprint.txt` in the same commit.
+- `WALLET_PRIVATE_KEY` is NEVER set on Cloud Run. The hosted service is
+  discovery-only (`discovery_only=True`). See `http_main.py` and `deploy-mcp.sh`.
+- `stateless_http=True` on the FastMCP constructor and the SSE guard middleware
+  stay in place (Cloud Run requirements — see global CLAUDE.md).
+- Do NOT create a new MCP server for the new app. Tools plug in here.
+
+---
+
+## Part A — App side (the member app's repo, any stack)
+
+The app must expose one POST route per paid capability, satisfying this
+contract (framework doesn't matter; Imagcon's backend is the worked example):
+
+1. **Route:** `POST https://<app-domain>/routes/x402/<capability-name>`.
+   Public — no auth, no API key. Input is multipart form (for file uploads) or
+   JSON. Output is the deliverable (`application/zip`, JSON, etc.).
+2. **x402 middleware (v2):** on an unpaid request, respond `402` with the
+   challenge in the `Payment-Required` header (base64 JSON). The challenge's
+   `accepts` entry must be:
+   - `scheme: "exact"`, `network: "eip155:8453"`
+   - `asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (USDC on Base)
+   - `payTo: 0x1f2A484ef654d49c58c625b09e78B538501D652D` (the suite wallet —
+     use the shared `X402_PAY_TO_ADDRESS` env var, never a new wallet)
+   - `amount`: price in USDC atomic units (6 decimals; $0.10 = `"100000"`).
+     Keep prices at or under $0.50 unless the gateway cap is raised first.
+3. **On paid retry** (request carries the signed payment header), settle via
+   the x402 middleware and return the result.
+4. **Optional but recommended:** include the Bazaar `extensions` metadata in
+   the challenge (input/output schema) — this is what gets the capability
+   indexed. Copy the shape from Imagcon's middleware config.
+5. **Verify before proceeding to Part B:**
+   `curl -s -D - -o /dev/null -X POST https://<app-domain>/routes/x402/<name> -H 'Content-Type: application/json' -d '{}'`
+   must return `HTTP 402` with a `Payment-Required` header whose decoded
+   `payTo` equals the suite wallet exactly.
+
+---
+
+## Identity & profile endpoints (if the app has them) — security rules
+
+Learned from Imagcon's wallet-profile hardening (2026-07-04). If a member app
+adds any account-ish surface to its x402 flows (profiles, saved data, tokens),
+these rules apply:
+
+1. **Secrets never appear in unauthenticated reads.** A public lookup endpoint
+   may return status and dates — never tokens, API keys, or anything that
+   gates a write. (Imagcon originally returned `profile_token` in the public
+   wallet lookup, which made it derivable from public on-chain data.)
+2. **Public identifiers never authorize writes.** A wallet address is public
+   information; anyone can enumerate payers on-chain. Any endpoint that
+   creates/changes profile data must require proof of wallet control:
+   a signature from the wallet key over the request payload.
+3. **Signature checks must be replay-proof.** The signed message includes a
+   timestamp or nonce, and the server rejects stale/reused signatures.
+4. **Zero human friction.** The MCP client signs automatically with the same
+   key it pays with — no extra agent inputs, no user prompts. Agents bounce at
+   any extra step (empirically confirmed by Abe). If a security measure adds a
+   visible step, redesign it to ride on the payment key instead.
+5. **The strong credential (API key etc.) gates data access only** — saved
+   content, galleries, full MCP tools. Do not require it for activation or
+   profile writes; users who haven't activated yet don't have it.
+
+---
+
+## Part B — Gateway side (this package)
+
+1. **Adapter module:** create `stackapps_mcp/<app>.py` modeled on
+   `stackapps_mcp/imagcon.py`:
+   - URL constants for each endpoint.
+   - Constructor takes `(private_key, network)` and builds a `SuiteX402Http`.
+   - One method per capability calling `self._x402.post(...)`.
+   - Do NOT copy Imagcon's profile-token logic unless the app actually issues
+     `X-<App>-Token` headers.
+   - Never construct raw httpx clients or handle 402 responses in the adapter —
+     that is `SuiteX402Http`'s job (it owns the safety guards).
+2. **Tools:** add `@mcp.tool()` functions in `stackapps_mcp/server.py`, modeled
+   on the existing ones. Docstring must state what it does and the exact price
+   ("Costs $X.XX USDC"). If the tool writes files, use `_safe_extractall` for
+   zips and document `output_dir`.
+3. **Wiring:** `main.py` constructs clients and passes them to the server
+   (see `set_client`). Extend the same pattern — one client per member app,
+   all sharing the wallet key. Close all clients in the `finally` block.
+4. **Blueprint (`stackapps_mcp/blueprint.txt`):** update ALL of:
+   - `# Version:` (bump minor) and `# Updated:` date
+   - `## SUMMARY` capabilities list (one line, with price)
+   - `### MCP TOOLS` (one line: `tool | params | description ($price) | source: <domain>`)
+   - a full `## CAPABILITY:` block with `### MCP tool:` sub-block
+   - `## SUITE` members list (move the app from "planned" to "live")
+5. **Release:** bump `version` in `pyproject.toml`. Build the wheel
+   (`uv build`), copy it to `client/public/downloads/`, then update the wheel
+   filename in every place that references it:
+   - `_WHEEL_URL` in `stackapps_mcp/server.py`
+   - all install/config lines in `stackapps_mcp/blueprint.txt`
+   - `client/public/llms.txt` and the hub blueprint files if they mention it
+   Old wheel stays available for one release, then delete it.
+6. **Deploy discovery:** run `./deploy-mcp.sh` from the repo root (deploys the
+   blueprint-only Cloud Run service; scale-to-zero, no secrets).
+
+---
+
+## Verification checklist (all must pass)
+
+- [ ] Live 402 probe of each new app endpoint shows `payTo` == suite wallet.
+- [ ] Guard test: feed the engine a forged challenge (wrong wallet / over-cap)
+      and confirm `NoMatchingRequirementsError` refusal; a legit challenge signs.
+      (Use a throwaway key — see the test pattern in the session that built this.)
+- [ ] `python -c "from stackapps_mcp import server, main"` imports cleanly in
+      the package venv.
+- [ ] MCP inspector (or `claude mcp add` locally): new tools appear in the tool
+      list with correct descriptions and prices.
+- [ ] One real paid call per new tool from a funded test wallet; deliverable
+      arrives; payment visible on Base for the correct amount.
+- [ ] `https://mcp.stackapps.app/blueprint.txt` serves the updated version.
+- [ ] Wheel installs: `uvx --from <wheel-url> stackapps-suite-mcp --help`.
+
+---
+
+## Current member apps
+
+| App | Status | Adapter |
+|---|---|---|
+| imagcon.app | live (5 paid + 2 free capabilities) | `stackapps_mcp/imagcon.py` |
+| stackbill.app | planned | — |
+| stackslip.app | planned | — |
+
+Candidate future members (shipped apps, no x402 routes yet): stackspent.app,
+stacktax.app, stackvideo.app, stackagent.app, stacklaunch.app, calypterv.com,
+easyhomeflow.com, dicta-notes.com.

stackapps_suite_mcp-0.1.5/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: stackapps-suite-mcp
+Version: 0.1.5
+Summary: MCP gateway for the StackApps tool suite — pay per call in USDC via x402, no account required
+Project-URL: Homepage, https://stackapps.app
+Project-URL: Source, https://github.com/Explorer-64/StackApps
+Project-URL: Blueprint, https://mcp.stackapps.app/blueprint.txt
+Author: Abe Reimer
+License: MIT
+Keywords: agent-payments,mcp,pwa-icons,stackapps,usdc,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: eth-account>=0.13.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.27.1
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: x402[clients,evm]>=2.0.0
+Description-Content-Type: text/markdown
+
+# stackapps-suite-mcp
+
+mcp-name: io.github.explorer-64/stackapps-suite-mcp
+
+One MCP server for the whole [StackApps](https://stackapps.app) tool suite.
+Pay per call in USDC on Base mainnet via [x402](https://www.x402.org/) — no
+account, no API key, no signup. Each member app (Imagcon today; more as they
+ship) contributes tools; one install covers the suite.
+
+## Install
+
+```bash
+claude mcp add stackapps-suite -- uvx stackapps-suite-mcp --wallet-key 0x...
+```
+
+Or in any MCP client config (Claude Desktop, Cursor, Windsurf, Cline):
+
+```json
+{
+  "mcpServers": {
+    "stackapps-suite": {
+      "command": "uvx",
+      "args": ["stackapps-suite-mcp"],
+      "env": { "WALLET_PRIVATE_KEY": "0x..." }
+    }
+  }
+}
+```
+
+Requirements: [uv](https://docs.astral.sh/uv/), Python 3.11+, an EVM wallet
+holding USDC on Base mainnet (eip155:8453). Prefer the `WALLET_PRIVATE_KEY`
+env var over the `--wallet-key` argument.
+
+## Tools
+
+| Tool | Price (USDC) | What it does |
+|---|---|---|
+| `create_pwa_icons_from_image` | $0.10 | Full PWA icon set (27 files + manifest.json) from a local image |
+| `create_splash_screens_from_image` | $0.10 | 16 iOS/iPad splash screens from a local image |
+| `generate_pwa_icons` | $0.295 | AI-generated PWA icon set from a text description |
+| `generate_image` | $0.195 | AI-generated source image (returns preview URL) |
+| `generate_splash_screens` | $0.295 | AI-generated splash screens from a text description |
+| `get_wallet_profile` | free | Check your wallet's Imagcon profile status |
+| `setup_wallet_profile` | free | Activate a permanent account (wallet-signature verified) |
+
+## Payment safety
+
+The server refuses to sign any payment challenge that does not pay the
+StackApps suite wallet, or that exceeds the per-call cap ($0.50 USDC by
+default; override with `STACKAPPS_MAX_USD_PER_CALL`). A compromised or spoofed
+endpoint cannot redirect or inflate payments. Payments settle on-chain via
+EIP-3009 — the gas is sponsored; your wallet needs only USDC.
+
+Never commit your wallet key, and never run this server on a public host with
+`WALLET_PRIVATE_KEY` set. The hosted endpoint at
+[mcp.stackapps.app](https://mcp.stackapps.app/blueprint.txt) serves discovery
+metadata only.
+
+## Discovery
+
+Machine-readable capability contract (Blueprint Protocol):
+[mcp.stackapps.app/blueprint.txt](https://mcp.stackapps.app/blueprint.txt)
+
+## Links
+
+- Suite: https://stackapps.app
+- Source: https://github.com/Explorer-64/StackApps (`stackapps-mcp/`)
+- Imagcon (current member app): https://imagcon.app

stackapps_suite_mcp-0.1.5/README.md

@@ -0,0 +1,68 @@
+# stackapps-suite-mcp
+
+mcp-name: io.github.explorer-64/stackapps-suite-mcp
+
+One MCP server for the whole [StackApps](https://stackapps.app) tool suite.
+Pay per call in USDC on Base mainnet via [x402](https://www.x402.org/) — no
+account, no API key, no signup. Each member app (Imagcon today; more as they
+ship) contributes tools; one install covers the suite.
+
+## Install
+
+```bash
+claude mcp add stackapps-suite -- uvx stackapps-suite-mcp --wallet-key 0x...
+```
+
+Or in any MCP client config (Claude Desktop, Cursor, Windsurf, Cline):
+
+```json
+{
+  "mcpServers": {
+    "stackapps-suite": {
+      "command": "uvx",
+      "args": ["stackapps-suite-mcp"],
+      "env": { "WALLET_PRIVATE_KEY": "0x..." }
+    }
+  }
+}
+```
+
+Requirements: [uv](https://docs.astral.sh/uv/), Python 3.11+, an EVM wallet
+holding USDC on Base mainnet (eip155:8453). Prefer the `WALLET_PRIVATE_KEY`
+env var over the `--wallet-key` argument.
+
+## Tools
+
+| Tool | Price (USDC) | What it does |
+|---|---|---|
+| `create_pwa_icons_from_image` | $0.10 | Full PWA icon set (27 files + manifest.json) from a local image |
+| `create_splash_screens_from_image` | $0.10 | 16 iOS/iPad splash screens from a local image |
+| `generate_pwa_icons` | $0.295 | AI-generated PWA icon set from a text description |
+| `generate_image` | $0.195 | AI-generated source image (returns preview URL) |
+| `generate_splash_screens` | $0.295 | AI-generated splash screens from a text description |
+| `get_wallet_profile` | free | Check your wallet's Imagcon profile status |
+| `setup_wallet_profile` | free | Activate a permanent account (wallet-signature verified) |
+
+## Payment safety
+
+The server refuses to sign any payment challenge that does not pay the
+StackApps suite wallet, or that exceeds the per-call cap ($0.50 USDC by
+default; override with `STACKAPPS_MAX_USD_PER_CALL`). A compromised or spoofed
+endpoint cannot redirect or inflate payments. Payments settle on-chain via
+EIP-3009 — the gas is sponsored; your wallet needs only USDC.
+
+Never commit your wallet key, and never run this server on a public host with
+`WALLET_PRIVATE_KEY` set. The hosted endpoint at
+[mcp.stackapps.app](https://mcp.stackapps.app/blueprint.txt) serves discovery
+metadata only.
+
+## Discovery
+
+Machine-readable capability contract (Blueprint Protocol):
+[mcp.stackapps.app/blueprint.txt](https://mcp.stackapps.app/blueprint.txt)
+
+## Links
+
+- Suite: https://stackapps.app
+- Source: https://github.com/Explorer-64/StackApps (`stackapps-mcp/`)
+- Imagcon (current member app): https://imagcon.app

stackapps_suite_mcp-0.1.5/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stackapps-suite-mcp"
+version = "0.1.5"
+description = "MCP gateway for the StackApps tool suite — pay per call in USDC via x402, no account required"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Abe Reimer" }]
+keywords = ["mcp", "x402", "usdc", "pwa-icons", "stackapps", "agent-payments"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+    "eth-account>=0.13.0",
+    "httpx>=0.27.0",
+    "mcp>=1.27.1",
+    "uvicorn>=0.30.0",
+    "x402[evm,clients]>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://stackapps.app"
+Source = "https://github.com/Explorer-64/StackApps"
+Blueprint = "https://mcp.stackapps.app/blueprint.txt"
+
+[project.scripts]
+stackapps-suite-mcp = "stackapps_mcp.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["stackapps_mcp"]

stackapps_suite_mcp-0.1.5/stackapps_mcp/__main__.py

@@ -0,0 +1,4 @@
+from stackapps_mcp.main import main
+
+if __name__ == "__main__":
+    main()