getsonar-mcp 0.1.0__tar.gz

getsonar_mcp-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+.venv/
+venv/
+env/
+
+# Environment — NEVER commit these
+.env
+backend/.env
+
+# Frontend
+frontend/node_modules/
+frontend/dist/
+frontend/.env
+
+# macOS
+.DS_Store
+
+# Logs
+*.log
+Logs/
+BG.mp4
+BG.png
+BG1 .mp4
+*.gif
+
+# Wave 2 validation venv — local only
+backend/.venv-test/

getsonar_mcp-0.1.0/LICENSE

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

getsonar_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: getsonar-mcp
+Version: 0.1.0
+Summary: MCP server for SONAR — competitive intelligence, KYB due diligence, and adverse media screening for AI agents.
+Project-URL: Homepage, https://getsonar.report
+Project-URL: Documentation, https://getsonar.report/developers
+Project-URL: API Reference, https://api.getsonar.report/docs
+Project-URL: Support, https://getsonar.report/api-keys
+Author-email: SONAR <ivan.vakulenko@wildix.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adverse-media,anthropic,claude,competitive-intelligence,compliance,kyb,mcp,model-context-protocol,osint
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: http
+Requires-Dist: uvicorn>=0.30.0; extra == 'http'
+Description-Content-Type: text/markdown
+
+# getsonar-mcp
+
+MCP server for [SONAR](https://getsonar.report) — competitive intelligence, KYB due diligence, and adverse media screening, exposed as tools any MCP-compatible AI client can call.
+
+Works with **Claude Desktop**, **Claude Code**, **Cursor**, **Windsurf**, **Continue.dev**, and any other [Model Context Protocol](https://modelcontextprotocol.io) client.
+
+## What it does
+
+Adds 7 tools to your AI assistant:
+
+| Tool | What it does | Cost (after free tier) |
+|---|---|---|
+| `kyb_findings` | Quick KYB lookup — corporate registration, sanctions, FCA, directors, UBOs | $0.40 |
+| `kyb_run_submit` | Full KYB report (async, with Claude analysis) | $2.00 |
+| `competitive_findings` | Quick competitor intel — pricing, hiring, product, sentiment | $0.40 |
+| `competitive_run_submit` | Full CI report (async, with Claude analysis) | $2.00 |
+| `adverse_media` | Negative news + complaints + bad-review screening | $0.40 |
+| `check_report_status` | Poll the result of an async `*_run_submit` call | free |
+| `account_balance` | Check remaining free-tier calls + usage | free |
+
+**Free tier: 100 calls/month** per API key. Beyond that, balance-deducted at the prices above.
+
+## Get an API key
+
+1. Sign up at [getsonar.report](https://getsonar.report)
+2. Go to **API Keys** in the sidebar
+3. Click **Create API Key**, copy the `sk-sonar-...` key
+4. (Optional) Top up your account on the same page if you'll exceed 100 calls/month
+
+## Install
+
+### Recommended: `uvx` (no install needed)
+
+If you have [`uv`](https://docs.astral.sh/uv/) installed (most modern Python setups), nothing to install — `uvx getsonar-mcp` runs the latest version on demand.
+
+### Alternative: `pipx`
+
+```bash
+pipx install getsonar-mcp
+```
+
+## Configure your MCP client
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "sonar": {
+      "command": "uvx",
+      "args": ["getsonar-mcp"],
+      "env": {
+        "SONAR_API_KEY": "sk-sonar-YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The 7 tools should appear in the 🔌 menu.
+
+### Claude Code
+
+Add to your project's `.mcp.json` or run:
+
+```bash
+claude mcp add sonar -- uvx getsonar-mcp
+# Then in your shell: export SONAR_API_KEY=sk-sonar-...
+```
+
+Or with the env var inline:
+
+```bash
+claude mcp add sonar --env SONAR_API_KEY=sk-sonar-... -- uvx getsonar-mcp
+```
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sonar": {
+      "command": "uvx",
+      "args": ["getsonar-mcp"],
+      "env": {
+        "SONAR_API_KEY": "sk-sonar-YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### Windsurf / Continue.dev
+
+Same config shape as Claude Desktop. See your client's MCP docs for the config file path.
+
+## Configuration
+
+Environment variables (all optional except `SONAR_API_KEY`):
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `SONAR_API_KEY` | (required) | Your `sk-sonar-...` API key |
+| `SONAR_API_BASE` | `https://api.getsonar.report` | Override for staging / self-hosted SONAR |
+| `SONAR_API_TIMEOUT` | `120` | Per-request timeout in seconds |
+| `SONAR_MCP_LOG_LEVEL` | `INFO` | `DEBUG` for verbose tool dispatch logs |
+
+## Example prompts
+
+After configuring, try these in Claude:
+
+> "Run a KYB check on Tesco PLC and tell me if anything looks risky."
+>
+> Claude calls `kyb_findings("Tesco PLC")` → ~30s → reads back the structured findings → highlights the FCA Register hit, any sanctions matches, director-level red flags.
+
+> "Submit a full competitive analysis for Notion and tell me when it's done."
+>
+> Claude calls `competitive_run_submit("Notion")` → gets `run_id` → polls `check_report_status` every 30s → returns the narrative report.
+
+> "Am I close to my free-tier limit?"
+>
+> Claude calls `account_balance()` → tells you how many of your 100 free monthly calls you've used.
+
+## How async reports work
+
+The `*_run_submit` tools return a `run_id` immediately (in <1s). Claude then needs to call `check_report_status(run_id, agent_type)` to fetch the result, which is normally ready in 60-180s. Most MCP clients handle this seamlessly — Claude knows from the tool descriptions to poll until status="completed".
+
+The cheaper `*_findings` tools are synchronous and complete in 30-90s on a single call. Use those when the LLM just needs raw structured data and will do its own analysis.
+
+## Verify your install
+
+Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to confirm the server starts and tool dispatch works:
+
+```bash
+SONAR_API_KEY=sk-sonar-... npx @modelcontextprotocol/inspector uvx getsonar-mcp
+```
+
+You should see all 7 tools listed and be able to invoke them with test inputs.
+
+## Source
+
+`getsonar-mcp` is a thin client for the SONAR public API. The source is currently maintained privately; for issues, feature requests, or transport changes, email **ivan.vakulenko@wildix.com**.
+
+## Troubleshooting
+
+**Claude says "tool not available"** — check `claude_desktop_config.json` is valid JSON, restart Claude Desktop, then verify `uvx --version` runs in your terminal.
+
+**`401 Unauthorized`** — `SONAR_API_KEY` is missing or wrong. Verify in the SONAR dashboard at [getsonar.report/api-keys](https://getsonar.report/api-keys).
+
+**`402 Payment Required`** — your free tier is exhausted and your balance is $0. Top up at [getsonar.report/api-keys](https://getsonar.report/api-keys).
+
+**Timeouts** — bump `SONAR_API_TIMEOUT` in your env config. The `/run` tools can take 3+ minutes for complex KYB subjects.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

getsonar_mcp-0.1.0/README.md

@@ -0,0 +1,160 @@
+# getsonar-mcp
+
+MCP server for [SONAR](https://getsonar.report) — competitive intelligence, KYB due diligence, and adverse media screening, exposed as tools any MCP-compatible AI client can call.
+
+Works with **Claude Desktop**, **Claude Code**, **Cursor**, **Windsurf**, **Continue.dev**, and any other [Model Context Protocol](https://modelcontextprotocol.io) client.
+
+## What it does
+
+Adds 7 tools to your AI assistant:
+
+| Tool | What it does | Cost (after free tier) |
+|---|---|---|
+| `kyb_findings` | Quick KYB lookup — corporate registration, sanctions, FCA, directors, UBOs | $0.40 |
+| `kyb_run_submit` | Full KYB report (async, with Claude analysis) | $2.00 |
+| `competitive_findings` | Quick competitor intel — pricing, hiring, product, sentiment | $0.40 |
+| `competitive_run_submit` | Full CI report (async, with Claude analysis) | $2.00 |
+| `adverse_media` | Negative news + complaints + bad-review screening | $0.40 |
+| `check_report_status` | Poll the result of an async `*_run_submit` call | free |
+| `account_balance` | Check remaining free-tier calls + usage | free |
+
+**Free tier: 100 calls/month** per API key. Beyond that, balance-deducted at the prices above.
+
+## Get an API key
+
+1. Sign up at [getsonar.report](https://getsonar.report)
+2. Go to **API Keys** in the sidebar
+3. Click **Create API Key**, copy the `sk-sonar-...` key
+4. (Optional) Top up your account on the same page if you'll exceed 100 calls/month
+
+## Install
+
+### Recommended: `uvx` (no install needed)
+
+If you have [`uv`](https://docs.astral.sh/uv/) installed (most modern Python setups), nothing to install — `uvx getsonar-mcp` runs the latest version on demand.
+
+### Alternative: `pipx`
+
+```bash
+pipx install getsonar-mcp
+```
+
+## Configure your MCP client
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "sonar": {
+      "command": "uvx",
+      "args": ["getsonar-mcp"],
+      "env": {
+        "SONAR_API_KEY": "sk-sonar-YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The 7 tools should appear in the 🔌 menu.
+
+### Claude Code
+
+Add to your project's `.mcp.json` or run:
+
+```bash
+claude mcp add sonar -- uvx getsonar-mcp
+# Then in your shell: export SONAR_API_KEY=sk-sonar-...
+```
+
+Or with the env var inline:
+
+```bash
+claude mcp add sonar --env SONAR_API_KEY=sk-sonar-... -- uvx getsonar-mcp
+```
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sonar": {
+      "command": "uvx",
+      "args": ["getsonar-mcp"],
+      "env": {
+        "SONAR_API_KEY": "sk-sonar-YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### Windsurf / Continue.dev
+
+Same config shape as Claude Desktop. See your client's MCP docs for the config file path.
+
+## Configuration
+
+Environment variables (all optional except `SONAR_API_KEY`):
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `SONAR_API_KEY` | (required) | Your `sk-sonar-...` API key |
+| `SONAR_API_BASE` | `https://api.getsonar.report` | Override for staging / self-hosted SONAR |
+| `SONAR_API_TIMEOUT` | `120` | Per-request timeout in seconds |
+| `SONAR_MCP_LOG_LEVEL` | `INFO` | `DEBUG` for verbose tool dispatch logs |
+
+## Example prompts
+
+After configuring, try these in Claude:
+
+> "Run a KYB check on Tesco PLC and tell me if anything looks risky."
+>
+> Claude calls `kyb_findings("Tesco PLC")` → ~30s → reads back the structured findings → highlights the FCA Register hit, any sanctions matches, director-level red flags.
+
+> "Submit a full competitive analysis for Notion and tell me when it's done."
+>
+> Claude calls `competitive_run_submit("Notion")` → gets `run_id` → polls `check_report_status` every 30s → returns the narrative report.
+
+> "Am I close to my free-tier limit?"
+>
+> Claude calls `account_balance()` → tells you how many of your 100 free monthly calls you've used.
+
+## How async reports work
+
+The `*_run_submit` tools return a `run_id` immediately (in <1s). Claude then needs to call `check_report_status(run_id, agent_type)` to fetch the result, which is normally ready in 60-180s. Most MCP clients handle this seamlessly — Claude knows from the tool descriptions to poll until status="completed".
+
+The cheaper `*_findings` tools are synchronous and complete in 30-90s on a single call. Use those when the LLM just needs raw structured data and will do its own analysis.
+
+## Verify your install
+
+Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to confirm the server starts and tool dispatch works:
+
+```bash
+SONAR_API_KEY=sk-sonar-... npx @modelcontextprotocol/inspector uvx getsonar-mcp
+```
+
+You should see all 7 tools listed and be able to invoke them with test inputs.
+
+## Source
+
+`getsonar-mcp` is a thin client for the SONAR public API. The source is currently maintained privately; for issues, feature requests, or transport changes, email **ivan.vakulenko@wildix.com**.
+
+## Troubleshooting
+
+**Claude says "tool not available"** — check `claude_desktop_config.json` is valid JSON, restart Claude Desktop, then verify `uvx --version` runs in your terminal.
+
+**`401 Unauthorized`** — `SONAR_API_KEY` is missing or wrong. Verify in the SONAR dashboard at [getsonar.report/api-keys](https://getsonar.report/api-keys).
+
+**`402 Payment Required`** — your free tier is exhausted and your balance is $0. Top up at [getsonar.report/api-keys](https://getsonar.report/api-keys).
+
+**Timeouts** — bump `SONAR_API_TIMEOUT` in your env config. The `/run` tools can take 3+ minutes for complex KYB subjects.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

getsonar_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "getsonar-mcp"
+version = "0.1.0"
+description = "MCP server for SONAR — competitive intelligence, KYB due diligence, and adverse media screening for AI agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "SONAR", email = "ivan.vakulenko@wildix.com" },
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "anthropic",
+    "kyb",
+    "compliance",
+    "competitive-intelligence",
+    "osint",
+    "adverse-media",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+http = [
+    "uvicorn>=0.30.0",
+]
+
+[project.urls]
+Homepage = "https://getsonar.report"
+Documentation = "https://getsonar.report/developers"
+"API Reference" = "https://api.getsonar.report/docs"
+Support = "https://getsonar.report/api-keys"
+
+[project.scripts]
+getsonar-mcp = "getsonar_mcp.__main__:main"
+getsonar-mcp-http = "getsonar_mcp.http_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/getsonar_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/pyproject.toml",
+]

getsonar_mcp-0.1.0/src/getsonar_mcp/__init__.py

@@ -0,0 +1,20 @@
+"""SONAR Intelligence MCP Server.
+
+Exposes SONAR's competitive intelligence, KYB due diligence, and adverse
+media screening tools to MCP-compatible AI clients (Claude Desktop, Claude
+Code, Cursor, etc.).
+
+Two transports from one codebase:
+
+  - **stdio** (default, for local install) — ``python -m getsonar_mcp`` or
+    ``uvx getsonar-mcp``. Each customer runs the server locally, configures
+    their API key via the ``SONAR_API_KEY`` env var, and adds the command
+    to their MCP client config. No infrastructure required.
+
+  - **streamable-http** (remote/hosted) — ``python -m getsonar_mcp.http_server``
+    starts an HTTP MCP endpoint suitable for Render / Cloud Run. Customers
+    paste a single URL into their MCP client config; OAuth handles auth.
+    See ``http_server.py`` and ``oauth.py`` for the deployment story.
+"""
+
+__version__ = "0.1.0"

getsonar_mcp-0.1.0/src/getsonar_mcp/__main__.py

@@ -0,0 +1,53 @@
+"""Stdio MCP entry point — what ``uvx getsonar-mcp`` and
+``python -m getsonar_mcp`` invoke.
+
+The default transport for local install. Each customer runs the server
+on their own machine; the MCP client (Claude Desktop / Code / Cursor)
+spawns this process and talks to it over stdin/stdout. The customer's
+``SONAR_API_KEY`` env var holds their API key — see the README for
+client-specific config snippets.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+from . import __version__
+from .tools import register_tools
+
+
+def _setup_logging() -> None:
+    """Log to stderr so MCP-protocol stdout stays clean."""
+    level = os.environ.get("SONAR_MCP_LOG_LEVEL", "INFO").upper()
+    logging.basicConfig(
+        level=getattr(logging, level, logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+def main() -> None:
+    _setup_logging()
+    log = logging.getLogger("getsonar-mcp")
+    log.info("Starting SONAR MCP server v%s (stdio transport)", __version__)
+
+    mcp = FastMCP(
+        "SONAR Intelligence",
+        description=(
+            "AI-powered competitive intelligence, KYB due diligence, and "
+            "adverse media screening. Backed by 40+ OSINT sources. "
+            "Get an API key at https://getsonar.report/api-keys."
+        ),
+    )
+    register_tools(mcp)
+
+    # FastMCP.run() defaults to stdio transport when called with no args
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

getsonar_mcp-0.1.0/src/getsonar_mcp/client.py

@@ -0,0 +1,213 @@
+"""HTTP client + response formatters for the SONAR public API.
+
+Shared by both stdio and streamable-http MCP transports. The transport
+layer just wires up tool dispatch; this module owns the actual API calls.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger("getsonar-mcp.client")
+
+# Public-API base URL. Custom-domain default — overridable for staging /
+# self-hosted deployments via env.
+DEFAULT_API_BASE = "https://api.getsonar.report"
+
+DEFAULT_TIMEOUT_S = 120
+
+
+def get_api_base() -> str:
+    return os.environ.get("SONAR_API_BASE", DEFAULT_API_BASE).rstrip("/")
+
+
+def get_default_timeout() -> int:
+    raw = os.environ.get("SONAR_API_TIMEOUT", "").strip()
+    if not raw:
+        return DEFAULT_TIMEOUT_S
+    try:
+        return max(5, int(raw))
+    except ValueError:
+        return DEFAULT_TIMEOUT_S
+
+
+def get_api_key_from_env() -> str:
+    """Resolve the API key from the environment. Raises a friendly error
+    when the env var is missing — the most common config mistake."""
+    key = os.environ.get("SONAR_API_KEY", "").strip()
+    if not key:
+        raise RuntimeError(
+            "SONAR_API_KEY environment variable is not set. "
+            "Get a key at https://getsonar.report/api-keys, then add "
+            "SONAR_API_KEY to your MCP client config."
+        )
+    return key
+
+
+async def call_sonar(
+    method: str,
+    path: str,
+    api_key: str,
+    *,
+    body: Optional[dict] = None,
+    timeout: Optional[int] = None,
+) -> dict:
+    """Call the SONAR REST API and return the parsed JSON response.
+
+    Returns ``{"error": True, "status": int, "message": str}`` on non-200
+    so callers can format a friendly message without try/except.
+    """
+    url = f"{get_api_base()}{path}"
+    headers = {
+        "Content-Type": "application/json",
+        "X-API-Key": api_key,
+        "User-Agent": "getsonar-mcp/0.1.0",
+    }
+    actual_timeout = timeout or get_default_timeout()
+
+    try:
+        async with httpx.AsyncClient(timeout=actual_timeout) as c:
+            if method == "POST":
+                resp = await c.post(url, json=body or {}, headers=headers)
+            else:
+                resp = await c.get(url, headers=headers)
+    except httpx.TimeoutException:
+        return {
+            "error": True,
+            "status": 0,
+            "message": (
+                f"Request to {path} timed out after {actual_timeout}s. "
+                "The /findings endpoint usually responds in 30-90s; if "
+                "you're consistently timing out, raise SONAR_API_TIMEOUT."
+            ),
+        }
+    except httpx.RequestError as e:
+        return {
+            "error": True,
+            "status": 0,
+            "message": f"Network error calling {path}: {type(e).__name__}",
+        }
+
+    if resp.status_code != 200 and resp.status_code != 202:
+        try:
+            err = resp.json()
+            # The SONAR public API wraps errors as
+            # {"detail": {"error": {"code": str, "message": str, ...}}}
+            msg = (
+                err.get("detail", {}).get("error", {}).get("message")
+                or err.get("detail")
+                or resp.text
+            )
+        except Exception:
+            msg = resp.text
+        return {
+            "error": True,
+            "status": resp.status_code,
+            "message": str(msg)[:400],
+        }
+
+    try:
+        return resp.json()
+    except ValueError:
+        return {"error": True, "status": resp.status_code, "message": "non-JSON response"}
+
+
+# ── Response formatters ──────────────────────────────────────────────────────
+
+
+def format_findings(result: dict, title: str) -> str:
+    """Format a /findings API response as readable Markdown for the LLM."""
+    if result.get("error"):
+        # Surface a friendly 402 message verbatim — it includes top-up URL
+        # and the customer needs to see it
+        if result.get("status") == 402:
+            return f"⚠️  Insufficient balance.\n\n{result.get('message', '')}"
+        return (
+            f"⚠️  SONAR API error (HTTP {result.get('status', '?')}).\n\n"
+            f"{result.get('message', 'unknown error')}"
+        )
+
+    fields = result.get("fields", {})
+    found = result.get("fields_found", []) or []
+    not_found = result.get("fields_not_found", []) or []
+    sources = result.get("sources_checked", 0)
+    time_ms = result.get("processing_time_ms", 0)
+
+    parts = [
+        f"# {title}",
+        f"Sources checked: {sources} · Processing time: {time_ms}ms",
+        f"Fields with data: {', '.join(found) if found else 'none'}",
+    ]
+    if not_found:
+        parts.append(f"No data for: {', '.join(not_found)}")
+    parts.append("")
+
+    for field_name, field_data in fields.items():
+        findings = (field_data or {}).get("findings", []) or []
+        confidence = (field_data or {}).get("confidence") or "N/A"
+        if findings:
+            label = field_name.replace("_", " ").title()
+            parts.append(f"## {label} (confidence: {confidence})")
+            for f in findings:
+                value = f.get("value", "") or ""
+                detail = f.get("detail", "") or ""
+                sources_list = f.get("sources", []) or []
+                url = sources_list[0].get("url", "") if sources_list else ""
+                parts.append(f"- **{value}**")
+                if detail:
+                    parts.append(f"  {detail}")
+                if url:
+                    parts.append(f"  Source: {url}")
+            parts.append("")
+
+    if not found:
+        parts.append("No findings detected across all sources.")
+
+    return "\n".join(parts)
+
+
+def format_run_started(result: dict, agent_type: str) -> str:
+    """Format the /run async-submit response."""
+    if result.get("error"):
+        if result.get("status") == 402:
+            return f"⚠️  Insufficient balance.\n\n{result.get('message', '')}"
+        return (
+            f"⚠️  Failed to start report (HTTP {result.get('status', '?')}).\n\n"
+            f"{result.get('message', '')}"
+        )
+
+    run_id = result.get("run_id", "")
+    status = result.get("status", "")
+    est = result.get("estimated_seconds", 90)
+    return (
+        f"Report submitted.\n"
+        f"- Run ID: `{run_id}`\n"
+        f"- Status: {status}\n"
+        f"- Estimated time: {est} seconds\n\n"
+        f"Call `check_report_status` with run_id='{run_id}' and "
+        f"agent_type='{agent_type}' in 30-60 seconds to get the result."
+    )
+
+
+def format_run_status(result: dict) -> str:
+    """Format the /run/{id} status-poll response."""
+    if result.get("error"):
+        return (
+            f"⚠️  Failed to check report status (HTTP {result.get('status', '?')}).\n\n"
+            f"{result.get('message', '')}"
+        )
+
+    status = result.get("status", "unknown")
+    if status == "completed":
+        report = result.get("report", {}) or result.get("report_json", {}) or {}
+        # Compress: skip empty fields, return the narrative + key findings
+        return f"Report completed.\n\n```json\n{json.dumps(report, indent=2)[:8000]}\n```"
+    if status == "failed":
+        err = result.get("error_message") or result.get("error") or "Unknown error"
+        return f"Report failed: {err}"
+    return f"Report status: {status}. Still processing — check again in 15-30 seconds."

getsonar_mcp-0.1.0/src/getsonar_mcp/http_server.py

@@ -0,0 +1,61 @@
+"""Streamable-HTTP MCP server entry point — for hosted/remote deployment.
+
+Same tools as the stdio variant, just exposed via Streamable HTTP so a
+single hosted instance can serve many customers. Combine with ``oauth.py``
+(in the parent directory) once OAuth is fully wired into the request
+pipeline so per-user API keys are resolved from the bearer token.
+
+For now this still uses the global ``SONAR_API_KEY`` env var as the
+authentication gate. That's correct for self-hosted single-tenant; full
+multi-tenant deployment needs the OAuth ``validate_token`` integration.
+
+Run via:
+    python -m getsonar_mcp.http_server
+or:
+    PORT=8080 python -m getsonar_mcp.http_server
+
+The Dockerfile in the parent directory uses the legacy ``server.py``
+entry which delegates here.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+from . import __version__
+from .tools import register_tools
+
+
+def _setup_logging() -> None:
+    level = os.environ.get("SONAR_MCP_LOG_LEVEL", "INFO").upper()
+    logging.basicConfig(
+        level=getattr(logging, level, logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+def main() -> None:
+    _setup_logging()
+    log = logging.getLogger("getsonar-mcp.http")
+    port = int(os.environ.get("PORT", "8080"))
+    log.info("Starting SONAR MCP server v%s (streamable-http on :%d)",
+             __version__, port)
+
+    mcp = FastMCP(
+        "SONAR Intelligence",
+        description=(
+            "AI-powered competitive intelligence, KYB due diligence, and "
+            "adverse media screening. Backed by 40+ OSINT sources."
+        ),
+    )
+    register_tools(mcp)
+    mcp.run(transport="streamable-http", host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    main()

getsonar_mcp-0.1.0/src/getsonar_mcp/tools.py

@@ -0,0 +1,261 @@
+"""MCP tool definitions — shared across stdio and HTTP transports.
+
+Each ``@mcp.tool`` calls the SONAR public API via ``client.call_sonar()``
+and formats the response as Markdown the LLM can ingest. Tool annotations
+follow the MCP spec (``readOnlyHint``, ``destructiveHint``, ``openWorldHint``)
+so MCP clients can render them with appropriate UX warnings.
+
+Tool catalogue:
+
+  - kyb_findings        — quick KYB lookup (raw signals, no AI analysis)
+  - kyb_run_submit      — full KYB report (Claude analysis, async)
+  - competitive_findings— quick CI lookup
+  - competitive_run_submit — full CI report (async)
+  - adverse_media       — focused negative-media + complaints check
+  - check_report_status — poll an async submission
+  - account_balance     — read current account balance + free-tier remaining
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .client import (
+    call_sonar,
+    format_findings,
+    format_run_started,
+    format_run_status,
+    get_api_key_from_env,
+)
+
+
+def register_tools(mcp: Any) -> None:
+    """Register all SONAR tools onto a FastMCP instance.
+
+    Caller passes their FastMCP instance (different transports build the
+    instance differently — see stdio.py and http_server.py).
+    """
+
+    # ── KYB ────────────────────────────────────────────────────────────────
+    @mcp.tool(
+        annotations={
+            "title": "KYB Quick Lookup",
+            "readOnlyHint": True,
+            "destructiveHint": False,
+            "openWorldHint": True,
+        }
+    )
+    async def kyb_findings(company_name: str, website: str = "") -> str:
+        """Run a fast KYB (Know Your Business) screening on a company.
+
+        Returns raw structured findings — corporate registration, sanctions,
+        adverse media, regulatory licensure (FCA for UK), directors, UBOs.
+        Cheap, fast (30-90s), no Claude analysis. Cost: $0.40/call beyond
+        free tier.
+
+        Args:
+            company_name: Legal name of the company (e.g. "Tesco PLC")
+            website: Company website URL for better disambiguation
+        """
+        api_key = get_api_key_from_env()
+        body = {"company_name": company_name}
+        if website:
+            body["website"] = website
+        result = await call_sonar(
+            "POST", "/v1/agents/kyb-diligence/findings", api_key, body=body,
+        )
+        return format_findings(result, f"KYB Quick Lookup: {company_name}")
+
+    @mcp.tool(
+        annotations={
+            "title": "KYB Full Report (async)",
+            "readOnlyHint": False,
+            "destructiveHint": False,
+            "openWorldHint": True,
+        }
+    )
+    async def kyb_run_submit(company_name: str, website: str = "") -> str:
+        """Submit a full KYB compliance report for AI-narrated analysis.
+
+        Returns a run_id immediately (202). Poll with check_report_status
+        in 1-3 minutes. Includes everything kyb_findings returns plus
+        Claude-generated risk flags, narrative summary, and recommendations
+        formatted for compliance-officer review. Cost: $2.00/call beyond
+        free tier.
+
+        Args:
+            company_name: Legal name of the company
+            website: Company website URL
+        """
+        api_key = get_api_key_from_env()
+        body = {"company_name": company_name}
+        if website:
+            body["website"] = website
+        result = await call_sonar(
+            "POST", "/v1/agents/kyb-diligence/run", api_key, body=body,
+        )
+        return format_run_started(result, "kyb-diligence")
+
+    # ── Competitive Intelligence ───────────────────────────────────────────
+    @mcp.tool(
+        annotations={
+            "title": "Competitive Intelligence Quick Lookup",
+            "readOnlyHint": True,
+            "destructiveHint": False,
+            "openWorldHint": True,
+        }
+    )
+    async def competitive_findings(company_name: str, website: str = "") -> str:
+        """Research a company across 40+ OSINT sources.
+
+        Returns structured signals on pricing changes, product updates,
+        hiring, corporate events, customer sentiment, tech stack, and
+        market presence. Cost: $0.40/call beyond free tier.
+
+        Args:
+            company_name: The company to research (e.g. "Notion")
+            website: Company website URL for better accuracy
+        """
+        api_key = get_api_key_from_env()
+        body = {"company_name": company_name}
+        if website:
+            body["website"] = website
+        result = await call_sonar(
+            "POST", "/v1/agents/company-intelligence/findings", api_key, body=body,
+        )
+        return format_findings(result, f"Competitive Intel: {company_name}")
+
+    @mcp.tool(
+        annotations={
+            "title": "Competitive Intelligence Full Report (async)",
+            "readOnlyHint": False,
+            "destructiveHint": False,
+            "openWorldHint": True,
+        }
+    )
+    async def competitive_run_submit(company_name: str, website: str = "") -> str:
+        """Submit a full competitive-intelligence report for AI analysis.
+
+        Async — returns run_id, poll with check_report_status. Includes
+        narrative analysis, top alerts, competitor positioning, strategic
+        recommendations. Cost: $2.00/call beyond free tier.
+
+        Args:
+            company_name: The company to analyze
+            website: Company website URL
+        """
+        api_key = get_api_key_from_env()
+        body = {"company_name": company_name}
+        if website:
+            body["website"] = website
+        result = await call_sonar(
+            "POST", "/v1/agents/company-intelligence/run", api_key, body=body,
+        )
+        return format_run_started(result, "company-intelligence")
+
+    # ── Adverse Media ──────────────────────────────────────────────────────
+    @mcp.tool(
+        annotations={
+            "title": "Adverse Media Check",
+            "readOnlyHint": True,
+            "destructiveHint": False,
+            "openWorldHint": True,
+        }
+    )
+    async def adverse_media(company_name: str, website: str = "") -> str:
+        """Screen a company for negative news, complaints, and bad reviews.
+
+        Checks news sources, review platforms (G2, Capterra, Trustpilot,
+        BBB), Reddit, and complaint databases. Cost: $0.40/call beyond
+        free tier.
+
+        Args:
+            company_name: Company to screen
+            website: Company website URL for accuracy
+        """
+        api_key = get_api_key_from_env()
+        body = {"company_name": company_name}
+        if website:
+            body["website"] = website
+        result = await call_sonar(
+            "POST", "/v1/agents/adverse-media/findings", api_key, body=body,
+        )
+        return format_findings(result, f"Adverse Media: {company_name}")
+
+    # ── Async polling ──────────────────────────────────────────────────────
+    @mcp.tool(
+        annotations={
+            "title": "Check Report Status",
+            "readOnlyHint": True,
+            "destructiveHint": False,
+            "openWorldHint": False,
+        }
+    )
+    async def check_report_status(
+        run_id: str,
+        agent_type: str = "kyb-diligence",
+    ) -> str:
+        """Poll the status of an async report submitted via *_run_submit.
+
+        Returns the full report JSON when status='completed'. Reports
+        typically complete in 60-180s.
+
+        Args:
+            run_id: The run_id returned by kyb_run_submit / competitive_run_submit
+            agent_type: One of "kyb-diligence", "company-intelligence", "adverse-media"
+        """
+        valid = {"kyb-diligence", "company-intelligence", "adverse-media"}
+        if agent_type not in valid:
+            return json.dumps({
+                "error": f"Invalid agent_type. Must be one of: {sorted(valid)}"
+            })
+        api_key = get_api_key_from_env()
+        result = await call_sonar(
+            "GET", f"/v1/agents/{agent_type}/run/{run_id}", api_key,
+        )
+        return format_run_status(result)
+
+    # ── Account / billing ──────────────────────────────────────────────────
+    @mcp.tool(
+        annotations={
+            "title": "Account Balance & Usage",
+            "readOnlyHint": True,
+            "destructiveHint": False,
+            "openWorldHint": False,
+        }
+    )
+    async def account_balance() -> str:
+        """Check current account usage and remaining free-tier quota.
+
+        Useful for AI agents to decide whether the next call will be free
+        or paid. Returns remaining free-tier calls this month plus the
+        per-key rate limit. (Pre-paid balance lookup requires a separate
+        JWT-authenticated endpoint and is not exposed via API key auth.)
+        """
+        api_key = get_api_key_from_env()
+        result = await call_sonar("GET", "/v1/usage", api_key)
+        if result.get("error"):
+            return f"⚠️  Couldn't read account: {result.get('message', '')}"
+        period = result.get("period", "")
+        total = result.get("total_requests", 0)
+        quota = result.get("monthly_quota", 100)
+        remaining = result.get("remaining", quota - total)
+        by_endpoint = result.get("by_endpoint", {}) or {}
+        lines = [
+            f"# Account usage — {period}",
+            f"- Calls this month: **{total} / {quota}**",
+            f"- Free tier remaining: **{remaining}** calls",
+        ]
+        if by_endpoint:
+            lines.append("")
+            lines.append("By endpoint:")
+            for k, v in sorted(by_endpoint.items()):
+                lines.append(f"  - {k}: {v}")
+        if remaining <= 5:
+            lines.append("")
+            lines.append(
+                "⚠️  Free tier nearly exhausted. Top up your balance at "
+                "https://getsonar.report/api-keys to keep calling."
+            )
+        return "\n".join(lines)