### Development Setup and Commands Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md This set of bash commands covers the initial setup and common development tasks for the ozon-mcp project. It includes cloning the repository, installing dependencies with `uv sync`, running tests, checking code quality with `ruff` and `mypy`, and generating code coverage reports. ```bash git clone https://github.com/PCDCK/ozon-mcp.git cd ozon-mcp uv sync --extra dev # Tests (≈25s, 274 currently) uv run pytest tests/ --ignore=tests/live # Code quality uv run ruff check src tests uv run mypy src/ozon_mcp # Coverage uv run pytest tests/ --ignore=tests/live --cov=src/ozon_mcp \ --cov-report=term-missing ``` -------------------------------- ### Development Setup and Testing Source: https://github.com/pcdck/ozon-mcp/blob/main/CONTRIBUTING.md Commands to clone the repository, set up the development environment, run tests, and perform linting and type checks. ```bash git clone https://github.com/PCDCK/ozon-mcp.git cd ozon-mcp uv sync --extra dev ``` ```bash # Test suite (≈25s, 274 tests) uv run pytest tests/ --ignore=tests/live ``` ```bash # Lint and type check uv run ruff check src tests uv run mypy src/ozon_mcp ``` ```bash # Coverage report uv run pytest tests/ --ignore=tests/live --cov=src/ozon_mcp \ --cov-report=term-missing ``` -------------------------------- ### Install ozon-mcp with uv Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md Clone the repository, navigate to the directory, and synchronize dependencies using uv. ```bash git clone https://github.com/PCDCK/ozon-mcp.git cd ozon-mcp uv sync ``` -------------------------------- ### Verify ozon-mcp installation Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md Run the --help command to confirm that the ozon-mcp server is installed and accessible. ```bash uv run ozon-mcp --help ``` -------------------------------- ### Example API Call: Fetch all products Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md This example shows the JSON payload sent to the ozon-mcp server to retrieve a list of all products using the ProductAPI_GetProductList operation. The server automatically handles pagination. ```json { "operation_id": "ProductAPI_GetProductList", "params": {"filter": {"visibility": "ALL"}}, "max_items": 10000 } ``` -------------------------------- ### Usage Example Knowledge Entry Source: https://github.com/pcdck/ozon-mcp/blob/main/CONTRIBUTING.md YAML format for providing usage examples of API methods, including request parameters, response excerpts, and pagination details. ```yaml - operation_id: ProductAPI_GetProductList title: "First 100 active products" description: | Minimal useful call — for UI / catalog preview. Use the returned last_id as the offset for the next page or call ozon_fetch_all for full pagination. request: filter: visibility: ALL last_id: "" limit: 100 response_excerpt: result: items: - product_id: 99000001 offer_id: TEST-SKU-001 last_id: WyI5OTAwMDAwMSJd total: 1 ``` -------------------------------- ### Example API Response: Product List Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md This is a realistic server response for fetching products, showing the structure of returned items, total count, and pagination details. Identifiers are anonymized. ```json { "ok": true, "items": [ {"product_id": 99000001, "offer_id": "TEST-SKU-001", "archived": false}, {"product_id": 99000002, "offer_id": "TEST-SKU-002", "archived": false}, {"product_id": 99000003, "offer_id": "TEST-SKU-003", "archived": true} ], "total_fetched": 3, "truncated": false, "pages_fetched": 1 } ``` -------------------------------- ### Auto-Pagination Example Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md This Python code demonstrates how to use `ozon_fetch_all` to retrieve all products matching specific filters. It shows the function call with operation ID and parameters, and the expected response structure including items, total fetched count, truncation status, and pages fetched. ```python ozon_fetch_all( operation_id="ProductAPI_GetProductList", params={"filter": {"visibility": "ALL"}}, max_items=10_000, ) # → {"items": [...all products...], "total_fetched": 847, # "truncated": false, "pages_fetched": 1} ``` -------------------------------- ### Business Context Knowledge Example Source: https://github.com/pcdck/ozon-mcp/blob/main/CONTRIBUTING.md YAML structure for defining business context for an API method, including its description, usage scenarios, and common mistakes. ```yaml - operation_id: AnalyticsAPI_StocksTurnover api: seller title: "Business context: stock-out planning" description: | Single call returns ads / idc / turnover_grade for every SKU. business_context: | The single best signal for purchase planning. idc < 14 means the item runs out within two weeks at current sell-through. Hard rate-limited to 1 req/min on the Ozon side. when_to_use: - "Daily OOS-risk monitoring" - "FBO supply planning" common_mistakes: - "Calling in a loop without backoff — guaranteed 429" severity: info extracted_from: curated ``` -------------------------------- ### Subscription Requirement Override Example Source: https://github.com/pcdck/ozon-mcp/blob/main/CONTRIBUTING.md YAML entry to override or specify subscription tier requirements for API methods, including the source of confirmation. ```yaml - operation_id: ProductPricesDetails required_tier: PREMIUM_PRO # PREMIUM | PREMIUM_PLUS | PREMIUM_PRO | unknown | null source: swagger+empirical # how you confirmed the requirement note: "Confirmed 403 on PREMIUM_PLUS, 200 on PREMIUM_PRO (2026-04-15)" ``` -------------------------------- ### Subscription Gate Error Example Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md This JSON object illustrates an error response when an API endpoint requires a higher subscription tier than the user currently has. It indicates the required tier and the cabinet's current tier, and that the HTTP call was skipped. ```json { "error": "subscription_gate", "error_type": "subscription_gate", "code": 7, "message": "Endpoint requires PREMIUM_PRO, cabinet has PREMIUM_PLUS", "operation_id": "ProductPricesDetails", "required_tier": "PREMIUM_PRO", "cabinet_tier": "PREMIUM_PLUS", "retryable": false, "http_call_skipped": true } ``` -------------------------------- ### Unified Error Envelope Example Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md This JSON object represents a common error structure returned by the API. It includes error type, a human-readable message, an error code, the operation ID, the affected endpoint, and retry information. ```json { "error": "rate_limit_exceeded", "error_type": "rate_limit | subscription_gate | not_found | invalid_params | server_error | timeout | auth | forbidden | conflict | ...", "message": "Human-readable explanation", "code": 429, "operation_id": "AnalyticsAPI_StocksTurnover", "endpoint": "/v1/analytics/turnover/stocks", "retryable": true, "retry_after_seconds": 60 } ``` -------------------------------- ### Configure Continue.dev for ozon-mcp Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md Add the ozon-mcp server configuration to the experimental section of your Continue.dev config.json file. ```json { "experimental": { "modelContextProtocolServers": [ { "transport": { "type": "stdio", "command": "uv", "args": ["--directory", "/absolute/path/to/ozon-mcp", "run", "ozon-mcp"] } } ] } } ``` -------------------------------- ### Configure Claude Desktop for ozon-mcp Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md Add the ozon-mcp server configuration to your Claude Desktop settings file. Ensure to replace placeholder values with your actual Ozon API credentials. ```json { "mcpServers": { "ozon": { "command": "uv", "args": ["--directory", "/absolute/path/to/ozon-mcp", "run", "ozon-mcp"], "env": { "OZON_CLIENT_ID": "your-seller-client-id", "OZON_API_KEY": "your-seller-api-key", "OZON_PERFORMANCE_CLIENT_ID": "your-perf-client-id", "OZON_PERFORMANCE_CLIENT_SECRET": "your-perf-secret" } } } } ``` -------------------------------- ### Configure Cline (VS Code extension) for ozon-mcp Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md Add the ozon-mcp server configuration through the Cline extension's settings interface in VS Code. ```json { "ozon": { "command": "uv", "args": ["--directory", "/absolute/path/to/ozon-mcp", "run", "ozon-mcp"] } } ``` -------------------------------- ### Configure Cursor for ozon-mcp Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md Add the ozon-mcp server configuration to Cursor's mcp.json file via the settings UI or by directly editing the file. ```json { "mcpServers": { "ozon": { "command": "uv", "args": ["--directory", "/absolute/path/to/ozon-mcp", "run", "ozon-mcp"] } } } ``` -------------------------------- ### Connect Claude Code (CLI) to ozon-mcp Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md Add the ozon-mcp server to your Claude CLI configuration. Alternatively, you can use the same JSON configuration as Claude Desktop. ```bash cd /path/to/ozon-mcp claude mcp add ozon -- uv run ozon-mcp ``` -------------------------------- ### Generic MCP stdio client configuration for ozon-mcp Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md A generic configuration for any MCP client that supports the stdio transport. This includes setting the command, arguments, transport type, and environment variables. ```yaml command: uv args: ["--directory", "/absolute/path/to/ozon-mcp", "run", "ozon-mcp"] transport: stdio env: OZON_CLIENT_ID: ... OZON_API_KEY: ... ``` -------------------------------- ### Sync API Specifications Source: https://github.com/pcdck/ozon-mcp/blob/main/README.md This bash script outlines the steps to update the local API specifications by downloading and sanitizing the swagger files from the parser repository. It includes commands to navigate to the parser directory, run the parsing script, and copy the updated swagger JSON files to the data directory. ```bash cd parser/ # the parser repo / drop-zone python parse_swagger.py # downloads + sanitises both APIs cp seller_swagger.json ../src/ozon_mcp/data/ cp perf_swagger.json ../src/ozon_mcp/data/ cp swagger_meta.json ../src/ozon_mcp/data/ ``` -------------------------------- ### Run Live Tests with Credentials Source: https://github.com/pcdck/ozon-mcp/blob/main/CONTRIBUTING.md Set Ozon API credentials as environment variables and run live tests using pytest. ```bash export OZON_CLIENT_ID=... export OZON_API_KEY=... uv run pytest tests/live -m live ``` -------------------------------- ### New Workflow Knowledge Structure Source: https://github.com/pcdck/ozon-mcp/blob/main/CONTRIBUTING.md YAML schema for defining new workflows, including steps, scheduling, rate limits, subscription requirements, and interpretation guidelines. ```yaml - name: my_new_workflow category: analytics # one of: catalog, orders, analytics, health, # pricing, content, advertising, # warehouse, returns, finance title: "Brief title" description: | What problem this workflow solves and when an agent should pick it. recommended_schedule: every 30 minutes # optional steps: - n: 1 operation_id: SomeAPI_SomeMethod purpose: "What this step accomplishes" pagination: "cursor / offset / page_number" notes: "Anything the agent has to know" rate_limit_note: "Aggregated rate-limit guidance" subscription_note: "Which tier is required" interpret: | How to read the response — which fields matter, what to filter on. when_to_use: - "Concrete situation 1" - "Concrete situation 2" common_mistakes: - "Pitfall the agent should avoid" gotchas: - "Schema-level surprises" review_status: draft # promote to "verified" after live validation ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.