stackapps-suite-mcp 0.1.5__py3-none-any.whl

stackapps_mcp/__main__.py

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

stackapps_mcp/blueprint.txt

@@ -0,0 +1,337 @@
+# BLUEPRINT: StackApps MCP Gateway [x402]
+# Version: 1.3.0
+# URL: https://mcp.stackapps.app
+# Updated: 2026-07-04
+
+## IDENTITY
+name: StackApps MCP Gateway
+description: Unified x402 gateway for the StackApps tool suite. Pay per call in USDC
+  on Base mainnet — no account required to start; first x402 payment may issue a temp
+  API key (first payment only). Each member app (Imagcon today; StackBill, StackSlip,
+  and others as they ship) contributes tools here. One server, one install, the full suite.
+category: developer-tools
+contact: support@stackapps.app
+
+## SUMMARY
+tagline: One server. All StackApps tools. Pay per call in USDC.
+audience: AI agents and developers who need StackApps suite tools without creating an
+  account. Requires an EVM wallet funded with USDC on Base mainnet (eip155:8453).
+capabilities:
+  - create-pwa-icons-from-image: Upload image → full PWA icon set (27 files + manifest.json) — $0.10 USDC
+  - create-splash-screens-from-image: Upload image → 16 iOS/iPad splash screens — $0.10 USDC
+  - generate-pwa-icons: Text prompt → AI-generated PWA icon set — $0.295 USDC
+  - generate-image: Text prompt → AI-generated source image (image_key + preview URL) — $0.195 USDC
+  - generate-splash-screens: Text prompt → AI-generated 16 iOS/iPad splash screens — $0.295 USDC
+  - get-wallet-profile: Look up temp vs permanent wallet profile — free
+  - setup-wallet-profile: Activate permanent account from first-payment profile token — free
+
+## AUTH
+provider: none
+payment: x402 — EVM wallet, USDC on Base mainnet (eip155:8453)
+note: No Firebase account or API key required to start. Each tool call settles independently
+  on-chain via EIP-3009. The MCP server signs payment authorizations with the
+  configured wallet and retries automatically — no user interaction needed per call.
+
+## WALLET PROFILE
+note: On every first payment from a new wallet, Imagcon auto-creates a 60-day
+  temporary account linked to that wallet address. No action required.
+headers-on-first-payment:
+  - X-Imagcon-Token: profile token (tok_...) — stored in session only, never echoed in tool text
+  - X-Imagcon-Profile-Setup: activate URL (non-secret) — first payment only
+  - X-Imagcon-Api-Key: Imagcon API key — first payment only; unlocks all 14 imagcon-mcp tools
+surfaced-by: stackapps-suite-mcp appends a non-secret opt-in message to tool results on
+  first payment only (when X-Imagcon-Profile-Setup is present). Secrets stay in session
+  memory — never in chat logs. Example: "A 60-day temp account was created for your wallet.
+  To keep it permanently (free), call setup_wallet_profile with the profile token from
+  secure storage, or visit the activate URL. An Imagcon API key was issued — use imagcon-mcp
+  with that key (store securely, not in chat)."
+activate-endpoint: POST https://imagcon.app/routes/x402/profile/activate
+  body: { "profile_token": "tok_...", "wallet_address": "0x...", "name": "...",
+    "terms_confirmed": true, "signature": "0x...", "message": "imagcon.app/profile/activate:tok_...:<unix_ts>" }
+  signature: EIP-191 personal_sign over the message, signed with the paying wallet
+    key — stackapps-suite-mcp signs automatically; no agent input required.
+    Server verifies the recovered address matches wallet_address (±300s window).
+  terms: https://imagcon.app/terms-of-service
+  note: stackapps-suite-mcp derives wallet_address from WALLET_PRIVATE_KEY automatically;
+    agents pass name and terms_confirmed to setup_wallet_profile. profile_token defaults
+    to the session token from the first paid call if omitted.
+paper-plan: If setup_wallet_profile is never called, the temp account auto-deletes
+  after 60 days. Next payment from same wallet starts a fresh 60-day window.
+
+## MCP
+server: stackapps-suite-mcp
+preferred-transport: stdio
+http-transport: discovery only — https://mcp.stackapps.app serves blueprint.txt; paid tools
+  require local stdio with WALLET_PRIVATE_KEY. Do not use HTTP MCP on Cloud Run.
+install: claude mcp add stackapps-suite -- uvx stackapps-suite-mcp --wallet-key 0x...
+package: stackapps-suite-mcp on PyPI
+fallback-wheel: https://stackapps.app/downloads/stackapps_suite_mcp-0.1.5-py3-none-any.whl
+requirements: uv/uvx installed (https://docs.astral.sh/uv/). Python 3.11–3.12.
+  EVM wallet private key. USDC on Base mainnet in that wallet.
+
+### TRANSPORT (stdio)
+command: uvx stackapps-suite-mcp --wallet-key 0x...
+note: Runs as a local stdio process. Use WALLET_PRIVATE_KEY env var rather than
+  passing the key on the command line.
+
+### MCP TOOLS
+server: stackapps-suite-mcp
+
+create_pwa_icons_from_image | image_path, output_dir | Full PWA icon set (27 files + manifest.json) from PNG/JPEG/WebP ($0.10 USDC) | source: imagcon.app
+create_splash_screens_from_image | image_path, background_color, output_dir | 16 iOS/iPad splash screens from PNG/JPEG/WebP ($0.10 USDC) | source: imagcon.app
+generate_pwa_icons | description, output_dir | AI-generate PWA icon set from text prompt ($0.295 USDC) | source: imagcon.app
+generate_image | description | AI-generate source image, returns image_key + preview_url ($0.195 USDC) | source: imagcon.app
+generate_splash_screens | description, background_color, output_dir | AI-generate 16 iOS/iPad splash screens ($0.295 USDC) | source: imagcon.app
+get_wallet_profile | (none) | Look up temp vs permanent wallet profile (free) | source: imagcon.app
+setup_wallet_profile | name, terms_confirmed, profile_token, company_name, tax_id | Activate permanent account from first-payment profile token (free) | source: imagcon.app
+
+### PAYMENTS
+network: Base mainnet (eip155:8453)
+asset: USDC
+mechanism: x402 (HTTP 402 / EIP-3009)
+flow: Each tool call makes an HTTP request to the source app's x402 endpoint. The
+  server receives a 402 challenge, signs a payment authorization with the configured
+  wallet, and retries. Settlement is on-chain; funds go directly to the source app's
+  wallet. StackApps takes no cut.
+prices:
+  - $0.10 USDC: create_pwa_icons_from_image, create_splash_screens_from_image
+  - $0.195 USDC: generate_image
+  - $0.295 USDC: generate_pwa_icons, generate_splash_screens
+  - free: get_wallet_profile, setup_wallet_profile (no x402 charge)
+client-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.
+
+### REQUIRED-SECRETS
+- WALLET_PRIVATE_KEY:
+    description: EVM wallet private key for signing x402 payment authorizations
+    format: 0x-prefixed hex string (64 hex chars after 0x)
+    funding: Wallet must hold USDC on Base mainnet.
+    storage:
+      shell: export WALLET_PRIVATE_KEY=0x... in ~/.zshrc or ~/.bashrc
+      claude-code: pass via --wallet-key argument in claude mcp add command
+    warning: never commit the raw key to git; never set on Cloud Run
+- IMAGCON_PROFILE_TOKEN:
+    description: Optional override for X-Imagcon-Token header on subsequent x402 calls
+    format: tok_... string from Imagcon first-payment response
+    note: Normally stored in session memory automatically after first paid call
+
+### CLIENT-CONFIGS
+
+#### Claude Code (CLI)
+claude mcp add stackapps-suite -- uvx stackapps-suite-mcp --wallet-key 0x...
+
+#### Claude Code / Cursor / Windsurf / Cline (JSON)
+{
+  "mcpServers": {
+    "stackapps-suite": {
+      "command": "uvx",
+      "args": ["stackapps-suite-mcp", "--wallet-key", "0x..."]
+    }
+  }
+}
+
+## ACCESS
+preferred: mcp
+
+## CAPABILITY: create-pwa-icons-from-image
+description: Generate a full PWA icon set from an existing local image file.
+  Produces 27 files covering all required PWA, iOS, Android, Windows tile, and
+  Safari pinned-tab sizes, plus manifest.json, packaged as a ZIP and extracted
+  to output_dir. No AI generation — source image is uploaded directly.
+  Powered by Imagcon (imagcon.app).
+input:
+  - name: image_path
+    type: string
+    required: true
+    description: Absolute path to a PNG, JPEG, or WebP file on the local machine.
+  - name: output_dir
+    type: string
+    required: false
+    default: ./public/icons
+    description: Directory where the ZIP is extracted. Relative paths resolve
+      against the MCP server process directory.
+output:
+  - type: file
+    description: ZIP extracted to output_dir. Contains icons/ subdirectory and manifest.json.
+auth-required: false
+payment: $0.10 USDC per call (Base mainnet, x402)
+source: imagcon.app/routes/x402/icons-from-image
+
+### MCP
+tool: create_pwa_icons_from_image
+
+## CAPABILITY: create-splash-screens-from-image
+description: Generate 16 iOS and iPad launch splash screens from an existing local
+  image file. Covers all current iPhone and iPad canvas sizes. Output is a ZIP
+  of flat PNG files extracted to output_dir. No AI generation — source image is
+  uploaded directly. Powered by Imagcon (imagcon.app).
+input:
+  - name: image_path
+    type: string
+    required: true
+    description: Absolute path to a PNG, JPEG, or WebP file on the local machine.
+  - name: background_color
+    type: string
+    required: false
+    default: "#ffffff"
+    description: Hex color string for the splash screen background (e.g. #1a1a2e).
+  - name: output_dir
+    type: string
+    required: false
+    default: ./public/splash
+    description: Directory where the ZIP is extracted.
+output:
+  - type: file
+    description: ZIP extracted to output_dir. Contains 16 flat PNG splash screens.
+auth-required: false
+payment: $0.10 USDC per call (Base mainnet, x402)
+source: imagcon.app/routes/x402/splash-from-image
+
+### MCP
+tool: create_splash_screens_from_image
+
+## CAPABILITY: generate-pwa-icons
+description: AI-generate a complete PWA icon set from a text description of your app.
+  Imagcon generates a source image from the prompt, then produces all 27 PWA icon
+  sizes plus manifest.json, packaged as a ZIP extracted to output_dir.
+  Powered by Imagcon (imagcon.app).
+input:
+  - name: description
+    type: string
+    required: true
+    description: Text description of the app — used as the AI image generation prompt.
+      Be specific about colors, style, and subject matter.
+  - name: output_dir
+    type: string
+    required: false
+    default: ./public/icons
+    description: Directory where the ZIP is extracted.
+output:
+  - type: file
+    description: ZIP extracted to output_dir. Contains AI-generated source image,
+      icons/ subdirectory, and manifest.json.
+auth-required: false
+payment: $0.295 USDC per call (Base mainnet, x402)
+source: imagcon.app/routes/x402/generate-pwa-icons
+
+### MCP
+tool: generate_pwa_icons
+
+## CAPABILITY: generate-image
+description: AI-generate a source image from a text description. Returns image_key
+  and a preview URL. Use this when you want to review the generated image before
+  committing to a full icon set generation. Powered by Imagcon (imagcon.app).
+input:
+  - name: description
+    type: string
+    required: true
+    description: Text description used as the AI image generation prompt.
+output:
+  - type: json
+    description: image_key (string) and preview_url (string). The image_key can
+      be passed to Imagcon's create_icons_from_key tool (via imagcon-mcp) to
+      generate the full icon set without regenerating the image.
+auth-required: false
+payment: $0.195 USDC per call (Base mainnet, x402)
+source: imagcon.app/routes/x402/generate-image
+
+### MCP
+tool: generate_image
+
+## CAPABILITY: generate-splash-screens
+description: AI-generate 16 iOS and iPad launch splash screens from a text description
+  of your app. Imagcon generates a source image from the prompt, then produces all
+  splash screen canvas sizes, packaged as a ZIP extracted to output_dir.
+  Powered by Imagcon (imagcon.app).
+input:
+  - name: description
+    type: string
+    required: true
+    description: Text description used as the AI image generation prompt.
+  - name: background_color
+    type: string
+    required: false
+    default: "#ffffff"
+    description: Hex color string for the splash screen background.
+  - name: output_dir
+    type: string
+    required: false
+    default: ./public/splash
+    description: Directory where the ZIP is extracted.
+output:
+  - type: file
+    description: ZIP extracted to output_dir. Contains AI-generated source image
+      and 16 flat PNG splash screens.
+auth-required: false
+payment: $0.295 USDC per call (Base mainnet, x402)
+source: imagcon.app/routes/x402/generate-splash-screens
+
+### MCP
+tool: generate_splash_screens
+
+## CAPABILITY: get-wallet-profile
+description: Look up the Imagcon wallet profile for the configured wallet address.
+  Use before prompting the user to activate — shows temp vs permanent status.
+input: []
+output:
+  - type: string
+    description: Profile status and optional display name.
+auth-required: false
+payment: free (no x402 charge)
+source: imagcon.app/routes/x402/profile/{wallet}
+
+### MCP
+tool: get_wallet_profile
+
+## CAPABILITY: setup-wallet-profile
+description: Activate a permanent Imagcon account linked to your wallet. Call this
+  after the first x402 payment. profile_token is stored in session memory after the
+  first paid call; pass explicitly from secure storage if needed. Permanent accounts
+  keep payment history indefinitely. Without activation the temp account auto-deletes
+  after 60 days (paper plan).
+input:
+  - name: name
+    type: string
+    required: true
+    description: Display name for the profile (person or business name).
+  - name: terms_confirmed
+    type: boolean
+    required: true
+    description: Must be true only after the human has read https://imagcon.app/terms-of-service and agreed.
+  - name: profile_token
+    type: string
+    required: false
+    description: tok_... token from first x402 payment. Defaults to session token if omitted.
+  - name: wallet_address
+    type: string
+    required: true
+    description: Derived from WALLET_PRIVATE_KEY by stackapps-suite-mcp (not an agent input).
+  - name: company_name
+    type: string
+    required: false
+    description: Optional business name.
+  - name: tax_id
+    type: string
+    required: false
+    description: Optional tax ID / VAT number.
+output:
+  - type: string
+    description: Confirmation message with account status.
+auth-required: false
+payment: free (no x402 charge)
+source: imagcon.app/routes/x402/profile/activate
+
+### MCP
+tool: setup_wallet_profile
+
+## SUITE
+note: This gateway grows as member apps ship x402 endpoints. Each new capability
+  will appear in ## MCP TOOLS above and as a ## CAPABILITY block below.
+  The install command and server URL do not change — agents with stackapps-suite-mcp
+  already installed receive new tools automatically on next connect.
+members:
+  - imagcon.app — PWA icons, splash screens, AI image generation (live)
+  - stackbill.app — invoicing (planned)
+  - stackslip.app — packing slips (planned)

stackapps_mcp/http_main.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import os
+
+import uvicorn
+
+from stackapps_mcp.server import create_app
+
+# Cloud Run serves blueprint discovery only. NEVER set WALLET_PRIVATE_KEY here —
+# a funded wallet on a public endpoint would be a drain vector.
+app = create_app(discovery_only=True)
+
+
+def main() -> None:
+    port = int(os.environ.get("PORT", "8080"))
+    uvicorn.run(app, host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    main()

stackapps_mcp/imagcon.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import json as _json
+import os
+import time
+
+import httpx
+
+from stackapps_mcp.x402_http import SuiteX402Http
+
+
+class ImagconX402Client:
+    """Imagcon member-app adapter: endpoint URLs + profile-token handling.
+
+    Payment signing, retry, and safety guards live in SuiteX402Http. New member
+    apps follow this same shape — see JOINING-THE-GATEWAY.md.
+    """
+
+    ICONS_URL = "https://imagcon.app/routes/x402/icons-from-image"
+    SPLASH_URL = "https://imagcon.app/routes/x402/splash-from-image"
+    GENERATE_IMAGE_URL = "https://imagcon.app/routes/x402/generate-image"
+    GENERATE_ICONS_AI_URL = "https://imagcon.app/routes/x402/generate-pwa-icons"
+    GENERATE_SPLASH_AI_URL = "https://imagcon.app/routes/x402/generate-splash-screens"
+    PROFILE_ACTIVATE_URL = "https://imagcon.app/routes/x402/profile/activate"
+    PROFILE_LOOKUP_URL = "https://imagcon.app/routes/x402/profile"
+
+    def __init__(self, private_key: str, network: str = "eip155:8453") -> None:
+        self._x402 = SuiteX402Http(private_key, network)
+        env_token = (os.environ.get("IMAGCON_PROFILE_TOKEN") or "").strip()
+        self._profile_token: str | None = env_token or None
+
+    @property
+    def wallet_address(self) -> str:
+        return self._x402.wallet_address
+
+    @property
+    def profile_token(self) -> str | None:
+        return self._profile_token
+
+    def _profile_headers(self) -> dict[str, str]:
+        if self._profile_token:
+            return {"X-Imagcon-Token": self._profile_token}
+        return {}
+
+    def _extract_profile(self, response: httpx.Response) -> dict:
+        extra: dict = {}
+        if token := response.headers.get("x-imagcon-token"):
+            extra["profile_token"] = token
+            self._profile_token = token
+        if setup_url := response.headers.get("x-imagcon-profile-setup"):
+            extra["is_first_payment"] = True
+            extra["profile_setup_url"] = setup_url
+        if response.headers.get("x-imagcon-api-key"):
+            extra["api_key_issued"] = True
+        return extra
+
+    def _call(
+        self,
+        url: str,
+        *,
+        files: dict | None = None,
+        data: dict | None = None,
+        json: dict | None = None,
+    ) -> tuple[bytes, dict]:
+        response = self._x402.post(
+            url, files=files, data=data, json=json, headers=self._profile_headers()
+        )
+        return response.content, self._extract_profile(response)
+
+    def generate_icons(self, image_bytes: bytes, filename: str) -> tuple[bytes, dict]:
+        return self._call(
+            self.ICONS_URL,
+            files={"image": (filename, image_bytes, "image/png")},
+        )
+
+    def generate_splash(
+        self,
+        image_bytes: bytes,
+        filename: str,
+        background_color: str = "#ffffff",
+    ) -> tuple[bytes, dict]:
+        return self._call(
+            self.SPLASH_URL,
+            files={"image": (filename, image_bytes, "image/png")},
+            data={"background_color": background_color},
+        )
+
+    def generate_image_ai(self, description: str) -> tuple[dict, dict]:
+        content, extra = self._call(self.GENERATE_IMAGE_URL, json={"description": description})
+        return _json.loads(content), extra
+
+    def generate_pwa_icons_ai(self, description: str) -> tuple[bytes, dict]:
+        return self._call(self.GENERATE_ICONS_AI_URL, json={"description": description})
+
+    def generate_splash_screens_ai(
+        self, description: str, background_color: str = "#ffffff"
+    ) -> tuple[bytes, dict]:
+        return self._call(
+            self.GENERATE_SPLASH_AI_URL,
+            json={"description": description, "background_color": background_color},
+        )
+
+    def get_wallet_profile(self) -> dict:
+        response = self._x402.get(f"{self.PROFILE_LOOKUP_URL}/{self.wallet_address}")
+        return response.json()
+
+    def setup_wallet_profile(
+        self,
+        profile_token: str,
+        name: str,
+        *,
+        terms_confirmed: bool,
+        company_name: str | None = None,
+        tax_id: str | None = None,
+    ) -> dict:
+        # Imagcon requires proof of wallet control: EIP-191 signature over
+        # "imagcon.app/profile/activate:{token}:{unix_ts}", ±300s server window.
+        message = f"imagcon.app/profile/activate:{profile_token}:{int(time.time())}"
+        body: dict = {
+            "profile_token": profile_token,
+            "wallet_address": self.wallet_address,
+            "name": name,
+            "terms_confirmed": terms_confirmed,
+            "signature": self._x402.sign_message(message),
+            "message": message,
+        }
+        if company_name:
+            body["company_name"] = company_name
+        if tax_id:
+            body["tax_id"] = tax_id
+        response = self._x402.post(self.PROFILE_ACTIVATE_URL, json=body)
+        return response.json()
+
+    def close(self) -> None:
+        self._x402.close()

stackapps_mcp/main.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from stackapps_mcp.imagcon import ImagconX402Client
+from stackapps_mcp.server import mcp, set_client
+
+
+def _resolve_wallet_key(cli_key: str | None) -> str:
+    key = (cli_key or os.environ.get("WALLET_PRIVATE_KEY") or "").strip()
+    if not key:
+        print(
+            "Missing wallet private key. Set WALLET_PRIVATE_KEY or pass --wallet-key.\n"
+            "You need an EVM wallet with USDC on Base mainnet (eip155:8453).",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+    if not key.startswith("0x"):
+        key = "0x" + key
+    return key
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="stackapps-suite-mcp")
+    parser.add_argument("--wallet-key", default=None)
+    parser.add_argument("--network", default="eip155:8453")
+    args, remaining = parser.parse_known_args()
+    sys.argv = [sys.argv[0], *remaining]
+
+    key = _resolve_wallet_key(args.wallet_key)
+    client = ImagconX402Client(key, args.network)
+    set_client(client)
+    try:
+        mcp.run()
+    finally:
+        client.close()

stackapps_mcp/server.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import io
+import zipfile
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse, Response
+from starlette.routing import Mount, Route
+
+from stackapps_mcp.imagcon import ImagconX402Client
+
+mcp = FastMCP("stackapps-suite-mcp", stateless_http=True)
+
+_client: ImagconX402Client | None = None
+_blueprint_text = (Path(__file__).parent / "blueprint.txt").read_text(encoding="utf-8")
+
+
+def set_client(client: ImagconX402Client) -> None:
+    global _client
+    _client = client
+
+
+def _require_client() -> ImagconX402Client:
+    if _client is None:
+        raise RuntimeError("Imagcon x402 client is not configured")
+    return _client
+
+
+def _profile_note(extra: dict) -> str:
+    if not extra.get("is_first_payment"):
+        return ""
+    parts = [
+        "A 60-day temp account was created for your wallet. To keep it permanently (free), "
+        "call setup_wallet_profile with the profile token from secure storage, or visit the activate URL."
+    ]
+    if url := extra.get("profile_setup_url"):
+        parts.append(f"Activate URL: {url}")
+    if extra.get("api_key_issued"):
+        parts.append(
+            "An Imagcon API key was issued — use imagcon-mcp with that key (store securely, not in chat)."
+        )
+    return "\n\n" + " ".join(parts)
+
+
+def _safe_extractall(zf: zipfile.ZipFile, output_dir: Path) -> None:
+    dest = output_dir.resolve()
+    for info in zf.infolist():
+        if ".." in Path(info.filename).parts or info.filename.startswith("/"):
+            raise ValueError(f"Unsafe path in zip: {info.filename}")
+        target = (dest / info.filename).resolve()
+        try:
+            target.relative_to(dest)
+        except ValueError:
+            raise ValueError(f"Unsafe path in zip: {info.filename}") from None
+    zf.extractall(dest)
+
+
+# --- tools ---
+
+@mcp.tool()
+def create_pwa_icons_from_image(
+    image_path: str,
+    output_dir: str = "./public/icons",
+) -> str:
+    """Generate a full PWA icon set (all sizes, manifest.json) from a local PNG/JPEG/WebP image via the Imagcon x402 anonymous endpoint. Costs $0.10 USDC. output_dir should be an absolute path."""
+    path = Path(image_path)
+    image_bytes = path.read_bytes()
+    zip_bytes, extra = _require_client().generate_icons(image_bytes, path.name)
+
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
+        count = len(zf.namelist())
+        _safe_extractall(zf, out)
+
+    return f"Generated {count} files in {out.resolve()}." + _profile_note(extra)
+
+
+@mcp.tool()
+def create_splash_screens_from_image(
+    image_path: str,
+    background_color: str = "#ffffff",
+    output_dir: str = "./public/splash",
+) -> str:
+    """Generate 16 iOS/iPad splash screens from a local PNG/JPEG/WebP image via the Imagcon x402 anonymous endpoint. Costs $0.10 USDC. output_dir should be an absolute path."""
+    path = Path(image_path)
+    image_bytes = path.read_bytes()
+    zip_bytes, extra = _require_client().generate_splash(
+        image_bytes, path.name, background_color=background_color
+    )
+
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
+        count = len(zf.namelist())
+        _safe_extractall(zf, out)
+
+    return f"Generated {count} files in {out.resolve()}." + _profile_note(extra)
+
+
+@mcp.tool()
+def generate_pwa_icons(
+    description: str,
+    output_dir: str = "./public/icons",
+) -> str:
+    """AI-generate a complete PWA icon set from a text description of your app. Costs $0.295 USDC. Imagcon generates the source image and all PWA sizes. output_dir should be an absolute path."""
+    zip_bytes, extra = _require_client().generate_pwa_icons_ai(description)
+
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
+        count = len(zf.namelist())
+        _safe_extractall(zf, out)
+
+    return f"Generated {count} files in {out.resolve()}." + _profile_note(extra)
+
+
+@mcp.tool()
+def generate_image(description: str) -> str:
+    """AI-generate a source image from a text description. Costs $0.195 USDC. Returns image_key and preview_url — useful for previewing before generating a full icon set."""
+    result, extra = _require_client().generate_image_ai(description)
+    msg = f"image_key: {result.get('image_key', '')}\npreview_url: {result.get('preview_url', '')}"
+    return msg + _profile_note(extra)
+
+
+@mcp.tool()
+def generate_splash_screens(
+    description: str,
+    background_color: str = "#ffffff",
+    output_dir: str = "./public/splash",
+) -> str:
+    """AI-generate 16 iOS/iPad splash screens from a text description of your app. Costs $0.295 USDC. output_dir should be an absolute path."""
+    zip_bytes, extra = _require_client().generate_splash_screens_ai(description, background_color)
+
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
+        count = len(zf.namelist())
+        _safe_extractall(zf, out)
+
+    return f"Generated {count} files in {out.resolve()}." + _profile_note(extra)
+
+
+@mcp.tool()
+def get_wallet_profile() -> str:
+    """Look up the Imagcon wallet profile for the configured wallet. Returns temp vs permanent status before prompting the user to activate."""
+    result = _require_client().get_wallet_profile()
+    profile = result.get("profile", result)
+    status = profile.get("status", "unknown")
+    name = profile.get("name", "")
+    parts = [f"Wallet {_require_client().wallet_address}: status={status}"]
+    if name:
+        parts.append(f"name={name}")
+    return ". ".join(parts) + "."
+
+
+@mcp.tool()
+def setup_wallet_profile(
+    name: str,
+    terms_confirmed: bool,
+    profile_token: str | None = None,
+    company_name: str | None = None,
+    tax_id: str | None = None,
+) -> str:
+    """Activate a permanent Imagcon account linked to your wallet. terms_confirmed must be true only after the human has read https://imagcon.app/terms-of-service and agreed. profile_token defaults to the session token from the first paid call if omitted."""
+    if not terms_confirmed:
+        raise ValueError(
+            "terms_confirmed must be true only after the human has read "
+            "https://imagcon.app/terms-of-service and agreed."
+        )
+    client = _require_client()
+    token = profile_token or client.profile_token
+    if not token:
+        raise ValueError(
+            "No profile token available. Complete a paid tool call first or pass profile_token "
+            "from secure storage."
+        )
+    result = client.setup_wallet_profile(
+        profile_token=token,
+        name=name,
+        terms_confirmed=terms_confirmed,
+        company_name=company_name,
+        tax_id=tax_id,
+    )
+    status = result.get("profile", {}).get("status", "permanent")
+    return f"Profile activated. Future payments from your wallet are linked to {name}. Status: {status}."
+
+
+# --- HTTP app: blueprint routes + SSE guard (for Cloud Run) ---
+
+async def _serve_blueprint(request: Request) -> Response:
+    return PlainTextResponse(_blueprint_text, media_type="text/plain; charset=utf-8")
+
+
+class _SSEGuard(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        if "text/event-stream" in request.headers.get("accept", ""):
+            return PlainTextResponse(
+                "SSE transport is not supported on this server.\n"
+                "Install the local stdio package instead:\n"
+                "  uvx stackapps-suite-mcp --wallet-key 0x...",
+                status_code=405,
+            )
+        return await call_next(request)
+
+
+def create_app(*, discovery_only: bool = False):
+    """ASGI app for Cloud Run (discovery_only=True) or local HTTP MCP."""
+    routes: list = [
+        Route("/blueprint.txt", _serve_blueprint),
+        Route("/.well-known/blueprint.txt", _serve_blueprint),
+    ]
+    if not discovery_only:
+        routes.append(Mount("/", app=mcp.streamable_http_app()))
+    return Starlette(
+        routes=routes,
+        middleware=[Middleware(_SSEGuard)],
+    )

stackapps_mcp/x402_http.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import os
+
+import httpx
+from eth_account import Account
+from eth_account.messages import encode_defunct
+from x402 import NoMatchingRequirementsError, max_amount, x402ClientSync
+from x402.http.x402_http_client import x402HTTPClientSync
+from x402.mechanisms.evm.exact import ExactEvmClientScheme
+
+# Every member app's x402 endpoint pays to this wallet. The client refuses to
+# sign a payment to any other address — a compromised or spoofed endpoint
+# cannot redirect funds. Never change without verifying against a live 402
+# challenge from a suite endpoint.
+SUITE_PAY_TO = "0x1f2A484ef654d49c58c625b09e78B538501D652D"
+
+_DEFAULT_MAX_USD_PER_CALL = 0.50
+
+
+def _max_usdc_units() -> int:
+    raw = (os.environ.get("STACKAPPS_MAX_USD_PER_CALL") or "").strip()
+    try:
+        usd = float(raw) if raw else _DEFAULT_MAX_USD_PER_CALL
+    except ValueError:
+        usd = _DEFAULT_MAX_USD_PER_CALL
+    return int(usd * 1_000_000)
+
+
+def _suite_pay_to_only(version, reqs):
+    return [r for r in reqs if r.pay_to.lower() == SUITE_PAY_TO.lower()]
+
+
+class SuiteX402Http:
+    """Shared x402 HTTP engine for all StackApps member apps.
+
+    Handles the 402 challenge/sign/retry cycle with two guards applied before
+    any payment is signed: the challenge must pay SUITE_PAY_TO, and the amount
+    must not exceed the per-call cap (STACKAPPS_MAX_USD_PER_CALL, default $0.50).
+    """
+
+    def __init__(self, private_key: str, network: str = "eip155:8453") -> None:
+        account = Account.from_key(private_key)
+        self._account = account
+        self._wallet_address = account.address.lower()
+        x402_client = x402ClientSync()
+        x402_client.register(network, ExactEvmClientScheme(signer=account))
+        x402_client.register_policy(_suite_pay_to_only)
+        x402_client.register_policy(max_amount(_max_usdc_units()))
+        self._x402_http = x402HTTPClientSync(x402_client)
+        self._http = httpx.Client(timeout=300.0)
+
+    @property
+    def wallet_address(self) -> str:
+        return self._wallet_address
+
+    def sign_message(self, text: str) -> str:
+        """EIP-191 personal_sign over a UTF-8 string; returns 0x-prefixed hex."""
+        signed = self._account.sign_message(encode_defunct(text=text))
+        sig = signed.signature.hex()
+        return sig if sig.startswith("0x") else "0x" + sig
+
+    def post(
+        self,
+        url: str,
+        *,
+        files: dict | None = None,
+        data: dict | None = None,
+        json: dict | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        headers = dict(headers or {})
+        response = self._http.post(url, files=files, data=data, json=json, headers=headers)
+        if response.status_code == 402:
+            try:
+                payment_headers, _ = self._x402_http.handle_402_response(
+                    dict(response.headers), response.content
+                )
+            except NoMatchingRequirementsError as e:
+                raise RuntimeError(
+                    f"Refused to pay {url}: the payment challenge does not pay the "
+                    f"StackApps suite wallet ({SUITE_PAY_TO}) or exceeds the per-call cap "
+                    f"(${_max_usdc_units() / 1_000_000:.2f} USDC). No payment was signed. "
+                    f"Details: {e}"
+                ) from e
+            response = self._http.post(
+                url, files=files, data=data, json=json, headers={**headers, **payment_headers}
+            )
+        if response.status_code >= 400:
+            raise RuntimeError(
+                f"x402 endpoint error {response.status_code} from {url}: {response.content[:200]}"
+            )
+        return response
+
+    def get(self, url: str) -> httpx.Response:
+        response = self._http.get(url)
+        if response.status_code >= 400:
+            raise RuntimeError(
+                f"x402 endpoint error {response.status_code} from {url}: {response.content[:200]}"
+            )
+        return response
+
+    def close(self) -> None:
+        self._http.close()

stackapps_suite_mcp-0.1.5.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+stackapps_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+stackapps_mcp/__main__.py,sha256=a5CB2dDZ8e5r66OVElwtjgg5LK7I_vjhKeV2tcGjM5Q,75
+stackapps_mcp/blueprint.txt,sha256=44-Zi7Wge31isqro5y4dFJXHGYRwmpPU7_TwSeSiMJg,14858
+stackapps_mcp/http_main.py,sha256=6y_BrtWwN3ZOBh2ekMuMM4I_M-YN6UPx3PTAYrutDWA,450
+stackapps_mcp/imagcon.py,sha256=rbwUr5Bwm-yrk0aKIv7GMaWBh4UvjRa4fRvKV_wewxY,4909
+stackapps_mcp/main.py,sha256=nebp3Ohm4SsLClDawHkxyxYzHEfd40iG4NiaBICxR9o,1117
+stackapps_mcp/server.py,sha256=nRdN1zkahs83mooCpuCg0WDjtKkqXY3zZVcrg_cdbxk,8351
+stackapps_mcp/x402_http.py,sha256=f75IzCXRwcEbKcory7JqwxsMZq25fKiXoq7P64dXFTM,4054
+stackapps_suite_mcp-0.1.5.dist-info/METADATA,sha256=IkiK5Zxo0DLsROEYhDiUKCOXEmdgz4cTDmmjEGznHQk,3525
+stackapps_suite_mcp-0.1.5.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+stackapps_suite_mcp-0.1.5.dist-info/entry_points.txt,sha256=FPq6hJduJbs8mQwX-n8c8hRqQrQBi77FZ6AnZy3CvT8,68
+stackapps_suite_mcp-0.1.5.dist-info/RECORD,,

stackapps_suite_mcp-0.1.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

stackapps_suite_mcp-0.1.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stackapps-suite-mcp = stackapps_mcp.__main__:main