silpo-py-mcp

Typed Python client for the official Silpo MCP server (https://mcp.silpo.ua/mcp).

Built on FastMCP 3.4.7 for the Silpo AI Factory hackathon. One library, two modes:

• Real server — Streamable HTTP transport with OAuth 2.1 + PKCE, encrypted on-disk token storage, 40 typed methods mirroring the documented silpo_* tools.
• In-memory mock — a FastMCP server that implements the same 40 tools with realistic fixtures, so you can develop and test without a Silpo account.

Requires Python 3.12+.

Install

pip install silpo-py-mcp
# or with uv
uv add silpo-py-mcp
# local development
uv sync

Quick start (mock — no auth needed)

import asyncio
from silpo_py_mcp import SilpoClient


async def main() -> None:
    async with SilpoClient.for_mock() as client:
        result = await client.get_products(
            "bran-1",
            "DeliveryHome",
            "2026-09-06T10:00:00+03:00",
            "2026-09-06T11:00:00+03:00",
            category="Молочні продукти",
        )
        for product in result.items:
            print(product.title, product.price)

        cart = await client.get_cart()
        await client.add_or_update_cart_products(
            cart.cart_id,
            [
                {
                    "productId": product.product_id,
                    "companyId": product.company_id,
                    "branchId": product.branch_id,
                    "quantity": 2,
                }
                for product in result.items
            ],
        )
        full = await client.get_cart_by_id(cart.cart_id)
        print("Total:", full.totals.total_price)


asyncio.run(main())

Quick start (real server)

The first connection opens a browser for login at auth.silpo.ua (phone + OTP or password). Tokens are encrypted and stored on disk, and the client refreshes them automatically.

import asyncio
from silpo_py_mcp import SilpoClient


async def main() -> None:
    async with SilpoClient.for_real_server() as client:
        tools = await client.list_tools()
        print(f"Connected. {len(tools)} tools available.")

        branches = await client.call_tool("silpo_list_branches", {"limit": 1})
        print("Branch:", branches["branches"][0]["address"])


asyncio.run(main())

Note on typed methods vs the real server. The typed methods and the mock mirror the live tools/list schemas and response shapes (verified Sep 2026; re-verified Sep 7 2026; reconciled with server release-1.110.0 on Sep 10 2026; reconciled with server release-1.110.1 on Sep 11 2026; re-verified Sep 14 2026 — still 40 tools, no renames, no required-set changes; reconciled with server release-1.111.0/1.111.1 on Sep 25 2026 — still 40 tools, no renames). Context arguments such as branchId/deliveryType/timeslotStart/timeslotEnd are required where the live schema requires them — since 1.110.1 this includes silpo_get_similar_products — cart tools take shoppingCartId, and silpo_add_or_update_cart_products takes products ([{productId, companyId, branchId, quantity, addQuantity?, comment?}] — omitted/false addQuantity replaces the quantity, true adds to it). silpo_add_or_update_certificates takes certificatesToAdd/ certificatesToRemove as [{barcode, pincode?}] objects (plain barcode strings are converted automatically). Product results carry displayPrice (fromPrice/toPrice filter by it, not by price); get_products requires at least one of category/mustHavePromotion/ promotionCode/set (release-1.111.0: missing filter raises ValueError client-side with the accepted-filter list; timeslotStart/timeslotEnd are not validated server-side — a bogus slot silently returns the full catalog, so pass a real slot from get_time_slots); get_time_slots sends deliveryTypes (singular deliveryType accepted server-side as an alias since 1.111.0; millisecond timestamps stripped since 1.111.1) and each slot carries serviceFee (SelfPickup "Сервісний збір"); find_address surfaces warning/houseNumberMatched for unmatched house numbers (release-1.111.1 — check before relying on coordinates); get_available_delivery_types coordinates are only validated for home-delivery types (SelfPickup/NovaPoshta always returned); get_product_details carries displayPrice/image/specialPrices/ externalProductId plus hasOfferAtBranch (release-1.110.0: price/ displayPrice/stock/available are the requested branch's real offer — check has_offer_at_branch first, False means no real offer at that branch); get_cart_by_id maps serviceFee from the top level or calculation (release-1.111.1); batch empty entries are skipped (meta.droppedCount → BatchProductResult.dropped_count). Coupon eligibility comes from canBeAppliedToOrder on silpo_get_coupon_details — never infer it from active/state alone. The mock cart tools (silpo_get_shopping_cart_by_id, silpo_clear_shopping_cart, ...) accept only shoppingCartId — the legacy cartId alias was removed in 0.3.1 to match the live schema. call_tool always passes arguments through verbatim for one-off calls. Responses come back JSON-like (nested FastMCP Root dataclasses are unwrapped automatically).

Smoke test against the real server

examples/real_smoke.py verifies the live contract and runs a read-only battery of calls:

uv run examples/real_smoke.py

On the first run a browser opens for login at auth.silpo.ua; afterwards the encrypted token in ~/.silpo_py_mcp is reused. The script checks:

• live tools/list matches the 40 documented tools and prints every live signature (arg names/types),
• a read-only battery of call_tool calls built from the live schemas (branches, address, delivery types, time slots, categories tree, promotions, products, profile, favorites, loyalty, coupons, orders, promos, certificates).

Failures are reported per check without aborting — server-side schema bugs and drift between the real server and the mock show up as ✗ lines. Exits non-zero if the tool-name contract is violated or a battery call fails.

Known server-side quirks (re-verified live, Sep 2026 — mitigated in examples/real_smoke.py)

Previously reported quirks that no longer reproduce (re-verified live, Sep 2026): silpo_get_category no longer triggers the fastmcp id rejection (it validates cleanly), and silpo_get_my_certificates — although still intermittently returning HTTP 500 — now responds with a normal certificates envelope (unwrapped by the client) that validates cleanly when it does respond.

Configuration

Configuration is read from environment variables (prefix SILPO_) or a .env file. Key settings:

Programmatic overrides are supported via SilpoSettings(...) or SilpoClient.from_fastmcp(client, mcp_url=...).

Schema-driven by design

The exact tool schemas (arguments, JSON Schema) are only known from tools/list after authentication, per the official docs. SilpoClient therefore exposes:

• list_tools() — the live schemas from the server.
• call_tool(name, arguments) — pass-through calls with typed error mapping.
• Typed convenience methods — wrappers over the live tool schemas (get_products, get_cart_by_id, add_or_update_cart_products, ...).

If Silpo renames or reshapes tools, only the affected convenience method needs updating; call_tool keeps working.

Error handling

silpo_py_mcp.exceptions maps Silpo's documented error responses:

Development

uv sync                  # install deps
uv run pytest            # run tests (all against the in-memory mock)
uv run ruff format .     # format
uv run ruff check .      # lint
uv run pyrefly check     # type check (strict)
uv run pre-commit install  # install git hooks (format/lint/type/tests)

Project layout

src/silpo_py_mcp/
├── client.py          # SilpoClient — typed methods + error mapping
├── mock_server.py     # SilpoMockServer — in-memory FastMCP server (40 tools)
├── auth.py            # OAuth 2.1 + PKCE helper, encrypted token storage
├── config.py          # pydantic-settings configuration
├── exceptions.py      # typed exceptions
└── models/            # Pydantic models (product, cart, branch, category, order)

License

MIT