bing-webmaster-mcp AGENTS.md

Working agreements for coding agents

Read SPEC.md first — it is the contract. This file is how to work in the repo, not what to build.

Ground rules

• Do not invent API details. Method names, parameter shapes, quota numbers and response formats come from a fetched Microsoft page or from docs/api-surface.md, never from memory. SPEC.md marks every fact as verified or unverified; if you need something marked unverified, fetch it and update the marking in the same commit.
• Never hardcode a quota. Read it from the API (SPEC.md §9).
• No network in tests. A test that reaches the internet is a broken test.
• No secrets in the repo. The API key comes from the environment. Never commit a real key, a key-file name, or a site list. .env stays ignored.
• Every write goes through the apply boundary. BING_WM_ALLOW_WRITES picks whether a human sits between plan and apply, not whether the boundary exists. A mutating operation that reaches Bing without creating a plan record and passing through apply_plan is a bug, however it was invoked (SPEC.md §6).
• Never add an apply or reject tool to the MCP server, in either mode. There is a test asserting their absence. If that test fails, the fix is to remove the tool, not to update the test. Enabling direct writes replaces the planning tools; it never adds a tool that can confirm a plan somebody else wrote.

Conventions

• Python ≥3.12, ruff (line-length = 100, select = ["E","F","I","UP","B","SIM","S"]).
• Dependency floors in pyproject.toml, exact pins in constraints.txt. Floors are lower bounds — do not raise one to the newest release just because it exists; that breaks every environment already running something older.
• One ops/ module per domain. CLI and MCP both call ops/, and neither holds logic of its own — if they can diverge in behaviour, the layering is wrong.
• Error codes are a public contract. Adding one is fine; renaming one is a breaking change.
• Tests mirror modules 1:1.