118 lines
5.3 KiB
Markdown
118 lines
5.3 KiB
Markdown
---
|
||
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. |