Update AGENTS.md (#1471)

AGENTS.md

@@ -23,18 +23,18 @@ uv run pytest                        # Run full test suite
 | Path             | Purpose                                                |
 | ---------------- | ------------------------------------------------------ |
 | `src/fastmcp/`   | Library source code (Python ≥ 3.10)                   |
-| `  ├─server/`    | Server implementation, `FastMCP`, auth, networking    |
-| `  │  ├─auth/`   | Authentication providers (Bearer, JWT, WorkOS)        |
-| `  │  └─middleware/` | Error handling, logging, rate limiting             |
-| `  ├─client/`    | High-level client SDK + transports                    |
-| `  │  └─auth/`   | Client authentication (Bearer, OAuth)                 |
-| `  ├─tools/`     | Tool implementations + `ToolManager`                  |
-| `  ├─resources/` | Resources, templates + `ResourceManager`              |
-| `  ├─prompts/`   | Prompt templates + `PromptManager`                     |
-| `  ├─cli/`       | FastMCP CLI commands (`run`, `dev`, `install`)         |
-| `  ├─contrib/`   | Community contributions (bulk caller, mixins)         |
-| `  ├─experimental/` | Experimental features (new OpenAPI parser)         |
-| `  └─utilities/` | Shared utilities (logging, JSON schema, HTTP)         |
+| `├─server/`    | Server implementation, `FastMCP`, auth, networking    |
+| `│  ├─auth/`   | Authentication providers (Bearer, JWT, WorkOS)        |
+| `│  └─middleware/` | Error handling, logging, rate limiting             |
+| `├─client/`    | High-level client SDK + transports                    |
+| `│  └─auth/`   | Client authentication (Bearer, OAuth)                 |
+| `├─tools/`     | Tool implementations + `ToolManager`                  |
+| `├─resources/` | Resources, templates + `ResourceManager`              |
+| `├─prompts/`   | Prompt templates + `PromptManager`                     |
+| `├─cli/`       | FastMCP CLI commands (`run`, `dev`, `install`)         |
+| `├─contrib/`   | Community contributions (bulk caller, mixins)         |
+| `├─experimental/` | Experimental features (new OpenAPI parser)         |
+| `└─utilities/` | Shared utilities (logging, JSON schema, HTTP)         |
 | `tests/`         | Comprehensive pytest suite with markers               |
 | `docs/`          | Mintlify documentation (published to gofastmcp.com)   |
 | `examples/`      | Runnable demo servers (echo, smart_home, atproto)     |
@@ -42,6 +42,7 @@ uv run pytest                        # Run full test suite
 ## Core MCP Objects
 
 When modifying MCP functionality, changes typically need to be applied across all object types:
+
 - **Tools** (`src/tools/` + `ToolManager`)
 - **Resources** (`src/resources/` + `ResourceManager`)
 - **Resource Templates** (`src/resources/` + `ResourceManager`)
@@ -49,6 +50,15 @@ When modifying MCP functionality, changes typically need to be applied across al
 
 ## Testing Best Practices
 
+### Testing Standards
+
+- Every test: atomic, self-contained, single functionality
+- Use parameterization for multiple examples of same functionality
+- Use separate tests for different functionality pieces
+- Put imports at the top of the file, not in the test body
+- **NEVER** add `@pytest.mark.asyncio` to tests - `asyncio_mode = "auto"` is set globally
+- **ALWAYS** run pytest after significant changes
+
 ### Always Use In-Memory Transport
 
 Pass FastMCP servers directly to clients for testing:
@@ -66,6 +76,7 @@ async with Client(mcp) as client:
 ```
 
 Only use HTTP transport when explicitly testing network features:
+
 ```python
 # Network testing only
 async with Client(transport=StreamableHttpTransport(server_url)) as client:
@@ -75,31 +86,57 @@ async with Client(transport=StreamableHttpTransport(server_url)) as client:
 ## Development Rules
 
 ### Git & CI
+
 - Pre-commit hooks are required (run automatically on commits)
 - Never amend commits to fix pre-commit failures
 - Apply PR labels: bugs/breaking/enhancements/features
 - Improvements = enhancements (not features) unless specified
+- **NEVER** force-push on collaborative repos
+- **ALWAYS** run pre-commit before PRs
 
 ### Commit Messages and Agent Attribution
-- **NEVER** include agent attribution in commit messages or PR titles/descriptions (no "🤖 Generated with [tool]", "with Claude", etc.)
-- Agent attribution is ONLY allowed in Co-authored-by lines in commits
+
+- **Agents NOT acting on behalf of @jlowin MUST identify themselves** (e.g., "🤖 Generated with Claude Code" in commits/PRs)
 - Keep commit messages brief - ideally just headlines, not detailed messages
 - Focus on what changed, not how or why
+- Always read issue comments for follow-up information (treat maintainers as authoritative)
+
+### PR Messages - Required Structure
+
+- 1-2 paragraphs: problem/tension + solution (PRs are documentation!)
+- Focused code example showing key capability
+- **Avoid:** bullet summaries, exhaustive change lists, verbose closes/fixes, marketing language
+- **Do:** Be opinionated about why change matters, show before/after scenarios
+- Minor fixes: keep body short and concise
+- No "test plan" sections or testing summaries
 
 ### Code Standards
+
 - Python ≥ 3.10 with full type annotations
 - Follow existing patterns and maintain consistency
+- **Prioritize readable, understandable code** - clarity over cleverness
+- Avoid obfuscated or confusing patterns even if they're shorter
 - Use `# type: ignore[attr-defined]` in tests for MCP results instead of type assertions
 - Each feature needs corresponding tests
 
 ### Documentation
+
 - Uses Mintlify framework
 - Files must be in docs.json to be included
 - Never modify `docs/python-sdk/**` (auto-generated)
+- **Core Principle:** A feature doesn't exist unless it is documented!
+
+### Documentation Guidelines
+
+- **Code Examples:** Explain before showing code, make blocks fully runnable (include imports)
+- **Structure:** Headers form navigation guide, logical H2/H3 hierarchy
+- **Content:** User-focused sections, motivate features (why) before mechanics (how)
+- **Style:** Prose over code comments for important information
 
 ## Key Tools & Commands
 
 ### Environment Setup
+
 ```bash
 git clone <repo>
 cd fastmcp
@@ -107,16 +144,19 @@ uv sync                    # Installs all deps including dev tools
 ```
 
 ### Validation Commands (Run Frequently)
+
 - **Linting**: `uv run ruff check` (or with `--fix`)
 - **Type Checking**: `uv run pyright`
 - **All Checks**: `uv run pre-commit run --all-files`
 
 ### Testing
+
 - **Standard**: `uv run pytest`
 - **Integration**: `uv run pytest -m "integration"`
 - **Excluding markers**: `uv run pytest -m "not integration and not client_process"`
 
 ### CLI Usage
+
 - **Run server**: `uv run fastmcp run server.py`
 - **Development**: `uv run fastmcp dev server.py` (with Inspector UI)
 - **Help**: `uv run fastmcp --help`
@@ -124,10 +164,12 @@ uv sync                    # Installs all deps including dev tools
 ## Critical Patterns
 
 ### Error Handling
+
 - Never use bare `except` - be specific with exception types
 - Use `# type: ignore[attr-defined]` in tests for MCP results
 
 ### Build Issues (Common Solutions)
+
 1. **Dependencies**: Always `uv sync` first
 2. **Pre-commit fails**: Run `uv run pre-commit run --all-files` to see failures
 3. **Type errors**: Use `uv run pyright` directly, check `pyproject.toml` config