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 .
```
