simlir-mcp 0.1.0__tar.gz

simlir_mcp-0.1.0/LICENSE

@@ -0,0 +1 @@
+UNLICENSED — publication and legal licensing gate pending.

simlir_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.2
+Name: simlir-mcp
+Version: 0.1.0
+Summary: A thin stdio MCP bridge for the simlir public product API
+Author: simlir engineering
+License: UNLICENSED — publication and legal licensing gate pending.
+        
+Keywords: mcp,model context protocol,product data,product search,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: simlir<0.2.0,>=0.1.0
+
+# simlir-mcp
+
+Release candidate for a thin Python stdio adapter around the simlir public
+product API. It is intentionally separate from Simlir’s internal
+repository-intelligence MCP server and contains no ingestion code, customer
+data, database credentials, or internal repository tooling.
+
+The PyPI publication workflow is configured, but the package remains
+unpublished pending legal licensing, public repository permissions, an assigned
+engineering-maintainer role, PyPI name/policy checks, stable API deployment,
+and release rollback evidence. Do not use the package name from a public
+registry until those gates are recorded.
+
+## Local use
+
+Install the SDK and this adapter from the local release candidates:
+
+```bash
+python -m pip install --no-deps ../python-sdk
+python -m pip install --no-deps .
+export SIMLIR_API_KEY=sk_your_key_here
+python -m simlir_mcp
+```
+
+The adapter keeps JSON-RPC responses on stdout and writes only structured,
+metadata-only diagnostics to stderr. Never put an API key in a checked-in
+configuration file.
+
+## Claude Desktop, Cursor, or VS Code
+
+After the external publication and stable-URL gates pass, the intended local
+configuration is:
+
+```json
+{
+  "mcpServers": {
+    "simlir": {
+      "command": "simlir-mcp",
+      "env": {
+        "SIMLIR_API_KEY": "${SIMLIR_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+## Supported tools
+
+| Tool | API operation |
+| --- | --- |
+| `simlir_search_products` | Semantic product search |
+| `simlir_search_products_by_image` | Visual product search with optional natural-language context |
+| `simlir_lookup_products_by_identifier` | Exact GTIN/MPN/SKU lookup |
+
+Tool names, required arguments, markets, and response shapes are pinned to the
+checked-in public contract. Update the contract first, then regenerate or
+update both MCP adapters and their tests when the public API changes.
+
+The image tool requires `image_url` and `market`. Its optional `query` field
+adds shopper context such as a size, product role, compatibility requirement,
+or use case; Simlir combines that context with the visual signal. Image-only
+calls remain valid.
+
+## Development
+
+```bash
+PYTHONPATH=../python-sdk/src:src python -m unittest discover -s tests -p 'test_*.py'
+python -m compileall -q src
+python -m pip wheel --no-deps --no-build-isolation --wheel-dir /tmp/simlir-python-mcp-wheel .
+```

simlir_mcp-0.1.0/README.md

@@ -0,0 +1,70 @@
+# simlir-mcp
+
+Release candidate for a thin Python stdio adapter around the simlir public
+product API. It is intentionally separate from Simlir’s internal
+repository-intelligence MCP server and contains no ingestion code, customer
+data, database credentials, or internal repository tooling.
+
+The PyPI publication workflow is configured, but the package remains
+unpublished pending legal licensing, public repository permissions, an assigned
+engineering-maintainer role, PyPI name/policy checks, stable API deployment,
+and release rollback evidence. Do not use the package name from a public
+registry until those gates are recorded.
+
+## Local use
+
+Install the SDK and this adapter from the local release candidates:
+
+```bash
+python -m pip install --no-deps ../python-sdk
+python -m pip install --no-deps .
+export SIMLIR_API_KEY=sk_your_key_here
+python -m simlir_mcp
+```
+
+The adapter keeps JSON-RPC responses on stdout and writes only structured,
+metadata-only diagnostics to stderr. Never put an API key in a checked-in
+configuration file.
+
+## Claude Desktop, Cursor, or VS Code
+
+After the external publication and stable-URL gates pass, the intended local
+configuration is:
+
+```json
+{
+  "mcpServers": {
+    "simlir": {
+      "command": "simlir-mcp",
+      "env": {
+        "SIMLIR_API_KEY": "${SIMLIR_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+## Supported tools
+
+| Tool | API operation |
+| --- | --- |
+| `simlir_search_products` | Semantic product search |
+| `simlir_search_products_by_image` | Visual product search with optional natural-language context |
+| `simlir_lookup_products_by_identifier` | Exact GTIN/MPN/SKU lookup |
+
+Tool names, required arguments, markets, and response shapes are pinned to the
+checked-in public contract. Update the contract first, then regenerate or
+update both MCP adapters and their tests when the public API changes.
+
+The image tool requires `image_url` and `market`. Its optional `query` field
+adds shopper context such as a size, product role, compatibility requirement,
+or use case; Simlir combines that context with the visual signal. Image-only
+calls remain valid.
+
+## Development
+
+```bash
+PYTHONPATH=../python-sdk/src:src python -m unittest discover -s tests -p 'test_*.py'
+python -m compileall -q src
+python -m pip wheel --no-deps --no-build-isolation --wheel-dir /tmp/simlir-python-mcp-wheel .
+```

simlir_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68,<77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simlir-mcp"
+version = "0.1.0"
+description = "A thin stdio MCP bridge for the simlir public product API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "simlir engineering" }]
+keywords = ["mcp", "model context protocol", "product data", "product search", "ai"]
+classifiers = ["Development Status :: 3 - Alpha", "Intended Audience :: Developers", "Programming Language :: Python :: 3"]
+dependencies = ["simlir>=0.1.0,<0.2.0"]
+
+[project.scripts]
+simlir-mcp = "simlir_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.simlir.release]
+publication_enabled = true
+contract_version = "1.0.0"
+contract_source_sha256 = "9c0f28ec07c4208be53335568e0a86d95ebadb617dff7f37909489db382802c4"
+publish_order = "simlir-sdk-before-simlir-mcp"

simlir_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

simlir_mcp-0.1.0/src/simlir_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Python stdio MCP adapter for the simlir public API release candidate."""
+
+from .server import SimlirMCPServer, create_client_from_environment, run_stdio
+
+__all__ = ["SimlirMCPServer", "create_client_from_environment", "run_stdio"]

simlir_mcp-0.1.0/src/simlir_mcp/__main__.py

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

simlir_mcp-0.1.0/src/simlir_mcp/protocol.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Mapping
+from dataclasses import asdict, is_dataclass
+from typing import Any, Protocol
+
+from simlir.errors import SimlirError
+
+logger = logging.getLogger("simlir.mcp")
+MCP_PROTOCOL_VERSION = "2025-03-26"
+SERVER_NAME = "simlir"
+SERVER_VERSION = "1.0.0"
+MAX_JSON_LINE_BYTES = 1_000_000
+
+MARKETS = ["gb", "us", "de", "fr", "es", "it", "au", "ca"]
+
+TOOL_DEFINITIONS: tuple[dict[str, Any], ...] = (
+    {
+        "name": "simlir_search_products",
+        "description": "Search the simlir product database using a natural-language query.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "minLength": 1, "maxLength": 1000},
+                "market": {"type": "string", "enum": MARKETS},
+                "category": {"type": "string", "maxLength": 160},
+                "brand": {"type": "string", "maxLength": 160},
+                "min_price": {"type": "number", "minimum": 0},
+                "max_price": {"type": "number", "minimum": 0},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 50},
+                "offset": {"type": "integer", "minimum": 0, "maximum": 500},
+            },
+            "required": ["query", "market"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "simlir_search_products_by_image",
+        "description": "Find products using a hosted HTTPS image URL, optionally guided by natural-language context or requirements.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "image_url": {"type": "string", "format": "uri", "maxLength": 2048},
+                "query": {"type": "string", "minLength": 1, "maxLength": 1000},
+                "market": {"type": "string", "enum": MARKETS},
+                "category": {"type": "string", "maxLength": 160},
+                "brand": {"type": "string", "maxLength": 160},
+                "min_price": {"type": "number", "minimum": 0},
+                "max_price": {"type": "number", "minimum": 0},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 50},
+                "offset": {"type": "integer", "minimum": 0, "maximum": 500},
+            },
+            "required": ["image_url", "market"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "simlir_lookup_products_by_identifier",
+        "description": "Look up products by an exact GTIN, MPN/model number, or retailer SKU.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "identifier": {"type": "string", "minLength": 1, "maxLength": 256},
+                "type": {"type": "string", "enum": ["auto", "gtin", "mpn", "sku"]},
+                "market": {"type": "string", "enum": MARKETS},
+                "brand": {"type": "string", "maxLength": 160},
+                "retailer": {"type": "string", "maxLength": 160},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 50},
+            },
+            "required": ["identifier", "market"],
+            "additionalProperties": False,
+        },
+    },
+)
+
+
+class SimlirClientLike(Protocol):
+    def search(self, **kwargs: Any) -> Any: ...
+
+    def search_by_image(self, **kwargs: Any) -> Any: ...
+
+    def lookup(self, **kwargs: Any) -> Any: ...
+
+
+def _jsonable(value: Any) -> Any:
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+    return value
+
+
+def _safe_error(error: Exception) -> dict[str, Any]:
+    if isinstance(error, SimlirError):
+        payload: dict[str, Any] = {"error": error.code, "message": error.message}
+        if error.retry_after_seconds is not None:
+            payload["retry_after_seconds"] = error.retry_after_seconds
+        if error.request_id:
+            payload["request_id"] = error.request_id
+        return payload
+    return {"error": "client_error", "message": "The simlir MCP request could not be completed."}
+
+
+def _tool_result(value: Any, is_error: bool = False) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "content": [{"type": "text", "text": json.dumps(_jsonable(value), separators=(",", ":"))}]
+    }
+    if is_error:
+        result["isError"] = True
+    return result
+
+
+def _rpc_ok(request_id: Any, result: Any) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "result": result, "id": request_id}
+
+
+def _rpc_error(request_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "error": {"code": code, "message": message, "data": None}, "id": request_id}
+
+
+def _arguments(value: Any) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if not isinstance(value, Mapping):
+        raise SimlirError("invalid_params", "Tool arguments must be an object.")
+    return dict(value)
+
+
+def _only(arguments: Mapping[str, Any], allowed: set[str]) -> dict[str, Any]:
+    if set(arguments) - allowed:
+        raise SimlirError("invalid_params", "Tool arguments contain an unsupported field.")
+    return dict(arguments)
+
+
+def call_tool(client: SimlirClientLike, name: str, arguments: Any) -> dict[str, Any]:
+    try:
+        values = _arguments(arguments)
+        if name == "simlir_search_products":
+            allowed = {"query", "market", "category", "brand", "min_price", "max_price", "limit", "offset"}
+            return _tool_result(client.search(**_only(values, allowed)))
+        if name == "simlir_search_products_by_image":
+            allowed = {"image_url", "query", "market", "category", "brand", "min_price", "max_price", "limit", "offset"}
+            return _tool_result(client.search_by_image(**_only(values, allowed)))
+        if name == "simlir_lookup_products_by_identifier":
+            allowed = {"identifier", "market", "type", "brand", "retailer", "limit"}
+            return _tool_result(client.lookup(**_only(values, allowed)))
+        raise SimlirError("invalid_params", f"Unknown tool: {name[:120]}.")
+    except Exception as error:
+        logger.error(
+            json.dumps(
+                {"event": "tool.call.failed", "tool": name[:120], "code": getattr(error, "code", "client_error")},
+                separators=(",", ":"),
+            )
+        )
+        return _tool_result(_safe_error(error), is_error=True)
+
+
+class SimlirMCPServer:
+    def __init__(self, client_factory: Any):
+        self._client_factory = client_factory
+        self._client: SimlirClientLike | None = None
+
+    def _client_or_create(self) -> SimlirClientLike:
+        if self._client is None:
+            self._client = self._client_factory()
+        return self._client
+
+    def handle(self, request: Mapping[str, Any]) -> dict[str, Any] | None:
+        request_id = request.get("id")
+        if request.get("jsonrpc") != "2.0" or not isinstance(request.get("method"), str):
+            return _rpc_error(request_id, -32600, "Invalid Request.")
+        method = request["method"]
+        if method == "initialize":
+            return _rpc_ok(
+                request_id,
+                {
+                    "protocolVersion": MCP_PROTOCOL_VERSION,
+                    "capabilities": {"tools": {"listChanged": False}},
+                    "serverInfo": {"name": SERVER_NAME, "version": SERVER_VERSION},
+                },
+            )
+        if method == "notifications/initialized":
+            return None
+        if method == "tools/list":
+            return _rpc_ok(request_id, {"tools": list(TOOL_DEFINITIONS)})
+        if method == "tools/call":
+            params = request.get("params")
+            if not isinstance(params, Mapping) or not isinstance(params.get("name"), str):
+                return _rpc_error(request_id, -32602, "Tool name is required.")
+            try:
+                client = self._client_or_create()
+            except Exception as error:
+                return _rpc_ok(request_id, _tool_result(_safe_error(error), is_error=True))
+            return _rpc_ok(request_id, call_tool(client, params["name"], params.get("arguments")))
+        return _rpc_error(request_id, -32601, f"Unknown method: {method[:120]}.")

simlir_mcp-0.1.0/src/simlir_mcp/server.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections.abc import Iterator, Mapping
+from typing import Any
+
+from simlir import Simlir
+from simlir.errors import SimlirError
+
+from .protocol import MAX_JSON_LINE_BYTES, SimlirMCPServer, _rpc_error
+
+
+def create_client_from_environment(env: Mapping[str, str] | None = None) -> Simlir:
+    values = os.environ if env is None else env
+    api_key = values.get("SIMLIR_API_KEY", "")
+    if not api_key:
+        raise SimlirError("configuration_error", "SIMLIR_API_KEY is required.")
+    kwargs: dict[str, Any] = {"api_key": api_key}
+    if values.get("SIMLIR_API_BASE_URL"):
+        kwargs["base_url"] = values["SIMLIR_API_BASE_URL"]
+    if values.get("SIMLIR_API_TIMEOUT"):
+        try:
+            kwargs["timeout"] = float(values["SIMLIR_API_TIMEOUT"])
+        except ValueError as error:
+            raise SimlirError("configuration_error", "SIMLIR_API_TIMEOUT must be numeric.") from error
+    if values.get("SIMLIR_API_MAX_RETRIES"):
+        try:
+            kwargs["max_retries"] = int(values["SIMLIR_API_MAX_RETRIES"])
+        except ValueError as error:
+            raise SimlirError("configuration_error", "SIMLIR_API_MAX_RETRIES must be an integer.") from error
+    return Simlir(**kwargs)
+
+
+def handle_message(server: SimlirMCPServer, raw: str) -> dict[str, Any] | None:
+    try:
+        request = json.loads(raw)
+    except json.JSONDecodeError:
+        return _rpc_error(None, -32700, "Parse error.")
+    if not isinstance(request, Mapping):
+        return _rpc_error(None, -32600, "Invalid Request.")
+    return server.handle(request)
+
+
+def _lines(stream: Any) -> Iterator[str]:
+    for raw in stream:
+        if len(raw.encode("utf-8")) > MAX_JSON_LINE_BYTES:
+            yield "{\"jsonrpc\":\"2.0\",\"method\":\"__oversize__\"}"
+        else:
+            yield raw
+
+
+def run_stdio(server: SimlirMCPServer | None = None, input_stream: Any = None, output_stream: Any = None) -> None:
+    active_server = server or SimlirMCPServer(create_client_from_environment)
+    input_value = input_stream or sys.stdin
+    output_value = output_stream or sys.stdout
+    for raw in _lines(input_value):
+        response = handle_message(active_server, raw)
+        if response is not None:
+            output_value.write(json.dumps(response, separators=(",", ":")) + "\n")
+            output_value.flush()
+
+
+def main() -> None:
+    run_stdio()

simlir_mcp-0.1.0/src/simlir_mcp.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.2
+Name: simlir-mcp
+Version: 0.1.0
+Summary: A thin stdio MCP bridge for the simlir public product API
+Author: simlir engineering
+License: UNLICENSED — publication and legal licensing gate pending.
+        
+Keywords: mcp,model context protocol,product data,product search,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: simlir<0.2.0,>=0.1.0
+
+# simlir-mcp
+
+Release candidate for a thin Python stdio adapter around the simlir public
+product API. It is intentionally separate from Simlir’s internal
+repository-intelligence MCP server and contains no ingestion code, customer
+data, database credentials, or internal repository tooling.
+
+The PyPI publication workflow is configured, but the package remains
+unpublished pending legal licensing, public repository permissions, an assigned
+engineering-maintainer role, PyPI name/policy checks, stable API deployment,
+and release rollback evidence. Do not use the package name from a public
+registry until those gates are recorded.
+
+## Local use
+
+Install the SDK and this adapter from the local release candidates:
+
+```bash
+python -m pip install --no-deps ../python-sdk
+python -m pip install --no-deps .
+export SIMLIR_API_KEY=sk_your_key_here
+python -m simlir_mcp
+```
+
+The adapter keeps JSON-RPC responses on stdout and writes only structured,
+metadata-only diagnostics to stderr. Never put an API key in a checked-in
+configuration file.
+
+## Claude Desktop, Cursor, or VS Code
+
+After the external publication and stable-URL gates pass, the intended local
+configuration is:
+
+```json
+{
+  "mcpServers": {
+    "simlir": {
+      "command": "simlir-mcp",
+      "env": {
+        "SIMLIR_API_KEY": "${SIMLIR_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+## Supported tools
+
+| Tool | API operation |
+| --- | --- |
+| `simlir_search_products` | Semantic product search |
+| `simlir_search_products_by_image` | Visual product search with optional natural-language context |
+| `simlir_lookup_products_by_identifier` | Exact GTIN/MPN/SKU lookup |
+
+Tool names, required arguments, markets, and response shapes are pinned to the
+checked-in public contract. Update the contract first, then regenerate or
+update both MCP adapters and their tests when the public API changes.
+
+The image tool requires `image_url` and `market`. Its optional `query` field
+adds shopper context such as a size, product role, compatibility requirement,
+or use case; Simlir combines that context with the visual signal. Image-only
+calls remain valid.
+
+## Development
+
+```bash
+PYTHONPATH=../python-sdk/src:src python -m unittest discover -s tests -p 'test_*.py'
+python -m compileall -q src
+python -m pip wheel --no-deps --no-build-isolation --wheel-dir /tmp/simlir-python-mcp-wheel .
+```

simlir_mcp-0.1.0/src/simlir_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/simlir_mcp/__init__.py
+src/simlir_mcp/__main__.py
+src/simlir_mcp/protocol.py
+src/simlir_mcp/server.py
+src/simlir_mcp.egg-info/PKG-INFO
+src/simlir_mcp.egg-info/SOURCES.txt
+src/simlir_mcp.egg-info/dependency_links.txt
+src/simlir_mcp.egg-info/entry_points.txt
+src/simlir_mcp.egg-info/requires.txt
+src/simlir_mcp.egg-info/top_level.txt
+tests/test_pypi_metadata.spec.py
+tests/test_server.py

simlir_mcp-0.1.0/src/simlir_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

simlir_mcp-0.1.0/src/simlir_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+simlir-mcp = simlir_mcp.server:main

simlir_mcp-0.1.0/src/simlir_mcp.egg-info/requires.txt

@@ -0,0 +1 @@
+simlir<0.2.0,>=0.1.0

simlir_mcp-0.1.0/src/simlir_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+simlir_mcp

simlir_mcp-0.1.0/tests/test_pypi_metadata.spec.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import pathlib
+import unittest
+
+
+ROOT = pathlib.Path(__file__).resolve().parents[3]
+
+
+class PythonMcpPyPiMetadataTests(unittest.TestCase):
+    def test_publication_metadata_matches_configured_workflow(self) -> None:
+        pyproject = (ROOT / "developer-channels/python-mcp/pyproject.toml").read_text()
+        workflow = (ROOT / ".github/workflows/publish-python-mcp.yml").read_text()
+
+        self.assertIn('name = "simlir-mcp"', pyproject)
+        self.assertIn('requires = ["setuptools>=68,<77"]', pyproject)
+        self.assertIn("publication_enabled = true", pyproject)
+        self.assertIn("workflow_dispatch:", workflow)
+        self.assertIn("pypa/gh-action-pypi-publish@", workflow)
+        self.assertIn("name: pypi", workflow)
+        self.assertIn("Verify Python MCP distribution metadata", workflow)
+
+
+if __name__ == "__main__":
+    unittest.main()

simlir_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import io
+import json
+import pathlib
+import unittest
+
+from simlir_mcp.protocol import MCP_PROTOCOL_VERSION, TOOL_DEFINITIONS
+from simlir_mcp.server import SimlirMCPServer, create_client_from_environment, handle_message, run_stdio
+
+
+class FakeClient:
+    def search(self, **kwargs):
+        return {"operation": "search", "arguments": kwargs}
+
+    def search_by_image(self, **kwargs):
+        return {"operation": "image", "arguments": kwargs}
+
+    def lookup(self, **kwargs):
+        return {"operation": "lookup", "arguments": kwargs}
+
+
+class PythonMcpServerTests(unittest.TestCase):
+    def setUp(self):
+        self.server = SimlirMCPServer(lambda: FakeClient())
+
+    def test_initialize_and_tools_list_match_contract(self):
+        initialize = self.server.handle({"jsonrpc": "2.0", "id": 1, "method": "initialize"})
+        self.assertEqual(initialize["result"]["protocolVersion"], MCP_PROTOCOL_VERSION)
+        self.assertEqual([tool["name"] for tool in TOOL_DEFINITIONS], [
+            "simlir_search_products",
+            "simlir_search_products_by_image",
+            "simlir_lookup_products_by_identifier",
+        ])
+        listed = self.server.handle({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
+        self.assertEqual(listed["result"]["tools"], list(TOOL_DEFINITIONS))
+
+    def test_routes_all_tools_without_exposing_transport(self):
+        cases = [
+            ("simlir_search_products", {"query": "headphones", "market": "gb"}, "search"),
+            ("simlir_search_products_by_image", {"image_url": "https://example.com/item.jpg", "market": "gb", "query": "small flat"}, "image"),
+            ("simlir_lookup_products_by_identifier", {"identifier": "123", "market": "gb"}, "lookup"),
+        ]
+        for name, arguments, operation in cases:
+            response = self.server.handle({"jsonrpc": "2.0", "id": name, "method": "tools/call", "params": {"name": name, "arguments": arguments}})
+            payload = json.loads(response["result"]["content"][0]["text"])
+            self.assertEqual(payload["operation"], operation)
+            self.assertEqual(payload["arguments"], arguments)
+
+    def test_errors_are_safe_and_stdio_keeps_notifications_off_stdout(self):
+        unknown = self.server.handle({"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "not_a_tool", "arguments": {}}})
+        self.assertTrue(unknown["result"]["isError"])
+        self.assertNotIn("sk_", json.dumps(unknown))
+
+        output = io.StringIO()
+        run_stdio(self.server, io.StringIO('{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":4,"method":"tools/list"}\n'), output)
+        lines = output.getvalue().splitlines()
+        self.assertEqual(len(lines), 1)
+        self.assertEqual(json.loads(lines[0])["id"], 4)
+
+    def test_missing_configuration_is_a_safe_tool_error(self):
+        server = SimlirMCPServer(lambda: create_client_from_environment({}))
+        response = server.handle({"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "simlir_search_products", "arguments": {}}})
+        self.assertTrue(response["result"]["isError"])
+        payload = json.loads(response["result"]["content"][0]["text"])
+        self.assertEqual(payload["error"], "configuration_error")
+        self.assertNotIn("sk_", json.dumps(response))
+
+    def test_invalid_json_and_oversized_input_are_bounded(self):
+        invalid = handle_message(self.server, "not json")
+        self.assertEqual(invalid["error"]["code"], -32700)
+        output = io.StringIO()
+        run_stdio(self.server, io.StringIO("x" * 1_000_001 + "\n"), output)
+        self.assertEqual(json.loads(output.getvalue())["error"]["code"], -32601)
+
+    def test_pypi_build_uses_compatible_metadata_backend(self):
+        root = pathlib.Path(__file__).resolve().parents[3]
+        pyproject = (root / "developer-channels/python-mcp/pyproject.toml").read_text()
+        workflow = (root / ".github/workflows/publish-python-mcp.yml").read_text()
+        self.assertIn('requires = ["setuptools>=68,<77"]', pyproject)
+        self.assertIn("Verify Python MCP distribution metadata", workflow)
+        self.assertIn('metadata.get("Name") != "simlir-mcp"', workflow)
+        self.assertIn('metadata.get("Version") != "0.1.0"', workflow)
+
+
+if __name__ == "__main__":
+    unittest.main()