waylMCP: Instructions file for Claude Code

CLAUDE.md

Guidance for working in this repository.

What this is

An MCP server that exposes the Wayl payments API as tools. Wayl is an Iraqi payment gateway: you create a payment link, send its URL to the buyer, and they pay on Wayl's hosted checkout. The server is domain-neutral — goods, digital downloads, services and invoices all go through the same payment-link flow.

Python 3.10+, uv for dependency management, the official mcp SDK, stdio transport.

Layout

Path	Purpose
src/wayl_mcp/server.py	All MCP tools. The only file that touches the MCP SDK.
src/wayl_mcp/client.py	httpx wrapper: auth header, response envelope, error mapping, retries.
src/wayl_mcp/validation.py	Client-side enforcement of Wayl's documented rules. Pure functions, no I/O.
src/wayl_mcp/webhooks.py	HMAC-SHA256 signature verification. Pure functions, no I/O.
src/wayl_mcp/config.py	Environment-variable config and the API's magic constants.
docs/openapi.v1.json	Vendored copy of Wayl's OpenAPI spec, fetched from https://api.thewayl.com/openapi.v1.json.
tests/	pytest + respx. No test may touch the network.

Commands

uv run pytest

uv run ruff check src tests

uv run wayl-mcp

Conventions

• Keep I/O out of validation.py and webhooks.py. They are pure and directly unit-testable; that is why the rule checks live there and not inline in the tools.
• Tool parameters are snake_case; the Wayl API is camelCase. server.py is where the two meet — build the request body with the API's spelling.
• Every tool needs a docstring. It becomes the tool description the model reads, and it is the main thing determining whether the tool gets used correctly. Say what the tool does, when to reach for it, and what the caller must be careful about.
• Use Annotated[T, Field(description=...)] for every parameter. These become the JSON Schema descriptions. Constraints like ge=1000 are worth adding even though validation.py also checks them: the schema helps the model self-correct, and the Python check produces the better error message when something bypasses the schema.
• Raise ToolError for anything the caller should see. _call converts WaylError and the @_validated decorator converts ValidationFailed.
• Set annotations= on new tools — READ_ONLY, WRITES, DESTRUCTIVE, or LOCAL_ONLY. Clients use destructiveHint to decide whether to confirm with the user, which is the difference between a refund happening silently and not.
• Always wrap interpolated path values in path_segment(). Reference IDs and product IDs are free text, and an unescaped # truncates the URL — order#42 becomes a request for order, silently returning a different order's payment status. Same for ? and /. It also encodes dots-only segments, because httpx resolves . and .. as path navigation and an ID of . turns a single-order lookup into a request for the whole collection.
• Put every constraint in the JSON Schema, not only in prose. Use Literal[...] for closed sets and min_length/max_length/ge for bounds. A constraint the model can see costs nothing; one it discovers by failing costs a turn. validation.py still checks the same rules for callers that bypass the schema.