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; reconciled with server release-1.111.2 on Sep 28 2026 — still 40 tools, no renames; reconciled with server release-1.111.3 on Sep 28 2026 — still 40 tools, no renames, no required-set changes, with the cart/payment/category changes below; reconciled with server release-1.111.4 on Sep 30 2026 — still 40 tools, no renames, no required-set changes, with the promotions/time-slots/cart-description fixes below; reconciled with server release-1.111.5 on Sep 30 2026 — still 40 tools, no renames, no required-set changes, with the gateway coupon below). 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 "Сервісний збір"); since release-1.111.2 the server normalizes timeslot bounds (Z, +00:00 and naive stamps are all read as UTC, date-only values are rejected) and restricts deliveryTypes to the 9-value TimeSlotDeliveryType enum — get_time_slots validates the types, the limit bounds (1..100) and the timestamp format client-side instead of letting the server answer -32602/400; release-1.111.4 makes the date normalizer more lenient (whitespace, lowercase z, comma fractions, +HHMM/+HH offsets and a space separator are read as UTC) and adds a total to the slots response ({success, summary, slots, total} — the client returns the list and ignores the count); get_promotions for an unknown branch returns [] instead of the pre-1.111.4 500; 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) and queries[].totalFound surfaces as BatchProductResult.total_found (truncated_queries flags queries whose real match count exceeded the returned products). Coupon eligibility comes from canBeAppliedToOrder on silpo_get_coupon_details — never infer it from active/state alone; since release-1.111.5 a non-null successorThreshold marks a gateway coupon (CouponDetail.is_gateway) that unlocks a different promo once the threshold is spent — present successor_threshold.description and read progress as tracking toward that threshold. 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).

release-1.111.3 (client 0.8.0) — breaking

release-1.111.4 (client 0.8.1)

release-1.111.5 (client 0.8.2)

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), silpo_get_time_slots accepts deliveryTypes: ["B2B"] again (release-1.111.2 put it back in the enum — it returns an empty slot list), 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.

Working with the cart

Since release-1.111.3 the update tool wants the cart's own address and shipments copied back verbatim, so read them off cart.update_payloads rather than rebuilding them. The cart also separates what the guest may pay with from what they will pay:

cart = await client.get_cart_by_id(cart_id)

# what the guest can actually pay with (not cart.payment_type, which is
# "Unknown" until a method is chosen at checkout)
print(cart.available_payment_types)  # ['Cashdesk', 'Card', 'Masterpass', ...]
print(cart.payment.unavailable_types)  # ['BNPL'] — below loan_config.min_total

# the amount to show the guest: total is *before* discounts
print(cart.total_to_pay, cart.totals.total_price)

# why the delivery was cheaper than its list price (the cause is not reported)
print(cart.delivery.sub_total, cart.delivery.sub_discount, cart.delivery.total)

# hand the address/shipments/timeslot straight back to an update
payloads = cart.update_payloads
assert payloads.is_sendable, payloads.missing_fields
await client.update_shopping_cart(
    cart_id,
    cart.delivery_type,
    payloads.timeslot,
    payloads.address,
    payloads.shipments,
)

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