microsoft-planner-mcp python.instructions.md

Python Source Conventions

Module Header

Every module starts with from __future__ import annotations.

Commenting Convention

Non-obvious decisions must include an inline comment that answers three questions:

1. Why it exists — the intent behind the choice
2. What breaks without it — the failure mode if it is removed or changed
3. Docs link — a URL the next developer can read for full context

Format (single line for short explanations, multi-line for more complex ones):

# <brief what/why>. Without this, <failure mode>.
# Docs: https://...

Apply to:

• Auth guards (get_access_token() is None checks)
• Error-code filtering (if exc.response_status_code != 403:)
• ETag retry logic
• Magic strings (orderHint: " !")
• Middleware registration calls
• Any SDK pattern that is non-obvious from the code alone (e.g. fresh HeadersCollection(), paginate() over bare .get())
• Sentinel values ("*all", select=None)

Do not add comments to obvious code (simple assignments, straightforward returns).

Client Logging (ctx)

Use get_optional_context() from src.deps to access the MCP context inside a tool. This is a project-level wrapper around get_context() from fastmcp.server.dependencies that returns None instead of raising RuntimeError when called outside a request (e.g. in unit tests):

from fastmcp.server.dependencies import get_access_token

from ..deps import get_optional_context

ctx = get_optional_context()

if ctx is not None:
    await ctx.info("Fetching items...")

Do not use the raw try/except RuntimeError pattern inline — use get_optional_context() instead. Do not add ctx: Context | None = None to tool signatures — it leaks internal plumbing to LLM clients.

Use ctx.info() for user-visible progress on multi-step or paginated operations. Use ctx.debug() for single fast calls where intermediate state is not interesting to the user. Docs: https://gofastmcp.com/servers/context#via-get_context-function