finn-mcp/.github/instructions/docs.instructions.md

name, description, applyTo

name	description	applyTo
Documentation lookups via context7 MCP	How and when to use the context7 MCP server for library documentation	**/*.py,**/*.md,**/*.toml,**/*.yaml,**/*.yml

Documentation lookups — use context7

When you are uncertain about a library's API, call the context7 MCP server before writing code. Do not rely on training-data memory. Pydantic, FastMCP, Typer, httpx, and pytest all evolve quickly; what was true two releases ago is often wrong now.

When to use context7

Use it before writing code involving any of these:

• FastMCP / MCP Python SDK — @mcp.tool() signatures, ToolAnnotations, mcp.run(transport=...), resource and prompt decorators, server lifecycle, streamable-HTTP setup.
• Pydantic v2 — BaseModel, Field, ConfigDict, model_validator, field_validator, model_dump / model_dump_json, discriminated unions, Annotated[...] with validators.
• Typer — Typer() apps, typer.Option, typer.Argument, sub-apps via add_typer, callbacks, exit codes, testing with CliRunner.
• httpx — AsyncClient, timeouts, transports, retries, Response API.
• respx — mocking httpx, respx.mock, route.mock, match patterns.
• msgpack — packing/unpacking, type extensions, raw vs string mode.
• base64 — urlsafe_b64encode, padding handling.
• pytest / pytest-asyncio — fixtures, parametrize, async tests, markers, tmp_path, monkeypatch.
• BeautifulSoup / lxml — selectors, parser flavors, element traversal.
• typer.testing.CliRunner — invoking apps, asserting on stdout/stderr/exit codes.

Use it also when:

• A test fails with an error like AttributeError: 'BaseModel' object has no attribute 'dict' (Pydantic v1 vs v2 confusion).
• You see a DeprecationWarning from a third-party library and aren't sure of the modern replacement.
• You're about to copy a code pattern from memory that feels "old".

When NOT to use it

• Pure Python stdlib (json, pathlib, dataclasses, typing) — these are stable and well-known.
• Project-internal modules — read the source.
• Generic programming questions ("what's a list comprehension") — use your own knowledge.
• FINN / Eiendom.no API behavior — these are not in context7. Use fixtures from prior runs in tests/fixtures/ and the endpoint notes in PRD.md §9.

How to use it

Two-step pattern:

1. Resolve the library ID

context7:resolve-library-id(query="fastmcp")
context7:resolve-library-id(query="pydantic")
context7:resolve-library-id(query="typer")

Returns the canonical library ID (e.g. pydantic/pydantic, fastapi/typer). Pick the most-starred / official-looking match.

2. Query the docs

context7:query-docs(
    context7CompatibleLibraryID="pydantic/pydantic",
    topic="field validators v2 mode after",
    tokens=3000,
)

• Keep the topic focused. "Pydantic v2 field validators with mode=after on Optional[str]" beats "Pydantic validation".
• Cap tokens to roughly what you need (1500–4000 is usually plenty). The default is fine for most calls.
• Use library-specific terminology in the topic — "discriminator field" for Pydantic, "tool annotations" for FastMCP, "sub-apps" for Typer.

Worked examples

Q: How do I declare a FastMCP tool with read-only annotations?

context7:resolve-library-id(query="modelcontextprotocol python sdk")
context7:query-docs(context7CompatibleLibraryID="<resolved id>",
                    topic="FastMCP @mcp.tool ToolAnnotations readOnlyHint")

Q: How do I write a Pydantic v2 model_validator that runs after field validation?

context7:resolve-library-id(query="pydantic")
context7:query-docs(context7CompatibleLibraryID="pydantic/pydantic",
                    topic="model_validator mode='after' v2")

Q: How do I mock an async httpx POST with respx?

context7:resolve-library-id(query="respx")
context7:query-docs(context7CompatibleLibraryID="<resolved id>",
                    topic="respx mock async httpx POST json body")

Q: How do I add a Typer sub-app for cache commands?

context7:resolve-library-id(query="typer")
context7:query-docs(context7CompatibleLibraryID="<resolved id>",
                    topic="Typer add_typer sub-application command groups")

After the lookup

• Cite or summarize what you found in a code comment only when the snippet documents a non-obvious API choice — otherwise the code is enough.
• If context7 returns nothing useful, fall back to:
  1. The library's official docs site.
  2. The library's repo README / examples/.
  3. The smallest possible spike (a 5-line script in the venv) to verify behavior.

Anti-patterns

• Don't invent a method signature from memory and hope. If you're not 100% sure of an API, look it up.
• Don't copy patterns from old Stack Overflow answers without verifying — Pydantic, FastMCP, and Typer all had breaking changes recently.
• Don't silence a warning instead of fixing the deprecation. Look up the modern API.
• Don't query context7 for FINN or Eiendom.no — those endpoints aren't in any public docs index. Use tests/fixtures/ and PRD.md §9.

Network configuration note

context7 is configured as a connected MCP server in this environment. If a call fails with a connection error, surface it clearly — don't fall back to guessing.