kwork-mcp: Instructions file for Codex

kwork-mcp

Stdio MCP gateway for the Kwork freelance marketplace: 22 tools (18 typed reads + a durable prepare → commit → reconcile write protocol) on FastMCP 4 / MCP SDK 2 over the pinned kwork==0.2.0 client. Python 3.12–3.14, managed with uv.

Commands

• uv run ruff check . — lint
• uv run ruff format --check . — format check
• uv run mypy — strict type check
• uv run python -m pytest tests/ -q — tests
• uv run python -m pytest tests/ -q --cov=kwork_mcp --cov-report=term-missing — tests + coverage (gate: 92% branch)
• uv run kwork-mcp — start the server (stdio); needs a bootstrapped account
• uv run kwork-mcp login — human TTY CLI: account auth; also status, logout, pending-writes, resolve-write (kwork-mcp-bootstrap is the old alias)

Project map

src/kwork_mcp/
  __init__.py       main(): bare command = stdio server (rejects secret env, no banner); args → terminal CLI
  bootstrap.py      terminal CLI: login (TTY auth → store, prints client commands), status, logout, write resolution
  config.py         KworkConfig (pydantic-settings, KWORK_ prefix), bound-account selection, proxy validation
  server.py         create_server(): FastMCP app, lifespan, SERVER_INSTRUCTIONS, unknown-tool guard
  session.py        KworkSessionManager: lazy auth, account identity checks, call_read / call_write_step
  coordination.py   CoordinationStore: shared SQLite — rate limits, circuits, cursors, write ledger, writer lock
  contracts.py      pinned pykwork signatures and generic route params (enforce_route_params)
  security.py       SecureTokenStore, sanitize_external / redact_text, log redaction
  errors.py         GatewayError taxonomy, classify_upstream_error
  models.py         ResultEnvelope, records, write requests, WriteState
  middleware.py     strict, sanitized tool-input validation
  upstream.py       GatewayKworkClient (keeps success:false payloads), secure web client
  gateway/          layered gateway, each module builds on the previous one:
    parsing.py      envelope/paging/scalar helpers
    base.py         shared state
    reads.py        typed read operations
    lookups.py      exhaustive scans for preflight and read-back
    offer_flow.py   submit_offer web flow (form → FAQ → draft → template check → create)
    actions.py      one ActionHandler per WriteAction: preflight / execute / read_back
    writes.py       durable prepare / commit / status / reconcile protocol
  tools/            read_tools.py, write_tools.py, common.py (envelope helpers, annotations)
tests/              pytest suite; test_live_contracts.py holds anonymized live response shapes
docs/               architecture, configuration, security, migration and release notes (Russian)
site/               GitHub Pages landing page (Russian), deployed by .github/workflows/pages.yml;
                    static, no build: index.html, style.css, app.js, theme.js, self-hosted fonts/;
                    og.png is rendered from assets/og.html; the pinned version is checked by tests