digikala-mcp

An MCP server for Digikala product discovery, product research, offer comparison, and bounded cart operations. Consumer applications own the conversation, product selection, user interface, and approval of cart changes.

Architecture

flowchart TD
    Host[Consumer / MCP host] -->|stdio| Server[FastMCP server]
    Server --> Tools[tools: validated MCP contracts]
    Tools --> App[app: application services]
    App --> Gateways[infra/http: market gateways]
    Gateways --> Cache[infra/cache: public observations]
    Gateways --> HTTP[HTTPConnection / httpx]
    HTTP --> Digikala[Digikala]
    App --> Repository[infra/db/repositories: cart journal]
    Repository --> Session[SQLModel AsyncSession]
    Session --> PostgreSQL[PostgreSQL]
    Bootstrap[bootstrap: provider composition] -.-> Providers[Dishka providers]
    Providers -.-> App
    Providers -.-> Gateways
    Providers -.-> Session

Responsibilities

Location	Responsibility
`src/server.py`	FastMCP factory, lifespan and tool registration; served over stdio.
`src/tools/`	Input/output contracts, tool descriptions, annotations and safe MCP errors.
`src/tools/dependencies.py`	Bridge FastMCP dependencies to Dishka scopes; injected services are absent from public input schemas.
`src/app/`	Catalog/research orchestration, comparisons, account sessions, cart planning, execution and reconciliation.
`src/infra/http/`	Fixed-origin HTTP requests, authentication, response normalization and market gateways.
`src/infra/cache/`	In-memory hash-map cache and shared tasks for identical public requests.
`src/infra/db/connection.py`	Lazy PostgreSQL engine, bounded pool and SQLModel session factory.
`src/infra/db/repositories/`	Queries and flushed writes on an injected session.
`src/infra/db/errors.py`, `exceptions.py`	Driver-error sanitization and independent persistence errors.
`src/models/schemas/`	Pydantic tool and application contracts.
`src/models/db/`	SQLModel table definitions, JSONB journal and database constraints.
`src/models/cache/`	Internal cache-entry models.
`src/providers/`	Separate HTTP, cache, gateway, database, catalog, cart and account providers, plus explicit overrides.
`src/bootstrap.py`	Compose the provider graph.
`src/config/`	Host-owned database connection and cart limits.
`migrations/`	Versioned Alembic schema changes, applied separately from request handling.

Dependency and session lifetime

The server owns one Dishka application container. HTTP clients, cache, database pool, application services and in-memory account tokens live at application scope. Each tool invocation gets a request scope. Cart services also receive an injected JournalFactory that opens a separate, short Dishka scope for each database phase.

CartJournal receives an AsyncSession; it only queries and flushes. The database provider commits on successful phase exit, rolls back failures or cancellation, and closes the session through Dishka. Concurrent phases use separate sessions. There is no custom Unit of Work or transaction-manager class, and no database session is held across storefront HTTP calls. The cache is finalized before its HTTP client closes.

Observations and cache

Public observations are cached for 60 seconds after successful completion, with up to 256 entries per process. Keys include relevant product/category IDs, query, page, sort and location. Identical concurrent reads share one task. Cache hits return independent copies and retain the original observation time; errors are not cached. Account reads, authentication, cart writes and purchase-time revalidation bypass this cache.

All monetary values are integer Iranian rials: 10 IRR = 1 toman. Missing prices, availability and shipping remain unknown. Product titles, reviews and questions are upstream text. Comparisons preserve exact offer IDs and observed attribute differences; they do not infer equivalent products or guarantee the cheapest delivered total.

Cart and account flow

A cart change follows prepare → host approval → execute → read back. Preparation creates a five-minute plan. Execution commits a journal claim before any remote write, then persists the observed result in another database phase. PostgreSQL conditional updates check ID, account, state and revision; a partial unique index permits one executing/uncertain operation per account. No application mutex or advisory lock is used.

Retries reuse the plan/request ID and never blindly repeat a mutation. Reconciliation can inspect uncertain outcomes; an executing record is not automatically taken over. Limits apply to merchandise amount and total units, excluding unknown shipping costs. The host owns approval; possession of a plan ID is not evidence of human approval.

Desktop tools use an OS-keyring account. Trusted backend account tools use isolated, process-local tokens with a 15-minute lifetime and cookies kept in memory. Passwords, cookies and tokens are not persisted in the cart journal. Payment, order placement, address selection and OTP handling are outside the tool boundary.

Tools and recorded responses

The server registers 40 tools. The examples below were captured through the actual MCP server on 2026-09-28 (UTC). Public catalog examples use live Digikala responses; price history returned the recorded rate_limited error. These are dated observations, not current price or inventory promises.

Account/cart examples use a separate process with no database connection, a disabled OS-keyring backend, and an invalid account token. They show actual validation and configuration/authentication responses, not successful live cart mutations. No real account was accessed or cart changed for these examples. The amount/unit limits shown are the capture process's settings. Zero IDs and the invalid token are deliberate test inputs, not reusable plan IDs, account credentials or verified purchase selections.

Success JSON shows structuredContent excerpts. Error JSON shows MCP isError and text content. Fields and array items may be omitted for readability; displayed values are copied from the captured responses. Each request is the tool's arguments object, without the surrounding MCP JSON-RPC envelope.

Discovery

Tool	What it does
`list_markets`	List implemented markets and capability verification status. This is metadata, not a live health check.
`get_trend_snapshot`	Read the homepage best-selling listing in upstream order, with an observation time. Sales periods and historical growth are unknown.
`list_categories`	Find native category IDs by text, parent, or root status; paginate the category tree locally.
`search_products`	Search or browse one native result page per selected market; isolate errors per market.
`get_product`	Read a product, specifications, media, rating, and observed seller offers.
`list_offers`	List offers from the product-detail response, optionally restricted to one exact variant. Coverage is limited to that response.
`autocomplete`	Read search suggestions and any category IDs supplied with them.

list_markets — request and recorded response

Inputs: None.

Request

{}

Local server response (excerpt)

{
  "markets": [
    {
      "market": "digikala",
      "capabilities": {
        "search": "verified",
        "product_detail": "verified",
        "product_price_history": "unknown",
        "cart_read": "verified"
      }
    }
  ]
}

get_trend_snapshot — request and recorded response

Inputs: None.

Request

{}

Live public response (excerpt)

{
  "source": "digikala_home_best_selling",
  "observed_at": "2026-09-28T14:26:00.338370Z",
  "period": null,
  "products": [
    {
      "product_id": "11801878",
      "title": "هدفون بلوتوثی انکر مدل SoundCore R50i A3949 بدون قابلیت نویز کنسلینگ، درگاه شارژ USB Type-C، دارای فناوری AI-Enhanced Calls برای کاهش نویز و بهبود مکالمات، مقاوم در برابر رطوبت و عرق",
      "price_rial": 26545000,
      "availability": "available"
    }
  ]
}

list_categories — request and recorded response

Inputs: Optional query: query, parent_id, roots_only, page, page_size.

Request

{
  "query": {
    "query": "گوشی",
    "page_size": 1
  }
}

Live public response (excerpt)

{
  "market": "digikala",
  "categories": [
    {
      "category_id": "11",
      "title": "گوشی موبایل",
      "title_en": "گوشی موبایل",
      "code": "mobile-phone",
      "parent_id": "1",
      "has_children": false
    }
  ],
  "page": 1,
  "page_size": 1,
  "total_items": 9,
  "total_pages": 9,
  "error": null
}

search_products — request and recorded response

Inputs: query with text and/or category_id; optional sort, page, price bounds, filters.values, markets, and location.

Request

{
  "query": {
    "category_id": "11",
    "filters": {
      "values": {
        "brands": [
          "18"
        ]
      }
    }
  }
}

Live public response (excerpt)

{
  "results": [
    {
      "market": "digikala",
      "category_id": "11",
      "page": 1,
      "total_pages": 52,
      "products": [
        {
          "product_id": "22484509",
          "title": "گوشی موبایل سامسونگ مدل Galaxy A37 دو سیم‌کارت ظرفیت 256 گیگابایت و رم 8 گیگابایت - ویتنام - به همراه یک عدد شارژر 45 وات سامسونگ، یک عدد کابل UBS-C به طول 1.8 متر، یک عدد کاور سیلیکونی و یک عدد محافظ صفحه نمایش",
          "price_rial": 1059000000,
          "availability": "available"
        }
      ],
      "error": null
    }
  ]
}

get_product — request and recorded response

Inputs: market, product_id; optional location.

Request

{
  "market": "digikala",
  "product_id": "20135132"
}

Live public response (excerpt)

{
  "market": "digikala",
  "product": {
    "product_id": "20135132",
    "title": "گوشی موبایل سامسونگ مدل Galaxy S25 FE دو سیم کارت ظرفیت 256 گیگابایت و رم 8 گیگابایت - ویتنام",
    "price_rial": 1796386000,
    "availability": "available"
  },
  "error": null
}

list_offers — request and recorded response

Inputs: product_id; optional variant_id.

Request

{
  "product_id": "20135132"
}

Live public response (excerpt)

{
  "product_id": "20135132",
  "observed_at": "2026-09-28T14:26:08.909035Z",
  "coverage": "product_response",
  "offers": [
    {
      "offer_id": "75026671",
      "seller_id": "1",
      "seller_name": "دیجی‌کالا",
      "price_rial": 1796386000,
      "availability": "available",
      "attributes": {
        "رنگ": "آبی"
      },
      "warranty": "گارانتی 18 ماهه -شرکتی",
      "shipping_price_rial": null
    }
  ]
}

autocomplete — request and recorded response

Inputs: market, query.

Request

{
  "market": "digikala",
  "query": "سامسونگ"
}

Live public response (excerpt)

{
  "market": "digikala",
  "suggestions": [
    {
      "text": "سامسونگ",
      "category": null,
      "category_id": null
    },
    {
      "text": "سامسونگ a17",
      "category": null,
      "category_id": null
    }
  ],
  "error": null
}

Product research

Tool	What it does
`get_category_filters`	Read supported brand, color, and attribute filter keys and value IDs for a category.
`get_product_variants`	Read seller-specific variants, attributes, warranties, prices, availability, and shipment metadata.
`get_product_variant_types`	Group observed variation dimensions and values, retaining their value and offer IDs.
`get_product_reviews`	Read one review page with body, buyer flag, 0–5 score, pros/cons, and votes.
`get_product_questions`	Read one question page and included answers. Included answers may be fewer than `answer_count`.
`get_product_ratings`	Read aggregate 0–100 scores, score distribution, and review/question counts.
`list_product_sellers`	Group observed variant offers by seller ID, preserving distinct offers and seller metrics.
`list_product_recommendation_sections`	Discover the recommendation section keys available for a product.
`get_product_recommendations`	Read a selected upstream recommendation section, retaining order and advertising flags. These are store suggestions.
`get_products_batch`	Read 1–20 distinct product IDs with separate product results and errors.
`get_product_media`	Return official image/video URLs and metadata without downloading media.
`get_product_price_history`	Read upstream price-chart series with original date text and seller/warranty labels when supplied. No interpolation or forecast.

get_category_filters — request and recorded response

Inputs: category_id; feed selections into search_products.query.filters.values.

Request

{
  "category_id": "11"
}

Live public response (excerpt)

{
  "category_id": "11",
  "observed_at": "2026-09-28T14:26:08.213745Z",
  "filters": [
    {
      "key": "brands",
      "title": "برند",
      "options": [
        {
          "value_id": "18",
          "title": "سامسونگ",
          "title_en": "Samsung"
        }
      ]
    }
  ]
}

get_product_variants — request and recorded response

Inputs: product_id.

Request

{
  "product_id": "20135132"
}

Live public response (excerpt)

{
  "product_id": "20135132",
  "observed_at": "2026-09-28T14:26:09.189696Z",
  "coverage": "variants_endpoint",
  "variants": [
    {
      "offer_id": "75026671",
      "seller_id": "1",
      "seller_name": "دیجی‌کالا",
      "price_rial": 1796386000,
      "availability": "available",
      "attributes": {
        "رنگ": "آبی"
      },
      "warranty": "گارانتی 18 ماهه -شرکتی",
      "shipping_price_rial": null
    }
  ]
}

get_product_variant_types — request and recorded response

Inputs: product_id.

Request

{
  "product_id": "20135132"
}

Live public response (excerpt)

{
  "product_id": "20135132",
  "types": [
    {
      "label": "رنگ",
      "nature": "color",
      "values": [
        {
          "value_id": "4",
          "title": "آبی",
          "code": "#0000FF",
          "offer_ids": [
            "75026671"
          ]
        }
      ]
    }
  ]
}

get_product_reviews — request and recorded response

Inputs: product_id; optional page and sort: default, newest, or buyers.

Request

{
  "product_id": "20135132"
}

The review body is omitted from this excerpt.

Live public response (excerpt)

{
  "product_id": "20135132",
  "page": 1,
  "sort": "default",
  "pager": {
    "current_page": 1,
    "total_pages": 83,
    "total_items": 1646
  },
  "reviews": [
    {
      "review_id": "90032643",
      "title": null,
      "rating": 5.0,
      "is_buyer": true,
      "created_at_text": "1 مهر 1405",
      "likes": 18,
      "dislikes": 3
    }
  ]
}

get_product_questions — request and recorded response

Inputs: product_id; optional page and sort: created_at or answers.

Request

{
  "product_id": "20135132"
}

Live public response (excerpt)

{
  "product_id": "20135132",
  "page": 1,
  "questions": [
    {
      "question_id": "10436880",
      "text": "اولترا خوبه یا آف ای ",
      "answer_count": 3,
      "answers": [
        {
          "answer_id": "15852431",
          "text": "آف ای هم خوبا",
          "responder_type": "buyer"
        }
      ]
    }
  ]
}

get_product_ratings — request and recorded response

Inputs: product_id.

Request

{
  "product_id": "20135132"
}

Live public response (excerpt)

{
  "product_id": "20135132",
  "observed_at": "2026-09-28T14:26:08.909035Z",
  "rating": {
    "score_percent": 91.13,
    "rating_count": 2355,
    "distribution_percent": {
      "20": 4.76,
      "40": 0.72,
      "60": 3.57,
      "80": 16.05,
      "100": 74.9
    },
    "comments_count": 1647,
    "questions_count": 1563
  }
}

list_product_sellers — request and recorded response

Inputs: product_id.

Request

{
  "product_id": "20135132"
}

Live public response (excerpt)

{
  "product_id": "20135132",
  "coverage": "variants_endpoint",
  "sellers": [
    {
      "seller_id": "1",
      "name": "دیجی‌کالا",
      "rating": {
        "stars": 5.0,
        "grade": "عالی"
      },
      "offers": [
        {
          "offer_id": "75026671",
          "seller_id": "1",
          "seller_name": "دیجی‌کالا",
          "price_rial": 1796386000,
          "availability": "available",
          "attributes": {
            "رنگ": "آبی"
          },
          "warranty": "گارانتی 18 ماهه -شرکتی",
          "shipping_price_rial": null
        }
      ]
    }
  ]
}

list_product_recommendation_sections — request and recorded response

Inputs: product_id.

Request

{
  "product_id": "20135132"
}

Live public response (excerpt)

{
  "product_id": "20135132",
  "sections": [
    {
      "key": "similar_products",
      "type": "carousel",
      "template": "grid"
    },
    {
      "key": "also_bought_products",
      "type": "carousel",
      "template": "grid"
    }
  ]
}

get_product_recommendations — request and recorded response

Inputs: product_id; optional section_key (default similar_products) and limit (1–50).

Request

{
  "product_id": "20135132"
}

Live public response (excerpt)

{
  "product_id": "20135132",
  "section_key": "similar_products",
  "title": "کالاهای مشابه",
  "products": [
    {
      "product_id": "20592831",
      "title": "گوشی موبایل سامسونگ مدل S25 FE دو سیم کارت ظرفیت 256 گیگابایت و رم 8 گیگابایت - ویتنام - به همراه شارژر 45 وات سامسونگ",
      "price_rial": 1952300000,
      "availability": "available"
    }
  ]
}

get_products_batch — request and recorded response

Inputs: query.product_ids.

Request

{
  "query": {
    "product_ids": [
      "20135132",
      "22672438"
    ]
  }
}

Live public response (excerpt)

{
  "results": {
    "20135132": {
      "product": {
        "product_id": "20135132",
        "price_rial": 1796386000,
        "availability": "available"
      },
      "error": null
    },
    "22672438": {
      "product": {
        "product_id": "22672438",
        "price_rial": 27999900,
        "availability": "available"
      },
      "error": null
    }
  }
}

get_product_media — request and recorded response

Inputs: product_id.

Request

{
  "product_id": "20135132"
}

Live public response (excerpt)

{
  "product_id": "20135132",
  "media": [
    {
      "kind": "image",
      "url": "https://dkstatics-public.digikala.com/digikala-products/55582a9ac4add1b88050b458e7d490564b3ac4b6_1759667022.jpg?x-oss-process=image/resize,m_lfit,h_800,w_800/quality,q_90",
      "is_main": true
    }
  ]
}

get_product_price_history — request and recorded response

Inputs: product_id. The captured call was rate-limited; no successful series is shown.

Request

{
  "product_id": "20135132"
}

Live public response (excerpt)

{
  "product_id": "20135132",
  "series": [],
  "error": {
    "code": "rate_limited",
    "message": "Market rate limit reached",
    "retryable": true
  }
}

Comparisons

Tool	What it does
`compare_offers`	Compare 2–6 exact offers, including attributes, warranty and item-price differences. No product substitution or delivered-price ranking.
`compare_product_sellers`	Compare 2–6 distinct offer IDs for the same product, including seller metrics.
`compare_products`	Compare literal specification labels and values across 2–6 products. Missing values stay unknown.

compare_offers — request and recorded response

Inputs: request.selections: market, product_id, offer_id; optional expected price and request location.

Request

{
  "request": {
    "selections": [
      {
        "market": "digikala",
        "product_id": "20135132",
        "offer_id": "75026671"
      },
      {
        "market": "digikala",
        "product_id": "20135132",
        "offer_id": "82990780"
      }
    ]
  }
}

Live public response (excerpt)

{
  "items": [
    {
      "selection": {
        "market": "digikala",
        "product_id": "20135132",
        "offer_id": "75026671",
        "expected_price_rial": null
      },
      "offer": {
        "offer_id": "75026671",
        "seller_id": "1",
        "price_rial": 1796386000,
        "attributes": {
          "رنگ": "آبی"
        }
      }
    },
    {
      "selection": {
        "market": "digikala",
        "product_id": "20135132",
        "offer_id": "82990780",
        "expected_price_rial": null
      },
      "offer": {
        "offer_id": "82990780",
        "seller_id": "1710056",
        "price_rial": 1894400000,
        "attributes": {
          "رنگ": "مشکی"
        }
      }
    }
  ],
  "pairs": [
    {
      "left_index": 0,
      "right_index": 1,
      "status": "compared",
      "attributes": "different",
      "warranty": "different",
      "price_difference_rial": 98014000
    }
  ]
}

compare_product_sellers — request and recorded response

Inputs: query.product_id, query.offer_ids from the variant/seller tools.

Request

{
  "query": {
    "product_id": "20135132",
    "offer_ids": [
      "75026671",
      "72608792"
    ]
  }
}

Live public response (excerpt)

{
  "items": [
    {
      "selection": {
        "market": "digikala",
        "product_id": "20135132",
        "offer_id": "75026671",
        "expected_price_rial": null
      },
      "offer": {
        "offer_id": "75026671",
        "seller_id": "1",
        "price_rial": 1796386000,
        "attributes": {
          "رنگ": "آبی"
        }
      }
    },
    {
      "selection": {
        "market": "digikala",
        "product_id": "20135132",
        "offer_id": "72608792",
        "expected_price_rial": null
      },
      "offer": {
        "offer_id": "72608792",
        "seller_id": "349337",
        "price_rial": 1900000000,
        "attributes": {
          "رنگ": "مشکی"
        }
      }
    }
  ],
  "pairs": [
    {
      "left_index": 0,
      "right_index": 1,
      "status": "compared",
      "attributes": "different",
      "warranty": "different",
      "price_difference_rial": 103614000
    }
  ]
}

compare_products — request and recorded response

Inputs: query.product_ids.

Request

{
  "query": {
    "product_ids": [
      "20135132",
      "22672438"
    ]
  }
}

Live public response (excerpt)

{
  "results": {
    "20135132": {
      "product": {
        "product_id": "20135132",
        "price_rial": 1796386000,
        "availability": "available"
      },
      "error": null
    },
    "22672438": {
      "product": {
        "product_id": "22672438",
        "price_rial": 27999900,
        "availability": "available"
      },
      "error": null
    }
  },
  "specifications": [
    {
      "title": "ریجن",
      "values": {
        "20135132": [
          "ویتنام "
        ],
        "22672438": null
      },
      "relation": "unknown"
    }
  ]
}

Desktop cart

Tool	What it does
`get_cart_limits`	Read host-configured merchandise amount and total-unit limits. Null limits disable increases.
`read_cart`	Read items, exact offers, quantities, merchandise total and known shipping for the desktop keyring account.
`prepare_cart_change`	Read and validate a proposed change, enforce limits, and persist a five-minute plan without changing the remote cart.
`add_to_cart`	POST one unit of the exact offer in an approved add plan; revalidate and read back the result.
`update_cart_item`	PATCH the final quantity from an approved update plan. Increases revalidate price, stock and limits.
`remove_from_cart`	DELETE the exact cart item identified by an approved remove plan.
`get_cart_operation`	Inspect a persisted plan or replacement and its current state for the connected account.
`reconcile_cart_operation`	Read back an uncertain operation and update its journal without resending a mutation. Executing operations remain blocked.

get_cart_limits — request and recorded response

Inputs: None.

Request

{}

Local server response (excerpt)

{
  "limits": {
    "max_total_rial": 50000000,
    "max_items": 3
  }
}

read_cart — request and recorded response

Inputs: None; requires a connected desktop account.

Request

{}

Unconfigured-environment response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error calling tool 'read_cart': keyring_unavailable: Configure a supported OS keyring backend"
    }
  ]
}

prepare_cart_change — request and recorded response

Inputs: change: add uses product_id + offer_id; update uses cart_item_id + final quantity; remove uses cart_item_id.

Request

{
  "change": {
    "action": "add",
    "product_id": "20135132",
    "offer_id": "75026671"
  }
}

Unconfigured-environment response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error calling tool 'prepare_cart_change': keyring_unavailable: Configure a supported OS keyring backend"
    }
  ]
}

add_to_cart — request and recorded response

Inputs: plan_id from an add plan.

Request

{
  "plan_id": "00000000000000000000000000000000"
}

Unconfigured-environment response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "database_not_configured: Set DATABASE_URL for cart persistence"
    }
  ]
}

update_cart_item — request and recorded response

Inputs: plan_id from an update plan.

Request

{
  "plan_id": "00000000000000000000000000000000"
}

Unconfigured-environment response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "database_not_configured: Set DATABASE_URL for cart persistence"
    }
  ]
}

remove_from_cart — request and recorded response

Inputs: plan_id from a remove plan.

Request

{
  "plan_id": "00000000000000000000000000000000"
}

Unconfigured-environment response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "database_not_configured: Set DATABASE_URL for cart persistence"
    }
  ]
}

get_cart_operation — request and recorded response

Inputs: operation_id: a plan ID, or replacement UUID as 32 lowercase hex digits.

Request

{
  "operation_id": "00000000000000000000000000000000"
}

Unconfigured-environment response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error calling tool 'get_cart_operation': keyring_unavailable"
    }
  ]
}

reconcile_cart_operation — request and recorded response

Inputs: operation_id.

Request

{
  "operation_id": "00000000000000000000000000000000"
}

Unconfigured-environment response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error calling tool 'reconcile_cart_operation': keyring_unavailable"
    }
  ]
}

Token-scoped accounts

Tool	What it does
`login_account`	Perform password login for a trusted backend. Return a process-local token, expiry, or fixed failure/challenge outcome.
`logout_account`	Discard a token from this server process; other accounts are unaffected.
`read_account_cart`	Read the cart for the token-bound account, with no desktop keyring fallback.
`prepare_account_cart_change`	Create a five-minute plan for the token-bound account without a remote mutation.
`add_to_account_cart`	POST one unit using an approved add plan belonging to the token account.
`update_account_cart_item`	PATCH the final quantity using an approved update plan belonging to the token account.
`remove_from_account_cart`	DELETE an item using an approved remove plan belonging to the token account.
`replace_account_cart`	Validate 1–3 exact selections, remove current items, and add one unit of each selection. Partial or uncertain outcomes block retries from resending writes.
`get_account_cart_operation`	Inspect a persisted plan or replacement belonging to the token account.
`reconcile_account_cart_operation`	Read back an uncertain token-account operation and update its journal without another remote mutation.

login_account — request and recorded response

Inputs: credentials.username, credentials.password; the example intentionally omits both to demonstrate validation without logging in.

Request

{
  "credentials": {}
}

Input-validation response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "2 validation errors for call[login_account]\ncredentials.username\n  Field required [type=missing, input_value={}, input_type=dict]\n    For further information visit https://errors.pydantic.dev/2.13/v/missing\ncredentials.password\n  Field required [type=missing, input_value={}, input_type=dict]\n    For further information visit https://errors.pydantic.dev/2.13/v/missing"
    }
  ]
}

logout_account — request and recorded response

Inputs: session_token; unknown tokens are also reported as disconnected.

Request

{
  "session_token": "invalid-documentation-token"
}

Unauthenticated response (excerpt)

{
  "disconnected": true
}

read_account_cart — request and recorded response

Inputs: session_token.

Request

{
  "session_token": "invalid-documentation-token"
}

Unauthenticated response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error calling tool 'read_account_cart': session_expired"
    }
  ]
}

prepare_account_cart_change — request and recorded response

Inputs: session_token, change with the same fields as prepare_cart_change.

Request

{
  "session_token": "invalid-documentation-token",
  "change": {
    "action": "add",
    "product_id": "20135132",
    "offer_id": "75026671"
  }
}

Unauthenticated response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error calling tool 'prepare_account_cart_change': session_expired"
    }
  ]
}

add_to_account_cart — request and recorded response

Inputs: session_token, plan_id.

Request

{
  "session_token": "invalid-documentation-token",
  "plan_id": "00000000000000000000000000000000"
}

Unauthenticated response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error calling tool 'add_to_account_cart': session_expired"
    }
  ]
}

update_account_cart_item — request and recorded response

Inputs: session_token, plan_id.

Request

{
  "session_token": "invalid-documentation-token",
  "plan_id": "00000000000000000000000000000000"
}

Unauthenticated response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error calling tool 'update_account_cart_item': session_expired"
    }
  ]
}

remove_from_account_cart — request and recorded response

Inputs: session_token, plan_id.

Request

{
  "session_token": "invalid-documentation-token",
  "plan_id": "00000000000000000000000000000000"
}

Unauthenticated response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error calling tool 'remove_from_account_cart': session_expired"
    }
  ]
}

replace_account_cart — request and recorded response

Inputs: session_token, replacement: request_id, max_total_rial, items containing product/offer/seller IDs and expected prices.

Request

{
  "session_token": "invalid-documentation-token",
  "replacement": {
    "request_id": "00000000-0000-0000-0000-000000000000",
    "max_total_rial": 50000000,
    "items": [
      {
        "product_id": "20135132",
        "offer_id": "75026671",
        "seller_id": "1",
        "expected_price_rial": 1
      }
    ]
  }
}

Unauthenticated response (excerpt)

{
  "request_id": "00000000-0000-0000-0000-000000000000",
  "state": "rejected",
  "reason": "session_expired",
  "cart": null
}

get_account_cart_operation — request and recorded response

Inputs: session_token, operation_id.

Request

{
  "session_token": "invalid-documentation-token",
  "operation_id": "00000000000000000000000000000000"
}

Unauthenticated response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error calling tool 'get_account_cart_operation': session_expired"
    }
  ]
}

reconcile_account_cart_operation — request and recorded response

Inputs: session_token, operation_id.

Request

{
  "session_token": "invalid-documentation-token",
  "operation_id": "00000000000000000000000000000000"
}

Unauthenticated response (excerpt)

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error calling tool 'reconcile_account_cart_operation': session_expired"
    }
  ]
}

Name		Name	Last commit message	Last commit date
assets/branding		assets/branding
migrations		migrations
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
alembic.ini		alembic.ini
pyproject.toml		pyproject.toml

Navigation Menu

Repository navigation

About

Repository files navigation

digikala-mcp

Architecture

Responsibilities

Dependency and session lifetime

Observations and cache

Cart and account flow

Tools and recorded responses

Discovery

Product research

Comparisons

Desktop cart

Token-scoped accounts

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

digikala-mcp

Architecture

Responsibilities

Dependency and session lifetime

Observations and cache

Cart and account flow

Tools and recorded responses

Discovery

Product research

Comparisons

Desktop cart

Token-scoped accounts

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages