pydoll-mcp-server: Instructions file for Codex

Agent Instructions

Project context

This repository implements a Python MCP server for browser automation with Pydoll. The server exposes a predictable and safe API for agents while preserving Pydoll's async model and client isolation.

The project language is English. Code, comments, documentation, commit messages, tests, fixtures, and progress notes must be written in English. Conversation with Yuri may happen in Portuguese, but repository artifacts should remain in English.

Golden rule

Keep quality high from the first change. Do not accept shortcuts, defer cleanup, or assume that temporary debt will be fixed later. Fix the root cause while the context is available.

Human readability, correctness, and safety take priority over terseness, implementation speed, and clever abstractions.

Local paths

• Project repository: C:\Users\Yuri\Documents\Git\pydoll-mcp-server.
• Local Pydoll repository, read-only: C:\Users\Yuri\Documents\Git\pydoll.
• Python via Anaconda: C:\Users\Yuri\anaconda3\python.exe.
• Vendored Pydoll documentation: references/pydoll-docs/.

These paths are local to this environment. Do not copy them into public documentation.

Non-negotiable rules

• Treat this machine with care. This machine is our home.
• Do not run destructive actions unless strictly necessary, and never revert changes made by others.
• Preserve UTF-8 and do not use em dash characters.
• Do not modify the websocket_lambda repository. It is a style reference only.
• Do not copy secrets, credentials, or insecure patterns found in other projects.
• Do not expose execute_cdp_cmd, operating-system commands, or arbitrary filesystem access.
• Do not weaken Ruff, mypy, Pyright, the LSP, or tests to hide a problem.
• Do not bend production code to make mocks easier or to make tests pass.
• Do not add artificial backward compatibility to preserve incorrect alpha contracts.

File size and module boundaries

• Target size: at most 400 physical lines per Python file.
• Hard limit: 450 physical lines per Python file.
• Files over 450 lines must be refactored before the work is considered complete.
• Files between 401 and 450 lines require a short review or progress note explaining why the code should remain together.
• Prefer cohesive extraction by domain behavior. Do not split a module only to satisfy a line count if the split makes the code harder to read.
• When a module nears the target, move stable helper logic, typed models, scripts, or adapters into focused sibling modules.