storesignal-mcp 0.1.0__tar.gz

storesignal_mcp-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+eggs/
+*.whl
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+.DS_Store

storesignal_mcp-0.1.0/Dockerfile

@@ -0,0 +1,17 @@
+# Container image for hosting the StoreSignal MCP server over streamable-HTTP
+# (used by Smithery's container runtime; see smithery.yaml).
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install the package plus the HTTP extra (uvicorn). Copy only what the build
+# needs first so the dependency layer caches well.
+COPY pyproject.toml README.md LICENSE ./
+COPY storesignal_mcp ./storesignal_mcp
+RUN pip install --no-cache-dir ".[http]"
+
+# Smithery sets PORT; default to 8080 for local runs.
+ENV PORT=8080
+EXPOSE 8080
+
+CMD ["storesignal-mcp", "--http"]

storesignal_mcp-0.1.0/LICENSE

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

storesignal_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: storesignal-mcp
+Version: 0.1.0
+Summary: MCP server for the StoreSignal API: Shopify store intelligence -- apps, tech stack, CDN, market aggregates, and competitive comparisons.
+Project-URL: Homepage, https://storesignal.anthesia.io
+Project-URL: Documentation, https://storesignal.anthesia.io/docs
+Project-URL: Repository, https://github.com/anthesiallc/storesignal-mcp
+Author-email: Anthesia <support@anthesia.io>
+License: MIT
+License-File: LICENSE
+Keywords: api,competitive-intelligence,dtc,ecommerce,mcp,model-context-protocol,shopify,store-intelligence
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: http
+Requires-Dist: uvicorn>=0.30.0; extra == 'http'
+Description-Content-Type: text/markdown
+
+# StoreSignal MCP Server
+
+mcp-name: io.github.anthesiallc/storesignal
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
+the [StoreSignal API](https://storesignal.anthesia.io) as tools, so any MCP
+client (Claude Desktop, Cursor, ChatGPT connectors, or an agent framework) can
+analyze Shopify stores and run market intelligence queries conversationally.
+
+It's a thin wrapper: each tool maps to one StoreSignal REST endpoint. All the
+data work happens in the API.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `analyze_store` | Full structured profile for a Shopify store URL (apps, CDN, security headers, schema.org, classification, revenue estimate) |
+| `compare_stores` | Side-by-side comparison of 2-5 stores (shared apps, exclusive apps, tier) |
+| `find_stores_using_app` | Paginated list of every analyzed store running a specific app |
+| `list_apps` | All 278 apps in the catalog, optionally filtered by category |
+| `app_adoption` | Top apps by adoption % across the corpus, optionally filtered by category |
+| `app_vs_app` | Head-to-head: install counts, overlap, co-install rate, bidirectional cross-adoption |
+| `industry_overview` | Per-vertical stats: store count, median price, top countries, top apps, tier mix |
+| `store_census` | Whole-corpus stats (19,647 stores, 20 industries, app/tier/type breakdowns) |
+| `get_usage` | Current billing period usage and plan limit |
+
+## Get an API key
+
+Free tier is 250 calls/month, no credit card:
+
+```bash
+curl -X POST https://storesignal.anthesia.io/api/v1/signup \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"you@example.com"}'
+```
+
+The key comes back in the `api_key` field of the response.
+
+## Install and run
+
+The easiest way is with [uv](https://docs.astral.sh/uv/) (no manual venv needed):
+
+```bash
+# stdio transport (default — for Claude Desktop, Cursor, most local clients)
+STORESIGNAL_API_KEY=ss_your_key uvx storesignal-mcp
+
+# streamable-HTTP transport (for remote / web clients)
+STORESIGNAL_API_KEY=ss_your_key uvx storesignal-mcp --http
+```
+
+Or install with pip into its own environment:
+
+```bash
+pip install storesignal-mcp
+STORESIGNAL_API_KEY=ss_your_key storesignal-mcp
+```
+
+> Note: install into a dedicated environment. The `mcp` SDK requires a newer
+> `starlette` than the StoreSignal API app pins, so the two will conflict if
+> installed together.
+
+Environment variables:
+
+- `STORESIGNAL_API_KEY` (required) — your StoreSignal API key.
+- `STORESIGNAL_BASE_URL` (optional) — defaults to `https://storesignal.anthesia.io`.
+- `STORESIGNAL_TIMEOUT` (optional) — request timeout in seconds, default `60`.
+
+## Client configuration
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "storesignal": {
+      "command": "uvx",
+      "args": ["storesignal-mcp"],
+      "env": { "STORESIGNAL_API_KEY": "ss_your_key" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add the same block to `~/.cursor/mcp.json` (or the project `.cursor/mcp.json`).
+
+### Smithery (hosted, no install)
+
+The server is hosted on [Smithery](https://smithery.ai/server/anthesiallc/storesignal),
+so MCP clients that support Smithery can connect without installing anything.
+You provide your StoreSignal API key in the Smithery config and it routes to
+the server.
+
+### LangChain / LangGraph
+
+Any LangChain or LangGraph agent can use these tools through
+[`langchain-mcp-adapters`](https://github.com/langchain-ai/langchain-mcp-adapters):
+
+```python
+# pip install langchain-mcp-adapters langgraph "langchain[anthropic]"
+from langchain_mcp_adapters.client import MultiServerMCPClient
+
+client = MultiServerMCPClient(
+    {
+        "storesignal": {
+            "transport": "stdio",
+            "command": "uvx",
+            "args": ["storesignal-mcp"],
+            "env": {"STORESIGNAL_API_KEY": "ss_your_key"},
+        }
+    }
+)
+tools = await client.get_tools()
+# hand `tools` to a LangGraph/LangChain agent, e.g.
+# from langgraph.prebuilt import create_react_agent
+# agent = create_react_agent("anthropic:claude-opus-4-8", tools)
+```
+
+LlamaIndex works the same way via its MCP tool spec.
+
+## Example agent conversations
+
+> "What apps does Allbirds use?"
+> → `analyze_store("https://www.allbirds.com")`
+
+> "Compare the tech stacks of Brooklinen and Bombas."
+> → `compare_stores(["https://brooklinen.com", "https://bombas.com"])`
+
+> "Which Shopify stores are running Judge.me?"
+> → `find_stores_using_app("judge-me")`
+
+> "What are the top email-marketing apps on Shopify?"
+> → `app_adoption(category="Email Marketing")`
+
+> "Compare Klaviyo to Omnisend."
+> → `app_vs_app("klaviyo", "omnisend")`
+
+> "Tell me about the Beauty vertical."
+> → `industry_overview("Beauty")`
+
+## Develop from source
+
+```bash
+git clone https://github.com/anthesiallc/storesignal-mcp && cd storesignal-mcp
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[http]"   # Windows; [http] adds uvicorn for --http
+# .venv/bin/pip install -e ".[http]"                # macOS/Linux
+STORESIGNAL_API_KEY=ss_your_key .venv/Scripts/python -m storesignal_mcp.server
+```
+
+## Notes
+
+- Data is extracted only from publicly accessible Shopify storefront endpoints.
+- Not affiliated with Shopify Inc.
+- The LLM-classification endpoints (industry / store type / growth stage) are
+  intentionally not exposed as MCP tools. The agent calling MCP is already an
+  LLM and can reason about the raw corpus data itself — exposing them would
+  waste tokens on a round trip to OpenAI.

storesignal_mcp-0.1.0/PUBLISH.md

@@ -0,0 +1,102 @@
+# Publish checklist for storesignal-mcp
+
+Following the same path meddata-mcp took. Order matters: GitHub first, then
+PyPI, then Smithery, then the MCP registry, then the landing-page section
+on storesignal.anthesia.io.
+
+## 1. GitHub repository
+
+Push this local repo to a new `anthesiallc/storesignal-mcp` repo on GitHub:
+
+```bash
+gh repo create anthesiallc/storesignal-mcp --public --source . --remote origin --push
+# or via web UI: github.com/new -> set name=storesignal-mcp -> add remote -> push
+```
+
+Verify the `Repository` link in `server.json` and the `Repository` URL in
+`pyproject.toml` both resolve.
+
+## 2. PyPI
+
+Build the wheel + sdist and upload. Requires a PyPI account + the package name
+`storesignal-mcp` available (it should be).
+
+```bash
+pip install --upgrade build twine
+python -m build
+twine upload dist/*
+```
+
+Verify after upload:
+
+```bash
+pip install --upgrade storesignal-mcp
+STORESIGNAL_API_KEY=ss_yourkey storesignal-mcp --help 2>&1 | head -3
+```
+
+(`mcp.run` doesn't have a `--help`, but the package should be importable and
+the script entry point should resolve.)
+
+## 3. Smithery
+
+Smithery hosts the streamable-HTTP transport. Push the GitHub repo first so
+Smithery can connect.
+
+1. Go to https://smithery.ai and sign in with the anthesiallc GitHub org
+2. Add a new server -> point at `github.com/anthesiallc/storesignal-mcp`
+3. Smithery reads `smithery.yaml`, builds the Dockerfile, and provisions the
+   container
+4. Test with the sample key (`ss_0123456789...`) -- it'll fail auth but should
+   confirm the server starts and accepts the apiKey config schema
+5. Update the README link from `https://smithery.ai/server/anthesiallc/storesignal`
+   to whatever URL Smithery assigns (should be exactly that, but verify)
+
+## 4. MCP registry
+
+The MCP registry indexes `server.json`. Submission:
+
+1. The schema URL in `server.json` is the official MCP one
+2. After PyPI is live, submit the server to https://registry.modelcontextprotocol.io
+   or PR it into the registry repo (the docs explain the path)
+3. Verify the package install path resolves
+4. Once accepted, MCP-aware clients will discover it automatically
+
+## 5. Landing-page section on storesignal.anthesia.io
+
+Mirror meddata's MCP block. The simplest is to add a new section between
+`#how-it-works` and `#pricing` on `app/static/index.html`:
+
+```html
+<section class="alt">
+  <div class="container" style="max-width: 720px;">
+    <div class="section-eyebrow"><span class="num">04</span>For AI agents (MCP)</div>
+    <h2>Use it from your agent</h2>
+    <p class="section-sub">StoreSignal runs as an MCP server, so Claude, Cursor, ChatGPT connectors, and LangChain agents can call it in conversation.</p>
+    <div style="background: var(--bg); border: 1px solid var(--border); border-radius: 10px; padding: 1.25rem; max-width: 480px; margin: 1rem auto; font-family: 'JetBrains Mono', monospace; font-size: 0.92rem; text-align: center;">uvx storesignal-mcp</div>
+    <div style="text-align: center; margin-top: 1rem;">
+      <a href="https://smithery.ai/server/anthesiallc/storesignal" style="margin: 0 0.5rem;">Connect on Smithery</a>
+      &middot;
+      <a href="https://github.com/anthesiallc/storesignal-mcp" style="margin: 0 0.5rem;">View source</a>
+    </div>
+  </div>
+</section>
+```
+
+(Renumber subsequent `<span class="num">` labels accordingly since pricing
+becomes No. 05 and signup becomes No. 06.)
+
+## 6. Final sanity checks
+
+After all the above, do an end-to-end install + call:
+
+```bash
+# In a fresh shell on a fresh machine:
+uvx storesignal-mcp --help   # entry point resolves
+# Then add to Claude Desktop config (per README), restart Claude Desktop,
+# ask: "What apps does Allbirds use?"
+# -> should trigger analyze_store and return the structured profile inline
+```
+
+If that works end-to-end, the MCP launch is done. Move the
+"build storesignal-mcp" todo from Pre-flight back to "shipped" in
+LAUNCH_PLAN.md.

storesignal_mcp-0.1.0/README.md

@@ -0,0 +1,161 @@
+# StoreSignal MCP Server
+
+mcp-name: io.github.anthesiallc/storesignal
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
+the [StoreSignal API](https://storesignal.anthesia.io) as tools, so any MCP
+client (Claude Desktop, Cursor, ChatGPT connectors, or an agent framework) can
+analyze Shopify stores and run market intelligence queries conversationally.
+
+It's a thin wrapper: each tool maps to one StoreSignal REST endpoint. All the
+data work happens in the API.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `analyze_store` | Full structured profile for a Shopify store URL (apps, CDN, security headers, schema.org, classification, revenue estimate) |
+| `compare_stores` | Side-by-side comparison of 2-5 stores (shared apps, exclusive apps, tier) |
+| `find_stores_using_app` | Paginated list of every analyzed store running a specific app |
+| `list_apps` | All 278 apps in the catalog, optionally filtered by category |
+| `app_adoption` | Top apps by adoption % across the corpus, optionally filtered by category |
+| `app_vs_app` | Head-to-head: install counts, overlap, co-install rate, bidirectional cross-adoption |
+| `industry_overview` | Per-vertical stats: store count, median price, top countries, top apps, tier mix |
+| `store_census` | Whole-corpus stats (19,647 stores, 20 industries, app/tier/type breakdowns) |
+| `get_usage` | Current billing period usage and plan limit |
+
+## Get an API key
+
+Free tier is 250 calls/month, no credit card:
+
+```bash
+curl -X POST https://storesignal.anthesia.io/api/v1/signup \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"you@example.com"}'
+```
+
+The key comes back in the `api_key` field of the response.
+
+## Install and run
+
+The easiest way is with [uv](https://docs.astral.sh/uv/) (no manual venv needed):
+
+```bash
+# stdio transport (default — for Claude Desktop, Cursor, most local clients)
+STORESIGNAL_API_KEY=ss_your_key uvx storesignal-mcp
+
+# streamable-HTTP transport (for remote / web clients)
+STORESIGNAL_API_KEY=ss_your_key uvx storesignal-mcp --http
+```
+
+Or install with pip into its own environment:
+
+```bash
+pip install storesignal-mcp
+STORESIGNAL_API_KEY=ss_your_key storesignal-mcp
+```
+
+> Note: install into a dedicated environment. The `mcp` SDK requires a newer
+> `starlette` than the StoreSignal API app pins, so the two will conflict if
+> installed together.
+
+Environment variables:
+
+- `STORESIGNAL_API_KEY` (required) — your StoreSignal API key.
+- `STORESIGNAL_BASE_URL` (optional) — defaults to `https://storesignal.anthesia.io`.
+- `STORESIGNAL_TIMEOUT` (optional) — request timeout in seconds, default `60`.
+
+## Client configuration
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "storesignal": {
+      "command": "uvx",
+      "args": ["storesignal-mcp"],
+      "env": { "STORESIGNAL_API_KEY": "ss_your_key" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add the same block to `~/.cursor/mcp.json` (or the project `.cursor/mcp.json`).
+
+### Smithery (hosted, no install)
+
+The server is hosted on [Smithery](https://smithery.ai/server/anthesiallc/storesignal),
+so MCP clients that support Smithery can connect without installing anything.
+You provide your StoreSignal API key in the Smithery config and it routes to
+the server.
+
+### LangChain / LangGraph
+
+Any LangChain or LangGraph agent can use these tools through
+[`langchain-mcp-adapters`](https://github.com/langchain-ai/langchain-mcp-adapters):
+
+```python
+# pip install langchain-mcp-adapters langgraph "langchain[anthropic]"
+from langchain_mcp_adapters.client import MultiServerMCPClient
+
+client = MultiServerMCPClient(
+    {
+        "storesignal": {
+            "transport": "stdio",
+            "command": "uvx",
+            "args": ["storesignal-mcp"],
+            "env": {"STORESIGNAL_API_KEY": "ss_your_key"},
+        }
+    }
+)
+tools = await client.get_tools()
+# hand `tools` to a LangGraph/LangChain agent, e.g.
+# from langgraph.prebuilt import create_react_agent
+# agent = create_react_agent("anthropic:claude-opus-4-8", tools)
+```
+
+LlamaIndex works the same way via its MCP tool spec.
+
+## Example agent conversations
+
+> "What apps does Allbirds use?"
+> → `analyze_store("https://www.allbirds.com")`
+
+> "Compare the tech stacks of Brooklinen and Bombas."
+> → `compare_stores(["https://brooklinen.com", "https://bombas.com"])`
+
+> "Which Shopify stores are running Judge.me?"
+> → `find_stores_using_app("judge-me")`
+
+> "What are the top email-marketing apps on Shopify?"
+> → `app_adoption(category="Email Marketing")`
+
+> "Compare Klaviyo to Omnisend."
+> → `app_vs_app("klaviyo", "omnisend")`
+
+> "Tell me about the Beauty vertical."
+> → `industry_overview("Beauty")`
+
+## Develop from source
+
+```bash
+git clone https://github.com/anthesiallc/storesignal-mcp && cd storesignal-mcp
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[http]"   # Windows; [http] adds uvicorn for --http
+# .venv/bin/pip install -e ".[http]"                # macOS/Linux
+STORESIGNAL_API_KEY=ss_your_key .venv/Scripts/python -m storesignal_mcp.server
+```
+
+## Notes
+
+- Data is extracted only from publicly accessible Shopify storefront endpoints.
+- Not affiliated with Shopify Inc.
+- The LLM-classification endpoints (industry / store type / growth stage) are
+  intentionally not exposed as MCP tools. The agent calling MCP is already an
+  LLM and can reason about the raw corpus data itself — exposing them would
+  waste tokens on a round trip to OpenAI.

storesignal_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "storesignal-mcp"
+version = "0.1.0"
+description = "MCP server for the StoreSignal API: Shopify store intelligence -- apps, tech stack, CDN, market aggregates, and competitive comparisons."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Anthesia", email = "support@anthesia.io" }]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "shopify",
+    "ecommerce",
+    "store-intelligence",
+    "competitive-intelligence",
+    "dtc",
+    "api",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+# Extra deps for serving over streamable-HTTP (e.g. hosted on Smithery).
+http = [
+    "uvicorn>=0.30.0",
+]
+
+[project.urls]
+Homepage = "https://storesignal.anthesia.io"
+Documentation = "https://storesignal.anthesia.io/docs"
+Repository = "https://github.com/anthesiallc/storesignal-mcp"
+
+[project.scripts]
+storesignal-mcp = "storesignal_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["storesignal_mcp"]

storesignal_mcp-0.1.0/server.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.anthesiallc/storesignal",
+  "description": "Shopify store intelligence: analyze any store URL for tech stack, apps, CDN, classification, and run market aggregates over a 19K-store corpus.",
+  "status": "active",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/anthesiallc/storesignal-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "storesignal-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "STORESIGNAL_API_KEY",
+          "description": "StoreSignal API key. Get a free one (250 calls/month, no card) at https://storesignal.anthesia.io",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": true
+        }
+      ]
+    }
+  ]
+}

storesignal_mcp-0.1.0/smithery.yaml

@@ -0,0 +1,25 @@
+# Smithery configuration for the StoreSignal MCP server.
+# https://smithery.ai/docs
+#
+# Hosted HTTP server: Smithery builds the Dockerfile and runs the container,
+# routing MCP traffic to /mcp on $PORT. Each user provides their own StoreSignal
+# API key, which Smithery passes as session config on every request.
+runtime: "container"
+build:
+  dockerfile: "Dockerfile"
+  dockerBuildPath: "."
+startCommand:
+  type: "http"
+  configSchema:
+    type: "object"
+    required:
+      - apiKey
+    properties:
+      apiKey:
+        type: "string"
+        title: "StoreSignal API Key"
+        description: >-
+          Your StoreSignal API key. Get a free one (250 calls/month, no card) at
+          https://storesignal.anthesia.io
+  exampleConfig:
+    apiKey: "ss_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

storesignal_mcp-0.1.0/storesignal_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""StoreSignal MCP server package."""
+
+__version__ = "0.1.0"

storesignal_mcp-0.1.0/storesignal_mcp/_smithery.py

@@ -0,0 +1,58 @@
+"""ASGI middleware for hosting on Smithery.
+
+Smithery's gateway forwards each user's configuration on the request to /mcp,
+either as a base64-encoded JSON `config` query parameter or as flat/dot-notation
+query parameters. This middleware extracts the StoreSignal API key from whichever
+form is present and stashes it in a ContextVar for the duration of the request,
+so each request uses its own caller's key (no shared global that could leak one
+user's key into another's concurrent request).
+
+Pair this with FastMCP(stateless_http=True) so the tool call is handled within
+the same request context that sets the key.
+"""
+
+import base64
+import json
+from urllib.parse import parse_qs, unquote
+
+from .config import request_api_key
+
+
+def _extract_api_key(query_string: str) -> str | None:
+    """Pull the StoreSignal API key out of Smithery's request config."""
+    qs = parse_qs(query_string)
+    # 1) Base64-encoded JSON config blob: ?config=<base64>
+    if "config" in qs and qs["config"]:
+        try:
+            decoded = base64.b64decode(unquote(qs["config"][0]))
+            cfg = json.loads(decoded)
+            if isinstance(cfg, dict):
+                key = cfg.get("apiKey") or cfg.get("storesignalApiKey")
+                if key:
+                    return key
+        except Exception:
+            pass
+    # 2) Flat or dot-notation query params: ?apiKey=... or ?config.apiKey=...
+    for name in ("apiKey", "storesignalApiKey", "config.apiKey"):
+        if name in qs and qs[name]:
+            return qs[name][0]
+    return None
+
+
+class SmitheryConfigMiddleware:
+    """Set the per-request API key ContextVar from the incoming /mcp request."""
+
+    def __init__(self, app) -> None:
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        token = None
+        if scope.get("type") == "http" and scope.get("path") in ("/mcp", "/mcp/"):
+            key = _extract_api_key(scope.get("query_string", b"").decode())
+            if key:
+                token = request_api_key.set(key)
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            if token is not None:
+                request_api_key.reset(token)

storesignal_mcp-0.1.0/storesignal_mcp/config.py

@@ -0,0 +1,26 @@
+"""Shared configuration and per-request key resolution.
+
+The API key can arrive two ways:
+- STORESIGNAL_API_KEY env var (stdio / local use, and a single-tenant default), or
+- per request via Smithery's config (set into request_api_key by the HTTP
+  middleware in _smithery.py).
+
+resolve_api_key() prefers the per-request value and falls back to the env var.
+"""
+
+import contextvars
+import os
+
+BASE_URL = os.environ.get("STORESIGNAL_BASE_URL", "https://storesignal.anthesia.io").rstrip("/")
+API_KEY = os.environ.get("STORESIGNAL_API_KEY", "")
+TIMEOUT = float(os.environ.get("STORESIGNAL_TIMEOUT", "60"))
+
+# Set per request by the Smithery middleware; unset in stdio mode.
+request_api_key: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "storesignal_api_key", default=None
+)
+
+
+def resolve_api_key() -> str:
+    """Return the caller's API key: per-request value if set, else the env var."""
+    return request_api_key.get() or API_KEY

storesignal_mcp-0.1.0/storesignal_mcp/server.py

@@ -0,0 +1,337 @@
+"""StoreSignal MCP server.
+
+Exposes the StoreSignal REST API (https://storesignal.anthesia.io) as Model
+Context Protocol tools so that agents and MCP-capable clients (Claude Desktop,
+Cursor, ChatGPT connectors, agent frameworks) can analyze Shopify stores,
+compare tech stacks, and surface market intelligence conversationally.
+
+This is a thin wrapper: every tool maps to one REST endpoint. The LLM-
+classification endpoints are intentionally not exposed -- the agent calling MCP
+is already an LLM and can reason about the raw corpus data itself.
+
+The API key is resolved per request: in stdio/local mode from the
+STORESIGNAL_API_KEY environment variable; when hosted over HTTP (e.g. on
+Smithery) from each caller's session config. Get a free key (250 calls/month,
+no card) from https://storesignal.anthesia.io or by POSTing your email to
+/api/v1/signup -- the key comes back in the response.
+
+Run it:
+    STORESIGNAL_API_KEY=ss_... storesignal-mcp                 # stdio (default)
+    STORESIGNAL_API_KEY=ss_... storesignal-mcp --http          # streamable-HTTP
+    STORESIGNAL_API_KEY=ss_... python -m storesignal_mcp.server # equivalent
+
+Data comes from publicly accessible Shopify storefront endpoints. Not affiliated
+with Shopify Inc.
+"""
+
+import os
+import sys
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+from mcp.server.transport_security import TransportSecuritySettings
+
+from .config import BASE_URL, TIMEOUT, resolve_api_key
+
+# stateless_http=True so that, when hosted over HTTP, each tool call is handled
+# within the request that carried the caller's config (see _smithery.py).
+#
+# DNS-rebinding protection validates the Host header against an allowlist, which
+# is meant for servers bound to localhost. This is a public, multi-tenant HTTP
+# gateway reached through Railway/Smithery under arbitrary hostnames, so that
+# check is disabled here; access is gated by the per-request StoreSignal API
+# key and the API's own quotas, not by the Host header.
+mcp = FastMCP(
+    name="StoreSignal",
+    stateless_http=True,
+    transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False),
+    instructions=(
+        "Tools for Shopify store intelligence: analyze any store URL to get its "
+        "tech stack (apps installed, payment providers, CDN, security headers, "
+        "schema.org markup, industry/store-type classification), compare stores "
+        "head-to-head, find every store using a specific app, and run market "
+        "aggregates over the 19,647-store corpus (app adoption %, app-vs-app "
+        "cross-install rates, per-industry rollups). Use analyze_store as the "
+        "default entry point when given a single URL. Use the /market tools "
+        "(app_adoption, app_vs_app, industry_overview) for population-level "
+        "questions like \"what apps are popular in Beauty?\" or \"how often "
+        "do Klaviyo and Omnisend coexist?\". All data is from publicly "
+        "accessible Shopify storefront endpoints; we do not bypass auth or "
+        "scrape private data."
+    ),
+)
+
+
+async def _get(path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Call a StoreSignal GET endpoint and return parsed JSON (or an error dict)."""
+    api_key = resolve_api_key()
+    if not api_key:
+        return {
+            "error": "missing_api_key",
+            "detail": (
+                "No StoreSignal API key configured. Set the STORESIGNAL_API_KEY "
+                "environment variable (stdio) or provide your key in the client "
+                "config (hosted). Get a free key at https://storesignal.anthesia.io "
+                "(no credit card)."
+            ),
+        }
+    headers = {"X-API-Key": api_key, "Accept": "application/json"}
+    try:
+        async with httpx.AsyncClient(timeout=TIMEOUT) as client:
+            resp = await client.get(f"{BASE_URL}{path}", params=params, headers=headers)
+    except httpx.RequestError as exc:
+        return {"error": "network_error", "detail": str(exc)}
+
+    if resp.status_code >= 400:
+        # The API returns a structured ErrorResponse; pass its detail through.
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {"detail": resp.text[:500]}
+        return {
+            "error": f"http_{resp.status_code}",
+            "detail": body.get("detail") or body.get("error") or "Request failed.",
+            "status_code": resp.status_code,
+        }
+    try:
+        return resp.json()
+    except ValueError:
+        return {"error": "bad_response", "detail": "API returned non-JSON content."}
+
+
+async def _post(path: str, body: dict[str, Any]) -> dict[str, Any]:
+    """Call a StoreSignal POST endpoint (currently only the batch endpoints)."""
+    api_key = resolve_api_key()
+    if not api_key:
+        return {
+            "error": "missing_api_key",
+            "detail": "No StoreSignal API key configured.",
+        }
+    headers = {
+        "X-API-Key": api_key,
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    try:
+        async with httpx.AsyncClient(timeout=TIMEOUT) as client:
+            resp = await client.post(f"{BASE_URL}{path}", headers=headers, json=body)
+    except httpx.RequestError as exc:
+        return {"error": "network_error", "detail": str(exc)}
+    if resp.status_code >= 400:
+        try:
+            err = resp.json()
+        except ValueError:
+            err = {"detail": resp.text[:500]}
+        return {
+            "error": f"http_{resp.status_code}",
+            "detail": err.get("detail") or err.get("error") or "Request failed.",
+            "status_code": resp.status_code,
+        }
+    try:
+        return resp.json()
+    except ValueError:
+        return {"error": "bad_response", "detail": "API returned non-JSON content."}
+
+
+@mcp.tool()
+async def analyze_store(url: str) -> dict[str, Any]:
+    """Analyze a single Shopify store URL and return a full structured profile.
+
+    Returns the store's name, theme, product count, apps installed, payment +
+    analytics + checkout providers, CDN brand, security headers, schema.org
+    markup, AI-classified industry / store type / growth stage (paid tiers),
+    revenue estimate, social media, and more.
+
+    Use this as the default entry point when the user asks "what's this store
+    using" or "tell me about https://...". If the URL is already in the 19K-store
+    corpus the response is served from cache; otherwise the API runs a fresh
+    crawl (5-15 seconds for new stores).
+
+    Args:
+        url: Shopify store URL, e.g. "https://www.allbirds.com".
+    """
+    return await _get("/api/v1/stores/analyze", {"url": url})
+
+
+@mcp.tool()
+async def compare_stores(urls: list[str]) -> dict[str, Any]:
+    """Side-by-side comparison of 2-5 Shopify stores.
+
+    Returns each store's profile plus a comparison table: shared apps, apps
+    unique to each, payment-provider overlap, tier comparison. Good for
+    "compare https://A and https://B" or competitive recon questions.
+
+    Args:
+        urls: 2-5 Shopify store URLs to compare.
+    """
+    if len(urls) < 2:
+        return {"error": "too_few_urls", "detail": "Provide at least 2 URLs."}
+    if len(urls) > 5:
+        return {"error": "too_many_urls", "detail": "Maximum 5 URLs per comparison."}
+    return await _post("/api/v1/stores/compare", {"urls": urls})
+
+
+@mcp.tool()
+async def find_stores_using_app(
+    app_slug: str, limit: int = 20, offset: int = 0
+) -> dict[str, Any]:
+    """List analyzed Shopify stores that have a specific app installed.
+
+    Returns paginated stores (up to 100 per page) with the basic profile so the
+    agent can do downstream filtering or rank by store tier / country / industry.
+    Useful for prospecting: "find me stores running Klaviyo" or "who's using
+    ReCharge Subscriptions in the apparel vertical".
+
+    Args:
+        app_slug: Catalog slug, e.g. "klaviyo", "judge-me", "loox", "yotpo",
+            "recharge", "shogun", "pagefly". List all slugs with list_apps().
+        limit: Results per page (1-100).
+        offset: Pagination offset.
+    """
+    return await _get(
+        f"/api/v1/apps/{app_slug}/stores",
+        {"limit": limit, "offset": offset},
+    )
+
+
+@mcp.tool()
+async def list_apps(category: str | None = None, limit: int = 50) -> dict[str, Any]:
+    """List all apps in the StoreSignal catalog (currently 278 apps).
+
+    Returns each app with its slug, display name, category, subcategory,
+    estimated monthly cost tier, competing alternatives, and live install count
+    across the corpus. Use this to discover what's trackable before calling
+    find_stores_using_app or app_vs_app.
+
+    Args:
+        category: Optional category filter, e.g. "Email Marketing", "Reviews",
+            "Payment", "Analytics", "Loyalty", "Privacy", "Fraud & Risk".
+        limit: Max apps to return (1-200).
+    """
+    params: dict[str, Any] = {"limit": limit}
+    if category:
+        params["category"] = category
+    return await _get("/api/v1/apps", params)
+
+
+@mcp.tool()
+async def app_adoption(category: str | None = None, limit: int = 25) -> dict[str, Any]:
+    """Percentage of analyzed Shopify stores using each app.
+
+    Returns apps ranked by adoption percentage. For example, PayPal is on 99.6%
+    of stores; Klaviyo 24.9%. Optionally filter by category to see (e.g.) only
+    the email-marketing landscape.
+
+    Args:
+        category: Optional category to filter on (Email Marketing, Reviews,
+            Payment, Analytics, Loyalty, etc).
+        limit: Top-N apps to return (1-200).
+    """
+    params: dict[str, Any] = {"limit": limit}
+    if category:
+        params["category"] = category
+    return await _get("/api/v1/market/app-adoption", params)
+
+
+@mcp.tool()
+async def app_vs_app(app_a: str, app_b: str) -> dict[str, Any]:
+    """Head-to-head comparison of two apps' installed bases.
+
+    Returns: install count for each app, exclusive users (A only / B only),
+    overlap (both installed), co-install rate (overlap as % of union), and
+    bidirectional cross-adoption (% of A users that also run B, and vice versa).
+
+    Good for competitive questions like "is Omnisend losing ground to Klaviyo?".
+    The cross-install asymmetry is usually the most interesting number: if 44%
+    of B users also run A but only 5% of A users run B, A is eating B's market
+    from the inside.
+
+    Args:
+        app_a: Slug of the first app (e.g. "klaviyo").
+        app_b: Slug of the second app (e.g. "omnisend").
+    """
+    return await _get(
+        "/api/v1/market/app-vs-app", {"a": app_a, "b": app_b}
+    )
+
+
+@mcp.tool()
+async def industry_overview(industry: str) -> dict[str, Any]:
+    """Big-picture stats for one industry vertical.
+
+    Returns: store count, median product count, median price (with p25/p75
+    quartiles), average domain age, country distribution, store-tier mix
+    (small/medium/large), store-type mix (DTC/marketplace/dropshipper), and
+    the top apps installed across the vertical.
+
+    Use for questions like "what does the Beauty vertical look like on
+    Shopify?" or "are Apparel stores mostly DTC or marketplaces?".
+
+    Args:
+        industry: One of: Apparel, Beauty, Home & Garden, Food & Beverage,
+            Electronics, Pets, Fitness & Sports, Jewelry & Accessories,
+            Toys & Games, Automotive, Health & Wellness, Outdoors & Adventure,
+            Baby & Kids, Books & Stationery, Arts & Crafts, Music & Instruments,
+            Office & Business, Travel & Luggage, Gifts & Novelty, Other.
+    """
+    return await _get(
+        "/api/v1/market/industry-overview", {"industry": industry}
+    )
+
+
+@mcp.tool()
+async def store_census() -> dict[str, Any]:
+    """High-level statistics for the entire analyzed-stores corpus.
+
+    Returns: total stores indexed, count classified, distinct countries,
+    distinct industries, total apps in the catalog, plus breakdowns
+    (top 25 countries, all industries, tier mix, store-type mix, growth-stage
+    mix). Useful when the agent or user wants to understand the dataset's
+    scope before doing more targeted queries.
+    """
+    return await _get("/api/v1/market/store-census")
+
+
+@mcp.tool()
+async def get_usage() -> dict[str, Any]:
+    """Show this API key's current billing period usage and plan limits."""
+    return await _get("/api/v1/billing/usage")
+
+
+def run_http() -> None:
+    """Serve over streamable-HTTP with CORS + Smithery config middleware.
+
+    Listens on $PORT (Smithery sets this; defaults to 8080) at /mcp.
+    """
+    import uvicorn
+    from starlette.middleware.cors import CORSMiddleware
+
+    from ._smithery import SmitheryConfigMiddleware
+
+    app = mcp.streamable_http_app()
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["GET", "POST", "OPTIONS"],
+        allow_headers=["*"],
+        expose_headers=["mcp-session-id"],
+        max_age=86400,
+    )
+    app = SmitheryConfigMiddleware(app)
+
+    port = int(os.environ.get("PORT", "8080"))
+    uvicorn.run(app, host="0.0.0.0", port=port, log_level="info")
+
+
+def main() -> None:
+    """Run the MCP server. Use --http for streamable-HTTP, otherwise stdio."""
+    if "--http" in sys.argv:
+        run_http()
+    else:
+        mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()