---
name: Documentation lookups via context7 MCP
description: How and when to use the context7 MCP server for library documentation
applyTo: "**/*.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.