kwork-mcp 0.1.0__tar.gz

kwork_mcp-0.1.0/.env.example

@@ -0,0 +1,11 @@
+# Required: one of (LOGIN+PASSWORD) or TOKEN
+KWORK_LOGIN=your_login
+KWORK_PASSWORD=your_password
+# KWORK_PHONE_LAST=1234          # Last 4 digits for 2FA (if enabled)
+# KWORK_TOKEN=existing_token      # Skip login, use this token directly
+
+# Optional
+# KWORK_PROXY_URL=socks5://host:port
+# KWORK_RPS_LIMIT=2
+# KWORK_BURST_LIMIT=5
+# KWORK_TOKEN_FILE=~/.kwork_token

kwork_mcp-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.kwork_token
+*.egg-info/
+dist/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+uv.lock
+CLAUDE.md
+.superpowers/

kwork_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 simonether
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kwork_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: kwork-mcp
+Version: 0.1.0
+Summary: MCP server for managing Kwork freelance marketplace
+Project-URL: Homepage, https://github.com/simonether/kwork-mcp
+Project-URL: Repository, https://github.com/simonether/kwork-mcp
+Project-URL: Issues, https://github.com/simonether/kwork-mcp/issues
+Author-email: Simon Sudarushkin <simonsudarushkin@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,freelance,kwork,mcp,mcp-server
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: kwork>=0.2.0
+Requires-Dist: loguru>=0.7
+Requires-Dist: mcp>=1.20
+Requires-Dist: pydantic-settings>=2.7
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/banner.svg" alt="kwork-mcp" width="100%">
+</p>
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2)](https://modelcontextprotocol.io)
+
+MCP server that exposes 25 tools for the [Kwork](https://kwork.ru) freelance marketplace — browse projects, submit offers, manage orders, send messages, and more.
+
+Built with [FastMCP](https://github.com/jlowin/fastmcp) (via [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)) and [pykwork](https://github.com/kesha1225/pykwork).
+
+## 🚀 Setup
+
+### Requirements
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+- Kwork account (login/password or API token)
+
+### Install
+
+```bash
+git clone https://github.com/simonether/kwork-mcp.git
+cd kwork-mcp
+uv sync
+```
+
+### Configure
+
+Copy `.env.example` to `.env` and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `KWORK_LOGIN` | yes* | — | Kwork login |
+| `KWORK_PASSWORD` | yes* | — | Kwork password |
+| `KWORK_TOKEN` | yes* | — | Auth token (skips login) |
+| `KWORK_PHONE_LAST` | no | — | Last 4 digits of phone (2FA) |
+| `KWORK_PROXY_URL` | no | — | SOCKS5 proxy |
+| `KWORK_RPS_LIMIT` | no | `2` | Requests per second |
+| `KWORK_BURST_LIMIT` | no | `5` | Burst limit |
+| `KWORK_TOKEN_FILE` | no | `~/.kwork_token` | Token persistence path |
+
+\*Either `KWORK_TOKEN` or both `KWORK_LOGIN` + `KWORK_PASSWORD`.
+
+Auth priority: `KWORK_TOKEN` env → saved token file → fresh login.
+
+## 💡 Usage
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kwork": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/kwork-mcp", "kwork-mcp"],
+      "env": {
+        "KWORK_LOGIN": "your_login",
+        "KWORK_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add kwork -- uv run --directory /path/to/kwork-mcp kwork-mcp
+```
+
+### stdio
+
+```bash
+uv run kwork-mcp
+```
+
+## 🛠 Tools
+
+<details>
+<summary><strong>Profile</strong> (3 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `get_me` | Current user profile, rating, balance |
+| `get_connects` | Connect count for exchange offers |
+| `get_user_info` | Public user info by ID |
+
+</details>
+
+<details>
+<summary><strong>Projects</strong> (4 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_projects` | Browse exchange projects with filters |
+| `get_project` | Project details by ID |
+| `search_projects` | Search by text query |
+| `get_exchange_info` | Exchange marketplace stats |
+
+</details>
+
+<details>
+<summary><strong>Offers</strong> (4 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_my_offers` | Your exchange offers |
+| `get_offer` | Offer details by ID |
+| `submit_offer` | Submit offer to a project (costs 1 connect) |
+| `delete_offer` | Delete an offer |
+
+</details>
+
+<details>
+<summary><strong>Orders</strong> (3 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_worker_orders` | Seller orders (all statuses) |
+| `get_order_details` | Order details by ID |
+| `send_order_for_approval` | Submit work for buyer review |
+
+</details>
+
+<details>
+<summary><strong>Dialogs</strong> (4 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_dialogs` | Conversations with latest messages |
+| `get_dialog` | Messages by username |
+| `send_message` | Send direct message |
+| `mark_dialog_read` | Mark as read |
+
+</details>
+
+<details>
+<summary><strong>Kworks</strong> (4 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_my_kworks` | Your services grouped by status |
+| `get_kwork_details` | Kwork details by ID |
+| `start_kwork` | Activate a paused kwork |
+| `pause_kwork` | Pause an active kwork |
+
+</details>
+
+<details>
+<summary><strong>Categories</strong> (2 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_categories` | Full category tree |
+| `get_favorite_categories` | User's favorite categories |
+
+</details>
+
+<details>
+<summary><strong>Notifications</strong> (1 tool)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_notifications` | User notifications |
+
+</details>
+
+## 🧑‍💻 Development
+
+```bash
+uv sync --dev
+uv run python -m pytest tests/ -x -v
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## License
+
+[MIT](LICENSE)

kwork_mcp-0.1.0/README.md

@@ -0,0 +1,188 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="kwork-mcp" width="100%">
+</p>
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2)](https://modelcontextprotocol.io)
+
+MCP server that exposes 25 tools for the [Kwork](https://kwork.ru) freelance marketplace — browse projects, submit offers, manage orders, send messages, and more.
+
+Built with [FastMCP](https://github.com/jlowin/fastmcp) (via [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)) and [pykwork](https://github.com/kesha1225/pykwork).
+
+## 🚀 Setup
+
+### Requirements
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+- Kwork account (login/password or API token)
+
+### Install
+
+```bash
+git clone https://github.com/simonether/kwork-mcp.git
+cd kwork-mcp
+uv sync
+```
+
+### Configure
+
+Copy `.env.example` to `.env` and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `KWORK_LOGIN` | yes* | — | Kwork login |
+| `KWORK_PASSWORD` | yes* | — | Kwork password |
+| `KWORK_TOKEN` | yes* | — | Auth token (skips login) |
+| `KWORK_PHONE_LAST` | no | — | Last 4 digits of phone (2FA) |
+| `KWORK_PROXY_URL` | no | — | SOCKS5 proxy |
+| `KWORK_RPS_LIMIT` | no | `2` | Requests per second |
+| `KWORK_BURST_LIMIT` | no | `5` | Burst limit |
+| `KWORK_TOKEN_FILE` | no | `~/.kwork_token` | Token persistence path |
+
+\*Either `KWORK_TOKEN` or both `KWORK_LOGIN` + `KWORK_PASSWORD`.
+
+Auth priority: `KWORK_TOKEN` env → saved token file → fresh login.
+
+## 💡 Usage
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kwork": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/kwork-mcp", "kwork-mcp"],
+      "env": {
+        "KWORK_LOGIN": "your_login",
+        "KWORK_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add kwork -- uv run --directory /path/to/kwork-mcp kwork-mcp
+```
+
+### stdio
+
+```bash
+uv run kwork-mcp
+```
+
+## 🛠 Tools
+
+<details>
+<summary><strong>Profile</strong> (3 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `get_me` | Current user profile, rating, balance |
+| `get_connects` | Connect count for exchange offers |
+| `get_user_info` | Public user info by ID |
+
+</details>
+
+<details>
+<summary><strong>Projects</strong> (4 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_projects` | Browse exchange projects with filters |
+| `get_project` | Project details by ID |
+| `search_projects` | Search by text query |
+| `get_exchange_info` | Exchange marketplace stats |
+
+</details>
+
+<details>
+<summary><strong>Offers</strong> (4 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_my_offers` | Your exchange offers |
+| `get_offer` | Offer details by ID |
+| `submit_offer` | Submit offer to a project (costs 1 connect) |
+| `delete_offer` | Delete an offer |
+
+</details>
+
+<details>
+<summary><strong>Orders</strong> (3 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_worker_orders` | Seller orders (all statuses) |
+| `get_order_details` | Order details by ID |
+| `send_order_for_approval` | Submit work for buyer review |
+
+</details>
+
+<details>
+<summary><strong>Dialogs</strong> (4 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_dialogs` | Conversations with latest messages |
+| `get_dialog` | Messages by username |
+| `send_message` | Send direct message |
+| `mark_dialog_read` | Mark as read |
+
+</details>
+
+<details>
+<summary><strong>Kworks</strong> (4 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_my_kworks` | Your services grouped by status |
+| `get_kwork_details` | Kwork details by ID |
+| `start_kwork` | Activate a paused kwork |
+| `pause_kwork` | Pause an active kwork |
+
+</details>
+
+<details>
+<summary><strong>Categories</strong> (2 tools)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_categories` | Full category tree |
+| `get_favorite_categories` | User's favorite categories |
+
+</details>
+
+<details>
+<summary><strong>Notifications</strong> (1 tool)</summary>
+
+| Tool | Description |
+|---|---|
+| `list_notifications` | User notifications |
+
+</details>
+
+## 🧑‍💻 Development
+
+```bash
+uv sync --dev
+uv run python -m pytest tests/ -x -v
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## License
+
+[MIT](LICENSE)

kwork_mcp-0.1.0/assets/banner.svg

@@ -0,0 +1,56 @@
+<svg viewBox="0 0 800 240" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0c0c0c"/>
+      <stop offset="50%" style="stop-color:#100d16"/>
+      <stop offset="100%" style="stop-color:#161022"/>
+    </linearGradient>
+    <linearGradient id="ac" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#e040fb"/>
+      <stop offset="100%" style="stop-color:#536dfe"/>
+    </linearGradient>
+    <radialGradient id="gl" cx="65%" cy="50%">
+      <stop offset="0%" style="stop-color:rgba(224,64,251,0.07)"/>
+      <stop offset="100%" style="stop-color:transparent"/>
+    </radialGradient>
+    <filter id="txtGlow" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="8" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <rect width="800" height="240" fill="url(#bg)"/>
+  <rect width="800" height="240" fill="url(#gl)"/>
+
+  <!-- Sparse constellation -->
+  <line x1="520" y1="45" x2="620" y2="75" stroke="rgba(224,64,251,0.12)" stroke-width="0.5"/>
+  <line x1="620" y1="75" x2="580" y2="150" stroke="rgba(83,109,254,0.1)" stroke-width="0.5"/>
+  <line x1="580" y1="150" x2="520" y2="45" stroke="rgba(124,77,255,0.08)" stroke-width="0.5"/>
+  <line x1="620" y1="75" x2="720" y2="55" stroke="rgba(224,64,251,0.1)" stroke-width="0.5"/>
+  <line x1="720" y1="55" x2="740" y2="140" stroke="rgba(83,109,254,0.09)" stroke-width="0.5"/>
+  <line x1="740" y1="140" x2="620" y2="75" stroke="rgba(224,64,251,0.07)" stroke-width="0.5"/>
+  <line x1="580" y1="150" x2="680" y2="190" stroke="rgba(83,109,254,0.07)" stroke-width="0.5"/>
+  <line x1="680" y1="190" x2="740" y2="140" stroke="rgba(224,64,251,0.06)" stroke-width="0.5"/>
+
+  <!-- Vertices -->
+  <circle cx="520" cy="45" r="2.5" fill="rgba(224,64,251,0.5)"/>
+  <circle cx="620" cy="75" r="3.5" fill="rgba(224,64,251,0.6)"/>
+  <circle cx="580" cy="150" r="2.5" fill="rgba(83,109,254,0.45)"/>
+  <circle cx="720" cy="55" r="2" fill="rgba(124,77,255,0.4)"/>
+  <circle cx="740" cy="140" r="3" fill="rgba(83,109,254,0.5)"/>
+  <circle cx="680" cy="190" r="2" fill="rgba(224,64,251,0.35)"/>
+  <circle cx="480" cy="200" r="1.5" fill="rgba(124,77,255,0.2)"/>
+  <circle cx="770" cy="25" r="1" fill="rgba(224,64,251,0.15)"/>
+
+  <!-- Title glow layer -->
+  <text x="55" y="100" font-family="'IBM Plex Mono', 'Source Code Pro', monospace" font-size="44" font-weight="600" fill="rgba(224,64,251,0.18)" filter="url(#txtGlow)">kwork-mcp</text>
+  <!-- Title sharp layer -->
+  <text x="55" y="100" font-family="'IBM Plex Mono', 'Source Code Pro', monospace" font-size="44" font-weight="600" fill="url(#ac)">kwork-mcp</text>
+
+  <!-- Tagline -->
+  <text x="57" y="135" font-family="'Outfit', 'Sora', sans-serif" font-size="13.5" fill="rgba(255,255,255,0.38)" letter-spacing="1">MCP server · 25 tools · Kwork freelance marketplace</text>
+
+  <!-- Accent dot + line -->
+  <circle cx="59" cy="155" r="2.5" fill="rgba(224,64,251,0.4)"/>
+  <rect x="68" y="153.5" width="80" height="1" fill="url(#ac)" rx="0.5" opacity="0.3"/>
+</svg>

kwork_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "kwork-mcp"
+version = "0.1.0"
+description = "MCP server for managing Kwork freelance marketplace"
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+    { name = "Simon Sudarushkin", email = "simonsudarushkin@gmail.com" },
+]
+keywords = ["mcp", "kwork", "freelance", "claude", "mcp-server"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "mcp>=1.20",
+    "kwork>=0.2.0",
+    "pydantic-settings>=2.7",
+    "loguru>=0.7",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.25",
+    "ruff>=0.9",
+]
+
+[project.scripts]
+kwork-mcp = "kwork_mcp:main"
+
+[project.urls]
+Homepage = "https://github.com/simonether/kwork-mcp"
+Repository = "https://github.com/simonether/kwork-mcp"
+Issues = "https://github.com/simonether/kwork-mcp/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kwork_mcp"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "N", "UP", "B", "SIM", "T20", "RUF", "ASYNC"]
+ignore = ["RUF001", "RUF002", "E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

kwork_mcp-0.1.0/src/kwork_mcp/__init__.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import sys
+
+from loguru import logger
+
+
+def main() -> None:
+    logger.remove()
+    logger.add(sys.stderr, level="INFO", format="{time:HH:mm:ss} | {level} | {message}")
+
+    from kwork_mcp.server import create_server
+
+    server = create_server()
+    server.run(transport="stdio")

kwork_mcp-0.1.0/src/kwork_mcp/__main__.py

@@ -0,0 +1,3 @@
+from kwork_mcp import main
+
+main()

kwork_mcp-0.1.0/src/kwork_mcp/config.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class KworkConfig(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="KWORK_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    login: str = ""
+    password: SecretStr = SecretStr("")
+    phone_last: str | None = None
+    token: SecretStr | None = None
+
+    proxy_url: str | None = None
+    timeout: int = 30
+
+    rps_limit: int = 2
+    burst_limit: int = 5
+
+    token_file: Path = Path.home() / ".kwork_token"

kwork_mcp-0.1.0/src/kwork_mcp/errors.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from kwork.exceptions import KworkException, KworkHTTPException
+from loguru import logger
+from mcp.server.fastmcp.exceptions import ToolError
+
+
+def _get_error_code(exc: KworkException) -> int | None:
+    """Extract Kwork API error_code from KworkHTTPException.response_json."""
+    if isinstance(exc, KworkHTTPException) and exc.response_json:
+        return exc.response_json.get("error_code")
+    return None
+
+
+@asynccontextmanager
+async def api_guard(operation: str = "Kwork API") -> AsyncIterator[None]:
+    """Context manager that translates pykwork exceptions into ToolError."""
+    try:
+        yield
+    except ToolError:
+        raise
+    except KworkHTTPException as exc:
+        code = _get_error_code(exc)
+        if code == 118 or "captcha" in str(exc).lower():
+            raise ToolError(
+                "Kwork требует капчу. Откройте kwork.ru в браузере, "
+                "решите капчу, затем передайте свежий токен через KWORK_TOKEN."
+            ) from exc
+        if exc.status == 401:
+            raise ToolError(
+                "Сессия истекла, повторная авторизация не удалась. Проверьте KWORK_LOGIN и KWORK_PASSWORD."
+            ) from exc
+        if exc.status == 403 or code == 403:
+            raise ToolError(
+                "IP заблокирован Kwork. Попробуйте позже или используйте прокси (KWORK_PROXY_URL)."
+            ) from exc
+        logger.error("{op} HTTP error: status={status} {exc}", op=operation, status=exc.status, exc=exc)
+        raise ToolError(f"Ошибка {operation}: {exc}") from exc
+    except KworkException as exc:
+        logger.error("{op} error: {exc}", op=operation, exc=exc)
+        raise ToolError(f"Ошибка {operation}: {exc}") from exc
+    except TimeoutError as exc:
+        raise ToolError("Kwork API недоступен (таймаут). Попробуйте позже.") from exc
+    except Exception as exc:
+        logger.exception("Unexpected error in {op}", op=operation)
+        raise ToolError(f"Непредвиденная ошибка {operation}: {exc}") from exc